学习 AI

简体中文

English

简体中文

English

外观

Gemini CLI ​

2026-06-18 起：个人账号与 Google AI Pro / Ultra 通过「Login with Google」访问 Gemini CLI 已停服，日常请改用 Antigravity 的 CLI 表面。Standard / Enterprise 许可证与付费 API key 不受影响。官方弃用说明。

基础用法 ​

  1. 按照 Gemini CLI 安装并登录 Gemini CLI，不同平台的详细安装说明请参阅 安装。
  2. 认证 CLI，阅读 认证 选择一种方式。

日常使用 ​

bash

# 仅在 CLI 中使用 LLM
gemini -p 'your prompt here' # gemini 将在终端输出结果

# 读取图像并在 CLI 中使用 LLM
gemini -p 'rename your image files'

# 帮助你理解代码
gemini -p "Clone the 'chalk' repository from https://github.com/chalk/chalk, read its key source files, and explain how it works."

# 通用脚本工具包
# Revenue - 2023.csv 和 Revenue - 2024.csv
gemini -p "Summarize the revenue growth of the company from 2023 to 2024."

快捷键 ​

按键功能
enter确认并运行命令
esc退出模式
ctrl+a移至行首
ctrl+e移至行尾
ctrl+k删除当前光标到行尾的内容
ctrl+u删除当前光标到行首的内容
ctrl+c删除当前输入
ctrl+backspace删除当前光标左侧字符
Command+backspace删除当前行
ctrl+l清屏
ctrl+p上一条命令
ctrl+n下一条命令
ctrl+r搜索历史命令

特性 ​

Gemini 支持多种特性。

特性描述
command支持运行子命令
checkpoint支持运行检查点 (checkpoint)

命令 ​

Gemini 支持多种命令，你可以使用 / 或 @ 进入子命令。 所有命令列表请参见 Commands

内置命令 ​

/chat ​

用于分割聊天上下文。

  1. /chat save <tag> 保存聊天
  2. /chat resume <tag> 恢复聊天
  3. /chat delete <tag> 删除聊天
  4. /chat list 列出所有聊天
  5. /chat share xx.md 分享此聊天文件

聊天保存在：

  • ~/.gemini/tmp/<project_hash>/ (Linux/macOS)
  • C:\Users\<YourUsername>\.gemini\tmp\<project_hash>\ (Windows)

你可以结合 /compress 命令来压缩聊天文件。

/directory ​

对于多根目录项目，使用 /project 命令添加项目。

  1. /directory add <path> 添加目录
  2. /directory add <path1>,<path2> 添加多个目录
  3. /directory show 列出所有已添加的目录

/clear ​

清除显示，快捷键是 control+c。

/stats ​

显示统计信息，结果如下：

下面是一次真实运行的输出样例。样例里的模型名反映的是采集当时的可用模型，其中部分已经停用；当前可用清单见速查表的模型现状。

bash
Session Stats                                                                                                                        │
│                                                                                                                                       │
│  Interaction Summary                                                                                                                  │
│  Session ID:                 8712b7bb-a1f6-4efb-837b-ef1fc6e5fc9d                                                                     │
│  Tool Calls:                 7 ( ✓ 6 x 1 )                                                                                            │
│  Success Rate:               85.7%                                                                                                    │
│  User Agreement:             85.7% (7 reviewed)                                                                                       │
│                                                                                                                                       │
│  Performance                                                                                                                          │
│  Wall Time:                  2h 42m 46s                                                                                               │
│  Agent Active:               13m 49s                                                                                                  │
│    » API Time:               1m 31s (11.1%)                                                                                           │
│    » Tool Time:              12m 17s (88.9%)                                                                                          │
│                                                                                                                                       │
│                                                                                                                                       │
│  Model Usage                 Reqs                  Usage left                                                                         │
│  ────────────────────────────────────────────────────────────                                                                         │
│  gemini-2.5-flash-lite          3   95.4% (Resets in 13h 25m)                                                                         │
│  gemini-3-pro-preview           7    0.0% (Resets in 13h 25m)                                                                         │
│  gemini-3-flash-preview         1   93.9% (Resets in 14h 18m)                                                                         │
│  gemini-2.5-flash               -   95.4% (Resets in 13h 25m)                                                                         │
│  gemini-2.5-pro                 -    0.0% (Resets in 13h 25m)                                                                         │
│                                                                                                                                       │
│  Usage limits span all sessions and reset daily.                                                                                      │
│  /auth to upgrade or switch to API key.                                                                                               │
│                                                                                                                                       │
│                                                                                                                                       │
│  » Tip: For a full token breakdown, run `/stats model`.

@ 命令 ​

你可以使用 @ 命令添加文件上下文。

!<shell_command> ​

你可以在任何 Shell 命令前添加 ! 前缀来运行它。

输入 ! 切换 Gemini 为 Shell 模式，在沙盒中运行命令。使用 esc 退出 Shell 模式。 在此模式下，你可以使用 GEMINI_CLI=1 检查沙盒。

自定义命令 ​

你可以使用自定义命令保存你的提示词模板。

  1. ~/.gemini/commands 这是针对所有项目的用户自定义命令

  2. .gemini/commands 这是项目自定义命令，如果有同名命令将覆盖用户命令

  3. ~/.gemini/commands/test.toml 将创建 /test 命令

  4. <project>/.gemini/commands/git/commit.toml 将创建 /git:commit 命令

TOML 模板如下所示：

toml
# 描述命令的注释
# 调用方式: /changelog 1.2.0 added "Support for default argument parsing."

# description 可选配置，描述此命令
description = "Adds a new entry to the project\'s CHANGELOG.md file."
# prompt 必填
prompt = """
# Task: Update Changelog

You are an expert maintainer of this software project. A user has invoked a command to add a new entry to the changelog.

**The user\'s raw command is appended below your instructions.**

Your task is to parse the `<version>`, `<change_type>`, and `<message>` from their input and use the `write_file` tool to correctly update the `CHANGELOG.md` file.

## Expected Format
The command follows this format: `/changelog <version> <type> <message>`
- `<type>` must be one of: "added", "changed", "fixed", "removed".

## Behavior
1. Read the `CHANGELOG.md` file.
2. Find the section for the specified `<version>`.
3. Add the `<message>` under the correct `<type>` heading.
4. If the version or type section doesn\'t exist, create it.
5. Adhere strictly to the "Keep a Changelog" format.
"""

在配置文件中，支持以下符号：

符号功能演示
将替换为命令后的用户输入prompt = "Please provide a code fix for the issue described here: ."
!{}运行 Shell 命令prompt = "Please summarize the findings for the pattern ", 你可以在 Shell 命令中使用
@{file}添加文件上下文prompt = "You are an expert code reviewer.@{docs/best-practices.md}"

会话 (Session) ​

每次使用 Gemini 都会创建一个会话。会话保存你的对话信息，如提示词、模型响应等。 会话保存在 ~/.gemini/tmp/<project_hash>/chats/<session_hash>。

你可以列出历史会话并重新进入：

bash
# 列出当前目录相关会话
gemini --list-sessions
# 进入当前目录的最新会话
gemini --resume
# 按索引进入当前目录的会话
gemini --resume 2
# 按哈希进入当前目录的会话
gemini --resume <hash>
# 删除当前目录的会话
gemini --delete-session 2

官方会话文档确认：--resume（别名 -r）可接 latest、索引（如 --resume 2）或会话 ID / 哈希；--delete-session 接索引或完整 UUID。见 Session management。

在 Gemini CLI 中，你也可以使用 /session 或 /resume 命令列出并进入会话。

会话配置 ​

你可以配置会话：

json
{
  "general": {
    "sessionRetention": {
      "enabled": true, // 会话清理开关默认为 false
      "maxAge": "30d", // 使能清理后，最多保存 30d
      "maxCount": 50, // 最多保留最近 50 个会话
      "minRetention": "1d" // 最短保留期限，小于此日期不会被删除，默认 1d
    }
  }
}

为了避免会话过长，你可以设置：

json
{
  "model": {
    "maxSessionTurns": 100 // 一个 session 最多允许 100 次聊天， 默认 `-1` 表示不限制
  }
}

检查点 (Checkpoint) ​

此特性默认禁用，编辑设置以开启它。

json
{
  "general": {
    "checkpointing": {
      "enabled": true
    }
  }
}

每次更改都会保存为一个点。

bash
# 列出所有检查点
/restore

# 恢复特定文件
/restore 2025-06-22T10-00-00_000Z-my-file.txt-write_file

无头模式 (Headless Mode) ​

通常我们使用交互模式的 Gemini CLI，但像 gemini -p <prompt> 是无头模式，只是让 Gemini 运行提示词。

你可以将其与自动化工具结合使用，例如 gemini -p "What is the capital of France?" --output-format json 解析输出内容以运行自动化。格式请参见 JSON 输出。

对于长时间任务支持流式输出，请参见 流式 JSON 了解更多。

无头模式的一些用例，参考 示例：

bash
# 代码审查
cat src/auth.py | gemini -p "Review this authentication code for security issues" > security-review.txt

# 生成提交信息
result=$(git diff --cached | gemini -p "Write a concise commit message for these changes" --output-format json)
echo "$result" | jq -r '.response'

# API 文档
result=$(cat api/routes.js | gemini -p "Generate OpenAPI spec for these routes" --output-format json)
echo "$result" | jq -r '.response' > openapi.json

# 批量代码分析
for file in src/*.py; do
    echo "Analyzing $file..."
    result=$(cat "$file" | gemini -p "Find potential bugs and suggest improvements" --output-format json)
    echo "$result" | jq -r '.response' > "reports/$(basename "$file").analysis"
    echo "Completed analysis for $(basename "$file")" >> reports/progress.log
done

# 日志分析
grep "ERROR" /var/log/app.log | tail -20 | gemini -p "Analyze these errors and suggest root cause and fixes" > error-analysis.txt


# 模型和工具使用跟踪
result=$(gemini -p "Explain this database schema" --include-directories db --output-format json)
total_tokens=$(echo "$result" | jq -r '.stats.models // {} | to_entries | map(.value.tokens.total) | add // 0')
models_used=$(echo "$result" | jq -r '.stats.models // {} | keys | join(", ") | if . == "" then "none" else . end')
tool_calls=$(echo "$result" | jq -r '.stats.tools.totalCalls // 0')
tools_used=$(echo "$result" | jq -r '.stats.tools.byName // {} | keys | join(", ") | if . == "" then "none" else . end')
echo "$(date): $total_tokens tokens, $tool_calls tool calls ($tools_used) used with models: $models_used" >> usage.log
echo "$result" | jq -r '.response' > schema-docs.md
echo "Recent usage trends:"
tail -5 usage.log

配置 ​

使用 Gemini Config 控制 Gemini CLI 的行为。 详情请阅读 Gemini CLI 配置。 支持的详细列表参考 JSON Schema。

配置层级 ​

Gemini 支持多个配置层级。完整路径与优先级只在速查表的配置层级维护一份，这里不重复抄表。官方说明见 配置层级。

配置文件里可以使用 $VAR_NAME 或 ${VAR_NAME} 引用环境变量。某些配置支持目录，详见 沙盒配置。

设置配置 ​

你可以直接修改配置文件，或使用 /settings 命令设置配置。 设置列表在 Settings 中。

系统提示词 (System Prompt) ​

你可以设置 .gemini/.env 文件来设置 持久化环境变量。

设置 GEMINI_SYSTEM_MD=true 或 GEMINI_SYSTEM_MD=1 即可启用自定义系统提示词。 CLI 将读取 .gemini/system.md 文件来设置系统提示词。

或者设置 GEMINI_SYSTEM_MD=/absolute/path/to/my-system.md 来设置系统提示词。

当 GEMINI_SYSTEM_MD 激活时，CLI 会在 UI 中显示 |⌐■_■| 指示器，以提示自定义系统提示词模式。

SYSTEM.md 和 GEMINI.md 的区别是：

  1. system.md 针对所有项目或团队，不可协商的操作规则：安全性、工具使用协议、批准以及保持 CLI 可靠的机制。
  2. gemini.md 角色、目标、方法论和项目/领域上下文。随任务演变；依赖 SYSTEM.md 进行安全执行。

主题配置 ​

你可以使用 /theme 命令设置主题。详情参见 主题。

设置信任文件夹 ​

信任文件夹使 Gemini 可以读取你的文件。详情参见 为什么信任很重要。

用下面的配置启用这个特性：

json
{
  "security": {
    "folderTrust": {
      "enabled": true
    }
  }
}

设置后，~/.gemini/trustedFolders.json 可以看到你的信任文件夹。 请注意，只有项目作为受信任文件夹时，项目设置（如 .gemini/settings.json）和自定义命令才能工作！！！！

MCP ​

设置 MCP ​

阅读 Github MCP。

设置之前，请确保已创建 GitHub Token。

  1. 安装 Github MCP 扩展

    bash
    gemini extensions install https://github.com/github/github-mcp-server

  2. 在 Gemini 中使用 /mcp 列出已安装的 MCP

有用的 MCP ​

工具 (Tools) ​

Gemini 使用工具帮助 LLM 更好地理解你的任务。一些内置工具如下：

类别工具描述
FilesLSTool列出目录内容
ReadFileTool读取文件
WriteFileTool写入内容到文件
GrepTool在文件中搜索模式
GlobTool查找匹配模式的文件
EditTool执行文件修改
ReadManyFilesTool读取并连接多个文件或 Glob 模式的内容，在 CLI 中使用 @
ExecutionShellTool执行 Shell 命令
Web ToolsWebFetchTool网络获取
WebSearchTool网络搜索
Memory toolsMemoryTool与记忆交互

可以用 <tool_name>(<args>) 的形式直接调用工具。

详见官方工具文档。

扩展自定义工具 ​

关于工具规则，你可以阅读 策略引擎

用例 ​

模式 ​

使用 ! 切换 Gemini 为 Shell 模式，使用 esc 退出。

连接到 Cursor ​

连接 IDE 后，你可以使用 IDE 查看 Gemini 修改的内容。

  1. 打开 Cursor
  2. 安装 Gemini CLI Companion
  3. 运行 gemini
  4. 输入 /ide install

其他 ​

沙盒 ​

Gemini CLI 可以在沙盒里运行以限制它对系统的影响。在 CLI 里用 -s 启用沙盒模式；以 YOLO 模式运行时默认会使用沙盒。详见沙盒配置与沙盒文档。

企业与可观测性 ​

企业部署相关内容见企业文档；想看更细的运行指标可以开启遥测。

相关页面 ​

  • 速查表 — 配置优先级与真实存在的配置键
  • Cookbook — 按任务查配方
  • 术语表 — Session、Checkpoint、Trusted Folder 等概念

为前端工程师打造 · 基于 VitePress 构建

版权所有 © 2024-present 学习 AI