e86a743c0b
Wires errand command group into CLI with start, list, chat, diff, complete, merge, resolve, abandon, and delete subcommands. All commands call tRPC procedures via createDefaultTrpcClient(). The start command validates description length client-side (≤200 chars) before making any network calls. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
173 lines
6.5 KiB
Markdown
173 lines
6.5 KiB
Markdown
# CLI & Configuration
|
|
|
|
`apps/server/cli/` — CLI commands, `apps/server/config/` — workspace configuration, `apps/server/bin/` — entry point.
|
|
|
|
## Entry Point
|
|
|
|
`apps/server/bin/cw.ts` — hashbang entry that imports and runs the CLI.
|
|
|
|
## CLI Framework
|
|
|
|
Uses **Commander.js** for command parsing.
|
|
|
|
## Global Flags
|
|
|
|
- `-s, --server` — Start coordination server in foreground
|
|
- `-p, --port <number>` — Server port (default: 3847, env: `CW_PORT`)
|
|
- `-d, --debug` — Enable debug mode (archive agent workdirs before cleanup)
|
|
|
|
## Commands
|
|
|
|
### System
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `cw init` | Create `.cwrc` workspace file in current directory |
|
|
| `cw start` | Start coordination server (see Server Wiring below) |
|
|
| `cw stop` | Stop running server (reads PID file, sends signal) |
|
|
| `cw status` | Query server health endpoint |
|
|
| `cw id [-n count]` | Generate nanoid(s) offline |
|
|
|
|
### Agent Management (`cw agent`)
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `spawn <prompt> --task <id> [--name] [--provider] [--initiative] [--cwd]` | Spawn agent |
|
|
| `stop <name>` | Stop running agent |
|
|
| `delete <name>` | Delete agent, clean workdir/branches/logs |
|
|
| `list` | List all agents with status |
|
|
| `get <name>` | Agent details (ID, task, session, worktree, status) |
|
|
| `resume <name> <answers>` | Resume with JSON answers or single string |
|
|
| `result <name>` | Get execution result |
|
|
|
|
### Task Management (`cw task`)
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `list --parent\|--phase\|--initiative <id>` | List tasks with counts |
|
|
| `get <taskId>` | Task details |
|
|
| `status <taskId> <status>` | Update status |
|
|
|
|
### Dispatch (`cw dispatch`)
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `queue <taskId>` | Queue task for dispatch |
|
|
| `next` | Dispatch next available task |
|
|
| `status` | Show queue status |
|
|
| `complete <taskId>` | Mark task complete |
|
|
|
|
### Initiative Management (`cw initiative`)
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `create <name> [--project <ids...>]` | Create initiative |
|
|
| `list [-s status]` | List initiatives |
|
|
| `get <id>` | Initiative details |
|
|
| `phases <initiativeId>` | List phases |
|
|
|
|
### Architect (`cw architect`)
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `discuss <initiativeId> [-c context]` | Start discussion agent |
|
|
| `plan <initiativeId> [-s summary]` | Start plan agent |
|
|
| `detail <phaseId> [-t taskName] [-c context]` | Detail phase into tasks |
|
|
|
|
### Phase (`cw phase`)
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `add-dependency --phase <id> --depends-on <id>` | Add dependency edge |
|
|
| `dependencies <phaseId>` | List dependencies |
|
|
| `queue <phaseId>` | Queue approved phase |
|
|
| `dispatch` | Dispatch next phase |
|
|
| `queue-status` | Show phase queue |
|
|
|
|
### Merge & Coordination (`cw merge`, `cw coordinate`)
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `merge queue <taskId>` | Queue task for merge |
|
|
| `merge status` | Show merge queue |
|
|
| `merge next` | Show next mergeable task |
|
|
| `coordinate [-t branch]` | Process all ready merges (default: main) |
|
|
|
|
### Messages (`cw message`)
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `list [--agent <id>] [--status <s>]` | List messages |
|
|
| `read <messageId>` | Read full message |
|
|
| `respond <messageId> <response>` | Respond to message |
|
|
|
|
### Projects (`cw project`)
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `register --name <n> --url <u>` | Register git repo |
|
|
| `list` | List projects |
|
|
| `delete <id>` | Delete project |
|
|
|
|
### Preview Deployments (`cw preview`)
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `start --initiative <id> --project <id> --branch <branch> [--phase <id>]` | Start Docker preview |
|
|
| `stop <previewId>` | Stop and clean up preview |
|
|
| `list [--initiative <id>]` | List active previews |
|
|
| `status <previewId>` | Get preview status with service details |
|
|
|
|
### Inter-Agent Conversation (`cw listen`, `cw ask`, `cw answer`)
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `listen --agent-id <id> [--poll-interval <ms>] [--timeout <ms>]` | Poll for pending questions, print JSON, exit |
|
|
| `ask <question> --from <agentId> [--agent-id\|--phase-id\|--task-id <target>] [--poll-interval <ms>] [--timeout <ms>]` | Ask question, block until answered, print answer |
|
|
| `answer <answer> --conversation-id <id>` | Answer a pending conversation |
|
|
|
|
All three commands output JSON for programmatic agent consumption.
|
|
|
|
### Errand Sessions (`cw errand`)
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `start <description> --project <id> [--base <branch>]` | Start a new errand session (description ≤200 chars) |
|
|
| `list [--project <id>] [--status <status>]` | List errands; status: active\|pending_review\|conflict\|merged\|abandoned |
|
|
| `chat <id> <message>` | Deliver a message to the running errand agent |
|
|
| `diff <id>` | Print unified git diff between base branch and errand branch |
|
|
| `complete <id>` | Mark errand as done and ready for review |
|
|
| `merge <id> [--target <branch>]` | Merge errand branch into target branch |
|
|
| `resolve <id>` | Print worktree path and conflicting files for manual resolution |
|
|
| `abandon <id>` | Stop agent, remove worktree and branch, keep DB record as abandoned |
|
|
| `delete <id>` | Stop agent, remove worktree, delete branch, and delete DB record |
|
|
|
|
### Accounts (`cw account`)
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `add [--provider] [--email] [--token]` | Auto-discover, manually register, or register with setup token |
|
|
| `list` | Show accounts with exhaustion status |
|
|
| `remove <id>` | Remove account |
|
|
| `refresh` | Clear expired exhaustion markers |
|
|
| `extract [--email <email>]` | Extract current Claude credentials as JSON (no server required) |
|
|
|
|
## Server Wiring
|
|
|
|
The CLI is the composition root. It creates concrete implementations and passes them as `contextDeps`:
|
|
|
|
```
|
|
ServerContextDeps = Omit<TrpcAdapterOptions, 'eventBus' | 'serverStartedAt' | 'processCount'>
|
|
```
|
|
|
|
This includes all repositories, managers, and the credential manager. The server adds `eventBus`, `serverStartedAt`, and `processCount` at startup.
|
|
|
|
## Workspace Configuration
|
|
|
|
`apps/server/config/` module:
|
|
|
|
### .cwrc File
|
|
JSON file at workspace root that marks a `cw` workspace:
|
|
```json
|
|
{ "version": 1 }
|
|
```
|
|
|
|
### findWorkspaceRoot()
|
|
Walks up directory tree looking for `.cwrc` file. Returns the directory containing it, or throws if not found.
|
|
|
|
### Schema
|
|
Currently `{ version: 1 }` — extend with new top-level keys as needed.
|
|
|
|
### Files
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| `types.ts` | CwrcConfig type definition |
|
|
| `cwrc.ts` | findWorkspaceRoot(), readCwrc(), writeCwrc() |
|
|
| `index.ts` | Public API exports |
|