# 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 |
| `add <name> --agent-id <id> [--description <desc>] [--category <cat>]` | Create sibling task in agent's phase |

### 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 |