FAQ & Troubleshooting

FAQ & Troubleshooting

Find answers to common questions and solutions for technical issues related to the Gemma CLI workstation.

---

FAQ Frequently Asked Questions

• Q: Is Gemma CLI an AI agent / agentic AI? A: Yes. Gemma CLI is a fully agentic system. Rather than just answering questions, Gemma autonomously decides when to use tools, chains multiple tool calls together to complete complex tasks, and operates on your local system on your behalf. In practice this means Gemma can receive a high-level instruction like "find all PowerShell scripts modified this week and summarize what each one does" and execute it end-to-end — searching directories, reading files, and synthesizing results - without you directing each step.

• Q: Is this free? A: Yes. The CLI itself is open-source under AGPL-3.0. It's designed to work with the Google AI Studio API, which offers both a free tier and paid options. While you can use Gemma CLI entirely with the free tier, upgrading to a paid plan unlocks higher rate limits and increased usage capacity. Gemma CLI automatically manages rate limits for both tiers.

• Q: Why use Gemma when you can make Gemini calls on the same free API? A: Quota isolation and performance. Each model (Gemma and Gemini) has its own rate limits, whether you're using the free or paid tiers. The dual-agent pipeline leverages this to maintain responsiveness even when one model is experiencing rate limits. Paid tiers offer significantly higher rate limits for both models. Unlike Gemini, Gemma can be ran locally with no rate limiting.

• Q: Can Gemma create her own tools? A: Yes. Gemma can write the code for new tools - she knows the tool structure and can produce a complete, ready-to-deploy .ps1 file. Hypothetically limitless capability! (arduino-cli implementation - on the roadmap.

• Q: How secure is my API key? A: Gemma CLI uses Windows DPAPI (Data Protection API). Your key is encrypted using your Windows User SID. It is never stored in plain text, and even if someone copies your apikey.xml file, they cannot decrypt it on another machine.

• Q: How do I change or reset my API key? A: Type /resetkey in the interactive loop. This will delete the encrypted file and quit. On your next launch, you will be prompted for a new key.

---

🛠️ Troubleshooting & Common Fixes

I added a custom tool but Gemma won't use it.

1. Check that the file is in the tools/ folder (not more_tools/).
2. Run /tools to see if it is registered.
3. If it doesn't appear, check the terminal for [FAIL] Error loading tool during startup.
4. Use Validate JSON to ensure your metadata doesn't have a JSON syntax error.

The model "forgot" what I told it 5 minutes ago.

This usually means a Trim occurred.

• The free API defaults to an 15,000 token per minute budget which means for longer context sessions we must trim history from the session.
• Check the Status Bar at the bottom. If ctx is low and you just saw a [SmartTrim] notice in the logs, use /recall to bring important facts back into focus.

I keep getting "429 Resource Exhausted" errors.

This is a rate limit from Google.

• Imagen/Nanobanana: This happens commonly using Google services.
• Solution: Try again later, or upgrade api to pay as you go for priority (Warning! Some users with paid api still report this happening).

Unblocking Files (ZIP Users)

Windows often blocks scripts downloaded from the internet. If the script fails to run after extracting the ZIP, run this in PowerShell inside the folder:

Get-ChildItem -Recurse | Unblock-File

Execution Policy

If you receive an error saying scripts are disabled on your system, run this command in an Administrator PowerShell window:

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

Updating

• Git Users: Run git pull.
• ZIP Users: Download the latest ZIP from GitHub and replace your old files (keep your config/ folder if you want to save custom commands).

---

Next Steps: If your issue isn't listed here, feel free to open a Bug Report.