DevCore CLI 参考手册

从 shell 驱动 DevAgent 的命令、选择器以及对 agent 友好的模式。

devcore CLI 会与正在运行的 DevAgent 运行时通信。当 shell 脚本或 agent 需要检查 worktree、启动终端、打开文件、自动化内置浏览器或将进度回报到 DevAgent 中时使用它。

验证运行时

在 设置 -> Experimental -> CLI 下注册 CLI，然后检查它能否连接到 DevAgent：

command -v devcore
devcore status --json

如果 DevAgent 尚未运行：

devcore open --json
devcore status --json

当另一个工具将解析结果时，使用 --json。可读输出用于快速的终端检查。

选择器

大多数命令接受选择器，而不必使用冗长的 ID：

devcore repo show --repo id:<repoId> --json
devcore worktree show --worktree active --json
devcore worktree show --worktree path:/abs/path/to/worktree --json
devcore worktree show --worktree branch:feature-name --json
devcore worktree show --worktree issue:123 --json

active 和 current 会从 shell 的当前目录或终端上下文解析为其所在的、由 DevAgent 管理的 worktree。在可能于目标 worktree 之外运行的脚本中，使用显式选择器。对于远程运行时，优先使用完整的服务端选择器，例如 id:<repoId>::<absolute-worktree-path> 或 path:<absolute-server-path>，因为本地 shell 的当前目录在运行时主机上可能并不存在。

运行时命令

devcore open --json
devcore status --json
devcore serve --port 6768 --pairing-address 100.64.1.20 --json

devcore serve 会在前台启动一个运行时服务器，而不打开桌面窗口。将它用于 Remote DevAgent Servers 或无头环境，并用 Ctrl-C 停止它。

仓库

devcore repo list --json
devcore repo add --path /abs/path/to/repo --json
devcore repo show --repo id:<repoId> --json
devcore repo set-base-ref --repo id:<repoId> --ref origin/main --json
devcore repo search-refs --repo id:<repoId> --query main --limit 10 --json

在创建大量 worktree 之前设置 repo 的 base ref，这样新任务默认就会从正确的位置分支。

Worktrees

devcore worktree list --repo id:<repoId> --json
devcore worktree ps --json
devcore worktree current --json
devcore worktree show --worktree active --json
devcore worktree create --repo id:<repoId> --name fix-login --json
devcore worktree create --name child-task --agent codex --prompt "Investigate the flaky login test" --json
devcore worktree set --worktree active --comment "reproduced failure; testing token refresh fix" --json
devcore worktree rm --worktree id:<worktreeId> --force --json

当 worktree create 从一个由 DevAgent 管理的 worktree 内部运行时，DevAgent 会在能推断出关系的情况下将新 worktree 记录为子 worktree。传入 --parent-worktree active 以明确指定，或在新工作独立时传入 --no-parent。

Agent 启动 flag：

devcore worktree create --name review-api --agent claude --setup run --json
devcore worktree create --name quick-check --agent codex --prompt "Summarize the diff" --setup skip --json
devcore worktree create --name hidden-setup --setup inherit --json

--agent 会在第一个终端中启动所选的 agent。--prompt 向该 agent 发送初始工作。--setup run|skip|inherit 控制 repo 的 setup hook；inherit 遵循 repo 策略。

终端

devcore terminal list --worktree active --json
devcore terminal show --terminal <handle> --json
devcore terminal read --terminal <handle> --json
devcore terminal read --terminal <handle> --cursor <cursor> --limit 1000 --json
devcore terminal send --terminal <handle> --text "continue" --enter --json
devcore terminal wait --terminal <handle> --for tui-idle --timeout-ms 300000 --json
devcore terminal create --worktree active --title "tests" --command "npm test" --json
devcore terminal 拆分 --terminal <handle> --direction horizontal --command "npm run dev" --json
devcore terminal rename --terminal <handle> --title "runner" --json
devcore terminal switch --terminal <handle> --json
devcore terminal close --terminal <handle> --json

省略 --terminal 以定位当前 worktree 中的活动终端。当你不确定终端在等待什么时，先读取再发送。

Terminal handle

Terminal handle 的作用范围限定于运行时。如果 DevAgent 重启，或某个命令报告 terminal handle 已过期，运行 devcore terminal list --json 并重新获取 handle。

对于长输出，使用游标读取。保存一次读取返回的 nextCursor，然后用 --cursor 传回，仅获取新输出。

文件

devcore file open src/App.tsx --worktree active --json
devcore file diff src/App.tsx --staged --worktree active --json
devcore file open-changed --mode both --worktree active --json

路径相对于所选的 worktree。open-changed 读取 git status，并以 edit、diff 或两者模式打开变更过的文件。

内置浏览器

浏览器命令控制所选 worktree 的 DevAgent 内嵌浏览器 标签页。它们不控制 Chrome、Safari 或 DevAgent 桌面 UI。

使用 snapshot -> act -> snapshot 循环：

devcore goto --url http://localhost:3000 --worktree active --json
devcore snapshot --worktree active --json
devcore click --element @e3 --worktree active --json
devcore fill --element @e1 --value "[email protected]" --worktree active --json
devcore wait --text "Welcome" --worktree active --json
devcore screenshot --worktree active --json

诸如 @e3 的 ref 来自 snapshot。在导航、标签页 切换、改变页面的点击以及任何过期 ref 错误之后，重新 snapshot。

标签页 和捕获命令：

devcore tab list --worktree active --json
devcore tab create --url http://localhost:3000 --worktree active --json
devcore tab switch --index 1 --worktree active --json
devcore capture start --worktree active --json
devcore console --limit 50 --worktree active --json
devcore network --limit 50 --worktree active --json
devcore full-screenshot --worktree active --json
devcore pdf --worktree active --json

仅对尚无对应类型化 DevAgent 命令的浏览器操作，使用 devcore exec --command "<agent-browser command>" --json。

浏览器设备模拟：

devcore set device --name "iPhone 12" --worktree active --json
devcore screenshot --worktree active --json

桌面 computer use

对于内置浏览器之外的原生桌面应用，使用 devcore computer：

devcore computer permissions --json
devcore computer list-apps --json
devcore computer get-app-state --app com.apple.Safari --json
devcore computer click --app com.apple.Safari --element-index 12 --json
devcore computer paste-text --app com.apple.Safari --text "hello" --json

完整工作流和权限设置参见 Computer use。

移动端 emulator

移动 emulator 命令通过 DevAgent 的 worktree 范围桥接来控制 iOS Simulator 设备。当 agent 在 DevAgent 内部操作时，使用它们而非原始的 serve-sim 或 simctl，这样生命周期和活动设备状态就会与当前 worktree 保持关联。

devcore emulator list --worktree active --json
devcore emulator attach "<device-name-or-udid>" --worktree active --json
devcore emulator tap 0.5 0.7 --worktree active --json
devcore emulator type "hello" --worktree active --json
devcore emulator gesture '[{"type":"begin","x":0.5,"y":0.8},{"type":"move","x":0.5,"y":0.4},{"type":"end","x":0.5,"y":0.2}]' --worktree active --json
devcore emulator button home --worktree active --json
devcore emulator rotate landscape_left --worktree active --json
devcore emulator exec --command "tap 0.5 0.7" --worktree active --json
devcore emulator kill --worktree active --json
devcore emulator shutdown --worktree active --json

坐标从 0 到 1 归一化。单次点击优先使用 tap，拖拽或多步触摸输入使用 gesture。当脚本必须定位到某个特定 simulator 而非 worktree 的活动 emulator 时，传入 --device <udid-or-name> 或 --emulator <id>。

Linear

devcore linear 接口是 agent 通过 orca-linear skill（旧安装名 linear-tickets 仍可用）所使用的。优先使用 --json。已关联的 worktree 用 --current 解析。

读取

devcore linear issue --current --full --json
devcore linear issue ENG-123 --comments --children --relations --activity --json
devcore linear search "auth bug" --workspace all --json
devcore linear list --filter assigned --limit 10 --json
devcore linear list-issues --team ENG --state started --assignee me --json
devcore linear list-issues --query auth --updated-at -P7D --cursor <cursor> --workspace <id> --json
devcore linear team list --json
devcore linear team states --team ENG --json
devcore linear team labels --team ENG --json
devcore linear project list --query launch --json

--full 会展开 comment、子项、attachment、relation 和 activity。分节 flag（--comments、--children、--attachments、--relations、--activity）可单独使用。

MCP 风格写入

# 创建或更新（省略 id/--current 表示创建；创建时需要 --team 和 --title）
devcore linear save-issue --team ENG --title "Fix auth" --priority high --json
devcore linear save-issue ENG-123 --state "In Progress" --assignee me --json
devcore linear save-issue --current --project null --due-date null --json

devcore linear relation add ENG-1 --related ENG-2 --type blocks --json
devcore linear relation remove ENG-1 --related ENG-2 --type related --json

save-issue 的 label 会替换整个 label 集合（与 Linear MCP save_issue 语义一致）。字面量 null 会清除 assignee、estimate、due date、project 或 parent。

字段辅助命令（仍然有效）

devcore linear status set --current --to "In Progress" --json
devcore linear assignee set --current --me --json
devcore linear priority set ENG-123 --to high --json
devcore linear estimate set --current --to 3 --json
devcore linear due-date set --current --to 2026-08-01 --json
devcore linear label add --current --label backend --json
devcore linear comment add --current --body "Investigating regression" --json
devcore linear attach --current --url https://example.com/repro --title "Repro" --json
devcore linear create --title "Flaky login test" --team ENG --priority high --json

运行 devcore linear --help 或 devcore skills get orca-linear 以获取与版本匹配的列表。当脚本可能在未与 DevAgent 关联的 worktree 之外运行时，传入显式的 issue id（例如 ENG-123）。

Skills（本地，无需运行时）

列出捆绑的指南、打印与版本匹配的指南，或在不使用桌面 设置 UI 的情况下安装/更新混合 skill 包：

devcore skills list
devcore skills get orca-cli
devcore skills get orchestration --full
devcore skills install --skill orca-cli --skill orchestration
devcore skills install --all --dry-run
devcore skills update --all

install / update 会转而执行 设置 所用的同一套 npx skills 命令。它们不与 DevAgent 运行时通信。参见 DevAgent skills。

Account（主机本地运行时）

在运行 DevAgent 的无头主机上（devcore serve 或桌面应用），当远程客户端无法使用 Add account 时（远程运行时作用范围会禁用该按钮），添加受管的 Claude/Codex 账号：

devcore account list
devcore account add                 # 默认 Claude
devcore account add --agent codex

account add 会在主机上的这个终端里运行 claude login / codex login，然后将捕获到的凭据注册到本地运行时。Codex 使用设备授权，因此浏览器授权可以在另一台机器上完成。请在拥有这些账号的机器上运行它们——而不是通过仅客户端的远程会话。

Artifacts

通过已登录的 DevAgent 账号发布 HTML 或 Markdown。查看公开链接无需登录；创建/列出/更新/删除则需要。发布默认关闭——必须由人在设备上启用 设置 → Artifacts → Allow publishing public artifact links。没有任何 CLI flag 能授予该开关。list、unshare 和 delete 仍然可用，因此在关闭发布后你仍可审计或撤销链接。

devcore artifacts share ./report.html --json
devcore artifacts share ./notes.md --json
devcore artifacts update ./notes.md --json
devcore artifacts unshare ./notes.md --json
devcore artifacts list --json
devcore artifacts list --cursor <cursor> --json
devcore artifacts delete <id> --json

• 接受的文件：.html、.htm、.md、.markdown。
• share 会将编辑令牌存储在活动的 DevAgent profile 中，且不会打印它。update / unshare 通过最初分享该文件时相同的本地路径和 profile 来解析。
• list 是分页的（nextCursor → --cursor）。delete 取用 list 中的 artifact id，无需原始文件。
• 相对的 HTML 资源不会被上传——请分享自包含的 HTML 或使用绝对资源 URL。
• 被拒绝的发布/更新会以 artifact_sharing_disabled 失败；请修正 设置 而非重试。
• 桌面端：打开本地 HTML 或 Markdown 文件并使用 Share as artifact，或从侧栏的 Artifacts 页面管理链接。

自动化、环境与 hook

计划的 prompt：

devcore automations list --json
devcore automations create --name "Daily review" --trigger daily --time 09:00 --prompt "Review open changes" --provider codex --repo id:<repoId> --disabled --json
devcore automations run <automationId> --json

远程运行时环境：

devcore environment add --name work-laptop --pairing-code "devcore://pair?code=..." --json
devcore environment list --json
devcore environment rm --environment <selector> --json

Agent 状态 hook：

devcore agent hooks status --json
devcore agent hooks on --json
devcore agent hooks off --json

Agent 使用习惯

• 对于自动化和 agent 调用，优先使用 --json。
• 优先使用选择器，而非解析 UI 标签。
• 除非下一个输入显而易见，否则在发送输入前先读取终端状态。
• 使用 worktree comment 作为进度检查点。参见 Worktree checkpoints。
• 对于需要跟踪的多 agent dispatch，使用 Orchestration 而非临时的终端 prompt。