CLI command reference - Paper Compute Docs

Full reference for the paperctl CLI.

`paperctl start`

Launch a supported agent through the local proxy. paperctl start claude sets ANTHROPIC_BASE_URL; paperctl start codex configures Codex model providers for the local Paper proxy.

paperctl start [agent]

Supported agents are claude, codex, and pi:

paperctl start claude
paperctl start codex
paperctl start pi

Anything after -- is passed straight through to the agent, so paper’s own flags never collide with the agent’s:

paperctl start claude -- --dangerously-skip-permissions

`paperctl shell`

Print Paper’s shell init script for bash, zsh, or fish. The script installs a claude function that wraps invocations through paperctl start claude, so plain claude always routes through the proxy.

eval "$(paperctl shell zsh)"    # add to .zshrc
eval "$(paperctl shell bash)"   # add to .bashrc
paperctl shell fish | source    # add to config.fish

The installer offers to add this to your rc file on first install.

`paperctl init`

Install paperd as a launchd agent (macOS) or systemd user unit and bring it up. Auto-discovers the default gateway and backend, and keeps a short-lived JWT warm so agents skip long-lived API keys.

paperctl init
paperctl init --dry-run
paperctl init --gateway my-gateway --backend my-backend

Flag	Description
`--dry-run`	Print the install plan without writing to disk or shelling out to `launchctl`/`systemctl`
`--gateway <slug>`	Gateway slug `paperd` should route through, pre-selected as the primary in `daemon.toml`
`--backend <slug>`	Backend slug `paperd` should route through, scoped to the `--gateway` above
`--environment <env>`	Environment defaults bundle to bootstrap: `production` (default) or `staging`. Ignored when `daemon.toml` already exists

`paperctl status`

Show the proxy address, auth health, current user, and org.

paperctl status

paperd:    running (pid 2330)
proxy:     127.0.0.1:51539
auth:      healthy (expires in 14m59s)
user:      [email protected]
org:       your-org
gateway:   default
backend:   ant-default
upstream:  https://your-org.papercompute.run/

`paperctl logs`

Print recent paperd logs.

paperctl logs
paperctl logs -n 500
paperctl logs --follow

-n / --lines sets how many recent lines to show (default 100). -f / --follow streams new log lines as they arrive, like tail -f.

`paperctl login`

Open a browser for WorkOS auth. Re-run to switch accounts.

paperctl login
paperctl login --no-browser

--no-browser prints the verification URL instead of opening it — for SSH sessions and machines without a browser, open the URL from any device.

`paperctl whoami`

Show the currently logged-in identity.

paperctl whoami
paperctl whoami --json

--json emits JSON instead of a human summary — handy for scripts.

`paperctl logout`

Clear daemon-owned credentials. Run paperctl login to sign back in.

paperctl logout

`paperctl org`

Manage organization context.

Use paperctl org membership add to add a teammate to the active org (requires the admin role). New members join as member; pass --role admin to grant admin:

paperctl org membership add [email protected]
paperctl org membership add [email protected] --role admin

When the new member runs paperctl login, the org is pre-selected and the CLI auto-discovers the default gateway — admins provision it during org setup on console.papercompute.com.

List your orgs with paperctl org list, and create one from the CLI with paperctl org create (prompts for a display name if --name is omitted):

paperctl org list
paperctl org create --name "Acme Robotics"

Use paperctl org select when you belong to more than one org and need to choose which gateway paper routes through. Bare org select lists your orgs and prompts; pass an org id, slug, or display name to skip the prompt:

paperctl org select
paperctl org select <org-slug>

The new selection takes effect the next time paperctl starts. If it’s already running, restart it:

paperctl init

`paperctl show`

Show the active organization, or a specific org by slug.

paperctl show
paperctl show your-org

`paperctl search`

Semantic search over your recorded sessions. Embeds the query and returns the matched turns, most-relevant first, matched by meaning, not exact keywords.

paperctl search "why did the deploy fail"
paperctl search "auth error" -k 20    # up to 20 matches (default 8)
paperctl search "auth error" --json   # raw JSON for scripts

-k / --top caps how many matched turns come back (default 8). --json emits the raw result list instead of the styled output.

`paperctl sessions`

List, inspect, and export the sessions captured for the active org.

paperctl sessions list                # most recent first
paperctl sessions get <session-id>
paperctl sessions export <session-id> --out session.ndjson

List

paperctl sessions list --limit 50 --sort total_cost_usd --direction desc
paperctl sessions list --since 2026-07-01T00:00:00Z --auth-subject <user-id>
paperctl sessions list --json

Flag	Description
`--limit <n>`	Max rows to return (server default 50, max 200)
`--sort <col>`	`last_active`, `started_at`, `turn_count`, `total_cost_usd`, `total_tokens`, `duration_ns`, `derived_status`, or `auth_subject`
`--direction <dir>`	`asc` or `desc`
`--since` / `--until`	Bound to sessions active in an RFC3339 time window
`--auth-subject <id>`	Scope to a single JWT subject (WorkOS user id)
`--cursor <cursor>`	Opaque pagination cursor from a previous response
`--json`	Emit the raw JSON response instead of formatted rows

Get

paperctl sessions get <session-id>
paperctl sessions get <session-id> --json

Export

Export sessions as NDJSON to a file (--out) or stdout.

paperctl sessions export <session-id> --out session.ndjson
paperctl sessions export --since 2026-07-01T00:00:00Z --until 2026-07-15T00:00:00Z
paperctl sessions export --all --out all.ndjson

Export scope is required: pass a session ID, a --since/--until window, or --all. A bare export is rejected so it never dumps everything by accident. --all exports every session, which the server clamps to a trailing 30 days. Use --detail traces for full trace/span granularity (the default is spans, one span-level record per turn).

`paperctl skill`

Browse, generate, and sync your organization’s skills.

paperctl skill list
paperctl skill generate <session-id>
paperctl skill sync <slug>

List

paperctl skill list                    # every skill in your org's library, with slugs
paperctl skill list --query release    # only skills matching "release"

Flag	Description
`--query <text>`	Filter to skills matching the text
`--limit <n>`	Max skills to return (default 24)
`--json`	Emit the raw list instead of the styled output

Generate

Generate a skill from one or more recorded sessions. Generation runs server-side (LLM-backed) — the command kicks it off and prints the result.

paperctl skill generate <session-id>
paperctl skill generate <session-id> <session-id> --name release-runbook

Flag	Description
`--name <name>`	Pin the skill name; omit to let the generator name it from the transcript
`--type <type>`	Skill type hint; omit for the server default (`workflow`)
`--json`	Emit the raw summary instead of the styled output

Sync

Write a skill’s rendered SKILL.md to a local skills directory as <skills-dir>/<slug>/SKILL.md. Re-running the same command overwrites with the skill’s current content — sync is also the update path. See Install a Skill for the workflow.

paperctl skill sync <slug>
paperctl skill sync <slug> --claude --dry-run

The argument is a skill slug (exact match) or a skill id (prefix match).

Flag	Description
`--claude`	Write to `.claude/skills` (for Claude Code) instead of `.agents/skills`
`--local`	Write under `./` instead of the home directory
`--dry-run`	Print the resolved target directory; write nothing

`paperctl tapes`

Create, inspect, and manage tapes AI gateway instances and their LLM backends.

paperctl tapes create
paperctl tapes gateway
paperctl tapes backend

Bootstrap interactively

Use paperctl tapes create when an org has no default gateway, or when you want to provision a second one:

paperctl tapes create

Manage gateways

Subcommand	Description
`paperctl tapes gateway create`	Create a new gateway
`paperctl tapes gateway list`	List gateways
`paperctl tapes gateway get`	Get gateway details
`paperctl tapes gateway delete`	Delete a gateway
`paperctl tapes gateway use`	Mark a gateway as the primary one `paperd` routes through

Manage backends

Backends are scoped to a gateway — every command takes --gateway [name].

Subcommand	Description
`paperctl tapes backend create`	Create a backend
`paperctl tapes backend list`	List backends
`paperctl tapes backend get`	Get backend details
`paperctl tapes backend delete`	Delete a backend
`paperctl tapes backend use`	Mark a backend (and its gateway) as primary

For Codex routing and custom backend shapes, see Custom backends.

`paperctl integrations`

Configure a local application to capture through paperd. Available from paperctl 0.23.0.

paperctl integrations codex writes a Paper OpenAI model provider into Codex’s config.toml, so sessions from the Codex desktop app, CLI, and IDE extensions route through the local proxy and are captured — including sessions you launch from Codex itself rather than paperctl start codex:

paperctl integrations codex
paperctl integrations codex --dry-run
paperctl integrations codex --auth api-key

The command changes local state only ($CODEX_HOME/config.toml, default ~/.codex/config.toml). Restart the Codex app after running it.

--auth picks how Codex authenticates through paperd: chatgpt (default) uses Codex’s own ChatGPT/OpenAI sign-in — the best fit for the desktop app — and api-key reads OPENAI_API_KEY from the Codex process environment. In api-key mode, --backend selects the backend segment (default openai-transparent). --dry-run prints the TOML that would be written without touching the file.

Capture flows for each agent are on Capture with Codex.

`paperctl doctor`

Check and repair the Paper installation: daemon, login, organization, and route. Prompts only where a choice is needed.

paperctl doctor

It also checks the install itself: if the directory containing the running binary is missing from PATH, or a stale pre-rename paper binary earlier in PATH shadows the new one, doctor names the problem and prints the exact command to fix it.

`paperctl configure`

Review and change Paper settings interactively. Runs the paperctl doctor checks first, then opens a settings menu.

paperctl configure

`paperctl menu`

Manage the menu-bar / system-tray app. Bare paperctl menu runs it in the foreground (same as paperctl menu run).

paperctl menu install
paperctl menu run
paperctl menu uninstall

paperctl menu install is the recommended setup — it installs a launchd agent (macOS) so the menu auto-starts on login and survives reboots. Picking Quit from the menu keeps it quit until the next login. paperctl menu uninstall stops the agent and removes it.

`paperctl upgrade`

Upgrade paperctl in place: download the requested build, verify its published checksum, atomically replace the binary, and restart paperd. With no flags it installs the newest release, and exits successfully without downloading when you’re already up to date.

paperctl upgrade
paperctl upgrade --version v0.21.0
paperctl upgrade --nightly

--version pins an exact release — older versions are allowed, so a bad release has an escape hatch. --nightly installs the rolling nightly build instead of a release.

The command is upgrade, not update, on purpose: upgrade means “replace the binary with another build”, and update is reserved for possible future semantics.

`paperctl version`

Print version information.

paperctl version

`paperctl uninstall`

Completely remove paperd and all local Paper state — the supervisor unit, control socket, credentials, daemon config, and logs — as if Paper was never installed.

paperctl uninstall

The command prompts for confirmation before removing anything; -y / --yes skips the prompt for scripted removal.

To start again, run paperctl init and paperctl login.

Configuration

org context

Which organization paper routes through. Auto-selected on paperctl login if you belong to one; choose with paperctl org select if you belong to multiple. View with paperctl status.

gateway context

Which tapes AI gateway paper routes inference through. Auto-discovered from the org default on paperctl init; manage with paperctl tapes gateway.

backend context

A backend is one route from a gateway to a single upstream model provider, defined by a schema (Anthropic, OpenAI, ChatGPTCodex), the upstream host, an auth mode, and a model allowlist. The active gateway routes to its primary backend; one is provisioned alongside the gateway by default. Manage backends with paperctl tapes backend.

Codex backend routes

Codex uses explicit Paper route prefixes instead of the primary backend route:

ChatGPT passthrough auth routes through /v1/openai-chatgpt/chatgpt-codex.
OpenAI API-key auth routes through /v1/openai-responses/<backend>/v1.

These routes are provisioned by default, so paperctl start codex works with no setup; see Custom backends to customize them or set a shared team key.

ANTHROPIC_BASE_URL

Environment variable Claude Code reads to find an alternate API endpoint. paperctl start claude sets it automatically for the launched process. To wire it up yourself, copy the proxy address from paperctl status and export it:

export ANTHROPIC_BASE_URL=http://127.0.0.1:51539

The proxy address comes from daemon configuration and stays the same across restarts (127.0.0.1:51539 by default). Still prefer paperctl start claude — or add eval "$(paperctl shell zsh)" (or the bash/fish equivalent) to your shell rc — so the address is resolved for you instead of hand-managed.

config location

Credentials and local state live in ~/.config/paper/. Removing this directory wipes your login — running paperctl login again recreates it.