cc-haha/docs/guide/cli-reference.md

CLI 参考

Claude Code Haha 默认启动交互式会话，也可以用 --print 作为脚本、CI 或其他程序中的非交互式 Agent。源码仓库中的命令是 ./bin/claude-haha；安装后的可执行文件名称以安装方式为准。

./bin/claude-haha --help

--help 是当前版本参数的最终依据。本页按任务解释最常用的参数，避免复制一份很快过期的完整帮助输出。

快速示例

# 在当前目录开始交互式会话
./bin/claude-haha

# 带着第一条需求进入会话
./bin/claude-haha "解释这个仓库的启动路径"

# 返回一段文本后退出
./bin/claude-haha --print "总结最近一次提交"

# 返回一个完整 JSON 结果
./bin/claude-haha --print --output-format json "列出主要模块"

# 继续当前目录最近的会话
./bin/claude-haha --continue

# 恢复指定会话，同时创建新的会话分支
./bin/claude-haha --resume <session-id> --fork-session

# 在新 Git worktree 中工作
./bin/claude-haha --worktree docs-refresh

先理解 --print 的安全边界

-p, --print 会跳过工作区信任对话框。它仍会读取启用的用户、项目和本地设置；可信项目中的 hooks、MCP、工具权限和环境配置也可能影响运行。

因此：

• 只在你信任的目录中运行 --print、doctor 和自动化任务。
• 处理陌生仓库时，先检查 .claude/、.mcp.json、插件和工作区说明。
• --dangerously-skip-permissions 会绕过所有权限检查，只适合无网络、可丢弃的隔离沙箱。
• --allow-dangerously-skip-permissions 只是允许会话选择绕过模式，并不会自动开启它。
• 自动化中明确限制 --tools、--allowed-tools、预算和可访问目录。

非交互输入与输出

参数	说明
-p, --print	处理请求，输出结果并退出
--output-format text	纯文本；默认格式
--output-format json	单个完整 JSON 结果
--output-format stream-json	持续输出 JSON 事件
--input-format text	普通文本输入；默认格式
--input-format stream-json	从标准输入持续接收 JSON 事件
--json-schema '<schema>'	要求最终结构化输出符合 JSON Schema
--include-partial-messages	在 stream-json 中包含增量消息片段
--include-hook-events	在 stream-json 中包含 hook 生命周期事件
--replay-user-messages	流式输入输出时，把用户消息重新发到标准输出作为确认
--no-session-persistence	非交互运行后不保存会话
--max-budget-usd <amount>	为 --print 设置最高 API 费用

结构化输出示例：

./bin/claude-haha --print \
  --output-format json \
  --json-schema '{"type":"object","properties":{"risk":{"type":"string"}},"required":["risk"]}' \
  "审查当前改动，只返回风险级别"

流式输出是事件协议，不等同于把普通 JSON 拆成多行。消费端应按 type 处理事件，并允许新事件字段出现。

会话与工作区

参数	说明
-c, --continue	继续当前目录最近一次会话
-r, --resume [value]	按会话 ID 恢复；省略值时打开选择器，也可传搜索词
--fork-session	恢复时创建新会话 ID，不覆盖原会话路径
--session-id <uuid>	指定本次会话 ID
-n, --name <name>	设置在恢复列表和终端标题中显示的名称
--from-pr [value]	按 PR 编号或 URL 恢复关联会话
--add-dir <paths...>	额外允许工具访问的目录
-w, --worktree [name]	为会话创建 Git worktree
--tmux	与 --worktree 配合创建 tmux 会话；受支持时使用 iTerm2 pane

--worktree 会改变本地 Git 工作区布局。运行前先确认仓库状态，并在自动化中提供明确名称。

模型与上下文

参数	说明
--model <model>	使用模型别名或完整模型 ID
--fallback-model <model>	--print 模式下主模型过载时使用备用模型
--effort <level>	设置推理投入，如 low、medium、high、xhigh 或 max
--agent <agent>	使用已配置的 Agent
--agents '<json>'	为本次会话定义自定义 Agent
--system-prompt <text>	替换本次会话的 system prompt
--append-system-prompt <text>	在默认 system prompt 后追加内容
--file <specs...>	启动时下载文件资源，格式为 file_id:relative_path
--bare	启动最小运行时，跳过 hooks、LSP、插件同步、自动记忆等自动发现能力

--bare 不是“更宽松”的模式。它减少隐式上下文和凭据来源，调用方需要显式提供 prompts、目录、MCP、设置、Agents 或插件。

工具与权限

参数	说明
--tools <tools...>	指定可用的内置工具；"" 禁用全部，default 使用默认集合
--allowed-tools <tools...>	允许匹配的工具，例如 Bash(git:*) Edit
--disallowed-tools <tools...>	拒绝匹配的工具
--permission-mode <mode>	选择 default、acceptEdits、plan、dontAsk、bypassPermissions 或 auto
--no-computer-use	本次会话不加载 Computer Use MCP
--chrome / --no-chrome	开启或关闭 Chrome 集成
--ide	只有一个有效 IDE 时自动连接

拒绝规则和平台策略仍可能覆盖允许规则。生产自动化应使用最小工具集，而不是依赖一次人工批准后的本机状态。

设置、MCP 与插件

参数	说明
--settings <file-or-json>	加载额外的设置文件或 JSON 字符串
--setting-sources <sources>	选择 user、project、local 设置来源
--mcp-config <configs...>	从 JSON 文件或 JSON 字符串加载 MCP 服务
--strict-mcp-config	忽略其他 MCP 配置，只使用命令行指定的配置
--plugin-dir <path>	为本次会话加载插件目录；多个目录要重复传参
--disable-slash-commands	禁用所有 Skills
-d, --debug [filter]	开启调试日志，可按分类筛选
--debug-file <path>	把调试日志写入指定文件

--mcp-debug 已弃用，请使用 --debug。

子命令

子命令	用途
agents	列出已配置的 Agents
auth	管理认证
auto-mode	查看 Auto mode 分类器配置
doctor	检查更新器和运行环境健康状态
install	安装指定渠道或版本的原生构建
mcp	配置和管理 MCP 服务
plugin / plugins	管理插件
setup-token	为 Claude 订阅创建长期认证 Token
update / upgrade	检查并安装更新

每个子命令都有独立帮助：

./bin/claude-haha mcp --help
./bin/claude-haha plugin --help

交互式命令

交互会话中输入 /help 查看当前可用命令。/commit、/review 等命令来自内置命令集；Skills 和插件也能动态加入命令，所以不要依赖文档中的固定清单。

如果命令不存在，先以 /help 的当前输出为准，并检查是否使用了 --disable-slash-commands。