ComateCLI 是一个运行在终端里的 AI 编码助手。

• 直接运行：打开一个可对话的交互式 TUI
• 配合子命令：化身可脚本化、可接入 CI 的 Headless CLI

两种模式共享同一套登录态、模型与配置。

1. 快速开始

一句话结论：三步 —— 安装、登录、使用 环境要求：Node.js ≥ 20.10

1.1 安装

使用 npm 全局安装：

1npm i -g @comate/comatecli

安装完成后，命令行工具名为 comatecli。

关于升级：

• TUI 启动时会自动在后台检查更新（见 §3.5）
• 也可手动执行 comatecli update

1.2 登录

1# 默认：设备码登录，自动打开浏览器完成授权
2comatecli login
3
4# SSH / 无浏览器环境：仅打印登录链接，手动在别处打开
5comatecli login --no-browser
6
7# 验证登录态
8comatecli status   # 已登录 → 退出码 0；未登录 → 退出码 1

1.3 第一次对话

1# 交互式 TUI
2comatecli
3
4# 一次性 Headless 提问
5comatecli run -q "解释这个仓库的构建流程"

2. 交互式 TUI：终端里的结对编程

2.1 Slash 命令全集

在输入框输入 / 即可弹出命令菜单（↑↓ 选择，Enter 执行，Tab 只补全，Esc 关闭）：

注意：路径如 /Users/xxx、/tmp/a 不会被误判为命令，可放心粘贴。 关于额度：赠送额度用尽后，模型会自动切换为 Auto 免费模式（每日有限额）。/model 会给出相应提示 —— 你仍可继续使用，升级套餐后恢复全部模型选择。

2.2 三种模式：Agent / Plan / Goal

• Plan 批准门：计划就绪后弹出「开始实施（切回 Agent 执行此计划）/ 继续完善计划（直接输入修改意见，Esc）」。
• Goal 横幅：顶部实时显示 ◆ 目标推进中 · 耗时 · 轮次 N · Xk tokens，四态（推进中 / 收尾中 / 已完成 / 已阻塞）。

模式与模型选择都会持久化，下次启动自动恢复。

2.3 会话管理

2.4 审批与安全

核心原则：有风险的操作（执行命令、退出时还有后台任务）都会先询问你；30 秒不操作自动取消，不会卡死。

Bash 命令审批门（三选项）：

1. 是（仅本次）
2. 是，本会话不再询问任何命令
3. 否，并告诉我该怎么做（Esc）

超时控制：

• 默认 30s（可通过环境变量 COMATE_APPROVAL_TIMEOUT_MS 调整）
• 超时自动取消执行
• 子任务（agent）里发起的命令同样会弹到主界面，并标注「来自 <agent 链>」

退出保护：

• Ctrl+C 时若有后台任务在跑，会弹「⚠ N 个后台任务仍在运行，退出会终止它们」
• 3 秒内再按一次 Ctrl+C 才真正退出（会逐个终止后台任务）
• 按任意其他键取消

2.5 输入进阶

• 多行输入：Opt+Enter（或 Ctrl+Enter）换行，Enter 发送。

• 粘贴图片：

  • 复制图片后按 Ctrl+V，插入 [image-N] 占位符，随消息一起发送
  • 单图 ≤ 10MB，每条消息最多 5 张
  • 剪贴板里有图时 footer 会提示「剪贴板有图片 · 按 ctrl+v 插入」

• 输入历史：

  • 输入框为空时 ↑/↓ 回溯历史输入
  • Ctrl+R 打开历史搜索

• Emacs 键位：

  • Ctrl+A/E：行首/尾
  • Ctrl+K/U/W：删至行尾/行首/前词
  • Ctrl+Y：粘回
  • Alt+B/F：按词移动

2.6 鼠标与滚动

滚轮上下翻（±3 行），PageUp/PageDown/Home/End 翻屏与跳转；上滚后底部显示「▲ 上方 N 行 · End 回到底部」。

框选复制：

• 左键拖拽框选（双击选词、三击选行）
• Cmd+C（kitty 系终端，保留选区）或 Ctrl+C（通用，复制后清选区）复制
• Esc 仅清选区
• 拖选本身不复制，需显式按键

折叠/展开：

• 单击可折叠 / 展开输出块
• Ctrl+O 全局展开 / 收起所有可折叠详情（长输出、diff、子任务树）

2.7 快捷键速查

2.8 自定义扩展：Skill / Command / Agent

把扩展放进 .comate/ 目录即可出现在 / 菜单（项目级 <仓库根>/.comate/ 或个人级 ~/.comate/）：

菜单里选中后先变成可编辑的青色 /name token，回车提交时才真正生效；删掉字符即取消。

同名条目自动去重，.comate 目录下的定义优先。

3. Headless 使用：脚本与 CI

一句话结论：comatecli run 是 Headless 模式的主入口 —— 一条命令完成一次（或多轮）AI 任务，stdout 出结果、stderr 出错误、退出码 0/1 可判定，天然适合管道、脚本与 CI。 周边还有 login/status/mode/model/update 等子命令，把「配置好再跑」的闭环补齐。

3.1 子命令总览

每个命令都支持 --help 查看详情。

3.2 comatecli run 详解

最小可用（--query、--activate-skill、--activate-command 至少给一个）：

1comatecli run -q "找出本仓库里所有 TODO 并按模块归类"

常用配方：

1# 指定模型与模式
2comatecli run -q "重构 src/utils 里的重复代码" -m "某模型显示名" --mode Agent
3
4# 多轮会话：继续当前目录最新会话 / 指定会话 ID
5comatecli run --continue -q "接着把单测也补上"
6comatecli run -c <conversationId> -q "第二轮问题"
7
8# 附件与能力激活
9comatecli run -q "看下这张报错截图" --attach-image ./shot.png
10comatecli run -q "评审这个文件" --attach-file src/app.ts --enable-codebase-search
11comatecli run --activate-skill deploy-check          # 直接跑一个 skill
12
13# 结构化输出（脚本解析）与流式输出
14comatecli run -q "总结变更" -d task-json | jq .
15comatecli run -q "长任务" -d delta-stream
16
17# 自动重试：最后一轮无文本产出/报错时补发「继续」，最多 3 次
18comatecli run -q "跑通全部单测" --retry 3 --retry-query "继续"
19
20# CI 示例：登录态检查 + 失败即挡门禁
21comatecli status || exit 1
22comatecli run -q "检查本次 diff 是否引入了明显缺陷，有则详细列出" || exit 1

Flag 全表（按用途分组）：

退出码约定：

• 0：成功
• 1：参数校验失败 / 鉴权失败 / 运行异常

错误信息走 stderr，正常输出走 stdout。

run 不带任何参数时只打印帮助，不会误发空请求。

3.3 Headless 鉴权的两种方式

3.4 mode / model 子命令

1# 模式管理
2comatecli mode              # 查看当前模式（未设显示默认 Agent）
3comatecli mode list         # Agent / Plan / Goal，当前项打 *
4comatecli mode set Plan
5
6# 模型管理
7comatecli model             # 查看当前模型（离线，只读本地配置）
8comatecli model list        # 联网列出可用模型名（--ids 附带模型 ID）
9comatecli model set auto            # auto 免联网即可设置
10comatecli model set "某模型显示名"    # 按名匹配（大小写不敏感），联网校验通过才落盘

3.5 update 升级

自动升级：TUI 启动后后台静默检查并安装，结果在下次启动的横幅提示（「 已更新到 vX」），不阻塞使用。

手动升级：

1comatecli update            # 前台安装，装完提示重启生效
2comatecli update --check    # 只检查：已最新退出码 0，有更新退出码 1（CI 友好）
3comatecli update --force    # 强制重装最新（含预发布）