Work from the terminal

The CLI uses your Devboxes account and organization. It can send work to another runner; you only need Docker and a running listener when this machine will execute tasks.

Sign in

Install the CLI, then approve terminal access in your browser:

devboxes login

Dashboard and CLI task writes require an owner or admin role.

Start a task

From a repository checkout:

devboxes dispatch --branch main https://github.com/your-team/your-repository/issues/123

The CLI tries to select a project from the checkout's Git origin. Use --project or --repo to make the choice explicit:

devboxes dispatch --repo your-team/your-repository --branch dev https://github.com/your-team/your-repository/issues/123

The repository must already be connected to a project. --project <id> takes precedence over --repo. The CLI defaults --branch to main, so specify the branch when your repository uses another target.

Use --model <provider/model> to select a model and --blueprint-version <id> for an exact blueprint version. Omitted blueprint selection uses the current Implement GitHub Issue default. A recognized GitHub issue URL or owner/repo#123 supplies its issue and destination-branch instructions. For free-form work, choose a blueprint version that accepts that task rather than assuming the issue workflow does.

Follow and continue a session

Dispatch returns an agentSessionId. Use that session ID for subsequent commands:

devboxes status <session-id>
devboxes result <session-id>
devboxes continue <session-id> "Add a test for embedded quotes as well."

status reads the current run once; it does not continuously follow the transcript. continue creates fresh execution in the existing session. Use the dashboard for the live transcript and diff.

Use JSON in scripts

Add --json to dispatch, continue, status, or result. Treat runStatus as execution status. terminal: true means the run has finished, which includes failure and cancellation.

result exits with status 1 when the run is not yet terminal. A script must still inspect runStatus, outcome, and errorMessage before reporting success. Use the exact returned IDs rather than parsing the human-readable terminal output.

Run a machine or expose MCP tools

See runners for connect, credential setup, and listen. See automation and MCP for devboxes mcp and its tool schemas.

Use devboxes <command> --help for the options supported by your installed version.