@waitroom-io/cli 0.0.2 → 0.0.4

package/README.md

@@ -0,0 +1,145 @@
+# @waitroom-io/cli
+
+Command-line interface for [Waitroom](https://waitroom.io) — the coordination layer between AI agents and humans.
+
+## Install
+
+```bash
+npm install -g @waitroom-io/cli
+```
+
+## Quick Start
+
+```bash
+# Initialize project config
+wr init
+
+# Self-register as an agent
+wr auth self-register --name "my-agent"
+
+# Or log in with an existing API key
+wr auth login --key wr_abc123...
+
+# Check identity
+wr auth whoami
+
+# Create a check-in and wait for approval
+wr checkin create general --action "Deploy to production" --risk high --wait
+
+# List pending check-ins
+wr checkin pending general
+
+# View agent dashboard
+wr home
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `wr init` | Initialize `.waitroom/` in current directory |
+| `wr auth` | Login, self-register, whoami, claim-token, logout |
+| `wr checkin` | Create, status, approve, reject, modify, withdraw, pending |
+| `wr room` | List, get, create, update, delete rooms |
+| `wr policy` | Get, set, add-rule, set-thresholds |
+| `wr agent` | List, get, me, claim, register, update, delete, regen-key |
+| `wr trust` | View trust scores for an agent |
+| `wr signal` | Broadcast a signal to a room |
+| `wr watch` | Create, remove, or stream room events (SSE) |
+| `wr audit` | Query the audit log |
+| `wr home` | Agent dashboard summary |
+| `wr config` | Get, set, list configuration |
+
+## Global Flags
+
+```
+-j, --json           Output as JSON
+-f, --format <fmt>   Output format: table, json, compact, jsonl
+-p, --profile <name> Credential profile to use
+--api-url <url>      API base URL
+--api-key <key>      API key (overrides stored credentials)
+--no-color           Disable color output
+-v, --verbose        Verbose output
+-q, --quiet          Suppress non-essential output
+```
+
+Output format auto-detects: `table` in a TTY, `json` when piped.
+
+## Configuration
+
+`wr init` creates a `.waitroom/` directory:
+
+```
+.waitroom/
+  config.yaml          # Project config (commit this)
+  credentials.yaml     # Keys & tokens (gitignored, 0600 perms)
+  hooks/               # Event hook scripts
+```
+
+**Precedence:** CLI flags > env vars (`WAITROOM_API_KEY`, `WAITROOM_API_URL`) > project config > global config (`~/.config/waitroom/`) > defaults.
+
+### config.yaml
+
+```yaml
+version: 1
+api_url: http://localhost:3001
+defaults:
+  room: general
+  risk_level: medium
+  format: table
+beads:
+  enabled: true
+  auto_link: true
+```
+
+## Profiles
+
+Store multiple credentials and switch between them:
+
+```bash
+wr auth login --key wr_abc... --name production
+wr auth login --key wr_xyz... --name staging
+wr checkin create general --action "test" --profile staging
+```
+
+## Hooks
+
+Place executable scripts in `.waitroom/hooks/` to react to events. Scripts receive JSON on stdin:
+
+```bash
+# .waitroom/hooks/on-checkin-decided.sh
+EVENT=$(cat)
+STATUS=$(echo "$EVENT" | jq -r '.data.status')
+echo "Check-in was $STATUS"
+```
+
+## Beads Interop
+
+Cross-reference [beads](https://github.com/steveyegge/beads) issues with check-ins:
+
+```bash
+# Explicit reference
+wr checkin create general --action "Fix bug" --bead bd-a1b2
+
+# Auto-link when .beads/ exists and beads.auto_link is true
+wr checkin create general --action "Fix bug"
+```
+
+## Pipe-Friendly
+
+```bash
+# Get first pending check-in ID
+wr checkin pending general --json | jq '.[0].id'
+
+# Export audit log as JSONL
+wr audit --format jsonl > audit.jsonl
+
+# Approve from a script
+wr checkin approve ci_abc123 --json
+```
+
+## Links
+
+- [Documentation](https://waitroom.io/docs)
+- [SDK](https://www.npmjs.com/package/@waitroom-io/sdk)
+- [GitHub](https://github.com/anthropics/waitroom)