Gemini CLI 的无头模式（-p 标志）让你能在脚本和 CI/CD 中调用 AI 能力：单条命令直接输出响应，Unix 管道传入日志/diff/代码，--output-format json 配合 jq 提取结构化数据。本页包含批量文档生成、git 提交信息自动化等完整脚本示例。

无头模式与自动化

Gemini CLI 的无头模式让你把 AI 能力嵌入脚本和流水线，无需人工交互——完美适配 CI/CD、批量处理和自定义工具构建。

前置条件

• Gemini CLI 已安装并完成认证，参见 安装指南
• 熟悉 Bash/Zsh 或 PowerShell 脚本

无头模式基础

用 -p（或 --prompt）标志提供 Prompt，直接输出响应并退出：

gemini -p "用 TypeScript 写一首赞美诗"

这会绕过交互界面，将响应打印到标准输出（stdout），方便与其他命令管道连接。

管道传入数据

用 Unix 管道 | 把数据传给 Gemini，Gemini 将标准输入作为上下文，回答你的问题：

传入文件内容：

# macOS/Linux
cat error.log | gemini -p "解释为什么失败"

# Windows PowerShell
Get-Content error.log | gemini -p "解释为什么失败"

传入命令输出：

git diff | gemini -p "为这些修改写一个提交信息"

在脚本中使用输出

Gemini 输出到 stdout，可以直接与其他工具连接或保存到文件。

场景：批量文档生成

为目录下的所有 Python 文件自动生成 README：

macOS/Linux (generate_docs.sh)：

#!/bin/bash

for file in *.py; do
  echo "正在为 $file 生成文档..."
  gemini -p "为 @$file 生成 Markdown 格式的文档摘要，输出到标准输出。" > "${file%.py}.md"
done

Windows PowerShell (generate_docs.ps1)：

Get-ChildItem -Filter *.py | ForEach-Object {
  Write-Host "正在为 $($_.Name) 生成文档..."
  $newName = $_.Name -replace '\.py$', '.md'
  gemini -p "为 @$($_.Name) 生成 Markdown 格式的文档摘要，输出到标准输出。" | Out-File -FilePath $newName -Encoding utf8
}

提取结构化 JSON 输出

需要在脚本中解析 AI 输出时，用 --output-format json 配合 jq：

场景：提取 package.json 信息

macOS/Linux (extract_deps.sh)：

#!/bin/bash

if [ ! -f "package.json" ]; then
  echo "错误：未找到 package.json"
  exit 1
fi

gemini --output-format json "从 @package.json 返回一个包含 'version' 和 'deps' 键的 JSON 对象" \
  | jq -r '.response' > data.json

Windows PowerShell (extract_deps.ps1)：

if (-not (Test-Path "package.json")) {
  Write-Error "错误：未找到 package.json"
  exit 1
}

$output = gemini --output-format json "从 @package.json 返回一个包含 'version' 和 'deps' 键的 JSON 对象" | ConvertFrom-Json
$output.response | Out-File -FilePath data.json -Encoding utf8

输出的 data.json 示例：

{
  "version": "1.0.0",
  "deps": {
    "react": "^18.2.0"
  }
}

构建自定义 AI 工具

场景：一键 AI 提交信息（Smart Commit）

在 Shell 配置中添加一个 gcommit 函数，自动用 AI 生成规范的提交信息：

macOS/Linux（.zshrc 或 .bashrc）：

function gcommit() {
  diff=$(git diff --staged)

  if [ -z "$diff" ]; then
    echo "没有已暂存的修改。"
    return 1
  fi

  echo "正在生成提交信息..."
  msg=$(echo "$diff" | gemini -p "为这个 diff 写一条简洁的 Conventional Commit 格式的提交信息，只输出信息本身。")

  git commit -m "$msg"
}

执行 source ~/.zshrc 后即可使用：

git add .
gcommit
# → feat: add user authentication with JWT

Windows PowerShell（$PROFILE）：

function gcommit {
  $diff = git diff --staged

  if (-not $diff) {
    Write-Host "没有已暂存的修改。"
    return
  }

  Write-Host "正在生成提交信息..."
  $msg = $diff | gemini -p "为这个 diff 写一条简洁的 Conventional Commit 格式的提交信息，只输出信息本身。"

  git commit -m "$msg"
}

下一步

• 了解无头模式的完整参数和 JSON Schema：CLI 命令参考
• 结合 Shell 命令让 AI 运行而不只是生成脚本：Shell 命令教程

常见问题

Q: 无头模式下能执行文件操作吗？

A: 可以，AI 仍然可以调用 read_file、write_file、run_shell_command 等工具。区别是：无头模式不会弹出交互式确认窗口，默认所有工具操作都需要在命令行参数中预先授权（如 --yolo 模式），或者对高权限操作直接拒绝。

Q: --output-format json 的输出结构是怎样的？

A: 响应是一个 JSON 对象，response 字段包含 AI 的文本回答，toolCalls 字段包含执行过的工具调用（如果有）。用 jq -r '.response' 提取纯文本回答。

Q: 如何在 CI/CD 中认证 Gemini CLI？

A: 在 CI 环境中，设置 GEMINI_API_KEY 环境变量，或将 service account 凭证文件路径设置为 GOOGLE_APPLICATION_CREDENTIALS 环境变量，Gemini CLI 会自动识别。详见 认证指南。