CLI reference
Gemini CLI 常用启动方式、参数、非交互式调用、session resume、model、sandbox、approval mode 和输出格式。
Gemini CLI 的命令行入口分两类：交互式会话用于持续协作，非交互式 prompt 用于脚本和自动化。不要把 CLI reference 当成参数长表背诵；先掌握运行位置、上下文输入、权限模式和输出格式。
先记 4 个入口：gemini 进入交互；gemini -p 一次性执行；gemini -r latest 恢复最近会话；cat file | gemini 处理管道输入。真实项目先用默认批准模式，不要第一天就开 yolo。
1. 常用启动方式
gemini
gemini -p "summarize README.md"
gemini "explain this project"
cat logs.txt | gemini
gemini -i "What is the purpose of this project?"
gemini -r "latest"
gemini -r "latest" "Check for type errors"
gemini -r "<session-id>" "Finish this PR"
gemini update这些入口的区别：
| 入口 | 适合场景 | 注意 |
|---|---|---|
gemini | 持续交互、真实项目理解和修改 | 会保留会话上下文 |
gemini -p "..." | 一次性回答、脚本、CI | 要明确输出格式和退出码处理 |
| `cat file | gemini` | 管道输入、日志解释、批处理 |
gemini -r latest | 恢复最近 session | 先确认是不是当前项目的 session |
gemini update | 更新 CLI | 团队环境要先确认版本策略 |
flowchart TD
Need["我要用 Gemini CLI"] --> Interactive{"需要持续对话?"}
Interactive -->|是| Repl["gemini"]
Interactive -->|否| Script{"脚本或 CI?"}
Script -->|是| Prompt["gemini -p + output format"]
Script -->|否| Pipe{"已有 stdin 输入?"}
Pipe -->|是| Stdin["cat file | gemini"]
Pipe -->|否| Resume{"继续旧会话?"}
Resume -->|是| Session["gemini -r latest"]
Resume -->|否| Repl
style Prompt fill:#fef3c7,stroke:#f59e0b
style Session fill:#dbeafe,stroke:#3b82f62. 常用参数
| 参数 | 用途 |
|---|---|
--model / -m | 指定模型或模型 alias |
--prompt / -p | 非交互式执行 prompt |
--prompt-interactive / -i | 先执行 prompt，再继续交互 |
--resume / -r | 恢复历史 session |
--sandbox / -s | 启用 sandbox |
--approval-mode | 设置工具执行批准模式 |
--include-directories | 把额外目录加入 workspace |
--output-format / -o | 输出 text / json / stream-json |
--extensions / -e | 指定启用 extension |
--allowed-mcp-server-names | 限制可用 MCP server |
参数优先级很高：命令行参数用于当前 session，会覆盖部分配置文件设置。临时试验可以用参数；团队默认行为应该沉淀到配置和文档里。
3. approval mode
当前官方配置文档把 --approval-mode 解释为工具调用批准模式，常见值是 default、auto_edit、yolo。Plan mode 另有专门页面，不要把它当成长期自动批准策略。
| 模式 | 使用建议 |
|---|---|
default | 日常默认，先确认再执行 |
auto_edit | 小范围编辑可考虑，但要看 diff |
yolo | 只适合低风险临时目录，不适合真实项目 |
不要在真实项目默认使用 yolo：生产仓库、含密钥目录、部署脚本目录、数据库迁移和客户数据目录都不适合跳过确认。需要自动化时，也应该先限制目录、工具和命令。
4. 输出格式和脚本化
非交互式任务优先使用结构化输出：
gemini -p "Explain this repository" --output-format json长任务监控可以按官方 README 的 stream-json 方式处理事件流；但脚本里要写清失败处理、超时、重试和日志脱敏，不要只管拿到一段文本。
5. model alias
官方 cheatsheet 中列出 auto、pro、flash、flash-lite 等 alias。具体解析到哪个模型会随官方实现变化，以当前官方文档和 CLI 输出为准。
模型 alias 是便利入口，不是长期契约。教程和团队规则里不要硬写“某个 alias 一定等于某个模型版本”；需要固定模型时，回模型选择章节和官方 CLI 输出核验。
6. 接下来去哪
命令系统
继续看 slash commands、@ 文件引用和 ! shell 的使用边界。
Headless mode
准备把 Gemini CLI 放进脚本或 CI 时，继续看非交互式模式。
配置文件
需要把默认模型、sandbox、工具限制和隐私设置长期化时，继续看 settings。