The ralph CLI

ralph is the operator CLI. It signs you in through the browser, keeps and refreshes your tokens, and mints the agent keys that unattended agents use.

Point it at the API

export RALPH_API_URL=https://<api-host>

Or pass --api https://<api-host> to any command. Plain http is accepted only for a loopback host.

Sign in

ralph login --org <slug>

It opens the browser for Google sign-in and consent, then stores the credential for that API in $XDG_CONFIG_HOME/ralph/credentials.json (~/.config/ralph/… by default, %APPDATA%\ralph\… on Windows), readable only by you. A session acts in one organisation: the one you pass, or the one you pick at consent. A scope is an area at a level, such as bookings:write or people:read, and a higher level includes the ones below it. Without --scopes it asks for everything the CLI may be given: every area at its highest level.

Commands

Command What it does
ralph login [--org <slug>] [--scopes <list>] Sign in via the browser and store tokens for this API.
ralph whoami Show the signed-in identity, email and organisation memberships.
ralph token Print a valid access token, refreshing it when under 60 seconds remain.
ralph agent-key create --org <slug> --name <name> --scopes <list> Mint an agent key. The secret is printed once, on stdout.
ralph agent-key verify --org <slug> [--mcp <url>] [--role <role>] Check a key read from stdin: the API and, with --mcp, the MCP server must both answer as that key.
ralph agent-key revoke --org <slug> <key-id> Revoke an agent key by its id.
ralph logout Forget the stored credential for this API.

Mint a key for an agent

ralph agent-key create --org <slug> --name "Dispatch agent" --scopes bookings:write,people:read

The secret (rk_…) goes to stdout once, and the key’s id to stderr. A new key can do nothing until it’s given scopes, so name each one it needs. A key acts for you by default, or for --person <id>, and expires in a year unless you pass --expires-at.

Check it before you hand it over. The key is read from stdin, so it never appears in your shell history:

ralph agent-key verify --org <slug> --mcp https://mcp.ralphops.ai/mcp < key.txt

Errors and hints

  • The browser didn’t open. ralph login prints the sign-in URL too. Open it yourself.
  • A create lost its answer. create announces its Idempotency-Key before minting. Rerun with --idempotency-key <uuid> within 24 hours: if the first attempt did mint a key, you’re told which one, and no second key is made. After 24 hours the idempotency key counts as new, so a rerun mints a second agent key: revoke whichever you don’t use.
  • 403 on something the key should do. A key can do only what both its scopes and its person’s roles allow. verify --role admin checks the person’s role.