CLI 命令

面向最终用户的 adhdev 命令行工具参考。

全局命令

`adhdev`

显示帮助和可用命令。

`adhdev setup`

交互式设置向导。把你的机器认证到 ADHDev Cloud。

bash

adhdev setup
# 打开浏览器进行设备认证
# 令牌存储在 ~/.adhdev/config.json 中

`adhdev daemon`

启动守护进程。连接到你的 IDE 和 ADHDev 服务器。

bash

adhdev daemon
# 在前台运行，按 Ctrl+C 停止

如果你想要仅本地的 standalone 服务器，请改用自托管文档：

`adhdev standalone`

启动自托管 standalone 服务器：本地仪表板 + 内嵌守护进程 + standalone session-host 命名空间。

bash

adhdev standalone
adhdev standalone --host 0.0.0.0
adhdev standalone --port 8080
adhdev standalone --token mysecret
adhdev standalone --no-open
adhdev standalone --dev

当你明确想要自托管/仅本地路径而非云端连接的守护进程流程时使用它。

重要行为：

除非你传入 --host，否则 standalone 默认保持仅 localhost
如果你在没有令牌认证或仪表板密码的情况下把它暴露在 0.0.0.0 上，standalone 会警告仪表板对你的局域网开放
standalone 默认使用自己的 session-host 命名空间，因此它不会与同一台机器上云端连接的守护进程争夺托管运行时

要了解更深入的自托管细节，请参见：

`adhdev daemon:status`

显示当前守护进程状态和本地健康信息。

bash

adhdev daemon:status
adhdev daemon:status --port 19222

此命令报告：

守护进程 PID 和日志路径
本地 IPC 可达性
可用时的 session-host 状态
当守护进程 IPC 不可用时的直接回退状态

`adhdev status`

显示当前机器的设置状态。

bash

adhdev status

当你想要对“这台机器是否已配置并已登录？”得到快速答案，而非守护进程/运行时诊断时使用它。

`adhdev mcp`

通过 stdio 启动 ADHDev MCP 服务器，让诸如 Claude Desktop 之类的 MCP 客户端可以检查和控制 ADHDev 会话。

bash

# 本地模式：与 localhost:3847 上的 standalone 守护进程通信
adhdev mcp
adhdev mcp --port 4000
adhdev mcp --password my-standalone-password

# Mesh 模式：通过守护进程 IPC 的协调者范围工具
adhdev mcp --mode ipc --repo-mesh mesh_abc123

# 被委派工作者模式（由守护进程启动，极简工具集）
adhdev mcp --mode ipc --worker

Claude Desktop 风格的配置：

json

{
  "mcpServers": {
    "adhdev": {
      "command": "adhdev",
      "args": ["mcp"]
    }
  }
}

可用工具（本地/mesh 模式）：list_daemons、list_sessions、launch_session、stop_session、check_pending、read_chat、read_chat_debug、send_chat、approve、git_status、git_log、git_diff、git_checkpoint、git_push、screenshot。Mesh 模式（--repo-mesh）还会额外暴露一个协调者范围的 mesh_* 工具集。--worker 模式只暴露被委派工作者所需的极简工具集。

选项：

标志	说明
`--mode <mode>`	MCP 传输模式：`local` 或 `ipc`
`--repo-mesh <mesh_id>`	以 mesh 模式启动（协调者范围工具）
`--worker`	被委派工作者模式 —— 只暴露极简的工作者工具集
`--port <n>`	本地模式的 standalone 守护进程端口（默认：`3847`）
`--password <pass>`	已配置时的 standalone 守护进程密码/令牌

启动命令

`adhdev launch [target]`

以启用 CDP 的方式启动或重新启动 IDE，或通过正在运行的守护进程启动一个 CLI 代理。

对于 CLI 提供方，普通启动默认是一个全新会话。恢复/复原只应在你明确选择一个已保存会话或有意使用托管运行时恢复时发生。

bash

# IDE
adhdev launch cursor          # 启动 Cursor（CDP 端口 9333）
adhdev launch antigravity     # 启动 Antigravity（CDP 端口 9335）
adhdev launch windsurf        # 启动 Windsurf（CDP 端口 9336）
adhdev launch vscode          # 启动 VS Code
adhdev launch kiro            # 启动 Kiro

# CLI 代理（8 个内置）
adhdev daemon                 # 先启动一次守护进程
adhdev launch claude          # 启动 Claude Code 会话
adhdev launch codex-cli       # 启动 Codex CLI 会话
adhdev launch cursor-cli      # 启动 Cursor CLI 会话
adhdev launch opencode        # 启动 OpenCode CLI 会话
adhdev launch antigravity-cli # 启动 Antigravity CLI 会话
adhdev launch grok-cli        # 启动 Grok CLI 会话
adhdev launch kimi            # 启动 Kimi 会话

选项：

标志	说明
`-w, --workspace <path>`	打开特定工作区/文件夹
`-n, --new-window`	在新窗口中打开
`-d, --dir <path>`	CLI 代理的工作目录（与 `-w` 不同，默认为当前目录）

WARNING

针对 IDE 的 adhdev launch 会关闭现有的 IDE 进程并以启用 CDP 的方式重新打开它。请先保存你的工作。

历史命令

`adhdev history list <provider>`

列出某个提供方已保存的提供方原生 CLI 历史。

bash

adhdev history list claude
adhdev history list codex-cli --json
adhdev history list codex-cli --limit 10 --offset 10
adhdev history list claude --resumable
adhdev history list claude --sort oldest
adhdev history list claude --sort messages
adhdev history list claude --text "reply with exactly" --workspace remote_vs --model gpt-5.4

当你的真实目标是以下情况时先使用它：

“我可以继续哪些对话？”
“我想要的上下文在哪个提供方历史里？”
“哪个已保存会话仍有可恢复的工作区？”

此命令读取已保存的历史元数据（providerSessionId、工作区、预览、消息数），而非 session-host 运行时记录。

有用的过滤器和排序模式：

--resumable → 只显示无需 --dir 即可立即恢复的条目
--text <text> → 按标题或预览子串过滤
--workspace <text> → 按工作区路径子串过滤
--model <text> → 按模型子串过滤
--sort recent → 最近活动优先（默认）
--sort oldest → 最早活动优先
--sort messages → 消息数最多优先

`adhdev history resume <provider> [historySessionId]`

恢复一个提供方原生的已保存历史会话。

bash

adhdev history resume claude 20260414_101931_38d017
adhdev history resume codex-cli 20260413_163128_d61494
adhdev history resume claude --dir /path/to/worktree   # 省略时以交互方式选择
adhdev history resume claude --resumable --sort messages
adhdev history resume claude --text "sonnet follow-up" --workspace remote_vs --model gpt-5.4

这是普通 CLI 使用的主要连续性路径。如果你想在同一个提供方对话中继续交谈，请优先选择它而非运行时 attach/recover。如果你省略 historySessionId，ADHDev 将：

在只有一个可恢复的已保存历史条目时自动选择它，或
在存在多个可恢复条目时打开一个交互式选择器。

交互式选择器控件：

--resumable → 隐藏仍需要 --dir 的条目
--text <text> → 按标题或预览子串过滤
--workspace <text> → 按工作区路径子串过滤
--model <text> → 按模型子串过滤
--sort recent|oldest|messages → 使用与 history list 相同的排序语义

如果已保存条目缺少工作区元数据，请显式传入 --dir。

运行时命令

`adhdev runtime list`

使用实时/恢复/非活动分组而非原始 session-host 诊断，列出托管运行时的恢复和诊断状态。

bash

adhdev runtime list
adhdev runtime list --all
adhdev runtime list --json

默认情况下，它把记录分组为：

实时运行时
恢复快照
当请求 --all 时的非活动记录

当你想回答以下问题时先使用它：

“现在实际处于实时的是什么？”
“我可以恢复什么？”
“哪条记录只是一个陈旧的快照？”

`adhdev runtime attach <runtimeTarget>`

把你当前的终端直接连接到一个实时托管运行时。

bash

adhdev runtime attach <runtimeTarget>
adhdev runtime attach <runtimeTarget> --read-only
adhdev runtime attach <runtimeTarget> --takeover

此命令只接受实时运行时。如果目标是恢复快照或非活动的已停止记录，它会快速失败并告诉你去恢复或重启，而不是假装该目标可连接。

`adhdev runtime open <runtimeTarget>`

为一个实时托管运行时打开一个 adhmux 工作区。

bash

adhdev runtime open <runtimeTarget>
adhdev runtime open <runtimeTarget> --read-only
adhdev runtime open <runtimeTarget> --workspace review-pane
adhdev runtime open <runtimeTarget> -n review-pane   # --workspace 的简写别名

当你明确想要高级的 mux/面板工作流时使用它。普通的终端连接和恢复流程仍应从 adhdev runtime attach、adhdev runtime recover 或 adhdev runtime restart 开始。

`adhdev runtime recover <runtimeTarget>`

恢复或复原一条托管运行时记录。

bash

adhdev runtime recover <runtimeTarget>
# 别名
adhdev runtime resume <runtimeTarget>

`adhdev runtime restart <runtimeTarget>`

重启一条托管运行时记录。

bash

adhdev runtime restart <runtimeTarget>

`adhdev runtime stop <runtimeTarget>`

停止一条托管运行时记录。

bash

adhdev runtime stop <runtimeTarget>

`adhdev runtime snapshot <runtimeTarget>`

打印一条托管运行时记录的最新终端快照。

bash

adhdev runtime snapshot <runtimeTarget>
adhdev runtime snapshot <runtimeTarget> --json

<runtimeTarget> 可以是会话 ID、运行时键、显示名称，或来自 adhdev runtime list 的唯一前缀。

这是托管运行时的恢复和诊断界面。当运行时进程本身在中断后需要恢复时使用它，而非作为继续提供方对话历史的常规方式。

对于最常见的两个运行时操作，还有顶层快捷方式：

bash

adhdev attach <runtimeTarget>
adhdev recover <runtimeTarget>
adhdev resume <runtimeTarget>

它们是 adhdev runtime attach 和 adhdev runtime recover 的直接快捷方式。

Session Host 命令

`adhdev daemon:session-host`

检查并控制本地 session host。

这是 adhdev runtime ... 背后的高级诊断和操作者控制界面。它被有意地从主 CLI 帮助中弱化，因为大多数用户应先从运行时界面开始。

bash

# 显示诊断快照
adhdev daemon:session-host

# 使用非默认的守护进程 IPC 端口
adhdev daemon:session-host --port 19222

# 打印原始诊断 JSON
adhdev daemon:session-host --json

# 重启一个托管运行时
adhdev daemon:session-host --session <sessionId> --restart

# 恢复一个运行时
adhdev daemon:session-host --session <sessionId> --resume

# 停止一个运行时
adhdev daemon:session-host --session <sessionId> --stop

# 发送一个信号
adhdev daemon:session-host --session <sessionId> --signal SIGINT

# 强制分离一个卡住的客户端
adhdev daemon:session-host --session <sessionId> --detach-client <clientId>

# 修剪同一提供方会话的陈旧重复运行时
adhdev daemon:session-host --prune-duplicates

# 强制获取写所有权
adhdev daemon:session-host --session <sessionId> --acquire-write <clientId> --owner-type user

# 释放写所有权
adhdev daemon:session-host --session <sessionId> --release-write <clientId>

当托管 CLI 会话卡住、断开连接或需要手动恢复时使用它。

托管运行时恢复是有意显式的。普通的守护进程启动不会自动重新打开托管 CLI 会话，除非你自己选择加入该行为。

选项：

标志	说明
`-p, --port <port>`	本地守护进程 IPC 端口
`--json`	打印 JSON 输出
`--limit <count>`	要包含的最近诊断条目数量
`--session <sessionId>`	目标运行时会话
`--restart`	重启目标运行时
`--resume`	恢复目标运行时
`--stop`	停止目标运行时
`--signal <signal>`	发送诸如 `SIGINT` 或 `SIGTERM` 之类的信号
`--detach-client <clientId>`	强制分离某个特定的已连接客户端
`--prune-duplicates`	移除陈旧的重复托管运行时
`--acquire-write <clientId>`	为某个客户端强制获取写所有权
`--release-write <clientId>`	释放某个客户端的写所有权
`--owner-type <type>`	`--acquire-write` 的所有者类型：`user` 或 `agent`

当 session-host 与守护进程状态看起来不同步、当某个运行时卡在 interrupted 状态，或当写所有权需要手动恢复时使用它。

服务管理

`adhdev service install`

把 ADHDev 守护进程注册为一个在登录时自动启动的操作系统后台服务。

bash

adhdev service install

平台	方法
macOS	LaunchAgent plist（`~/Library/LaunchAgents/dev.adhf.daemon.plist`）
Windows	启动文件夹中的 VBScript（隐藏控制台窗口）
Linux	无内置自动安装助手

守护进程在崩溃时会自动重启，但如果它干净地退出（例如当另一个实例已经在运行时），则不会进入重启循环。

`adhdev service uninstall`

移除操作系统后台服务。当前正在运行的守护进程不受影响 —— 请用 adhdev daemon:stop 单独停止它。

bash

adhdev service uninstall

`adhdev service status`

显示服务注册状态和实时守护进程健康状况（PID、运行时长、内存、日志大小）。

bash

adhdev service status
# ✓ Service is installed.
# ✓ Daemon running — PID 12723, uptime 2h 13m, 58 MB
# Logs: stdout 4.2 KB, stderr 0 B

`adhdev service logs`

实时查看守护进程服务日志（tail -f）。

bash

adhdev service logs             # 跟随 stdout 日志
adhdev service logs --err       # 跟随 stderr 日志
adhdev service logs -n 50       # 显示最后 50 行
adhdev service logs --clear     # 清空所有日志文件

`adhdev service restart`

通过操作系统服务重启守护进程。向当前进程发送 SIGTERM 并让服务管理器（launchd / Windows 启动）重新启动它。同时轮换超过 10 MB 的日志。

bash

adhdev service restart

账户与数据

`adhdev logout`

从 ADHDev 登出。清除认证凭据，但保留 IDE 和工作区设置。

bash

adhdev logout
adhdev logout -f   # 跳过确认提示

`adhdev reset`

重置 ADHDev 配置。在清除 ~/.adhdev/config.json 之前请求确认。

bash

adhdev reset

`adhdev uninstall`

从系统中完全移除 ADHDev。停止守护进程，移除操作系统后台服务，并删除 ~/.adhdev 中的所有数据。

bash

adhdev uninstall
adhdev uninstall -f   # 跳过确认提示
adhdev uninstall --dry-run   # 只打印将要删除的内容，不实际删除

此命令执行以下步骤：

停止正在运行的守护进程（如果有）
移除操作系统后台服务（LaunchAgent / Startup 脚本）
删除 ~/.adhdev/ —— 所有配置、认证令牌、日志和缓存数据
打印用 npm uninstall -g adhdev 收尾的说明

WARNING

此操作无法撤销。所有设置、凭据和已下载的提供方将被永久删除。如果你只想清除认证或配置，请使用 adhdev logout 或 adhdev reset。

版本与升级

`adhdev --version`

显示当前 ADHDev 版本。

`adhdev update`

把 ADHDev 升级到最新版本并重启守护进程。是 adhdev daemon:upgrade 的别名。

bash

adhdev update
adhdev update --no-restart   # 仅升级，跳过守护进程重启

adhdev update 和 adhdev daemon:upgrade 都还接受 --channel <channel> 标志，用于兼容旧的调用方式——由于发布渠道现在在构建时就已固定，该标志已被弃用，会被静默忽略。

`adhdev daemon:upgrade`

把守护进程升级到最新版本。

bash

adhdev daemon:upgrade
# 下载并安装最新版本

`adhdev daemon:api [mode]`

管理服务器 REST API 中继访问。默认禁用 —— 仪表板流量始终使用 P2P/本地 IPC。

bash

adhdev daemon:api           # 显示当前状态
adhdev daemon:api enable    # 允许服务器端 REST 代理路由
adhdev daemon:api disable   # 撤销服务器端 REST 代理路由

这只影响服务器 API 代理路由。无论此设置如何，仪表板命令/数据平面仍保持 P2P 优先。

配额命令

`adhdev quota <provider>`

显示某个 AI 编码代理的剩余套餐配额。antigravity/agy、codex、grok 和 kimi 会实时查询提供方自己的用量 API —— 无需安装任何东西。

bash

adhdev quota antigravity   # 别名：agy
adhdev quota codex
adhdev quota grok
adhdev quota kimi
adhdev quota claude         # 需要先运行 `adhdev quota claude:install`

Claude Code 仅通过其 statusLine 钩子暴露用量数字，因此读取它们意味着要用一个包装器占用那个槽位。这是可选启用的，绝不会自动完成：

bash

adhdev quota claude:install     # 别名：claude-install —— 包装你现有的 statusline
adhdev quota claude:uninstall   # 别名：claude-uninstall —— 恢复你原来的 statusline
adhdev quota claude:status      # 显示该包装器是否已设置

codex 和 kimi 没有 install/uninstall/status 子命令 —— 对于实时 API 查询没有什么需要设置的。

`adhdev quota refresh [providers...]`

要求正在运行的守护进程立即重新读取提供方配额，使仪表板和 mesh 路由立刻看到更新后的数字，而不是等待守护进程自己的缓存过期。

bash

adhdev quota refresh              # 刷新所有提供方
adhdev quota refresh codex kimi   # 刷新特定的提供方

一个当前正处于自己的 HTTP 429 冷却期内的提供方不会被重新探测（再次命中它会延长限流）；相反会报告其冷却解除的时间。claude 和 codex 是本地文件类提供方，没有冷却期，总是会重新读取。

配置命令

`adhdev config env set/unset/list`

持久化一个按守护进程范围生效的环境变量/功能开关覆盖，该覆盖会在重启和升级后仍然保留，并在下一次守护进程重启时生效（而非当前正在运行的进程）。

bash

adhdev config env set ADHDEV_WORKER_MCP on
adhdev config env unset ADHDEV_WORKER_MCP
adhdev config env list

这个界面仅用于功能开关 —— 看起来像密钥、令牌或凭据的键会被拒绝。显式设置的 process.env 值始终优先于持久化的覆盖。

诊断

`adhdev doctor`

诊断安装健康状况、原生依赖、CLI 解析和文件夹浏览访问权限。

bash

adhdev doctor

这项检查（除其他事项外）包括构建轨道、原生模块加载（例如 node-datachannel、sharp）、该安装是链接/开发模式还是普通的 npm 全局包、PATH 上的 CLI 二进制文件解析，以及对常见文件夹浏览根目录的读取权限。当守护进程或其原生依赖看起来有问题时，请先用这个命令，然后再提交 issue。

高级命令

诸如 adhdev provider ...、adhdev cdp ... 和 adhdev daemon --dev 之类的命令主要用于诊断、提供方工作或本地调试。这里有意把它们从常规用户工作流中排除。

CLI 命令 ​

全局命令 ​

adhdev ​

adhdev setup ​

adhdev daemon ​

adhdev standalone ​

adhdev daemon:status ​

adhdev status ​

adhdev mcp ​

启动命令 ​

adhdev launch [target] ​

历史命令 ​

adhdev history list <provider> ​

adhdev history resume <provider> [historySessionId] ​

运行时命令 ​

adhdev runtime list ​

adhdev runtime attach <runtimeTarget> ​

adhdev runtime open <runtimeTarget> ​

adhdev runtime recover <runtimeTarget> ​

adhdev runtime restart <runtimeTarget> ​

adhdev runtime stop <runtimeTarget> ​

adhdev runtime snapshot <runtimeTarget> ​

Session Host 命令 ​

adhdev daemon:session-host ​

服务管理 ​

adhdev service install ​

adhdev service uninstall ​

adhdev service status ​

adhdev service logs ​

adhdev service restart ​

账户与数据 ​

adhdev logout ​

adhdev reset ​

adhdev uninstall ​

版本与升级 ​

adhdev --version ​

adhdev update ​

adhdev daemon:upgrade ​

adhdev daemon:api [mode] ​

配额命令 ​

adhdev quota <provider> ​

adhdev quota refresh [providers...] ​

配置命令 ​

adhdev config env set/unset/list ​

诊断 ​

adhdev doctor ​

高级命令 ​

CLI 命令

全局命令

`adhdev`

`adhdev setup`

`adhdev daemon`

`adhdev standalone`

`adhdev daemon:status`

`adhdev status`

`adhdev mcp`

启动命令

`adhdev launch [target]`

历史命令

`adhdev history list <provider>`

`adhdev history resume <provider> [historySessionId]`

运行时命令

`adhdev runtime list`

`adhdev runtime attach <runtimeTarget>`

`adhdev runtime open <runtimeTarget>`

`adhdev runtime recover <runtimeTarget>`

`adhdev runtime restart <runtimeTarget>`

`adhdev runtime stop <runtimeTarget>`

`adhdev runtime snapshot <runtimeTarget>`

Session Host 命令

`adhdev daemon:session-host`

服务管理

`adhdev service install`

`adhdev service uninstall`

`adhdev service status`

`adhdev service logs`

`adhdev service restart`

账户与数据

`adhdev logout`

`adhdev reset`

`adhdev uninstall`

版本与升级

`adhdev --version`

`adhdev update`

`adhdev daemon:upgrade`

`adhdev daemon:api [mode]`

配额命令

`adhdev quota <provider>`

`adhdev quota refresh [providers...]`

配置命令

`adhdev config env set/unset/list`

诊断

`adhdev doctor`

高级命令