feat(cli): add client commands and home-based local runtime defaults

2026-02-20 07:10:58 -06:00
parent 8e3c2fae35
commit 8f3fc077fa
40 changed files with 2284 additions and 138 deletions
--- a/doc/CLI.md
+++ b/doc/CLI.md
@@ -0,0 +1,128 @@
+# CLI Reference
+
+Paperclip CLI now supports both:
+
+- instance setup/diagnostics (`onboard`, `doctor`, `configure`, `env`)
+- control-plane client operations (issues, approvals, agents, activity, dashboard)
+
+## Base Usage
+
+Use repo script in development:
+
+```sh
+pnpm paperclip --help
+```
+
+First-time local bootstrap + run:
+
+```sh
+pnpm paperclip run
+```
+
+Choose local instance:
+
+```sh
+pnpm paperclip run --instance dev
+```
+
+All client commands support:
+
+- `--api-base <url>`
+- `--api-key <token>`
+- `--context <path>`
+- `--profile <name>`
+- `--json`
+
+Company-scoped commands also support `--company-id <id>`.
+
+## Context Profiles
+
+Store local defaults in `~/.paperclip/context.json`:
+
+```sh
+pnpm paperclip context set --api-base http://localhost:3100 --company-id <company-id>
+pnpm paperclip context show
+pnpm paperclip context list
+pnpm paperclip context use default
+```
+
+To avoid storing secrets in context, set `apiKeyEnvVarName` and keep the key in env:
+
+```sh
+pnpm paperclip context set --api-key-env-var-name PAPERCLIP_API_KEY
+export PAPERCLIP_API_KEY=...
+```
+
+## Company Commands
+
+```sh
+pnpm paperclip company list
+pnpm paperclip company get <company-id>
+```
+
+## Issue Commands
+
+```sh
+pnpm paperclip issue list --company-id <company-id> [--status todo,in_progress] [--assignee-agent-id <agent-id>] [--match text]
+pnpm paperclip issue get <issue-id-or-identifier>
+pnpm paperclip issue create --company-id <company-id> --title "..." [--description "..."] [--status todo] [--priority high]
+pnpm paperclip issue update <issue-id> [--status in_progress] [--comment "..."]
+pnpm paperclip issue comment <issue-id> --body "..." [--reopen]
+pnpm paperclip issue checkout <issue-id> --agent-id <agent-id> [--expected-statuses todo,backlog,blocked]
+pnpm paperclip issue release <issue-id>
+```
+
+## Agent Commands
+
+```sh
+pnpm paperclip agent list --company-id <company-id>
+pnpm paperclip agent get <agent-id>
+```
+
+## Approval Commands
+
+```sh
+pnpm paperclip approval list --company-id <company-id> [--status pending]
+pnpm paperclip approval get <approval-id>
+pnpm paperclip approval create --company-id <company-id> --type hire_agent --payload '{"name":"..."}' [--issue-ids <id1,id2>]
+pnpm paperclip approval approve <approval-id> [--decision-note "..."]
+pnpm paperclip approval reject <approval-id> [--decision-note "..."]
+pnpm paperclip approval request-revision <approval-id> [--decision-note "..."]
+pnpm paperclip approval resubmit <approval-id> [--payload '{"...":"..."}']
+pnpm paperclip approval comment <approval-id> --body "..."
+```
+
+## Activity Commands
+
+```sh
+pnpm paperclip activity list --company-id <company-id> [--agent-id <agent-id>] [--entity-type issue] [--entity-id <id>]
+```
+
+## Dashboard Commands
+
+```sh
+pnpm paperclip dashboard get --company-id <company-id>
+```
+
+## Heartbeat Command
+
+`heartbeat run` now also supports context/api-key options and uses the shared client stack:
+
+```sh
+pnpm paperclip heartbeat run --agent-id <agent-id> [--api-base http://localhost:3100] [--api-key <token>]
+```
+
+## Local Storage Defaults
+
+Default local instance root is `~/.paperclip/instances/default`:
+
+- config: `~/.paperclip/instances/default/config.json`
+- embedded db: `~/.paperclip/instances/default/db`
+- logs: `~/.paperclip/instances/default/logs`
+- secrets key: `~/.paperclip/instances/default/secrets/master.key`
+
+Override base home or instance with env vars:
+
+```sh
+PAPERCLIP_HOME=/custom/home PAPERCLIP_INSTANCE_ID=dev pnpm paperclip run
+```