receipt binary is a fixed sentence, so the fastest route to a fix is to search this page for the message you got. Two commands resolve most of them: receipt doctor, which reports without changing anything, and receipt setup, which signs you in again.
Start with doctor
receipt doctor resolves which host you are pointed at, probes the gateway and the sign-in origin, and prints the saved session with its expiry. It never opens a browser and never signs you in, so it is safe to run at any point.
0 when the gateway answers a health check with a 2xx, the sign-in origin answers at all, and any saved session is live and matches the gateway; it exits 1 otherwise. Three causes account for most of what it flags:
- You are not signed in, or the session file was removed.
- The token expired. CLI tokens last 12 hours and there is no refresh.
- You are pointed at the wrong host — usually a
localor self-hosted target whose stack is not running, or a session saved for a different target.
Install and first launch
Re-running the installer overwrites the binary at the same path and leaves
~/.receipt alone, so your saved session survives an upgrade. receipt mcp install codex records an absolute path to the binary in the Codex config, so that entry survives an in-place upgrade too. If you move the binary instead — a different RECEIPT_CLI_BIN_DIR, or a manual install — Codex keeps calling the old path; run receipt mcp remove codex, then receipt mcp install codex, to repoint it. See Install the CLI.Endpoint and target
Signing in
The approval page has its own messages.
Select a workspace first appears with Receipt Connect credentials are stored at the workspace level. Open Receipt, select a workspace, then run the CLI command again. — the browser half of the workspace error above. This Receipt Connect code is invalid or expired. means the code is unknown or past its ten minutes. This Receipt Connect code was already used. Run the CLI command again. means you approved the same code twice; each one is single-use. A successful approval reads Receipt Connect is approved, with You can return to the terminal. This page can be closed.
Sessions and authorization
A session file that will not parse, or that is missing its gateway URL, token or organization id, is treated as no session rather than as an error — you get
not signed in and the fix is receipt setup. A file the CLI cannot read at all, such as one with wrong permissions, is different: the read throws and the command exits 1 with the underlying error. Deleting ~/.receipt/session.json and signing in again clears both.Connecting a provider
Tools and MCP clients
Observing Claude Code
When the CLI opens a browser you did not ask for
Runningreceipt with no arguments, or receipt --help <word>, starts provider onboarding — which begins a real device login. Ctrl-C cancels the poll, and the code expires on its own after 10 minutes. Use receipt --help alone for help. The CLI overview covers this and the other parsing traps.
Exit codes
The binary uses0 for success and 1 for every failure, including a device-login failure, a rate limit, a rejected token and any validation error. receipt doctor also exits 1 when its checks do not pass. The one code that does not come from the CLI itself is 137 on macOS, which is the operating system killing a quarantined copy of the binary before it runs. The full list, with the environment variables each command reads, is in Environment and exit codes.
Hosted, local, and automation
Hosted. There is nothing to configure.receipt doctor, then receipt setup.
A local or self-hosted stack. Set the gateway origin and the sign-in origin — RECEIPT_CONNECT_LOCAL_SERVER_URL and RECEIPT_CONNECT_LOCAL_AUTH_URL for --target local — then run receipt doctor --target local before receipt setup --target local. The most recent setup decides which target workspace, tools and mcp use, so a plain receipt setup flips you back to the hosted app.
CI and sandboxes. Export RECEIPT_CONNECT_GATEWAY_URL and RECEIPT_CONNECT_TOKEN together — either one alone fails with the message above instead of falling back to your saved session — and gate the job on the exit code of receipt doctor --json. The whole recipe, including the organization id, an isolated config directory and browser suppression, is in Environment and exit codes.
If a message is not here, check whether it came from the gateway rather than the CLI — MCP Gateway troubleshooting covers the server side — or ask through Getting help.
Next step: meet the developer CLI that runs from source.