Paperclip Cheatsheet — CLI, Concepts & Quick Reference

📎

What is Paperclip?

Paperclip is the control plane for autonomous AI companies: org charts, goals, tasks (issues), budgets, approvals, and heartbeats. Agents run in your tools (Cursor, OpenClaw, shell, HTTP); Paperclip orchestrates who works on what and how spend is capped.

From paperclip.ing

Hire AI employees, set goals, automate jobs — structured like a company, not a single chatbot.
Bring your own agent — any runtime that can receive a heartbeat can be an employee.
Goal alignment — tasks trace back to company mission via goals and projects.
Cost control — monthly budgets per agent; at 100% utilization agents pause (board can override).
Multi-company — one deployment, isolated data per company.
Tickets & trace — instructions, tool calls, and decisions logged for audit.

What Paperclip is not

Not a chat UI — work flows through tasks and governance.
Not an agent framework — it organizes agents you already run.
Not a drag-and-drop workflow builder — it models companies (org, goals, budgets).

⚡

Quickstart & Install

Public npm CLI

# Fastest path (from paperclip.ing)
npx paperclipai onboard --yes

From repository Dev

# From repo: API + UI at http://localhost:3100
pnpm install
pnpm dev

Docs: Node 20+, pnpm 9+. Embedded Postgres by default for local dev.

One-command run CLI

# One-command bootstrap + start (after repo clone)
pnpm paperclipai run

# Named instance
pnpm paperclipai run --instance dev

🏢

Core Concepts

Operating model

Concept	Role
Company	Top-level tenant; goals, org, agents, and data isolation.
Goal / project	Mission hierarchy — tasks carry context tracing back to the “why.”
Agent (employee)	Configured worker tied to an adapter (Claude, Codex, HTTP, process, …).
Issue / task	Unit of work with owner, status, thread, and trace.
Heartbeat	Scheduled wake — agent checks work, claims tasks, reports progress.
Approval	Board gate for hires, strategy, or sensitive actions.
Budget	Per-agent token/spend cap; soft warnings and hard stop at limit.

CLI: agent heartbeat

Trigger or test heartbeat integration from the terminal:

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

⌨️

Setup CLI

Commands below use pnpm paperclipai as in the official docs; globally installed npx paperclipai works the same for subcommands.

Onboarding CLI

pnpm paperclipai onboard
pnpm paperclipai onboard --run
pnpm paperclipai onboard --yes

Doctor CLI

pnpm paperclipai doctor
pnpm paperclipai doctor --repair

# With isolated data dir
pnpm paperclipai doctor --data-dir ./tmp/paperclip-dev

Configure & env CLI

pnpm paperclipai configure --section server
pnpm paperclipai configure --section secrets
pnpm paperclipai configure --section storage

Resolved env

pnpm paperclipai env

Isolate data directory

# Override home / instance
PAPERCLIP_HOME=/custom/home PAPERCLIP_INSTANCE_ID=dev pnpm paperclipai run

🎛️

Control-plane CLI

Issues CLI

pnpm paperclipai issue list [--status todo,in_progress] [--assignee-agent-id <id>] [--match text]
pnpm paperclipai issue get <issue-id-or-identifier>
pnpm paperclipai issue create --title "..." [--description "..."]
pnpm paperclipai issue update <issue-id> [--status in_progress] [--comment "..."]
pnpm paperclipai issue comment <issue-id> --body "..."
pnpm paperclipai issue checkout <issue-id> --agent-id <agent-id>
pnpm paperclipai issue release <issue-id>

Companies CLI

pnpm paperclipai company list
pnpm paperclipai company get <company-id>
pnpm paperclipai company export <company-id> --out ./exports/acme --include company,agents
pnpm paperclipai company import --from ./exports/acme --target new --new-company-name "Acme" --include company,agents

Agents CLI

pnpm paperclipai agent list
pnpm paperclipai agent get <agent-id>

Approvals CLI

pnpm paperclipai approval list [--status pending]
pnpm paperclipai approval get <approval-id>
pnpm paperclipai approval approve <approval-id> [--decision-note "..."]
pnpm paperclipai approval reject <approval-id>

Activity & dashboard CLI

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

Dashboard snapshot

pnpm paperclipai dashboard get

🔑

Context profiles

Store API base, company id, and auth defaults in ~/.paperclip/context.json so you do not repeat flags on every command.

# Defaults for API / company (stored ~/.paperclip/context.json)
pnpm paperclipai context set --api-base http://localhost:3100 --company-id <id>
pnpm paperclipai context show
pnpm paperclipai context list
pnpm paperclipai context use default

# Prefer env for secrets
pnpm paperclipai context set --api-key-env-var-name PAPERCLIP_API_KEY
export PAPERCLIP_API_KEY=...

Global flags (all commands)

Flag	Purpose
`--data-dir`	Isolate local instance data.
`--api-base`	Control-plane URL.
`--api-key`	Auth token.
`--company-id`	Scope to a company (where applicable).
`--json`	Machine-readable output.

🔌

Adapters & skills

Execution happens outside Paperclip. Adapters connect runtimes (Claude Code, Codex, Gemini, HTTP webhooks, local processes) to the control plane.

Docs index

Topic	Link
Adapters overview	docs →
Claude local	docs →
Codex local	docs →
HTTP adapter	docs →
Heartbeat protocol	docs →
Writing a skill	docs →

SKILLS.md

Agents discover workflow and project context through skills. Official guide covers frontmatter, discovery, and packaging — see Writing a skill.

🛡️

Governance & costs

Board workflow

Approvals for hires and sensitive changes (types vary by setup).
Full activity and issue history for accountability.
Budget soft warning (~80%) and hard pause at 100% unless you override.

Learn more

🔧

Troubleshooting

Health checks

pnpm paperclipai doctor
pnpm paperclipai doctor --repair

# With isolated data dir
pnpm paperclipai doctor --data-dir ./tmp/paperclip-dev

Common issues

Symptom	What to try
CLI cannot reach API	Confirm server is running, `--api-base` matches URL, firewall/Tailscale hostname allowed if needed.
Wrong company context	`paperclipai context set --company-id …` or pass `--company-id` per command.
Agent never picks up work	Verify adapter receives heartbeats; see heartbeat docs and adapter logs.
Agent paused “out of budget”	Raise budget or resume after reviewing costs dashboard.

📖

Glossary

Control plane: Paperclip core: API + UI for org, tasks, budgets, approvals.

Adapter: Bridge between Paperclip and an agent runtime (IDE bot, HTTP, shell, …).

Heartbeat: Scheduled signal for an agent to wake, claim work, and report.

Issue: Task ticket with status, owner, thread, and trace metadata.

Company: Isolated tenant: org chart, goals, agents, and spend.

Board: Human operator approving hires, strategy, or limits.

📂

Default paths

Local instance (from docs)

Data	Default
Config	`~/.paperclip/instances/default/config.json`
Database	`~/.paperclip/instances/default/db`
Logs	`~/.paperclip/instances/default/logs`
Storage	`~/.paperclip/instances/default/data/storage`
Secrets key	`~/.paperclip/instances/default/secrets/master.key`
CLI context	`~/.paperclip/context.json`

The Paperclip Cheatsheet

📚 Authoritative sources

🚀 Zero to running