CLI 命令行参考手册
Ante 可以作为交互式 TUI 终端、单次无头命令行任务、长寿命协议服务端或消息渠道网关运行。
ante [OPTIONS] [COMMAND]
命令总览
| 命令 | 说明 |
|---|---|
ante | 启动交互式 TUI 终端。若提供了 -p / --prompt，则以无头模式运行。 |
ante auth | 登录、存储 API 密钥并管理已存储的凭据，无需启动会话。 |
ante usage | 查询 Claude Code 与 Codex 订阅配额，无需启动会话。 |
ante serve | 运行长寿命的协议服务端，支持 stdio、Unix 套接字或 WebSocket。 |
ante gateway | 运行接入 Slack / Discord 的消息网关。 |
ante update | 检查最新版本的 Ante 并自动安装。 |
ante offline | 管理离线模式使用的本地推理引擎。 |
ante rage | 收集脱敏后的排错诊断归档包（日志 + 环境信息），便于提交 Issue。 |
ante catalog | 以 JSON 格式打印当前生效的提供商与模型目录。 |
ante doctor | 执行启动自检并输出各启动阶段的耗时与健康报告。 |
ante <name> | 运行外部 ante-<name> 应用。 |
ante 主命令
ante [OPTIONS]
不带 --prompt 时，Ante 启动交互式 TUI。传入 --prompt 时，Ante 执行单次无头任务后退出。
TUI 要求 stdout 连接到系统终端。若重定向或通过管道输出（如 ante > log.txt），Ante 会在启动时直接拒绝并提示使用无头模式，而非在后续查询游标位置时异常退出。
| 参数标识 | 说明 |
|---|---|
-m, --model <MODEL> | 覆盖默认模型名称。 |
--provider <PROVIDER> | 覆盖使用的 API 模型提供商标识。 |
--profile <NAME> | 在整个进程中使用现有的 ~/.ante/<name>.settings.json 替代 settings.json；可置于任意子命令前后，环境变量 ANTE_PROFILE 等效。未知名称会警告并回退到 settings.json。内置 bare Profile 会禁用技能、MCP 服务器、会话持久化、自动记忆及环境感知 UI 功能。 |
--effort <LEVEL> | 覆盖本次运行模型的思考深度等级：min、low、medium、high、xhigh 或 max。 |
--yolo | 跳过本次会话的所有工具审批确认提示。 |
--fullscreen | 仅在本次运行中使用全屏 TUI 聊天：进入备用屏幕并由 Ante 管理滚动历史。不会持久化 render_mode 设置，在无头模式中忽略。 |
--permission-mode <MODE> | 覆盖本次运行的权限模式：strict、auto 或 yolo。与 --yolo 互斥。无头运行会遵循该覆盖，并立即拒绝需要交互审批的调用。 |
--system-prompt <PROMPT> | 完全替换默认的系统提示词。与 --system-prompt-file 互斥。持久化默认值请配置 system_prompt 设置。 |
--system-prompt-file <PATH> | 从 UTF-8 文件中读取替换的系统提示词。与 --system-prompt 互斥。 |
--append-system-prompt <TEXT> | 向默认系统提示词末尾追加内容。持久化默认值请配置 append_system_prompt 设置。 |
--short-prompt | 本次运行使用更短的内置工具描述；系统指令已经精简，保持不变。持久化请配置 short_prompt 设置。 |
--skills | 强制加载技能系统，覆盖配置项。与 --no-skills 互斥。 |
--no-skills | 跳过技能发现，覆盖配置项。不会向模型声明技能，也不提供斜杠命令。 |
--include-skills <SKILLS> | 为本次会话添加精确匹配的技能名称，并替换 include_skills 设置。可传入逗号分隔值或重复使用参数；--no-skills 或 "skills": false 生效时不会重新启用技能。 |
--exclude-skills <SKILLS> | 从本次会话移除精确匹配的技能名称，并替换 exclude_skills 设置。可传入逗号分隔值或重复使用参数；排除优先于包含。 |
--enable-auto-memory | 强制启用自动记忆，覆盖配置项。与 --disable-auto-memory 互斥。 |
--disable-auto-memory | 强制禁用自动记忆，覆盖配置项。与 --enable-auto-memory 互斥。 |
--tools <TOOLS> | 用这些工具精确替换默认工具集。每次传入逗号分隔的值，也可重复使用参数；空格分隔列表会报错。覆盖 tools 配置。旧参数名 --allowed-tools 已移除。 |
--include-tools <TOOLS> | 在默认工具集或 --tools 基础集之上添加工具。每次传入逗号分隔的值，也可重复使用参数。 |
--exclude-tools <TOOLS> | 在 --tools 与 --include-tools 处理后移除工具。每次传入逗号分隔的值，也可重复使用参数。已弃用的别名 --disallowed-tools 仍可使用。 |
--output-format <FORMAT> | 无头模式输出格式：json、human 或 minimal（默认）。 |
-p, --prompt <PROMPT> | 无头模式下执行的任务提示词。支持标准输入管道。 |
--draft <TEXT> | 启动交互式 TUI 时，将文字放入输入框供编辑，不自动发送。可搭配 --resume <SESSION_ID>；与 -p / --prompt 互斥。 |
--check | 在无头任务完成后自动执行一轮自我验证检查。 |
-r, --resume [SESSION_ID] | 按 ID 恢复会话；省略 ID 时直接打开当前目录的交互式会话选择器。无头模式必须提供 ID。 |
--session-save | 保存会话记录与可恢复快照，覆盖配置项。与 --no-session-save 互斥。 |
--no-session-save | 不保存会话记录与快照，覆盖配置项。与 --resume 互斥。 |
--offline-model [MODEL] | 为 TUI 或无头运行启动本地引擎。接受 GGUF 路径、已发现的文件名或验证模型名称/URL；省略值则启动 ante offline use 保存的默认模型。与 --model、--provider 互斥。 |
-h, --help | 打印帮助信息。 |
-V, --version | 打印 Ante 版本号。 |
使用示例
ante
ante -p "explain what this project does"
git diff | ante -p "review this diff for bugs"
ante --provider openai --model gpt-6.1-sol -p "refactor the database module"
ante --effort max -p "find the race condition in the scheduler"
ante --draft "Review the authentication changes"
ante --profile work
ante --profile bare -p "review this repository"
ante --resume ses_01ARZ3NDEKTSV4RRFFQ69G5FAV -p "now add tests"
ante -p "summarize this repo" --enable-auto-memory
恢复会话时，已保存的系统提示词和提示词模式优先于 --system-prompt、--system-prompt-file、--append-system-prompt 与 --short-prompt。这些参数只作用于本次启动中的全新会话，包括稍后通过 /clear 创建的会话。
自 v0.3.1 起，--resume 也会应用 --tools、--include-tools 和 --exclude-tools。省略 --tools 时，基础集合来自当前 tools 设置或默认工具集，不会从已保存的对话中恢复。示例请参阅恢复无头会话。
ante auth
ante auth list [--json]
ante auth login <NAME> [--no-browser]
ante auth logout <NAME>
ante auth add <NAME>
ante auth rm <REFERENCE>
在不启动会话的情况下管理 Ante 存储的凭据。NAME 为提供商、OAuth Profile 或 MCP 服务器名称，可附加 /label 以区分第二个账号（如 anthropic/work）。
| 命令 | 说明 |
|---|---|
list | 列出已存储的凭据：类型、签发方、账号、状态（set、valid、expired、invalid、unreadable），以及使用该凭据的提供商。 |
login <NAME> | 通过浏览器登录。NAME 可以是 OAuth Profile（anthropic、openai、antix 或你在 oauth_profiles 中定义的条目）、通过 OAuth 登录的提供商（anthropic-subscription），或远程 MCP 服务器。再次运行会重新登录。 |
logout <NAME> | 清除登录状态。 |
add <NAME> | 存储 API 密钥，从 stdin 读取（在终端中会提示输入）。若 NAME 为提供商，Ante 会先向该提供商校验密钥，被拒绝的密钥不会存储。 |
rm <REFERENCE> | 删除已存储的凭据：密钥（NAME 或 secret:NAME）、登录（oauth:NAME），或 helper 的缓存输出（helper:NAME，使该 helper 立即重新运行）。 |
| 参数标识 | 说明 |
|---|---|
--json | 仅用于 list：输出一个包含 credentials 数组的 JSON 对象，不含密钥或令牌值。自 v0.3.1 起可用。 |
--no-browser | 仅用于 login：打印授权 URL 而非自动拉起浏览器，适用于远程机器。 |
-h, --help | 打印帮助信息。 |
使用示例
ante auth login antix
ante auth login anthropic/work --no-browser
ante auth login linear # an MCP server in mcp_servers
echo "$TOGETHER_API_KEY" | ante auth add together
ante auth rm oauth:anthropic/work
ante auth list
凭据以仅所有者可读的文件形式存储在 ~/.ante/auth/ 下。提供商如何引用这些凭据，请参阅凭据。
JSON 凭据清单
ante auth list --json 返回 {"credentials": [...]}。每个条目包含 reference、kind（secret、oauth 或 helper）、name、issuer、account、state 和 used_by（提供商 ID 列表）。issuer 与 account 可以为 null；没有已存储凭据时返回 {"credentials": []}。环境变量不是已存储凭据，因此不会列出。
ante auth list --json | jq '.credentials[] | {reference, state, used_by}'
协议客户端可将 reference 原样作为 StartSession 或 ResumeSession 的 credential，在首次请求之前选定账户。请传递引用，不要传递密钥或令牌本身。
ante usage
ante usage [NAME] [--json]
自 v0.3.2 起可用。查询已存储的 Claude Code（anthropic）与 Codex（openai）OAuth 账户的订阅配额使用百分比和重置时间。不传 NAME 时检查所有受支持的已存储登录，包括带标签的账户。这里报告的是提供商订阅额度；会话 Token 总量仍在 TUI 的 /usage 对话框中查看，不包含 API 密钥账单。
NAME 必须是完整匹配的已存储登录名称，例如 openai/work，不带 oauth: 前缀。未知或不受支持的名称会报错，不会改选其他账户。使用 ante auth list 可查看已存储名称。
ante usage
ante usage anthropic
ante usage openai/work --json
--json 输出一个包含 subscriptions 数组的对象。每个账户都有 credential（已存储名称）、provider（稳定的 OAuth Profile ID：anthropic 或 openai）、email、plan 和 status。email 与 plan 可以为 null。
ready包含windows，每个窗口有label、used_percent和resets_at（UTC 时间戳或null）。空窗口列表表示提供商未报告额度限制。expired表示需要运行ante auth login <NAME>重新登录。unavailable包含reason，说明无法读取配额的原因。
若任一选定账户已过期或不可用，命令会先打印完整报告，再以状态码 1 退出。没有受支持的已存储登录时，命令会成功退出：JSON 模式返回 {"subscriptions": []}，文本模式显示登录提示。必须有账户的脚本还应检查列表是否为空。
ante serve
ante serve [OPTIONS]
服务模式默认在 stdin/stdout 上暴露 Ante 协议；传入 --sock 时通过 Unix 域套接字提供服务，传入 --ws 时通过 WebSocket 提供服务。
| 参数标识 | 说明 |
|---|---|
--stdio | 通过 stdin/stdout 提供 JSONL 协议服务（默认传输方式）。三个传输方式参数互斥。 |
--sock [PATH] | 通过 Unix 域套接字提供服务。未指定路径时默认为 Ante 主目录下的 run/serve.sock。 |
--ws <ADDR> | 在给定的本地回环地址上通过 WebSocket 提供服务。 |
--offline-model [MODEL] | 启动时加载本地或验证模型；接受与普通运行相同的模型引用。省略值则加载已保存的默认模型。 |
-h, --help | 打印帮助信息。 |
serve 是会话无关的守护进程，因此不接收会话级参数（--model、--provider、--yolo、--system-prompt、--tools 等）。接入的客户端会通过协议在每个会话中独立配置这些参数。
--ws 要求设置非空的 ANTE_SERVE_TOKEN，且仅接受本地回环地址（127.0.0.0/8、::1）。客户端必须在 WebSocket 升级请求中发送 Authorization: Bearer <token>；缺少或错误的令牌会返回 HTTP 401，握手超时为 10 秒。非回环地址（如 0.0.0.0:8080）会在绑定前被拒绝。远程连接请使用 SSH 隧道，或提供 TLS（wss://）与身份验证的反向代理。
同一时刻只有一个宿主拥有某个套接字路径。--sock 会在套接字旁的 .lock 文件上获取排他锁，因此同一路径上的第二个 ante serve --sock 会拒绝启动，并保持正在运行的宿主的套接字不受影响。崩溃遗留的套接字文件不持有锁，会在下次启动时被替换。
每个客户端连接驱动各自的会话。某个客户端的 Shutdown 只结束该连接 —— 宿主继续监听，并在收到 SIGINT 或 SIGTERM 时退出。
使用示例
ante serve
ante serve --sock # ~/.ante/run/serve.sock
ante serve --sock /tmp/ante.sock
ANTE_SERVE_TOKEN="your-secret-token" ante serve --ws 127.0.0.1:8080
ante gateway
ante gateway [OPTIONS]
从 v0.2.2 起，此命令分派给单独安装的 ante-gateway 程序，后续参数原样传递。它通过 SDK 连接 Ante 宿主，并按 channels 配置接入 Slack 和 Discord。安装方法参阅网关模式；未安装时以状态码 127 退出。
| 参数标识 | 默认值 | 说明 |
|---|---|---|
--config <PATH> | ~/.ante/channels.json | 渠道配置文件的路径。 |
--connect <ENDPOINT> | unix:~/.ante/run/serve.sock | Ante 宿主端点：unix:<path>、ws://<addr>、wss://<addr> 或 stdio。通过 ante serve --sock 启动宿主。 |
--model <MODEL> | — | 请求的模型（未指定时使用宿主设置）。 |
--provider <PROVIDER> | — | 请求的提供商（未指定时由宿主解析）。 |
--output-format <FORMAT> | minimal | 网关 stdout 输出格式：json、human 或 minimal。 |
-h, --help | - | 打印帮助信息。 |
使用示例
ante gateway
ante gateway --connect unix:/tmp/ante.sock
ante gateway --provider anthropic --model claude-sonnet-5-5
ante gateway --config ./channels.json --output-format human
ante update
ante update [OPTIONS] [CHANNEL]
检查更新并自动安装新版本。无参数时跟踪 ~/.ante/settings.json 中配置的通道（默认 stable）。传入通道名（位置参数或 --channel）仅覆盖本次更新。
| 位置参数 | 说明 |
|---|---|
[CHANNEL] | 更新追踪的发布通道（stable 或 nightly）。latest 为 stable 的历史兼容别名。与 --channel 和 --version 互斥。 |
| 参数标识 | 说明 |
|---|---|
--channel <CHANNEL> | 更新追踪的发布通道。等同于位置参数形式。 |
--version <VERSION> | 安装指定的具体发布版本而非通道最新版。支持带或不带前缀 v（如 v0.3.2 或 0.3.2）。与通道参数互斥。 |
-h, --help | 打印帮助信息。 |
使用示例
ante update
ante update nightly
ante update --channel stable
ante update --version v0.3.2
ante offline
ante offline <COMMAND>
管理离线模式使用的引擎、模型及已保存的加载偏好，无需启动会话。
| 子命令 | 说明 |
|---|---|
install | 下载并安装 Ante 固定版本的 llama.cpp 运行时。已是当前版本时不做修改，否则替换不匹配或未记录版本的安装。 |
status [--json] | 显示引擎版本与路径、模型目录、默认模型、托管路由器、其他本地服务及可用内存。 |
list [--json] | 列出本地 GGUF 与验证模型，包含大小、最大上下文、内存适配估算和默认标记。JSON 中的 reference 可直接传给 use 或 --offline-model。 |
use <MODEL> [OPTIONS] | 保存默认模型及指定的加载偏好，不启动引擎或下载模型。每次都会输出 Loads with: 配置摘要。 |
stop | 停止当前 Ante 主目录的托管路由器，包括之前选择保留的进程或其他会话正在使用的进程；所有共享该路由器的会话都会受影响。 |
MODEL 接受 GGUF 路径、已发现的文件名或验证模型名称/URL（见 ante offline list）。裸 --offline-model 使用 use 保存的默认模型；尚未设置时会报错并提示先设置默认值。验证模型在首次加载时下载，use 本身不下载。
use 的加载选项（v0.2.12）：
| 选项 | 说明 |
|---|---|
--context <TOKENS> | 上下文窗口，从 8192 到模型支持的最大值。 |
--thinking on / --thinking off | 开启或关闭思考。 |
--temperature <T> | 采样温度，范围 0–2；传入 default 清除已保存的覆盖值。 |
--args "<OPTIONS>" | 替换额外 llama.cpp 选项；支持 Shell 风格引号。传入 --args "" 清除。 |
每个选项只替换自己的保存值，其余偏好保留。保存前会检查上下文与温度选项的取值范围。额外参数只进行基本语法检查，并拒绝保留或已移除的选项；其他错误可能到加载模型时才出现。偏好适用于后续 TUI、无头及 serve 加载；完整说明见模型偏好。
使用示例
ante offline install
ante offline status
ante offline list --json
ante offline use Qwen3.5-9B --context 32768 --thinking off --temperature 0.7
ante --offline-model
ante --offline-model -p "Explain this code"
ante serve --sock --offline-model
ante rage
ante rage [OPTIONS]
发生故障时，ante rage 会收集排查所需的上下文信息并打包为一个脱敏归档，便于附加到 GitHub Issue。默认生成 ./ante-rage-<timestamp>.tar.gz 并打印简要总结。不会自动上传任何数据 —— 归档始终保存在本地。
使用 --no-compress 时，完整报告写入 ./ante-rage-<timestamp> 目录，或 --output 指定的精确路径。两种格式均拒绝覆盖已有输出，且父目录必须已经存在。压缩失败时，会在归档路径后追加 .uncompressed，将报告保存为该目录。
所有敏感信息在写入前均会脱敏处理。API 密钥和 OAuth Token 仅记录存在状态（<SET> / <UNSET>），URL 中的凭据被掩码，对话记录与系统提示词被排除，且 ~/.ante/auth/*.json 与 channels.json 绝不会被打包。
归档包含：
| 文件 | 内容说明 |
|---|---|
report.md | Ante 版本、操作系统架构、Shell、Git 分支、解析的模型/提供商、认证状态表、遥测安装 ID 及脱敏说明。 |
env.txt | 相关的环境变量。安全值原样显示；敏感密钥显示为 <SET> / <UNSET>。 |
settings.redacted.json | 移除敏感信息后的 ~/.ante/settings.json（剥离 MCP 凭证和自定义提示词）。 |
catalog.redacted.json | 移除敏感信息后的 ~/.ante/catalog.json（存在自定义目录时包含）。 |
logs/ | 最近的应用程序与崩溃日志（过滤剥离 DEBUG/TRACE，避免请求体进入归档）。 |
当收集目录适用某个项目设置文件时，其 .ante/settings.json 也会一并收录，脱敏方式与用户设置文件相同 —— 使问题报告能反映实际生效的配置。
默认收集最新的日志文件（最多 10 个文件或 10 MB，崩溃日志优先）。使用 --since 可指定时间窗口。
| 参数标识 | 说明 |
|---|---|
--output <PATH> | 精确输出路径：默认写入归档，配合 --no-compress 则写入报告目录。默认路径分别为 ./ante-rage-<timestamp>.tar.gz 与 ./ante-rage-<timestamp>。 |
--no-compress | 将完整报告写入目录，而非生成 .tar.gz。 |
--verbose-logs | 同时包含 DEBUG/TRACE 日志行（对话记录与系统提示词仍被排除）。 |
--since <DURATION> | 收集指定时间窗口内的所有日志，忽略文件数量与大小限制（如 7d、48h、90m、2）。 |
-h, --help | 打印帮助信息。 |
使用示例
ante rage
ante rage --output ./ante-bug.tar.gz
ante rage --since 7d
ante rage --no-compress
ante catalog
ante catalog
将合并后的提供商目录（内置预设加上 ~/.ante/catalog.json）以 JSON 格式打印到 stdout（包含单个 providers 数组）。每个提供商内嵌了应用了用户模型覆盖后的推荐模型列表。警告信息输出至 stderr，因此 stdout 保持干净的 JSON 文档，可直接通过管道传给 jq。
使用示例
ante catalog
ante catalog | jq '.providers[].id'
ante doctor
ante doctor
启动与真实运行相同的运行时 —— 加载合并目录、初始化守护进程会话并渲染首帧 TUI —— 随后打印各阶段耗时的就绪报告。用于确认 Ante 是否安装配置正确，或作为 CI 冒烟测试。
无需 TTY 和 API 密钥：跳过 MCP 预热，直接基于目录进入就绪状态。报告包含五项检查 —— home（Ante 目录与输入历史可写性）、project（适用于当前目录的项目设置文件，或提示未找到）、catalog（提供商/模型计数）、session（解析的提供商/模型）以及 first frame（无头渲染），最后输出总耗时。警告（例如未认证的提供商、被跳过的目录条目、settings.json 解析提示，或项目设置文件中被丢弃的键）列在表格下方。若任何硬性检查失败（如目录不可写），doctor 会返回非零退出码。
使用示例
ante doctor
ante doctor || echo "ante is not healthy"
外部应用
无法识别的命令名称会自动派发给名为 ante-<name> 的可执行文件，遵循与 git 子命令相同的约定：
# 运行 ~/.ante/bin/ante-deploy 或 PATH 上的 ante-deploy
ante deploy --target production
Ante 会优先在 ~/.ante/bin 中查找，若未找到则在 PATH 中搜索；当 ~/.cargo/bin 未包含在 PATH 中时，还会回退在 ~/.cargo/bin 中查找。剩余参数原样传递，并镜像应用程序的退出状态。内置子命令始终具有最高优先级，因此外部可执行文件无法覆盖 ante update 或其他内置命令。如果找不到可执行文件，Ante 会返回退出状态 127，并针对可能的输入错误提供名称相似的内置命令建议。
外部应用会接收到 ANTE（Ante 二进制文件的绝对路径）、ANTE_APP（解析出的应用名称）以及当前激活时的 ANTE_PROFILE 环境变量。与帮助信息和用法错误相同，派发逻辑在 Ante 启动运行时、日志记录、遥测或崩溃处理机制之前执行。
输出格式
| 格式 | 说明 |
|---|---|
minimal | 仅输出智能体回复消息、通知信息与错误。 |
human | 以人类易读的格式和 ANSI 终端彩色展示所有事件。 |
json | 逐行输出 JSON Lines 事件对象，供程序解析。 |