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>

Skills Commands

paperclipai skills covers three distinct operations:

1. Company install — adds or updates a row in company_skills for the whole company. This is what skills install, skills import, skills create, and skills scan-projects do.
2. Agent attach — replaces an agent's desired company skill set (skills agent sync/clear). This is a desired-state operation on the agent's adapter config; it does not change the company library.
3. Adapter runtime sync — the adapter reconciles the desired skill set with files on disk and reports an AgentSkillSnapshot (skills agent list). skills agent sync triggers this automatically after updating desired state.

Required Paperclip runtime skills (heartbeat, etc.) remain server-enforced and are added on top of whatever the desired set names.

Catalog (app-shipped skills)

The Paperclip app ships a curated catalog under @paperclipai/skills-catalog. Browse and inspect commands never mutate company state; install adds a catalog skill to the company library.

pnpm paperclipai skills browse [--kind bundled|optional] [--category <slug>] [--query <text>]
pnpm paperclipai skills search "<text>" [--kind bundled|optional] [--category <slug>]
pnpm paperclipai skills inspect <catalog-id-or-key-or-slug>
pnpm paperclipai skills install <catalog-id-or-key-or-slug> [--as <slug>] [--force] --company-id <company-id>

Catalog semantics:

• Bundled skills live in packages/skills-catalog/catalog/bundled/<category>/<slug> and are recommended defaults for most companies. They use canonical key paperclipai/bundled/<category>/<slug>.
• Optional skills live in packages/skills-catalog/catalog/optional/<category>/<slug> and are role-specific or domain-specific (browser, AWS ops, etc.). Same key shape with optional in place of bundled.
• skills install materializes the catalog files into a company-managed skill directory and records provenance (catalogId, catalogKey, packageVersion, originHash, …) so future updates and audit decisions stay consistent.
• --as <slug> overrides the company skill slug. --force may replace a same-key catalog-managed skill but never bypasses hard validation or hard-stop audit findings.

Examples:

pnpm paperclipai skills browse --kind bundled --company-id <company-id>
pnpm paperclipai skills search "pull request" --kind bundled
pnpm paperclipai skills inspect github-pr-workflow
pnpm paperclipai skills install github-pr-workflow --company-id <company-id>
pnpm paperclipai skills install paperclipai:optional:browser:agent-browser --company-id <company-id>

External GitHub, skills.sh, local-path, and URL sources still go through skills import; catalog commands are for the app-shipped catalog only.

Company library

pnpm paperclipai skills list --company-id <company-id>
pnpm paperclipai skills show <skill-id-or-key-or-slug> --company-id <company-id>
pnpm paperclipai skills file <skill-id-or-key-or-slug> [--path SKILL.md] --company-id <company-id>
pnpm paperclipai skills import <source> --company-id <company-id>
pnpm paperclipai skills create --name "Review PRs" [--slug review-prs] [--description "..."] [--body-file SKILL.md] --company-id <company-id>
pnpm paperclipai skills scan-projects [--project-id <id>...] [--workspace-id <id>...] --company-id <company-id>
pnpm paperclipai skills check [skill-id-or-key-or-slug] --company-id <company-id>
pnpm paperclipai skills update <skill-id-or-key-or-slug> [--force] --company-id <company-id>
pnpm paperclipai skills update --all [--force] --company-id <company-id>
pnpm paperclipai skills audit [skill-id-or-key-or-slug] --company-id <company-id>
pnpm paperclipai skills reset <skill-id-or-key-or-slug> [--yes] [--force] --company-id <company-id>
pnpm paperclipai skills remove <skill-id-or-key-or-slug> --yes --company-id <company-id>

skills import <source> accepts a skills.sh URL, the equivalent <owner>/<repo>/<skill> shorthand, a GitHub URL, a local path, or an npx skills add … command. See references/company-skills.md in the agent skill bundle for the source-type table.

skills check, skills update, skills audit, and skills reset are the maintenance loop for catalog-installed skills:

• check reports whether each skill's installed bytes match its pinned origin (hasUpdate, installedHash, originHash, updateHoldReason, auditVerdict).
• update installs the pinned update through the existing install-update API. --all checks every company skill and updates only those with hasUpdate=true. --force discards local-modification or soft-audit holds; hard-stop audit findings still block the update.
• audit re-scans installed bytes and reports findings without executing anything.
• reset reinstalls a catalog-managed skill from its pinned origin, discarding local edits. Prompts in a TTY; requires --yes for non-interactive use.

Agent attach

pnpm paperclipai skills agent list <agent-id-or-shortname> --company-id <company-id>
pnpm paperclipai skills agent sync <agent-id-or-shortname> --skill <skill-id-or-key-or-slug> [--skill <skill-id-or-key-or-slug>...] --company-id <company-id>
pnpm paperclipai skills agent clear <agent-id-or-shortname> --yes --company-id <company-id>

skills agent sync replaces the agent's non-required desired skill set (it is not additive) and returns the resulting adapter AgentSkillSnapshot. skills agent clear sends an empty desired list. Required Paperclip skills are still enforced by the server in both cases.

Notes

• Skill references accept company skill id, canonical key, or unique slug; catalog references accept catalog id, key, or unique slug.
• skills file prints raw file content in human mode so it can be piped.
• skills create --body-file - reads the skill markdown body from stdin.
• skills remove, skills reset, and skills agent clear prompt in a TTY and require --yes in non-interactive use.
• --json prints the raw API result for each command.

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)