metadata
title: CLI Overview
summary: CLI installation and setup
The Paperclip CLI handles instance setup, diagnostics, and control-plane operations.
Examples on this page use the installed penclip command. If you are running without installing first, prefix the command with npx.
Usage
penclip --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:
penclip run --data-dir ./tmp/paperclip-dev
Context Profiles
Store defaults to avoid repeating flags:
# Set defaults
penclip context set --api-base http://localhost:3100 --company-id <id>
# View current context
penclip context show
# List profiles
penclip context list
# Switch profile
penclip context use default
To avoid storing secrets in context, use an env var:
penclip 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:
- Setup commands — instance bootstrap, diagnostics, configuration
- Control-plane commands — issues, agents, approvals, activity