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

Claude Desktop 风格的配置：

json

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

可用工具：

模式	工具
本地 standalone	`list_sessions`、`read_chat`、`send_chat`、`approve`、`screenshot`、`git_status`
Mesh (`--repo-mesh`)	协调者范围的 `mesh_*` 工具集

选项：

标志	说明
`--mode <mode>`	MCP 传输模式：`local` 或 `ipc`
`--repo-mesh <mesh_id>`	以 mesh 模式启动（协调者范围工具）
`--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 代理
adhdev daemon                 # 先启动一次守护进程
adhdev launch gemini          # 启动 Gemini CLI 会话
adhdev launch claude          # 启动 Claude Code 会话
adhdev launch codex           # 启动 Codex CLI 会话
adhdev launch aider           # 启动 Aider 会话
adhdev launch cursor-cli      # 启动 Cursor CLI 会话
adhdev launch github-copilot-cli # 启动 GitHub Copilot CLI 会话
adhdev launch goose           # 启动 Goose CLI 会话
adhdev launch opencode        # 启动 OpenCode CLI 会话

选项：

标志	说明
`-w, --workspace <path>`	打开特定工作区/文件夹
`-n, --new-window`	在新窗口中打开

WARNING

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

历史命令

`adhdev history list <provider>`

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

bash

adhdev history list claude
adhdev history list hermes-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 hermes-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

当你明确想要高级的 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   # 跳过确认提示

此命令执行以下步骤：

停止正在运行的守护进程（如果有）
移除操作系统后台服务（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 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 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] ​

高级命令 ​

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]`

高级命令