# 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

```sh
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

```sh
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

```sh
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:

```sh
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.