Skip to content

Commit 56d4581

Browse files
lzwjavalzwjava
committed
docs(notes): add Gemini CLI guide
1 parent f374382 commit 56d4581

File tree

1 file changed

+193
-0
lines changed

1 file changed

+193
-0
lines changed

‎notes/2025-06-29-gemini-cli-guide-en.md

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
---
2+
title: "Install and Use Gemini CLI"
3+
lang: en
4+
layout: post
5+
audio: false
6+
translated: false
7+
generated: true
8+
---
9+
10+
Below is a concise guide to installing, setting up, and using the **Google Gemini CLI**, an open-source AI agent that integrates Gemini’s capabilities into your terminal for coding, task automation, and more. This guide is based on the latest available information as of June 29, 2025.[](https://github.com/google-gemini/gemini-cli)[](https://dev.to/auden/google-gemini-cli-tutorial-how-to-install-and-use-it-with-images-4phb)[](https://gemini-cli.click/)
11+
12+
---
13+
14+
## **Google Gemini CLI Guide**
15+
16+
### **What is Gemini CLI?**
17+
Gemini CLI is an open-source command-line tool developed by Google that brings the power of the Gemini 2.5 Pro model (with a 1 million token context window) to your terminal. It supports coding, debugging, content generation, task automation, and multimodal tasks like image and video generation. It’s free to use with a Google account and integrates with tools like Google Search and Model Context Protocol (MCP) servers.[](https://blog.google/technology/developers/introducing-gemini-cli-open-source-ai-agent/)[](https://dev.to/auden/google-gemini-cli-tutorial-how-to-install-and-use-it-with-images-4phb)
18+
19+
---
20+
21+
### **Prerequisites**
22+
- **Node.js**: Version 18 or higher. Check with `node -v`. Install from [nodejs.org](https://nodejs.org) if needed.
23+
- **Google Account**: Required for free access to Gemini 2.5 Pro (60 requests/minute, 1,000 requests/day).[](https://medium.com/google-cloud/getting-started-with-gemini-cli-8cc4674a1371)[](https://dev.to/auden/google-gemini-cli-tutorial-how-to-install-and-use-it-with-images-4phb)
24+
- (Optional) **API Key**: For higher limits or specific models, generate one from [Google AI Studio](https://aistudio.google.com).[](https://github.com/google-gemini/gemini-cli)
25+
- (Optional) **Docker**: For MCP server integration (e.g., GitHub tools).[](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/tutorials.md)
26+
27+
---
28+
29+
### **Installation**
30+
There are two ways to get started with Gemini CLI:
31+
32+
1. **Install Globally**:
33+
```bash
34+
npm install -g @google/gemini-cli
35+
gemini
36+
```
37+
This installs the CLI globally and runs it with the `gemini` command.[](https://gemini-cli.click/)
38+
39+
2. **Run Without Installing**:
40+
```bash
41+
npx https://github.com/google-gemini/gemini-cli
42+
```
43+
This runs the CLI directly without installation, ideal for testing.[](https://www.bleepingcomputer.com/news/artificial-intelligence/google-releases-gemini-cli-with-free-gemini-25-pro/)
44+
45+
---
46+
47+
### **Setup**
48+
1. **Launch the CLI**:
49+
- Run `gemini` in your terminal.
50+
- On first run, select a theme (e.g., ASCII, dark, light) and press Enter.[](https://dev.to/auden/google-gemini-cli-tutorial-how-to-install-and-use-it-with-images-4phb)
51+
52+
2. **Authenticate**:
53+
- Choose **Login with Google** for free access (recommended for most users).
54+
- A browser window will open; sign in with your Google account.
55+
- Alternatively, use an API key:
56+
- Generate a key from [Google AI Studio](https://aistudio.google.com).
57+
- Set it as an environment variable:
58+
```bash
59+
export GEMINI_API_KEY=YOUR_API_KEY
60+
```
61+
- This is useful for higher limits or enterprise use.[](https://github.com/google-gemini/gemini-cli)[](https://dev.to/auden/google-gemini-cli-tutorial-how-to-install-and-use-it-with-images-4phb)
62+
63+
3. **Navigate to Your Project**:
64+
- Run `gemini` in your project’s root directory to provide context for code-related tasks.[](https://dev.to/proflead/gemini-cli-full-tutorial-2ab5)
65+
66+
---
67+
68+
### **Basic Usage**
69+
Gemini CLI operates in an interactive Read-Eval-Print Loop (REPL) environment. Type commands or natural language prompts to interact with the Gemini model. Here are some common tasks:
70+
71+
1. **Code Explanation**:
72+
- Navigate to a project folder and run:
73+
```bash
74+
gemini
75+
```
76+
- Prompt: `Explain the architecture of this project` or `Describe the main function in main.py`.
77+
- The CLI reads files and provides a structured explanation.[](https://www.datacamp.com/tutorial/gemini-cli)
78+
79+
2. **Code Generation**:
80+
- Prompt: `Create a simple to-do app in HTML, CSS, and JavaScript`.
81+
- The CLI generates the code and can save it to files if requested.[](https://dev.to/proflead/gemini-cli-full-tutorial-2ab5)
82+
83+
3. **Debugging**:
84+
- Paste an error message or stack trace and ask: `What’s causing this error?`.
85+
- The CLI analyzes the error and suggests fixes, potentially using Google Search for additional context.[](https://ts2.tech/en/everything-you-need-to-know-about-google-gemini-cli-features-news-and-expert-insights/)
86+
87+
4. **File Management**:
88+
- Prompt: `Organize my PDF invoices by month of expenditure`.
89+
- The CLI can manipulate files or convert formats (e.g., images to PNG).[](https://github.com/google-gemini/gemini-cli)
90+
91+
5. **GitHub Integration**:
92+
- Use MCP servers for GitHub tasks (e.g., listing issues):
93+
- Configure a GitHub MCP server in `.gemini/settings.json` with a Personal Access Token (PAT).[](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/tutorials.md)
94+
- Prompt: `Get all open issues assigned to me in the foo/bar repo`.
95+
- Run `/mcp` to list configured MCP servers and tools.[](https://medium.com/google-cloud/getting-started-with-gemini-cli-8cc4674a1371)
96+
97+
6. **Multimodal Tasks**:
98+
- Generate media with tools like Imagen or Veo:
99+
- Prompt: `Create a short video of a cat’s adventures in Australia using Veo`.[](https://blog.google/technology/developers/introducing-gemini-cli-open-source-ai-agent/)
100+
101+
---
102+
103+
### **Key Features**
104+
- **Context Files (GEMINI.md)**: Add a `GEMINI.md` file in your project root to define coding styles, project rules, or preferences (e.g., “Use async/await for JavaScript”). The CLI uses this for tailored responses.[](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/configuration.md)[](https://ts2.tech/en/everything-you-need-to-know-about-google-gemini-cli-features-news-and-expert-insights/)
105+
- **Built-in Tools**:
106+
- `/tools`: List available tools (e.g., Google Search, file operations).[](https://dev.to/proflead/gemini-cli-full-tutorial-2ab5)
107+
- `/compress`: Summarize chat context to save tokens.[](https://www.datacamp.com/tutorial/gemini-cli)
108+
- `/bug`: File issues directly to the Gemini CLI GitHub repo.[](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/commands.md)
109+
- **Non-Interactive Mode**: For scripting, pipe commands:
110+
```bash
111+
echo "Write a Python script" | gemini
112+
```
113+
[](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/index.md)
114+
- **Conversation Memory**: Save session history with `/save <tag>` and resume with `/restore <tag>`.[](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/commands.md)
115+
- **Custom Configuration**:
116+
- Edit `~/.gemini/settings.json` for global settings or `.gemini/settings.json` in a project for local settings.
117+
- Example: Set MCP servers or custom themes.[](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/configuration.md)
118+
119+
---
120+
121+
### **Tips and Tricks**
122+
- **Start with Plans**: For complex tasks, ask for a plan first: `Create a detailed implementation plan for a login system`. This ensures structured output.
123+
- **Use Local Context**: Encode project-specific details in `GEMINI.md` instead of relying on MCP servers for faster, reliable responses.
124+
- **Debugging**: Enable verbose logging with `DEBUG=true gemini` for detailed request/response info.[](https://apidog.com/blog/google-gemini-open-code-cli/)
125+
- **Review Changes**: Always review file modifications or commands before approving (type `y` to confirm).[](https://apidog.com/blog/google-gemini-open-code-cli/)
126+
- **Explore Tools**: Run `/tools` to discover built-in capabilities like web search or memory saving.[](https://dev.to/proflead/gemini-cli-full-tutorial-2ab5)
127+
128+
---
129+
130+
### **Troubleshooting**
131+
- **Authentication Issues**: Ensure your Google account or API key is valid. Use `/auth` to switch methods.[](https://www.datacamp.com/tutorial/gemini-cli)
132+
- **Rate Limits**: The free tier allows 60 requests/minute and 1,000/day. For higher limits, use an API key or Vertex AI.[](https://blog.google/technology/developers/introducing-gemini-cli-open-source-ai-agent/)
133+
- **Errors**: Check the [Troubleshooting Guide](https://github.com/google-gemini/gemini-cli/docs/troubleshooting.md) on GitHub.[](https://github.com/google-gemini/gemini-cli)
134+
- **Slow Responses**: The CLI is in preview and may be slow with API calls. File feedback on GitHub.[](https://www.datacamp.com/tutorial/gemini-cli)
135+
136+
---
137+
138+
### **Advanced Usage**
139+
- **MCP Server Integration**:
140+
- Set up a GitHub MCP server for repository interactions:
141+
- Create a GitHub PAT with necessary scopes.
142+
- Add to `.gemini/settings.json`:
143+
```json
144+
{
145+
"mcpServers": [
146+
{
147+
"name": "github",
148+
"url": "http://localhost:8080",
149+
"type": "github"
150+
}
151+
]
152+
}
153+
```
154+
- Run a Docker container for the MCP server (see GitHub docs).[](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/tutorials.md)
155+
- **Scripting**: Automate tasks by integrating Gemini CLI into scripts:
156+
```bash
157+
gemini --non-interactive "Generate a bash script to backup my files"
158+
```
159+
[](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/index.md)
160+
- **Multimodal Prompts**:
161+
- Example: `Describe this image: path/to/image.jpg` (requires a vision-capable model like `gemini-pro-vision`).[](https://github.com/eliben/gemini-cli)
162+
163+
---
164+
165+
### **Limitations**
166+
- **Preview Stage**: Gemini CLI is in pre-GA, with potential for limited support or bugs.[](https://cloud.google.com/gemini/docs/codeassist/gemini-cli)
167+
- **Not Fully Open-Source**: Only the CLI UI is Apache 2.0 licensed; the Gemini model is proprietary.[](https://www.bleepingcomputer.com/news/artificial-intelligence/google-releases-gemini-cli-with-free-gemini-25-pro/)
168+
- **Quota Sharing**: Limits are shared with Gemini Code Assist if used.[](https://developers.google.com/gemini-code-assist/docs/gemini-cli)
169+
- **Future Pricing**: Post-preview pricing is unclear; advanced features may require payment.[](https://ts2.tech/en/everything-you-need-to-know-about-google-gemini-cli-features-news-and-expert-insights/)
170+
171+
---
172+
173+
### **Resources**
174+
- **Official GitHub**: [github.com/google-gemini/gemini-cli](https://github.com/google-gemini/gemini-cli)[](https://github.com/google-gemini/gemini-cli)
175+
- **Documentation**: [gemini-cli.click](https://gemini-cli.click) or GitHub docs[](https://gemini-cli.click/)
176+
- **Blog Announcement**: [blog.google](https://blog.google)[](https://blog.google/technology/developers/introducing-gemini-cli-open-source-ai-agent/)
177+
- **Feedback**: File bugs or suggestions on GitHub.[](https://ts2.tech/en/everything-you-need-to-know-about-google-gemini-cli-features-news-and-expert-insights/)
178+
179+
---
180+
181+
### **Example Workflow**
182+
1. Install: `npm install -g @google/gemini-cli`
183+
2. Run: `cd my-project && gemini`
184+
3. Authenticate: Log in with Google.
185+
4. Prompt: `Write a Python script for a REST API with FastAPI`.
186+
5. Review and save the generated code.
187+
6. Use `/tools` to explore additional features like GitHub integration.
188+
189+
---
190+
191+
Gemini CLI is a powerful tool for developers, offering seamless AI integration in the terminal. Start simple, leverage `GEMINI.md` for context, and explore its multimodal capabilities to boost productivity. For more examples, check the [GitHub tutorials](https://github.com/google-gemini/gemini-cli/docs/cli/tutorials.md).[](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/tutorials.md)
192+
193+
If you need specific examples or have questions about a particular feature, let me know!

0 commit comments

Comments
 (0)