receipt binary is one compiled file: it holds a session, switches workspaces, lists and calls gateway tools, authorizes providers, and writes MCP client configuration, without ever holding a provider credential itself. It already knows the hosted endpoint, so a plain receipt setup signs a fresh machine in with nothing to configure; you name a host only for a dev or self-hosted origin.
The server it talks to is Receipt Connect, the part of the MCP Gateway that holds your organization’s connections. That name appears in the CLI’s own output and in most of its error strings, so it is worth recognising before you meet it.
Install the CLI
One command, macOS and Linux.
Five-minute quickstart
Sign in, choose a workspace, call a tool.
Sign in and out
What setup, login and logout do, and the session file they leave behind.
Diagnose your setup
The read-only check on your endpoint, the gateway and your saved session.
Command reference
Flags, defaults and exit codes.
Environment and exit codes
Every variable the binary reads, and where it keeps your session.
Troubleshooting
Error strings, cause and fix.
Developer CLI from source
The larger in-repo CLI: receipts, jobs, Factory and simulation.
Two programs are named receipt
One is the released binary you install on your own machine. The other is the in-repo developer CLI, which only runs inside a Receipt git checkout. This tab documents the released binary, and keeps the developer CLI to its own section. A third build exists that you never invoke: Factory’s sandbox workers carry a cut-down receipt in their container image, with no sign-in verbs — its identity comes from an environment token.
They are not one program with two option sets. Command for command, the released binary is a subset: whoami, run, jobs, memory, debug, factory and the rest of the developer surface exist only in the other one. Sign-in and sign-out are not among the gaps — receipt setup, receipt login and receipt logout all live here.
Everything the released binary can do
The command surface is:setup— sign in, and install the Claude observer when the companion binary is presentlogin [prod|dev|local|<url>]— sign in only, without the connector summary or observer install; the target is an optional positionallogout— delete the saved session and sign outdoctor— check the endpoint, gateway and session without signing in (read-only)workspace— read and switch the workspace your session is bound totools— list, describe, and call gateway toolsmcp— print, install, and serve MCP client configurationconnect— authorize providers, inspect connections, and disconnect themimportandobserve— capture Claude Code activity--version, or-V— prints the build version; it works only as the entire command line
receipt logout deletes the active session and its matching per-target file. Run it with no session and it prints receipt logout: not signed in.
Parsing behaviour worth knowing before you hit it
The binary matches commands in a fixed order and the first match wins. Three consequences bite early.--help does not work on every command
tools, mcp and workspace are matched before the help check, so receipt tools --help, receipt mcp --help and receipt workspace --help never print help. They try to run instead; signed out, they hit the errors above. With a saved session they run their default subcommand: receipt mcp --help runs mcp status codex, receipt tools --help runs tools list, and receipt workspace --help fails with receipt workspace supports list, current, create, rename, use, and delete.
receipt connect list, receipt connect tools and receipt connect call are claimed before the help check too. Signed out, receipt connect list fails with Receipt Connect gateway is unavailable; run 'receipt setup' or set RECEIPT_CONNECT_TOKEN. The other two check their arguments first, so a bare receipt connect tools fails with receipt connect tools requires a connection id or provider:name before it looks for a session at all.
Help works everywhere else. receipt help, receipt -h, receipt --help and receipt connect help all print the same usage screen, and so does a trailing --help on any command the parser has not already claimed — receipt doctor --help and receipt setup --help print usage rather than running. Only --help is position-sensitive: a word after it becomes its value.
The word connect is optional
A leading connect is dropped before dispatch, so receipt status is receipt connect status and receipt aws is receipt connect aws.
Bare receipt is therefore receipt connect: it starts the interactive onboarding flow, which signs you in through the browser first unless a live session for that gateway is already saved. A browser opening where you expected a help screen is intended, not a bug.
A boolean flag can swallow the next word
--flag value consumes the following token as that flag’s value unless the token starts with two dashes. Boolean flags are not exempt, so:
no-open to the string "status" rather than true. The check is for the literal true, so the browser still opens. Put boolean flags last, or use the --flag=value form — for the browser flag, --open=false:
receipt --help extra fails the same way: help takes the value extra, so you get onboarding — a browser sign-in — instead of usage.
Setting RECEIPT_CONNECT_OPEN_BROWSER=0 also keeps the browser closed. A bare -- ends flag parsing, and a repeated flag accumulates with the last value winning.
tools, mcp and connect list|tools|call use a simpler parser of their own: --key value, --key=value and a bare --key as a boolean, with no -- terminator, and a repeated flag overwriting rather than accumulating.receipt workspace is stricter again. It recognises only a bare --json and --target <value> — --target=dev is ignored — and it drops any other flag silently while keeping the word after it as a positional. So receipt workspace create --server-url X My Team creates a workspace named X My Team.The two binaries side by side
Both use the same session store,
~/.receipt/session.json by default. Results go to standard output; errors go to standard error and set exit code 1. Environment and exit codes has the variables, the session files and the exit codes in full.
Next step: install the released binary.