DevCore CLI reference

Commands, selectors, and agent-friendly patterns for driving DevAgent from a shell.

The devcore CLI talks to a running DevAgent runtime. Use it when a shell script or agent needs to inspect worktrees, launch terminals, open files, automate the built-in browser, or report progress back into DevAgent.

Verify the runtime

Register the CLI under Settings -> Experimental -> CLI, then check that it can reach DevAgent:

command -v devcore
devcore status --json

If DevAgent is not already running:

devcore open --json
devcore status --json

Use --json when another tool will parse the result. Human-readable output is for quick terminal checks.

Selectors

Most commands accept selectors instead of requiring long IDs:

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 and current resolve to the enclosing DevAgent-managed worktree from the shell's current directory or terminal context. Use explicit selectors in scripts that may run outside the target worktree. For remote runtimes, prefer full server-side selectors such as id:<repoId>::<absolute-worktree-path> or path:<absolute-server-path> because the local shell's current directory may not exist on the runtime host.

Runtime commands

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

devcore serve starts a runtime server in the foreground without opening the desktop window. Use it for Remote DevAgent Servers or headless environments, and stop it with Ctrl-C.

Repos

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

Set the repo base ref before creating lots of worktrees so new tasks branch from the right place by default.

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

When worktree create runs from inside a DevAgent-managed worktree, DevAgent records the new worktree as a child when it can infer the relationship. Pass --parent-worktree active to be explicit, or --no-parent when the new work is independent.

Agent startup flags:

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 launches the selected agent in the first terminal. --prompt sends initial work to that agent. --setup run|skip|inherit controls repo setup hooks; inherit follows the repo policy.

Terminals

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 split --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

Omit --terminal to target the active terminal in the current worktree. Read before sending when you are not sure what the terminal is waiting for.

Terminal handles

Terminal handles are runtime-scoped. If DevAgent restarts or a command reports a stale terminal handle, run devcore terminal list --json and reacquire the handle.

For long output, use cursor reads. Save nextCursor from one read, then pass it back with --cursor to fetch only new output.

Files

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

Paths are relative to the selected worktree. open-changed reads git status and opens changed files in edit, diff, or both modes.

Built-in browser

Browser commands control DevAgent's embedded browser tab for the selected worktree. They do not control Chrome, Safari, or the DevAgent desktop UI.

Use a snapshot -> act -> snapshot loop:

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

Refs such as @e3 come from snapshot. Re-snapshot after navigation, tab switches, clicks that change the page, and any stale-ref error.

Tab and capture commands:

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

Use devcore exec --command "<agent-browser command>" --json only for browser actions that do not have a typed DevAgent command yet.

Browser device emulation:

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

Desktop computer use

Use devcore computer for native desktop apps outside the built-in browser:

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

See Computer use for the full workflow and permission setup.

Mobile emulator

The mobile emulator commands control iOS Simulator devices through DevAgent's worktree-scoped bridge. Use them instead of raw serve-sim or simctl when an agent is operating from inside DevAgent, so lifecycle and active-device state stay attached to the current 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

Coordinates are normalized from 0 to 1. Prefer tap for single taps, and use gesture for drags or multi-step touch input. Pass --device <udid-or-name> or --emulator <id> when a script must target a specific simulator instead of the worktree's active emulator.

Linear

The devcore linear surface is what agents use via the orca-linear skill (legacy install name linear-tickets still works). Prefer --json. Linked worktrees resolve with --current.

Read

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 expands comments, children, attachments, relations, and activity. Section flags (--comments, --children, --attachments, --relations, --activity) work individually.

MCP-style write

# Create or update (omit id/--current to create; requires --team and --title on create)
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 labels replace the full label set (Linear MCP save_issue semantics). Literal null clears assignee, estimate, due date, project, or parent.

Field helpers (still valid)

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

Run devcore linear --help or devcore skills get orca-linear for the version-matched list. Pass an explicit issue id (e.g. ENG-123) when a script may run outside a DevAgent-linked worktree.

Skills (local, no runtime required)

List bundled guides, print a version-matched guide, or install/update hybrid skill packages without the desktop Settings UI:

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 shell out to the same npx skills commands Settings uses. They do not contact the DevAgent runtime. See DevAgent skills.

Account (host-local runtime)

On a headless host running DevAgent (devcore serve or the desktop app), add managed Claude/Codex accounts when the remote client cannot use Add account (remote runtime scope disables that button):

devcore account list
devcore account add                 # Claude by default
devcore account add --agent codex

account add runs claude login / codex login in this terminal on the host, then registers the captured credentials with the local runtime. Codex uses device authorization so the browser can finish on another machine. Run these on the machine that owns the accounts — not through a client-only remote session.

Artifacts

Publish HTML or Markdown through the signed-in DevAgent account. Viewing a public link does not require sign-in; create/list/update/delete do. Publishing is off by default — a human must enable Settings → Artifacts → Allow publishing public artifact links on the device. There is no CLI flag that grants the gate. list, unshare, and delete stay available so you can audit or revoke links after turning publishing off.

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

• Accepted files: .html, .htm, .md, .markdown.
• share stores the edit token in the active DevAgent profile and does not print it. update / unshare resolve by the same local path and profile that originally shared the file.
• list is paged (nextCursor → --cursor). delete takes the artifact id from list and does not need the original file.
• Relative HTML assets are not uploaded — share self-contained HTML or absolute asset URLs.
• Denied publish/update fails with artifact_sharing_disabled; fix Settings instead of retrying.
• Desktop: open a local HTML or Markdown file and use Share as artifact, or manage links from the sidebar Artifacts page.

Automations, environments, and hooks

Scheduled prompts:

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

Remote runtime environments:

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

Agent status hooks:

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

Agent habits

• Prefer --json for automation and agent calls.
• Prefer selectors over parsing UI labels.
• Read terminal state before sending input unless the next input is obvious.
• Use worktree comments for progress checkpoints. See Worktree checkpoints.
• Use Orchestration for tracked multi-agent dispatches instead of ad hoc terminal prompts.