Troubleshooting

paperctl: command not found after install

The installer puts paperctl in ~/.local/bin and writes a PATH export into your shell rc — but the shell that ran the installer hasn’t sourced it yet. Open a new terminal, or in the current one:

export PATH="$HOME/.local/bin:$PATH"

Non-interactive shells (CI, coding agents) don’t read your rc at all: export the PATH as above, or call the binary by its full path, ~/.local/bin/paperctl. If it’s still not found, ls ~/.local/bin/paperctl to confirm the install landed, and paperctl doctor (by full path) names any remaining install problem.

paper: command not found (renamed to paperctl)

The binary was renamed from paper to paperctl in v0.21.0 — a hard cut, with no compat symlink. If a script, CI job, or coding agent’s saved instructions still call paper, the fix is to update the caller. Blocked mid-task? Bridge the gap:

alias paper=paperctl

Or, for callers that don’t go through your shell, a symlink:

ln -s ~/.local/bin/paperctl ~/.local/bin/paper

Drop the bridge once the caller says paperctl — it re-creates the name collision the rename removed.

Proxy not running

paperctl init

If it still won’t start, run paperctl status to see what’s wrong, then paperctl logs for the underlying error.

Sessions not appearing in paper console

Open the paperctl CLI menu bar app and confirm:

• you are authenticated and your auth is not expired
• you are connected to the correct organization
• paperd is running

Then re-run your paperctl start command (paperctl start claude, paperctl start codex, or paperctl start pi) so the new session is routed through the local proxy.

The paperctl CLI won’t start (multiple orgs)

If you belong to more than one org and haven’t picked one, paperctl logs shows:

paperd: cannot derive inference upstream: no org selected — run `paperctl org select` or pass --upstream

Run paperctl org select, then paperctl init.

Claude Code can’t connect

Confirm ANTHROPIC_BASE_URL matches the proxy address in paperctl status. The address is set by daemon configuration and stays the same across restarts, so a mismatch usually means a typo or a changed proxy_listen setting. Re-run paperctl start claude to have the address resolved for you — or copy the proxy address from paperctl status and re-export it if you’re managing the env var yourself.

Model rejected

The backend’s model allowlist doesn’t include the model you requested. Contact the team to update the allowlist, or switch to a model that’s already enabled.

401 from the gateway

A 401 is one of two credentials being rejected — work out which:

• Your paper identity. paperctl status shows auth health; if it’s expired or unhealthy, paperctl login fixes it. For direct access, a 401 usually means the API key was revoked — create a new one from the console’s API keys page.
• The provider credential. On a transparent backend that’s your own API key or plan sign-in — renew it with the provider. On a managed backend, the stored team key may be wrong or expired — an admin recreates the backend with a fresh key.

Gateway stuck in Pending, or a backend shows Failed

Provisioning brings up real infrastructure; a new gateway can sit in Pending or Provisioning for a few minutes before Running, and the console’s Gateways page refreshes status live. Traffic only flows on a Running gateway with a ready backend. A Failed gateway or backend won’t repair itself — delete and recreate it, and contact support if it fails again. Before deleting a gateway others use, read what delete-and-recreate costs: its backends and any stored managed keys go with it, and traffic through it pauses until the replacement is Running.

The console shows onboarding again

Console onboarding progress is tracked in your browser, so a new browser or cleared storage shows the onboarding steps again even though your organization is fully set up. Nothing is wrong with your account or data — step through or dismiss it, and everything is where you left it.

A session appears, but shows 0 turns and unknown status

The row appearing means capture worked — turns, status, and cost are filled in by a processing pass after the content arrives, and a fresh session shows zeros until it runs. Interactive sessions usually fill in within a couple of minutes; short one-shot runs (an agent invoked with a single -p prompt) can take considerably longer. If an ordinary interactive session stays empty well past a few minutes, check paperctl logs for upload errors (a transcript upload: session pushed line means your side finished its job) and contact support with the session id. Sessions that haven’t been processed yet also don’t show up in search — indexing reads from the same processed data.

Your agent starts, but nothing is captured

Make sure you started your agent with the paperctl CLI:

paperctl start claude
paperctl start codex
paperctl start pi

If you started the agent directly (plain claude, codex, or pi), the paperctl CLI will not be able to capture the session.