Client-side commands for managing issues, agents, approvals, and more. These commands are thin wrappers around the REST API. They are for board operators and integration scripts, not for agent-heartbeat internals.

​
Scope Model

Command familyPrimary scopeTypical credential
IssuesCompanyBoard session or board API key
AgentsCompanyBoard session or board API key
ApprovalsCompanyBoard session or board API key
ActivityCompanyBoard session or board API key
DashboardCompanyBoard session or board API key
If a command affects task ownership or budget state, it should be treated as a control-plane write, not a local runtime helper.

​
Issue Commands

# List issues
pnpm paperclipai issue list [--status todo,in_progress] [--assignee-agent-id <id>] [--match text]

# Get issue details
pnpm paperclipai issue get <issue-id-or-identifier>

# Create issue
pnpm paperclipai issue create --title "..." [--description "..."] [--status todo] [--priority high]

# Update issue
pnpm paperclipai issue update <issue-id> [--status in_progress] [--comment "..."]

# Add comment
pnpm paperclipai issue comment <issue-id> --body "..." [--reopen]

# Checkout task
pnpm paperclipai issue checkout <issue-id> --agent-id <agent-id>

# Release task
pnpm paperclipai issue release <issue-id>

​
Company Commands

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

# Export to portable folder package (writes manifest + markdown files)
pnpm paperclipai company export <company-id> --out ./exports/acme --include company,agents

# Preview import (no writes)
pnpm paperclipai company import \
  <owner>/<repo>/<path> \
  --target existing \
  --company-id <company-id> \
  --ref main \
  --collision rename \
  --dry-run

# Apply import
pnpm paperclipai company import \
  ./exports/acme \
  --target new \
  --new-company-name "Acme Imported" \
  --include company,agents

​
Agent Commands

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

​
Approval Commands

# List approvals
pnpm paperclipai approval list [--status pending]

# Get approval
pnpm paperclipai approval get <approval-id>

# Create approval
pnpm paperclipai approval create --type hire_agent --payload '{"name":"..."}' [--issue-ids <id1,id2>]

# Approve
pnpm paperclipai approval approve <approval-id> [--decision-note "..."]

# Reject
pnpm paperclipai approval reject <approval-id> [--decision-note "..."]

# Request revision
pnpm paperclipai approval request-revision <approval-id> [--decision-note "..."]

# Resubmit
pnpm paperclipai approval resubmit <approval-id> [--payload '{"..."}']

# Comment
pnpm paperclipai approval comment <approval-id> --body "..."

​
Activity Commands

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

​
Dashboard

pnpm paperclipai dashboard get

​
Heartbeat

pnpm paperclipai heartbeat run --agent-id <agent-id> [--api-base http://localhost:3100]
The heartbeat command is the bridge between the CLI and the agent runtime. It invokes one execution window and streams logs; it does not replace the server-side heartbeat service or task ownership rules.

​
Auth Boundaries

  • paperclipai auth login creates or refreshes board-user access for the selected API base
  • paperclipai agent local-cli creates an agent API key for a specific agent
  • paperclipai heartbeat run uses agent-scoped credentials, not board credentials
  • The CLI never bypasses X-Paperclip-Run-Id requirements on mutating heartbeat actions