Your all-in-one reference for Google’s AI-powered terminal assistant.
🛠️ 1. Installation
Linux / macOS
# Install globally
npm install -g @google/gemini-cli
# OR run without install
npx https://github.com/google-gemini/gemini-cli
# Verify installation
gemini --version
💡 If you get permission errors, prepend sudo or install Node.js via nvm.
Windows (PowerShell / CMD)
# Global install
npm install -g @google/gemini-cli
# One-time run
npx https://github.com/google-gemini/gemini-cli
# Check version
gemini --version
⚠️ On Windows, ensure npm and node are in your PATH (node -v to verify).
🔐 2. First-Time Setup
Run and Configure
gemini
Then follow prompts:
Choose color theme.
Sign in with Google or paste API key.
Confirm workspace directory permissions.
Save settings (auto-created on first run).
Config file locations
| OS | Config File Path |
|---|
| Linux | ~/.gemini/settings.json |
| macOS | ~/Library/Application Support/gemini/settings.json |
| Windows | C:\Users\<you>\AppData\Roaming\gemini\settings.json |
🧩 Workspace settings override user-level configs (.gemini/settings.json inside project).
⚡ 3. Basic Usage
Start interactive session
gemini
One-off (non-interactive) prompt
gemini -p "Summarize this folder’s code structure"
Choose a specific model
gemini -m "gemini-2.5-pro"
gemini -m "gemini-2.5-flash"
🧠 Pro = higher accuracy / reasoning
⚡ Flash = faster, cheaper, lighter
💬 4. Everyday Commands
| Action | Command / Example |
|---|
| Ask a question | > What does main.py do? |
| Generate code | > Create a REST API using Flask |
| Refactor | > Refactor login.js for async/await |
| Generate docs | > Write documentation for utils/ |
| Generate tests | > Create Jest tests for helpers.js |
| Summarize files | > Summarize key modules in src/ |
| Fix bug | > Find and fix undefined variable errors |
🧰 5. Built-in Tools (Automated)
| Tool | Description |
|---|
| read-file | Reads a single file |
| write-file | Edits / writes files |
| read-many-files | Scans multiple files |
| glob | Finds files by pattern |
| grep | Searches text patterns |
| shell | Runs terminal commands |
| memoryTool | Stores session memory |
| web-search | Looks up online info |
| web-fetch | Fetches URLs / APIs |
Gemini automatically uses these tools when you give a natural-language command.
🧩 6. Slash Commands (Meta Controls)
| Command | Purpose |
|---|
| /help | Show all commands |
| /tools | List available tools |
| /memory | View / clear memory |
| /stats | Check token & usage info |
| /theme | Change CLI theme |
| /mcp | Manage connected MCP servers |
| /quit or /exit | Leave session |
🪄 7. Shell Integration
You can run native commands inside Gemini with a ! prefix:
| Example | Description |
|---|
| !ls -al | List directory (Linux/macOS) |
| !dir | List directory (Windows) |
| !git status | Show Git changes |
| !npm test | Run tests |
| !python app.py | Run Python app |
📂 8. Typical Workflow
cd ~/projects/myapp
gemini
Then inside CLI:
> Explain architecture of this repo
> Fix bug in src/api/order.js
> Generate README.md with project overview
> !git diff
> Add error logging to server.js
🧠 9. Useful Flags
| Flag | Description | Example |
|---|
| -p | Run one-time prompt | gemini -p "Summarize this repo" |
| -m | Choose model | gemini -m gemini-2.5-flash |
| --help | Show help menu | gemini --help |
| --version | Check version | gemini --version |
🧩 10. Config Customization
Edit .gemini/settings.json in your project for defaults:
{
"model": "gemini-2.5-flash",
"theme": "dark",
"autoApproveToolUse": true,
"maxTokens": 8192
}
🪶 You can also set autoApproveToolUse to false for manual control.
🧭 11. Troubleshooting Quick Fixes
| Issue | Fix |
|---|
| Permission error (Linux/macOS) | Run with sudo or reinstall Node using nvm |
| Command not found | Add npm global bin to PATH |
| Login redirect fails | Retry or use API key from Google AI Studio |
| Quota exceeded | Wait 24h or upgrade your API key |
| Cannot find module | npm uninstall -g @google/gemini-cli && npm install -g @google/gemini-cli |
| Security prompt each time | Add "autoApproveToolUse": true to config |
🧩 12. Pro Tips & Tricks
gemini -p "Generate release notes for v2.0" > changelog.txt
gemini -p "Summarize src/app.js"
/mcp connect http://localhost:8080
/model gemini-2.5-pro
/stats
🔒 13. Security & Safe Use
Run in trusted directories only.
Review diffs before accepting file changes.
Use isolated environments for sensitive projects.
Stay updated — run:
npm update -g @google/gemini-cli
🌈 14. Bonus Shortcuts
| Action | Linux/macOS | Windows |
|---|
| Clear terminal | Ctrl + L | Ctrl + L |
| Copy last output | Ctrl + Shift + C | Ctrl + C (PowerShell) |
| Paste command | Ctrl + Shift + V | Ctrl + V |
| Interrupt task | Ctrl + C | Ctrl + C |
🧭 15. Quick Reference Summary
| Category | Command |
|---|
| Launch | gemini |
| Prompt (inline) | gemini -p "..." |
| Model select | gemini -m "gemini-2.5-pro" |
| Help | /help |
| Tools list | /tools |
| Check stats | /stats |
| Quit | /quit |
| Shell inside | !ls, !git status |
| Update CLI | npm update -g @google/gemini-cli |