[riglar]

What

The first dcd device commands from the Agent Devices plan (dcd docs/device-v1-plan.md, stages 3.1 and 3.2):

dcd device start --platform ios|android [--model] [--os] [--google-play] [--app <path|url>]
                 [--app-binary-id] [--locale] [--name] [--ttl] [--no-record] [--wait]
dcd device list [--all]
dcd device status [id]
dcd device stop [id] | --all
dcd device install [id] <path|url> | --app-binary-id
dcd device launch [id] [bundle-id|package] [--clear-state]
dcd device models [--platform]

They call the new /device/sessions API.

Rules that apply to every command

• --json prints one object, { ok, session, data, error }, on success and on failure. error is { code, message }, where code is the API's machine code (LIVE_NOT_FOUND, LIVE_SPEND_CAP, …) or null.
• Exit codes: 0 ok, 1 usage error, 2 command failed, 3 limit hit, 4 session ended or not found.
• Default session: the id can be left out when exactly one session is open. With none or several, the command exits 1 and lists the candidates.
• No spinners when not at a terminal. Progress lines go to stderr, so stdout carries only the result.
• x-dcd-source: cli is sent on every call, so the session timeline shows where a command came from.

Notes

• start --app ./build.app uploads the build first, using the same upload code as dcd upload. An https URL is passed to the API's install-from-URL instead.
• install and launch take one or two positionals. With one, a URL, a file or a build extension is read as the app, and a bundle id (it has a dot) as the app id.
• There is no --idle-timeout: the idle timeout is fixed at 5 minutes.
• The plan said to reuse src/utils/envelope.ts, but that file is the binary encryption envelope. The JSON envelope is in a new src/utils/device-output.ts.
• dcd device is hidden from dcd --help until the API is in production. The /device/sessions routes are only on dcd's feature/agent-devices branch so far. Plan Phase 8 unhides it.

Next

Stacked PRs will follow: inspect, screenshot, run, logs and open (3.3), the dcd live alias (3.4), artifacts (5.3) and the dcd mcp bridge (4.4).

Tests

test/unit/device-command.test.ts (17 tests) covers the exit-code mapping, the default-session rule, the envelope on success and failure, the request bodies, and the positional heuristics. pnpm lint, pnpm typecheck, pnpm test:unit (372 passing) and pnpm build pass.

🤖 Generated with Claude Code

https://claude.ai/code/session_018tQfgpTsA9UhcopKoDezUA

[claude]

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

🤖 Generated with Claude Code