安装

官方地址：https://geminicli.com/docs/get-started/installation/

当前环境
系统：macos26
ide：vscode

google推荐npm，但npm在mac上比较危险，我们选择使用Homebrew

使用 Homebrew 安装

直接在终端（Terminal）或 VS Code 的集成终端中运行：

brew install gemini-cli

为什么选择 Homebrew 而不是 npm？

  • 权限管理： npm install -g 经常需要 sudo，这会污染系统级目录。Homebrew 将文件存放在 /opt/homebrew（Apple Silicon）下，无需特殊权限。

  • 卸载干净： brew uninstall 会比 npm 移除得更彻底。

  • 自动路径配置： 安装后 gemini 命令会自动加入你的 PATH。

在 VS Code 中配置

由于你使用的是 VS Code，建议完成以下操作以获得最佳开发体验：

  1. 验证安装： 在 VS Code 终端输入

    gemini --version，确保能正确显示版本号。

  2. 环境变量： 如果你在安装后发现 command not found，请确保你的 .zshrc（或 .bash_profile）中包含 Homebrew 的路径。通常安装 Homebrew 时已配置好，但可以检查一下：

    Bash

    # 对于 Apple Silicon Mac
export PATH="/opt/homebrew/bin:$PATH"

  3. Shell 推荐： 文档提到推荐 Zsh（macOS 默认），这与 VS Code 的默认终端配置是契合的

初始化登录

https://geminicli.com/docs/get-started/authentication/

它支持api和google登录，我有google ai 体验版一年（学生会员），可以直接尝试google使用
启动命令行界面：

gemini

  1. 选择“使用 Google 登录”。Gemini CLI 将使用您的 Web 浏览器打开登录提示。请按照屏幕上的说明操作。您的凭据将被缓存到本地，以便下次登录时使用。

这样我们就可以直接使用啦，但还需要做一些

命令

1. 启动与执行命令 (CLI Commands)

这些命令是在你的终端（如 Zsh 或 PowerShell）中直接输入的：

命令示例

说明

gemini

启动交互式对话模式（REPL）。

gemini -p "你的问题"

非交互模式：直接输出结果并退出（常用于脚本）。

gemini -i "你的问题"

混合模式：执行初始 Prompt 后保持交互状态。

cat logs.txt | gemini

管道模式：处理来自其他命令的输入。

gemini -r "latest"

继续上一次的对话会话。

gemini update

更新 Gemini CLI 到最新版本。

2. 核心启动选项 (CLI Options)

选项

别名

默认值

说明

--model

-m

auto

指定模型（如 pro, flash）。

--sandbox

-s

false

在 Docker 沙箱中运行（执行代码更安全）。

--yolo

-

false

YOLO 模式：模型执行所有操作（含删改文件）无需人工确认。

--debug

-d

false

显示详细日志，用于排查错误。

--version

-v

-

查看当前安装版本。

3. 交互模式内的斜杠命令 (Slash Commands)

在 gemini 会话中，输入 / 触发功能指令：

系统管理

  • /help 或 /?: 显示所有可用命令的帮助文档。

  • /settings: 打开图形化设置界面（调整 UI、快捷键等）。

  • /auth: 管理身份验证状态或切换账号。

  • /quit 或 /exit: 退出当前会话。

会话与记忆管理

  • /memory: 查看模型当前加载的所有 GEMINI.md 记忆上下文。

  • /memory reload: 手动强制刷新当前目录下的上下文文件。

  • /clear: 清除终端屏幕，但不重置会话。

  • /stats: 显示 Token 使用量、工具调用次数等统计信息。

  • /resume: 管理、保存或列出已命名的会话存档。

开发与工具

  • /plan: 计划模式：让模型先提供修改步骤，经你确认后再开始写代码。

  • /shells: 查看后台正在运行的终端任务或进程。

  • /tools: 列出当前模型可以调用的所有工具（如文件读写、搜索等）。

  • /mcp: 配置或查看 Model Context Protocol 扩展服务器。

4. 特殊前缀快捷操作

  • @ 文件引用：在 Prompt 中输入 @ 触发文件搜索，快速将文件内容读入上下文。

    • 示例：解释一下这个函数 @src/main.js

  • ! 终端直通：直接在 gemini 对话框里执行本地 Shell 命令。

    • 示例：! ls -la (列出文件，并将结果直接反馈给 AI 观察)

💡 快捷键提示 (macOS)

  • Enter: 提交 Prompt。

  • Shift + Enter: 换行。

  • Ctrl + C: 终止 AI 正在生成的响应。

  • Alt + M: 切换 Markdown 渲染预览。

CLI 命令指南

Gemini CLI 支持多种内置命令，旨在帮助您管理会话、自定义界面以及控制其行为。这些命令通常以正斜杠 (/)、艾特符号 (@) 或感叹号 (!) 开头。

斜杠命令 (/)

斜杠命令用于对 CLI 本身进行元级控制。

内置命令

/about

  • 说明： 显示版本信息。在提交 Issue 时请提供此信息。

/auth

  • 说明： 打开一个对话框，允许您更改身份验证方法。

/bug

  • 说明： 提交关于 Gemini CLI 的 Issue。默认情况下，Issue 会提交到 Gemini CLI 的 GitHub 仓库中。/bug 后输入的字符串将作为标题。此行为可通过 .gemini/settings.json 中的 advanced.bugCommand 进行修改。

/chat

  • 说明： /resume 的别名。两个命令现在共享相同的会话浏览器操作和检查点子命令。
  • 输入 /chat（或 /resume）时的菜单布局：
    • -- auto --
      • list（选择此项打开自动保存的会话浏览器）
    • -- checkpoints --
      • list, save, resume, delete, share（手动标记的检查点）
  • 子命令：
    • debug: 导出最近一次 API 请求的 JSON 负载。
    • delete <tag>: 删除已保存的对话检查点。
    • list: 列出当前项目中手动保存的检查点标签。注意：对话记录是项目限定的。
    • resume <tag>: 从之前的保存点恢复对话。必须在保存该对话的项目目录下运行。
    • save <tag>: 为当前对话保存一个带标签的检查点。
      • 检查点位置： - Linux/macOS: ~/.gemini/tmp/<project_hash>/
        • Windows: C:\Users\<用户名>\.gemini\tmp\<project_hash>\
    • share [filename]: 将当前对话写入 Markdown 或 JSON 文件。

/clear

  • 说明： 清除终端屏幕，包括会话历史记录和滚动回溯。
  • 快捷键： 随时按下 Ctrl+L 即可执行。

/commands

  • 说明： 管理从 .toml 文件加载的自定义斜杠命令。
  • 子命令：
    • reload: 从所有来源（用户级、项目级、MCP、扩展）重新加载自定义命令定义，无需重启 CLI。

/compress

  • 说明： 用摘要替换整个对话上下文。这可以在保留历史概况的同时节省后续任务的 Token 消耗。

/copy

  • 说明： 将 Gemini CLI 的最后一次输出复制到剪贴板。
  • 依赖： Linux 需要 xclip 或 xsel；macOS 自带 pbcopy；Windows 自带 clip。远程会话（SSH/WSL）需要终端支持 OSC 52。

/directory (或 /dir)

  • 说明： 管理多目录支持的工作区目录。
  • 子命令：
    • add: 添加目录（支持绝对路径、相对路径或家目录引用 ~）。
    • show: 显示所有已添加的目录。

/docs

  • 说明： 在浏览器中打开 Gemini CLI 文档。

/editor

  • 说明： 打开对话框以选择支持的编辑器。

/extensions

  • 说明： 管理扩展功能。
  • 常用子命令： install (安装), list (列表), enable/disable (启/禁用), update (更新), uninstall (卸载)。

/help (或 /?)

  • 说明： 显示 Gemini CLI 的帮助信息。

/hooks

  • 说明： 管理钩子（Hooks），用于在特定生命周期事件中拦截或自定义 CLI 行为。

/ide

  • 说明： 管理 IDE 集成（如启用、禁用或安装配套组件）。

/init

  • 说明： 分析当前目录并生成定制的 GEMINI.md 上下文文件，方便为 AI Agent 提供项目特定说明。

/mcp

  • 说明： 管理模型上下文协议 (Model Context Protocol) 服务器。
  • 常用子命令： list (查看工具), refresh (重启服务器并重新发现工具), auth (OAuth 认证)。

/memory

  • 说明： 管理 AI 的指令上下文（从 GEMINI.md 加载的分层记忆）。
  • 子命令： show (查看完整记忆内容), refresh (重新加载所有 GEMINI.md), add (临时添加记忆)。

/model

  • 说明： 管理模型配置。
  • 子命令： set <model-name> [--persist] (设置并持久化模型选择)。

/permissions

  • 说明： 管理文件夹信任设置及其他权限。

/plan

  • 说明： 切换到计划模式（只读），并查看当前生成的计划。

/privacy

  • 说明： 显示隐私声明并管理数据收集偏好。

/quit (或 /exit)

  • 说明： 退出 Gemini CLI。

/restore

  • 说明： 将项目文件恢复到执行工具之前的状态。常用于撤销 AI 对文件的修改。

/rewind

  • 说明： 在对话历史中回溯。允许预览过去的交互并选择性地撤销对话状态或代码更改。
  • 快捷键： 快速连按两次 Esc。

/settings

  • 说明： 打开设置编辑器以修改 Gemini CLI 的行为和外观。

/stats

  • 说明： 显示当前会话、模型使用量（Token）或工具调用的统计数据。

/theme

  • 说明： 更改 Gemini CLI 的视觉主题。

/tools

  • 说明： 显示当前可用的工具列表。使用 /tools desc 查看详细描述。

/vim

  • 说明： 切换 Vim 模式。开启后，输入区域支持普通模式（NORMAL）和插入模式（INSERT）的 Vim 导航与编辑指令。

输入提示词快捷键

这些快捷键直接作用于输入框中的文本：

  • 撤销 (Undo): Alt+z 或 Cmd+z
  • 重做 (Redo): Shift+Alt+Z 或 Shift+Cmd+Z

At 命令 (@)

用于将文件或目录的内容注入到提示词中，支持 Git 感知过滤。

  • @<路径>
    • 说明： 读取指定文件或目录的内容并发送给 Gemini。
    • 示例： @README.md 这文件讲了什么？ 或 @src/ 总结这个目录的代码。
    • 特性： 默认排除 node_modules、.git 等被 git 忽略的文件。

Shell 模式与透传命令 (!)

使用 ! 前缀直接从 CLI 与系统 Shell 交互。

  • !<命令>: 执行单条 Shell 命令并返回。例如：!git status。
  • ! (单独输入): 切换 Shell 模式。进入后，所有输入都将直接视为 Shell 命令，直到再次切换退出。
  • 环境变量： 执行时会自动设置 GEMINI_CLI=1，以便脚本识别环境。