Claude Code CLI 是与 Claude Code 交互的主要方式，提供了强大的命令行选项来运行查询、管理会话、配置模型并集成到开发工作流中。本参考手册系统讲解其命令、标志与高级用法，重点涵盖脚本集成与 CI/CD 自动化场景，帮助你高效构建生产级 AI 辅助开发流程。

Claude Code CLI 参考手册：命令行用法、脚本集成与 CI/CD 自动化

Claude Code 的命令行界面（CLI）是驱动其所有功能的底层引擎。无论是启动交互式会话、在脚本中处理文件，还是集成到持续集成流水线，CLI 都提供了完整且灵活的控制能力。

1. CLI 概述与架构

Claude Code CLI 的工作模式如下图所示，它支持交互式（REPL）与非交互式（Print）两种主要模式，可根据任务需求选择。

graph TD
    A["User Terminal"] -->|"claude [options] [query]"| B["Claude Code CLI"]
    B -->|Interactive| C["REPL Mode"]
    B -->|"--print"| D["Print Mode (SDK)"]
    B -->|"--resume"| E["Session Resume"]
    C -->|Conversation| F["Claude API"]
    D -->|Single Query| F
    E -->|Load Context| F
    F -->|Response| G["Output"]
    G -->|text/json/stream-json| H["Terminal/Pipe"]

交互模式（REPL）：默认模式，支持多轮对话、Tab 补全、历史记录和斜杠命令。
打印模式（Print）：通过 -p 标志启用，执行单次查询后退出，输出可被管道处理或用于脚本，支持 JSON 格式。

2. 安装与运行时变化

自 v2.1.113 起，CLI 在 macOS 和 Linux 上默认启动一个原生二进制文件，它与你的操作系统和架构匹配，取代了旧的 JavaScript 运行时。

安装方式不变：依然使用 npm install -g @anthropic-ai/claude-code，npm 会自动下载适合你平台的二进制文件。
关键变更 (v2.1.116+)：原生二进制文件的下载源已变更为 https://downloads.claude.ai/claude-code-releases。

企业/代理用户注意：如果你的网络需要显式白名单，请务必将 downloads.claude.ai 加入代理出站规则。仅允许 storage.googleapis.com 或 npm 注册表的环境需要更新设置，否则 claude update 和初次安装会失败。

验证安装：

claude --version
# 应输出类似 `Claude Code 2.x.xxx` 的版本号

3. 核心命令详解

以下是常用 CLI 命令的速查表，更多命令可参考完整的CLI 参考模块。

命令	描述	示例
`claude`	启动交互式 REPL 会话	`claude`
`claude "query"`	带初始提示启动 REPL	`claude “解释这个项目”`
`claude -p "query"`	打印模式：查询后退出	`claude -p “解释这个函数”`
`cat file \| claude -p "query"`	处理管道输入内容	`cat logs.txt \| claude -p “分析错误”`
`claude -c`	继续最近一次对话	`claude -c`
`claude -r "<session>" "query"`	通过 ID 或名称恢复会话	`claude -r “auth-refactor” “完成这个 PR”`
`claude update`	更新至最新版本	`claude update`
`/doctor`	在 REPL 内运行诊断，检查安装、配置与插件健康状态	在 REPL 中输入 `/doctor`
`claude project purge [path]`	清理项目所有本地 Claude Code 状态（v2.1.126+）	`claude project purge ~/work/repo --dry-run`
`claude agents`	打开 Agent View，查看所有会话状态（v2.1.139+）	`claude agents`

4. 核心标志（Flags）用法

标志用于控制 CLI 的行为，是集成与自动化的关键。

模式与会话控制：

-p, --print：启用打印模式。
-c, --continue：加载最近的对话。
-r, --resume：恢复指定会话。
--bare：最小模式，跳过所有钩子、技能、插件、MCP、自动记忆和 CLAUDE.md 文件加载，适用于纯净查询。
--from-pr <url-or-number>：恢复与 PR 关联的会话（v2.1.119+ 已支持 GitHub、GitLab、Bitbucket URL）。

模型与性能：

--model：指定模型（如 opus、sonnet、haiku 或完整名称）。
--effort：设置思考努力级别（low/medium/high/xhigh/max）。
--max-turns：限制非交互模式下的最大交互轮次，对控制脚本成本至关重要。

权限与工具管理（详见高级功能指南）：

--permission-mode：设置权限模式（如 plan 只读模式）。
--tools：限制可用的内置工具。
--allowedTools / --disallowedTools：精细控制哪些工具可自动执行或被禁止。
--dangerously-skip-permissions：跳过所有权限提示（仅限安全沙箱环境）。

PowerShell 自动审批 (v2.1.119)：在 Windows 上，PowerShell 工具的权限可以像 Bash 工具一样自动批准，使用相同的匹配语法，例如 PowerShell(Get-ChildItem:*)。

5. 实用场景与脚本集成

5.1 CI/CD 自动化集成

Claude Code CLI 可无缝集成到 GitHub Actions 或 Jenkins 等系统中，用于自动代码审查、测试生成等。

GitHub Actions 示例：

name: AI Code Review
on: [pull_request]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code
      - name: Run Code Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude -p --output-format json \
            --max-turns 1 \
            "审查此 PR 的变更，关注安全漏洞、性能问题和代码质量，输出包含 ‘issues’ 数组的 JSON。" > review.json
      - name: Post Review Comment
        # ... 使用 `review.json` 发布评论

Headless ultrareview (v2.1.120+)：

# .github/workflows/ultrareview.yml
- name: Claude ultrareview
  run: claude ultrareview ${{ github.event.pull_request.number }} --json > review.json

此命令在审查无问题时返回退出码 0，有问题时返回 1，可直接用作 PR 门禁。使用 --timeout 可覆盖默认的 30 分钟超时。

5.2 脚本管道与数据处理

利用打印模式和管道，将 Claude 集成到 shell 工作流中。

# 分析错误日志
tail -1000 /var/log/app/error.log | claude -p “总结这些错误并提出修复建议”

# 生成 API 文档
cat src/api/*.ts | claude -p “生成 Markdown 格式的 API 文档”

# 获取结构化 JSON 输出并用 jq 处理
claude -p --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array"},"complexity":{"type":"string"}}}' \
  “分析 main.py，返回函数列表及复杂度评级” | jq '.functions[] | select(.complexity == "high")'

5.3 多会话与状态管理

管理多个并行任务，利用会话分叉进行实验。

# 恢复名为 “feature-auth” 的会话继续工作
claude -r "feature-auth" “添加密码重置功能”

# 从一个会话分叉，尝试不同方案
claude --resume feature-auth --fork-session “尝试使用 OAuth 方案”

# 清理项目的旧状态
claude project purge ~/old-project --dry-run # 先预览
claude project purge ~/old-project --yes     # 确认删除

6. 模型选择与配置

Claude Code 支持多个模型，可通过标志或环境变量灵活选择。

# 使用 Opus 进行复杂架构分析
claude --model opus “设计一个缓存策略”

# 使用 Haiku 进行快速格式化
claude --model haiku -p “格式化此 JSON”

# 使用 opusplan 别名（Opus 规划，Sonnet 执行）
claude --model opusplan “设计并实现缓存层”

# 设置全局默认模型（通过环境变量）
export ANTHROPIC_MODEL=sonnet

7. 高级特性与环境变量

Agent View (v2.1.139+)

claude agents 命令打开一个全局视图，列出机器上所有 Claude Code 会话及其状态（运行中、等待输入、已完成），是管理多个后台代理会话的中心。

Gateway 模型发现 (v2.1.129+)

当 ANTHROPIC_BASE_URL 指向一个兼容 Anthropic 的网关时，设置环境变量 CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1，可以让 /model 命令列出网关提供的所有可用模型。

关键环境变量速查

变量	描述
`ANTHROPIC_API_KEY`	用于认证的 API 密钥
`ANTHROPIC_MODEL`	覆盖默认模型
`CLAUDE_CODE_EFFORT_LEVEL`	设置全局思考努力级别 (`low`/`medium`/`high`/`xhigh`/`max`)
`CLAUDE_CODE_SIMPLE`	最小模式，由 `--bare` 标志设置
`DISABLE_UPDATES`	阻止所有更新路径，包括手动 `claude update` (v2.1.118+)
`CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY`	启用网关模型列表发现 (v2.1.129+)

8. 故障排除

安装或更新失败

问题：运行 claude update 或初次安装报错。排查：

检查网络代理设置，确保允许访问 downloads.claude.ai。
使用 /doctor 命令进行全面的健康检查。
尝试清除 npm 缓存：npm cache clean --force。

权限被拒绝

问题：在脚本中运行时因权限提示而中断。解决：

在脚本中明确使用 --permission-mode plan 进入只读模式。
或使用 --allowedTools 精确授权所需的命令，例如 --allowedTools "Bash(git status:*)"。

FAQ

Q: 如何查看当前会话使用了哪个模型？ A: 在交互模式中，可以直接输入 /model 命令查看和切换模型。在脚本中，通常通过 --model 标志或 ANTHROPIC_MODEL 环境变量来明确指定。

Q: --bare 模式和 CLAUDE_CODE_SIMPLE 环境变量有什么区别？ A: 两者功能相同，--bare 标志会在运行时设置 CLAUDE_CODE_SIMPLE=1 环境变量，从而跳过所有配置文件和自动化功能的加载，适用于最简洁的查询场景。

Q: 在 CI/CD 中如何安全地传递 API 密钥？ A: 务必使用 CI 平台提供的秘密管理功能（如 GitHub Actions 的 secrets），将 ANTHROPIC_API_KEY 作为环境变量传入，切勿将其硬编码在代码或日志中。

Claude Code CLI 参考手册：命令行用法、脚本集成与 CI/CD 自动化 #

1. CLI 概述与架构 #

2. 安装与运行时变化 #

3. 核心命令详解 #

4. 核心标志（Flags）用法 #

5. 实用场景与脚本集成 #

5.1 CI/CD 自动化集成 #

5.2 脚本管道与数据处理 #

5.3 多会话与状态管理 #

6. 模型选择与配置 #

7. 高级特性与环境变量 #

Agent View (v2.1.139+) #

Gateway 模型发现 (v2.1.129+) #

关键环境变量速查 #

8. 故障排除 #

安装或更新失败 #

权限被拒绝 #

FAQ #