Company Commands

Companies are the top-level container in Paperclip: every agent, project, goal, issue, and budget lives inside one. Use paperclipai company when you want to inspect companies, edit their settings and branding, move a whole company between instances as a portable package, pull feedback traces, or delete a company when the server policy allows it.

A board operator sees and manages every company on the instance. An agent persona is scoped to exactly one company, so company-scoped reads and the deletion guard rails resolve against that single company unless you pass an explicit ID.

Tip: Add --json to any command when you are scripting. The human-readable output is summarized; the JSON output is the full server record.

Common Options

Every command on this page accepts the standard client options: --data-dir <path>, --api-base <url>, --api-key <token>, --context <path>, --profile <name>, and --json. See Common Options for how the API base and credentials are resolved.

Two commands — feedback:list and feedback:export — take the company as a required -C, --company-id <id> flag rather than a positional argument. The import command also accepts -C, --company-id <id> to name an existing target company. Everywhere else the company ID is a positional <companyId> argument.

Read Commands

These are read-only and safe to run anywhere.

paperclipai company list
paperclipai company get <company-id>
paperclipai company current
paperclipai company stats

company list with an agent credential returns only your scoped company; with a board credential it returns every company on the instance.

company current is the convenient way to read the company you are already scoped to: it resolves the current company ID the same way every other command does and returns the same full record as company get <companyId>. With an agent credential — which is bound to exactly one company — it always returns that company.

Create and Update

create, update, and branding:update send raw JSON payloads through to the API. The CLI does not validate the shape — it forwards your --payload-json to the server, which applies the matching schema (CreateCompany, UpdateCompany, UpdateCompanyBranding). Build the object the API expects and pass it as a single JSON string.

paperclipai company create \
  --payload-json '{"name":"Acme","issuePrefix":"ACME"}'

paperclipai company update <company-id> \
  --payload-json '{"budgetMonthlyCents":500000}'

paperclipai company branding:update <company-id> \
  --payload-json '{"primaryColor":"#1f6feb","logoUrl":"https://cdn.example.com/acme.png"}'

Note: Because the payload is forwarded verbatim, a malformed or unknown field surfaces as a server-side validation error, not a CLI error. Use --json and read the response when a write is rejected.

Archive

paperclipai company archive <company-id>

company archive posts to /api/companies/{id}/archive and takes no payload. Archiving is the reversible way to take a company out of active rotation. Reach for company delete only when you genuinely need the records gone and the server is configured to permit it.

Export and Import

Paperclip companies are portable. company export writes a company to a folder of markdown-backed files (plus a .paperclip.yaml manifest and any binary assets), and company import reads that package back — from a local path, a .zip, or a GitHub repository — into a new or existing company.

Export a portable package

paperclipai company export <company-id> \
  --out ./exports/acme \
  --include company,agents,projects,issues,skills

The default --include is deliberately small (company,agents) so a quick export does not drag along every task. Widen it explicitly when you want a full clone. If the output directory already contains files, the command asks you to confirm an overwrite in an interactive terminal, and refuses outright in a non-interactive one — choose an empty directory for headless runs.

On success the command prints the resolved output path, the package root, the number of files written, the .paperclip.yaml extension path, and a warning count.

Import a package

paperclipai company import ./exports/acme \
  --target new \
  --new-company-name "Acme (imported)"

paperclipai company import https://github.com/acme/company-pack \
  --target existing --company-id <company-id> \
  --collision replace --yes

The source argument is a local directory, a local .zip file, a GitHub URL, or owner/repo[/path] shorthand. Generic HTTP URLs are rejected — only GitHub / GitHub Enterprise URLs and local paths are supported.

The import always runs a server-side preview first and shows you the plan — package contents, per-group create/update/skip counts, sample entities, and any warnings or errors — before anything is written. In an interactive terminal without --include or --yes, you also get a selection menu to pick exactly which projects, tasks, agents, and skills to bring in. With --dry-run the command stops after the preview.

Warning: Applying an import is gated. With --json you must pass --yes (run --dry-run first to inspect the preview as JSON). From a non-interactive terminal you must also pass --yes. Without --yes in an interactive terminal, the CLI prompts for explicit confirmation before applying.

When an imported agent has a process adapter with no explicit adapter, the CLI currently falls back to the claude-local adapter and tells you so in the preview/result info block.

Raw API passthrough variants

If you would rather drive the server's portability routes directly with a hand-built payload, four passthrough commands post your --payload-json to the raw routes. These do not read or write local files — they are the API endpoints behind export/import exposed for scripting.

paperclipai company export:preview <company-id> --payload-json '{...}'
paperclipai company export:api <company-id> --payload-json '{...}'
paperclipai company import:preview <company-id> --payload-json '{...}'
paperclipai company import:apply <company-id> --payload-json '{...}'

Prefer the high-level export/import commands for day-to-day work; they handle file I/O, source resolution, previews, and confirmation for you. Use the passthrough variants only when you need precise control over the request body.

Feedback Traces

Feedback traces capture votes and reviews recorded against agent work. Use these two commands to read them or pull them out for analysis. Both require -C, --company-id <id>.

paperclipai company feedback:list --company-id <company-id> --status open --vote down
paperclipai company feedback:export --company-id <company-id> --from 2026-01-01 --format ndjson --out ./feedback.ndjson

feedback:list prints a compact row per trace (id, issue, vote, status, target type, target label) or the full records with --json. feedback:export adds two flags:

feedback:export includes payload snapshots by default (unlike feedback:list, where you opt in with --include-payload). When you pass --out, the command writes the file and reports the count; otherwise it streams the serialized traces to stdout, which makes it easy to pipe into another tool.

Delete a Company

company delete is destructive and intentionally hard to trigger by accident. It removes a company and its records permanently.

paperclipai company delete PAP --yes --confirm PAP
paperclipai company delete 5cbe79ee-acb3-4597-896e-7662742593cd \
  --yes --confirm 5cbe79ee-acb3-4597-896e-7662742593cd

The selector argument is either a company ID (UUID) or an issue prefix/shortname (for example PAP).

Guard rails

Deletion has to clear four separate checks, by design:

1. Server policy. The instance must have PAPERCLIP_ENABLE_COMPANY_DELETION enabled. If it is off, the API rejects the delete regardless of your flags.
2. --yes. Without it the command errors immediately — no API call is made.
3. --confirm <value>. The value must match the resolved company's ID or its issue prefix (prefix match is case-insensitive). A mismatch errors with the expected ID and prefix so you can correct it.
4. Unambiguous resolution. In auto mode, a selector that matches both a different company's ID and another's prefix is rejected as ambiguous — re-run with --by id or --by prefix.

Resolution order: the CLI tries an ID lookup when the selector looks like a UUID (or --by id), then your scoped company from context, then a board-wide company list. With an agent credential, the board-wide lookup is unavailable — deletion is company-scoped, so use the current company's ID or prefix (via --company-id or PAPERCLIP_COMPANY_ID), not another company's.

Warning: There is no undo. If you only need to take a company out of rotation, use company archive instead.

On success the command prints ok: true with the deleted company's ID, name, and prefix.

See also

• Common Options — API base resolution, credentials, and the flags every command shares
• Output and Scripting — using --json and piping CLI output
• Project Commands — manage the projects inside a company
• Agent Commands — inspect agents and set up a local agent CLI session
• Feedback Commands — work with feedback traces beyond the company-scoped views
• Your First Company via CLI — end-to-end walkthrough