The d:spatch CLI is a standalone Rust binary that gives you full control over workspaces, agents, and the Docker engine from your terminal.

dspatch-cli <command> [options]

Standalone binary

The CLI is separate from the d:spatch desktop app, but can be used side by side.

Getting started

Before you can launch workspaces, authenticate and make sure Docker is ready:

# Authenticate (or use local-only mode)
dspatch-cli auth login
dspatch-cli auth anonymous   # no account required

# Check that Docker and the runtime image are good to go
dspatch-cli engine status
dspatch-cli engine build-runtime

Typical workflow

A common session looks like this — scaffold a config, register a template, create a workspace, and launch it:

# 1. Scaffold a workspace config in your project
dspatch-cli init --path ./my-project

# 2. Register an agent template
dspatch-cli template add ./my-agent
dspatch-cli template add https://github.com/user/agent.git --branch main

# 3. Edit your dspatch.workspace.yml, then validate it
dspatch-cli validate --path ./my-project/dspatch.workspace.yml

# 4. Create the workspace
dspatch-cli workspace create --path ./my-project/dspatch.workspace.yml

# 5. Launch it (blocks until Ctrl+C or terminal state)
dspatch-cli launch <workspace_id>

Monitoring a running workspace

While a workspace is running, you can inspect it from another terminal:

# Workspace status
dspatch-cli status <workspace_id>

# Stream agent logs in real time
dspatch-cli logs <run_id> --follow

# Filter to a single agent instance
dspatch-cli logs <run_id> --instance <instance_id>

# Watch agent messages
dspatch-cli messages <run_id> <instance_id> --follow

Responding to inquiries

Agents can raise inquiries when they need human input. You can list and respond to them directly from the CLI:

dspatch-cli inquiries list --pending
dspatch-cli inquiries respond <inquiry_id> "Use PostgreSQL for the database"

Scripting with JSON output

Most commands accept --json for machine-readable output, making it easy to integrate with scripts and tools like jq:

# List workspace names
dspatch-cli list --json | jq '.[].name'

# Check if the runtime image is built
dspatch-cli engine status --json | jq '.runtime_image'

# Get all pending inquiry IDs
dspatch-cli inquiries list --pending --json | jq '.[].id'

Exploring commands

The CLI is self-documenting. Use --help at any level to see available commands and options:

dspatch-cli --help
dspatch-cli workspace --help
dspatch-cli template add --help

Your First Workspace — step-by-step workspace setup
Workspaces — workspace concepts and YAML reference

CLI