CLI Reference

Applies to: Dispatch v1.0.0, last verified 2026-04-05

The Dispatch CLI (cli.js) talks to the running server API. You need the server running before executing CLI commands.

Commands

Add a project

node cli.js add /path/to/project --name "Project Name"

The path must exist on disk. Dispatch validates it and saves the registration to ~/.dispatch/config.json. You can register multiple projects.

List registered projects

node cli.js list

Remove a project

node cli.js remove "Project Name"

Configuration file

All registrations are stored in ~/.dispatch/config.json:

{
  "projects": [
    { "name": "My Project", "path": "/absolute/path/to/project" }
  ],
  "onboarded": false
}

You can inspect and edit this file directly. The server reads it on startup.

Managing projects from the dashboard

If you prefer not to use the CLI, the Project Manager in the dashboard provides the same functionality:

• Click + Project in the header (or the Projects section in the sidebar)
• Browse workspace tab: scans a directory for git repos; toggle the button next to any repo to add or remove it
• Add manually tab: enter a name and absolute path directly

Starting agents

Dispatch supports four CLI agent providers. Each has its own binary and invocation pattern.

Supported CLI binaries

Provider	Binary	Spawn support	Session tracking
Claude Code	claude	Yes	Real-time (file watcher)
OpenAI Codex	codex	Yes	30s poller
Google Gemini	gemini	Yes	30s poller
GitHub Copilot	gh	No (MCP only)	30s poller

Running Claude agents

cd /path/to/your/project
claude --agent <agent-name>

The agent appears in the dashboard within seconds — liveness is derived from JSONL session mtime (5-minute staleness threshold). The --agent flag requires Claude Code with multi-agent support.

Limitations

• One agent per shell: the agent occupies the foreground. Open a new terminal for each agent.
• The agent name must match the file name (without .md) of an entry in ~/.claude/agents/.

Running Codex agents

codex exec --json "your task description"

The --json flag causes Codex to emit structured output that Dispatch’s session scanner can parse. Sessions appear in the Sessions list within the next polling cycle (default 30 seconds). For real-time updates, configure HTTP hooks to push to Dispatch’s /hooks/* endpoints.

To resume an existing session:

codex exec --json resume <sessionId> "follow-up prompt"

Running Gemini agents

gemini "your task description"

Gemini sessions are detected by Dispatch’s Gemini session scanner, which reads Gemini’s chat JSON files. Sessions appear in the dashboard within 30 seconds.

Copilot (MCP only)

Copilot does not have a CLI spawn interface. Use the MCP integration path from within VS Code. See the Copilot integration guide for setup instructions.

Spawning agents from the dashboard

You can also spawn agents directly from Dispatch’s UI. Click the Run button on any TODO or BLOCKED phase in the epic drawer. Dispatch launches the assigned agent’s CLI with the phase context as its prompt, and streams output back via SSE. See Agent Execution for details.

Troubleshooting

See the Troubleshooting page for solutions to common CLI problems.