x401-cli lets you and your coding agent call endpoints that require proof of identity from a terminal.
When an endpoint answers with an x401 proof request, the user presents their credential from their Proof Cloud Wallet, and the CLI retries the request with the presented credential and prints the endpoint's answer.
In code, use x401-agent instead.
- Installation
- Quickstart
- Usage
- Use with agents
- Commands
- Options
- Environment variables
- Exit codes
- Links
- License
npm install -g @proof.com/x401-cliSign in to Proof's sandbox and request the sandbox test endpoint:
x401-cli login --sandbox
x401-cli fetch "https://try.proof.com/x401/protected?env=fairfax"Proof emails the user an approval link. The CLI waits for the approval and prints the endpoint's answer:
x401-cli: approval_required email j******@proof.com expires=2026-10-27T11:42:09Z id=ot7gzqj4p
x401-cli: 200 (238 B)
{"ok":true,"kind":"protected","credentials":{"proof_id_default":[{"credentialType":"ProofCredentialV1","format":"dc+sd-jwt","nonce":"afc8ffc9-e6cc-4a1d-9cd7-0c0635f264df","givenName":"Alexander J","familyName":"Sample","isOver18":true}]}}
--no-wait exits with code 5 while the request waits for the user's approval, and --timeout does
the same when the wait runs out. resume takes the request id that fetch printed, waits for the
approval and replays the request.
x401-cli fetch --no-wait "https://try.proof.com/x401/protected?env=fairfax"
x401-cli resume ot7gzqj4px401-cli cancel ot7gzqj4p--device signs in with a code instead of a local redirect, for example on a remote host or in a
container. The CLI opens the sign-in page in your browser when it can, and always prints the URL and
the code so that you can sign in from any device. Check that the page shows the same code, then
approve. The CLI waits for the approval.
x401-cli login --deviceOpening Proof in your browser to sign in.
If nothing opened, or to sign in from another device, go to:
https://api.proof.com/oauth/v2/device
and enter this code:
WDJB-MJHT
x401-cli: logged_in production (~/.config/proof/x401-cli/credentials.json)
token prints the access token.
export PROOF_ACCESS_TOKEN=$(x401-cli token --sandbox)- Pass
--jsonand readexit_code. - Pass a
--timeoutshorter than your tool's time limit, for example--timeout 9m. - On exit code 5, ask the user to present their credential from their Proof Cloud Wallet, and run
x401-cli resume <presentation_id> --json. - Run
resumefor a pending request rather thanfetchagain: eachfetchsends the user a new request.
| Command | Description |
|---|---|
login |
Signs the user in to Proof in the browser and stores the tokens |
logout |
Revokes and removes the stored tokens |
status |
Shows the stored logins |
token |
Prints the access token; signs in first when there is no login |
fetch <url> |
Requests the URL and presents the user's credential when the endpoint asks for one |
resume <id> |
Waits for a pending approval and replays the request, or prints the PROOF-RESPONSE for present |
cancel <id> |
Cancels a pending request |
present |
Turns a PROOF-REQUEST into a PROOF-RESPONSE |
| Option | Commands | Description |
|---|---|---|
--sandbox |
login, logout, status, token, fetch, present |
Uses Proof's sandbox |
--json |
all | Prints one JSON object on stdout: the response's status, headers and body, or error and exit_code |
--timeout <d> |
login, token, fetch, resume, present |
How long to wait for the sign-in or the approval, e.g. 9m (default 15m) |
--no-wait |
fetch, present |
Exits with code 5 while the approval is pending |
--no-browser |
login, token |
Prints the sign-in URL instead of opening the browser |
--device |
login, token |
Signs in with a code, without a local redirect; the sign-in page can open on any device |
-X, -H, -d |
fetch |
Method, header, body, as in curl; -d @file and -d @- read the body from a file or stdin |
-o <file> |
fetch |
Writes the body to a file |
--proof-request <v> |
present |
The PROOF-REQUEST value, - for stdin, @file |
| Name | Required | Default | Description |
|---|---|---|---|
PROOF_ACCESS_TOKEN |
no | none | Used instead of the stored login, no refresh |
| Code | Name | Meaning |
|---|---|---|
| 0 | Success. For fetch, the endpoint answered with any HTTP status |
|
| 1 | usage |
Invalid command or option |
| 2 | network |
The endpoint or Proof could not be reached |
| 3 | unauthorized |
No login, or Proof refused the token; run login |
| 4 | environment_mismatch |
The request is for a Proof environment you are not signed in to; run login for it |
| 5 | approval_pending |
The user has not approved yet; run resume |
| 7 | expired |
The request expired before the user approved |
| 8 | cancelled |
The request was cancelled |
| 9 | proof_rejected |
The endpoint rejected the presented credential |
| 10 | invalid_proof_request |
The endpoint's PROOF-REQUEST is not valid |
| 11 | rate_limited |
Too many requests; retry_after is in seconds |
| 12 | presentation_failed |
Proof answered with an error status or an unexpected body |