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

The Anthropic API key stored in your backend may be wrong or expired. Run paperctl login again — the wizard will prompt you to re-enter it.

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.