@custral/cli package gives you a custral command that holds a real Custral session (not an API key), so it can act as you, across every organization you belong to.
The CLI is you. For unattended / CI use, prefer an API key with the REST API or
@custral/sdk instead. Those are org-scoped, server-to-server credentials.Install
Sign in
~/.custral/config.json (0600).
1
Run custral login
The CLI requests a device code and prints a verification URL + short code.
2
Approve in the browser
Open the URL, enter the code, and confirm. No password is ever typed into the terminal.
3
Session saved
The minted session is written to
~/.custral/config.json. Revoke it any time in Settings → Sessions.Commands
Switching orgs is instant and local. The session works for every org you belong to, so
org switch just changes which one subsequent commands target.
What custral api can reach
Every path is sent under /v1, so applications and v1/applications both mean /v1/applications. Internal API routes are out of reach by design.
The CLI holds your session, not an API key, and most of /v1 accepts only a key. So custral api works on the routes that also take a session:
Anything else (
records/…, objects, conversations, and so on) answers authorization_missing, because no key was sent. To call those, mint a key and use curl or the SDK:
custral api prints the data on success. On a failure it prints the error code and reqId, and exits with 1.
Connect to MCP
custral mcp wires Custral’s MCP server into your MCP client so an agent (Claude Code, Claude Desktop, Cursor, …) can search and manage your records and conversations. Because the MCP server is API-key authenticated, the command mints a scoped key on a “Custral CLI” application for you, then prints the endpoint and a paste-ready config for each client:
mcp:read, mcp:write, objects:read, records:read, records:write, conversations:read and conversations:write. So the agent can read your schema and view and manage records and conversations. It can’t read documents, tasks, usage or billing, and it can’t provision keys or webhooks (no applications:manage / webhooks:manage). For a wider reach, create a key with the scopes you want and pass it with --key. The plaintext key is shown once. It’s minted under an application named Custral CLI, which later runs reuse, and you can revoke it in Settings → Developers → Applications. Already have a key? Skip the minting:
Configuration
Staying up to date
When a newer@custral/cli is published, the CLI prints a one-line upgrade notice
to stderr (so it never interferes with piping custral api … output):
~/.custral/update-check.json) and the registry is polled at
most once a day in the background, so it never adds latency to a command, the
notice you see reflects the last check. Set CUSTRAL_NO_UPDATE_CHECK to turn it
off entirely.
Auth model
The CLI signs in as you withcustral login, the same way the web app does, and acts against whichever workspace you select. It is deliberately not an API-key client, which is why custral api reaches only the session-capable routes. See Authentication for when to use a session and when to use a key.
Troubleshooting
Could not start login. Check your connection or CUSTRAL_API_URL.
Could not start login. Check your connection or CUSTRAL_API_URL.
The CLI couldn’t reach the API to begin the device flow. Confirm you’re online and that
CUSTRAL_API_URL (if set) points at a reachable Custral API. It defaults to https://api.custral.com.The code expired before it was approved
The code expired before it was approved
Device codes are short-lived. Run
custral login again and approve promptly. If you keep missing the window, the URL printed after “or go straight to…” opens the approval screen with the code pre-filled.custral whoami shows the wrong organization
custral whoami shows the wrong organization
The session spans every org you belong to; only the current one changes. Run
custral org list to see your orgs, then custral org switch <slug>.custral api prints Not signed in. Run custral login.
custral api prints Not signed in. Run custral login.
There’s no session in
~/.custral/config.json. Run custral login.custral api prints The request body must be valid JSON.
custral api prints The request body must be valid JSON.
The third argument isn’t JSON. Wrap it in single quotes so your shell leaves the double quotes alone.
Commands fail with an auth error after a while
Commands fail with an auth error after a while
Your session may have been revoked (in Settings → Sessions) or expired. Run
custral logout then custral login to mint a fresh one.Related
Authentication
Sessions versus keys, and every scope.
MCP
The server
custral mcp connects you to.Applications & keys
The routes
custral api can reach.TypeScript SDK
Call the key-only routes from code.