The Paperclip CLI is the operational interface for instance setup, diagnostics, and control-plane management.

​
Usage

pnpm paperclipai --help

​
What The CLI Covers

Use the CLI when you need to:
  • bootstrap a new instance
  • inspect deployment and storage state
  • configure mode, hostname, and secrets
  • manage companies, agents, issues, approvals, activity, and dashboards from the terminal

​
Global Options

All commands support:
FlagDescription
--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
--jsonOutput as JSON
Company-scoped commands also accept --company-id <id>. For clean local instances, pass --data-dir on the command you run: 
pnpm paperclipai run --data-dir ./tmp/paperclip-dev

​
Context Profiles

Store defaults to avoid repeating flags: 
# Set defaults
pnpm 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
pnpm paperclipai context use default
To avoid storing secrets in context, use an env var: 
pnpm paperclipai context set --api-key-env-var-name PAPERCLIP_API_KEY
export PAPERCLIP_API_KEY=...
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

​
Deployment Notes

Deployment mode and hostname trust are part of the CLI contract, not hidden implementation details.
  • paperclipai onboard writes the initial deployment mode
  • paperclipai configure --section server updates the runtime mode later
  • paperclipai allowed-hostname <host> adds private hostnames for authenticated/private deployments