paperclip/doc/CLI.md

CLI Reference

Paperclip CLI now supports both:

• instance setup/diagnostics (onboard, doctor, configure, env, allowed-hostname, env-lab)
• control-plane client operations (issues, approvals, agents, activity, dashboard)

Base Usage

Use repo script in development:

pnpm paperclipai --help

First-time local bootstrap + run:

pnpm paperclipai run

Choose local instance:

pnpm paperclipai run --instance dev

Deployment Modes

Mode taxonomy and design intent are documented in doc/DEPLOYMENT-MODES.md.

Current CLI behavior:

• paperclipai onboard and paperclipai configure --section server set deployment mode in config
• server onboarding/configure ask for reachability intent and write server.bind
• paperclipai run --bind <loopback|lan|tailnet> passes a quickstart bind preset into first-run onboarding when config is missing
• runtime can override mode with PAPERCLIP_DEPLOYMENT_MODE
• paperclipai run and paperclipai doctor still do not expose a direct low-level --mode flag

Canonical behavior is documented in doc/DEPLOYMENT-MODES.md.

Allow an authenticated/private hostname (for example custom Tailscale DNS):

pnpm paperclipai allowed-hostname dotta-macbook-pro

Bring up the default local SSH fixture for environment testing:

pnpm paperclipai env-lab up
pnpm paperclipai env-lab doctor
pnpm paperclipai env-lab status --json
pnpm paperclipai env-lab down

All client commands support:

• --data-dir <path>
• --api-base <url>
• --api-key <token>
• --context <path>
• --profile <name>
• --json

Company-scoped commands also support --company-id <id>.

Use --data-dir on any CLI command to isolate all default local state (config/context/db/logs/storage/secrets) away from ~/.paperclip:

pnpm paperclipai run --data-dir ./tmp/paperclip-dev
pnpm paperclipai issue list --data-dir ./tmp/paperclip-dev

Context Profiles

Store local defaults in ~/.paperclip/context.json:

pnpm paperclipai context set --api-base http://localhost:3100 --company-id <company-id>
pnpm paperclipai context show
pnpm paperclipai context list
pnpm paperclipai context use default

To avoid storing secrets in context, set apiKeyEnvVarName and keep the key in env:

pnpm paperclipai context set --api-key-env-var-name PAPERCLIP_API_KEY
export PAPERCLIP_API_KEY=...

Company Commands

pnpm paperclipai company list
pnpm paperclipai company get <company-id>
pnpm paperclipai company delete <company-id-or-prefix> --yes --confirm <same-id-or-prefix>

Examples:

pnpm paperclipai company delete PAP --yes --confirm PAP
pnpm paperclipai company delete 5cbe79ee-acb3-4597-896e-7662742593cd --yes --confirm 5cbe79ee-acb3-4597-896e-7662742593cd

Notes:

• Deletion is server-gated by PAPERCLIP_ENABLE_COMPANY_DELETION.
• With agent authentication, company deletion is company-scoped. Use the current company ID/prefix (for example via --company-id or PAPERCLIP_COMPANY_ID), not another company.

Issue Commands

pnpm paperclipai issue list --company-id <company-id> [--status todo,in_progress] [--assignee-agent-id <agent-id>] [--match text]
pnpm paperclipai issue get <issue-id-or-identifier>
pnpm paperclipai issue create --company-id <company-id> --title "..." [--description "..."] [--status todo] [--priority high]
pnpm paperclipai issue update <issue-id> [--status in_progress] [--comment "..."]
pnpm paperclipai issue comment <issue-id> --body "..." [--reopen]
pnpm paperclipai issue checkout <issue-id> --agent-id <agent-id> [--expected-statuses todo,backlog,blocked]
pnpm paperclipai issue release <issue-id>

Agent Commands

pnpm paperclipai agent list --company-id <company-id>
pnpm paperclipai agent get <agent-id>
pnpm paperclipai agent local-cli <agent-id-or-shortname> --company-id <company-id>

agent local-cli is the quickest way to run local Claude/Codex manually as a Paperclip agent:

• creates a new long-lived agent API key
• installs missing Paperclip skills into ~/.codex/skills and ~/.claude/skills
• prints export ... lines for PAPERCLIP_API_URL, PAPERCLIP_COMPANY_ID, PAPERCLIP_AGENT_ID, and PAPERCLIP_API_KEY

Example for shortname-based local setup:

pnpm paperclipai agent local-cli codexcoder --company-id <company-id>
pnpm paperclipai agent local-cli claudecoder --company-id <company-id>

Secrets Commands

pnpm paperclipai secrets list --company-id <company-id>
pnpm paperclipai secrets declarations --company-id <company-id> [--include agents,projects] [--kind secret]
pnpm paperclipai secrets create --company-id <company-id> --name anthropic-api-key --value-env ANTHROPIC_API_KEY
pnpm paperclipai secrets link --company-id <company-id> --name prod-stripe-key --provider aws_secrets_manager --external-ref <provider-ref>
pnpm paperclipai secrets doctor --company-id <company-id>
pnpm paperclipai secrets migrate-inline-env --company-id <company-id> [--apply]

Secret listing and declarations never print secret values. create accepts --value-env so shell history does not capture the value. link records provider-owned references without copying the secret value into Paperclip. For AWS-backed secrets, secrets doctor reports missing non-secret provider env and the expected AWS SDK runtime credential source; do not store AWS bootstrap credentials in Paperclip secrets.

Per-company provider vaults (multiple vault instances per provider, default vault selection, coming-soon GCP/Vault) are configured from the board UI under Company Settings → Secrets → Provider vaults or through /api/companies/{companyId}/secret-provider-configs. There is no CLI surface for vault management today. See the secrets deploy guide and API reference for the contract.

Approval Commands

pnpm paperclipai approval list --company-id <company-id> [--status pending]
pnpm paperclipai approval get <approval-id>
pnpm paperclipai approval create --company-id <company-id> --type hire_agent --payload '{"name":"..."}' [--issue-ids <id1,id2>]
pnpm paperclipai approval approve <approval-id> [--decision-note "..."]
pnpm paperclipai approval reject <approval-id> [--decision-note "..."]
pnpm paperclipai approval request-revision <approval-id> [--decision-note "..."]
pnpm paperclipai approval resubmit <approval-id> [--payload '{"...":"..."}']
pnpm paperclipai approval comment <approval-id> --body "..."

Activity Commands

pnpm paperclipai activity list --company-id <company-id> [--agent-id <agent-id>] [--entity-type issue] [--entity-id <id>]

Dashboard Commands

pnpm paperclipai dashboard get --company-id <company-id>

Heartbeat Command

heartbeat run now also supports context/api-key options and uses the shared client stack:

pnpm paperclipai heartbeat run --agent-id <agent-id> [--api-base http://localhost:3100] [--api-key <token>]

Local Storage Defaults

Local Paperclip data lives under the selected instance root. PAPERCLIP_HOME chooses the home directory and PAPERCLIP_INSTANCE_ID chooses the instance.

~/.paperclip/                                     # PAPERCLIP_HOME
└── instances/
    └── default/                                  # instance root (PAPERCLIP_INSTANCE_ID)
        ├── config.json                           # runtime config
        ├── .env                                  # instance env file
        ├── db/                                   # embedded PostgreSQL data
        ├── data/
        │   ├── storage/                          # local_disk uploads
        │   └── backups/                          # automatic DB backups
        ├── logs/
        ├── secrets/
        │   └── master.key                        # local_encrypted master key
        ├── workspaces/                           # default agent workspaces
        ├── projects/                             # project execution workspaces
        ├── companies/                            # per-company adapter homes (e.g. codex-home)
        └── codex-home/                           # per-instance codex home (when not company-scoped)

Default paths for the canonical install:

• config: ~/.paperclip/instances/default/config.json
• embedded db: ~/.paperclip/instances/default/db
• logs: ~/.paperclip/instances/default/logs
• storage: ~/.paperclip/instances/default/data/storage
• secrets key: ~/.paperclip/instances/default/secrets/master.key

Override base home or instance with env vars:

PAPERCLIP_HOME=/custom/home PAPERCLIP_INSTANCE_ID=dev pnpm paperclipai run

Storage Configuration

Configure storage provider and settings:

pnpm paperclipai configure --section storage

Supported providers:

• local_disk (default; local single-user installs)
• s3 (S3-compatible object storage)