---
title: "CLI reference"
description: "Gemini CLI 常用启动方式、参数、非交互式调用、session resume、model、sandbox、approval mode 和输出格式。"
verifiedAt: "2026-05-09"
---

Gemini CLI 的命令行入口分两类：交互式会话用于持续协作，非交互式 prompt 用于脚本和自动化。不要把 CLI reference 当成参数长表背诵；先掌握运行位置、上下文输入、权限模式和输出格式。

> [!NOTE]
> **先记 4 个入口**：`gemini` 进入交互；`gemini -p` 一次性执行；`gemini -r latest` 恢复最近会话；`cat file | gemini` 处理管道输入。真实项目先用默认批准模式，不要第一天就开 `yolo`。

## 1. 常用启动方式

```bash
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 | 团队环境要先确认版本策略 |

```mermaid
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:#3b82f6
```

## 2. 常用参数

| 参数 | 用途 |
| --- | --- |
| `--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 |

> [!IMPORTANT]
> **参数优先级很高**：命令行参数用于当前 session，会覆盖部分配置文件设置。临时试验可以用参数；团队默认行为应该沉淀到配置和文档里。

## 3. approval mode

当前官方配置文档把 `--approval-mode` 解释为工具调用批准模式，常见值是 `default`、`auto_edit`、`yolo`。Plan mode 另有专门页面，不要把它当成长期自动批准策略。

| 模式 | 使用建议 |
| --- | --- |
| `default` | 日常默认，先确认再执行 |
| `auto_edit` | 小范围编辑可考虑，但要看 diff |
| `yolo` | 只适合低风险临时目录，不适合真实项目 |

> [!WARNING]
> **不要在真实项目默认使用 `yolo`**：生产仓库、含密钥目录、部署脚本目录、数据库迁移和客户数据目录都不适合跳过确认。需要自动化时，也应该先限制目录、工具和命令。

## 4. 输出格式和脚本化

非交互式任务优先使用结构化输出：

```bash
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. 接下来去哪

<Cards>
  <Card title="命令系统" description="继续看 slash commands、@ 文件引用和 ! shell 的使用边界。" href="/docs/gemini-cli/official/01-cli-workflow/11-commands" />
  <Card title="Headless mode" description="准备把 Gemini CLI 放进脚本或 CI 时，继续看非交互式模式。" href="/docs/gemini-cli/official/07-integrations-automation/72-headless-mode" />
  <Card title="配置文件" description="需要把默认模型、sandbox、工具限制和隐私设置长期化时，继续看 settings。" href="/docs/gemini-cli/official/02-context-config/20-settings" />
</Cards>

## 官方来源

- [Gemini CLI Cheatsheet](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/cli-reference.md)
- [Gemini CLI Configuration](https://google-gemini.github.io/gemini-cli/docs/get-started/configuration.html)
- [Gemini CLI GitHub](https://github.com/google-gemini/gemini-cli)
