CLI Overview

The Paperclip CLI handles instance setup, diagnostics, and control-plane operations.

Usage

pnpm paperclipai --help

Global Options

All commands support:

Flag	Description
--data-dir <path>	Local Paperclip data root (isolates from ~/.paperclip)
--api-base <url>	API base URL
--api-key <token>	API authentication token
--context <path>	Context file path
--profile <name>	Context profile name
--json	Output as JSON

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

For clean local instances, pass --data-dir on the command you run:

npx paperclipai run --data-dir ./tmp/paperclip-dev

Context Profiles

Store defaults to avoid repeating flags:

# Set defaults
npx paperclipai context set --api-base http://localhost:3100 --company-id <id>

# View current context
pnpm paperclipai context show

# List profiles
pnpm paperclipai context list

# Switch profile
npx paperclipai context use default

To avoid storing secrets in context, use an env var:

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

Secret operations are available under paperclipai secrets:

npx paperclipai secrets declarations --company-id <company-id> --kind secret
npx paperclipai secrets create --company-id <company-id> --name anthropic-api-key --value-env ANTHROPIC_API_KEY
npx paperclipai secrets link --company-id <company-id> --name prod-stripe-key --provider aws_secrets_manager --external-ref <provider-ref>
npx paperclipai secrets doctor --company-id <company-id>
npx paperclipai secrets migrate-inline-env --company-id <company-id> --apply

Context is stored at ~/.paperclip/context.json.

Command Categories

The CLI has two categories:

1. Setup commands — instance bootstrap, diagnostics, configuration
2. Control-plane commands — issues, agents, approvals, activity