---
title: Auth commands
description: Sign in to Thru Developers from the CLI, get an API key for RPC
  calls, create keys for CI and AI agents, and manage your organization's API
  keys.
source_url:
  html: https://thru.org/docs/cli-reference/auth-commands/
  md: https://thru.org/docs/cli-reference/auth-commands.md
---

# Auth commands

`thru auth` signs this machine in to [Thru Developers](https://dev.thru.org/) and gives the CLI an API key for Thru’s public RPC endpoints. Signing in creates your account on first use (GitHub, Google or X).

Without a key, RPC calls are limited to 10 weighted requests per second per IP address. See [Rate limits and API keys](https://thru.org/docs/api-ref/rate-limits.md).

## Sign in

```bash
thru auth login               # Approve in your browser
thru auth login --no-browser  # Print the approval URL and code instead of opening a browser
```

After you approve, the CLI stores this machine’s credentials. It also creates an API key named `CLI on <machine>` in your organization. That key is sent automatically to `rpc.betanet.thru.org`, and never to other endpoints. Signing in again on the same machine replaces that key.

### From an AI agent or a script

An agent usually waits for each command to exit, so it can’t show the approval URL while `thru auth login` is waiting. Split the login in two:

```bash
thru auth login --no-wait --json  # Prints the approval URL and code, then exits
thru auth login --resume          # Waits for approval and finishes signing in
```

`--no-wait` prints:

```json
{
  "auth": {
    "status": "pending",
    "verification_uri_complete": "https://dev.thru.org/device?user_code=ABCD2345&ref=cli",
    "user_code": "ABCD2345",
    "expires_in": 600,
    "next": "thru auth login --resume"
  }
}
```

Show `verification_uri_complete` to a person, who opens it and approves, then run `thru auth login --resume`. The pending login is kept in an owner-only file until it expires (10 minutes) or completes.

## Check status

```bash
thru auth status
```

`status` shows:

- the signed-in account;
- this machine’s API key;
- your organization and its rate limits;
- whether RPC calls to the configured endpoint send the key.

## Organization API keys

The key from `thru auth login` is tied to this machine. For CI, servers, other machines and AI agents, create named keys:

```bash
thru auth keys create --name ci
thru auth keys list
thru auth keys revoke <KEY_ID>
```

- `list` and `revoke` use this machine’s login. They act on the organization this machine’s key lives in, and you need to be an owner or admin there.
- Rate limits are set per organization by Thru. All keys in an organization share them.
- You can also manage keys in [Thru Developers](https://dev.thru.org/keys).

Send a key as `Authorization: Bearer thru_...`, or set `THRU_API_KEY` for the CLI.

### Create a key

```bash
thru auth keys create --name ci
```

Every key you create needs your approval in the browser, even when this machine is signed in:

1. The CLI prints an approval link and code, and opens your browser (pass `--no-browser` to only print them).
2. Sign in to Thru Developers. If you have no account, signing in creates one, so you don’t need to run `thru auth login` first.
3. Choose the organization the key belongs to. The page lists the organizations where you can manage keys.
4. Approve. The approval creates only this one key.

Without `--agent`, the CLI then prints the key once. Store it in your secret environment right away; it can’t be retrieved later.

To restrict a key to browser origins, create it, then set its allowed origins at [dev.thru.org/keys](https://dev.thru.org/keys). `thru auth keys create` doesn’t accept `--origin`.

### Create a key for an AI agent

`--agent <client>` creates a key for an AI agent and connects the agent to the [Thru MCP](https://thru.org/docs/api-ref/thru-mcp/overview.md) server at `https://mcp.thru.org/mcp`:

```bash
thru auth keys create --name <name> --agent claude-code
```

- The key is tagged as an agent key for that client. Without `--name`, it’s named `agent-<client>-<machine>`.
- `<client>` is 1 to 32 lowercase letters, digits or `-`, starting with a letter or digit.
- For `claude-code`, `codex`, `cursor` and `vscode`, the CLI installs the key into the client’s MCP configuration and never prints it, so the key stays out of the agent’s transcript:

| Client | What the CLI does |
| - | - |
| `claude-code` | Runs `claude mcp add --scope user --transport http thru https://mcp.thru.org/mcp` with the `Authorization` header. |
| `codex` | Adds `[mcp_servers.thru]` to `~/.codex/config.toml` (or `$CODEX_HOME/config.toml`), reading the key from `THRU_MCP_API_KEY`. It saves the key to an owner-only file under `~/.thru/cli` and prints the `export THRU_MCP_API_KEY=...` line to add to your shell profile. |
| `cursor` | Adds `mcpServers.thru` to `~/.cursor/mcp.json`. |
| `vscode` | Adds `servers.thru` to VS Code’s user `mcp.json`. |

- The CLI keeps the other entries in these files and saves the previous file as `<file>.bak`.
- For any other client, or with `--print`, the CLI prints the key once together with the MCP URL instead of installing it.
- With `--agent`, the CLI also installs the Thru skill with `npx skills add https://thru.org`. Pass `--no-skill` to skip it.
- Afterwards, reload MCP servers in the client, for example by starting a new session, to get the `thru` tools.

`THRU_MCP_URL` overrides the MCP URL the key is installed for. Use it only for testing against another deployment.

### Create a key from an AI agent or a script

An agent waits for each command to exit, so it can’t show the approval link while `thru auth keys create` is waiting. Split the command in two:

```bash
thru auth keys create --name <name> --agent claude-code --no-wait --json  # Prints the approval link and code, then exits
thru auth keys create --resume                                            # Waits for approval, then installs or prints the key
```

`--no-wait` prints:

```json
{
  "auth_key": {
    "status": "pending",
    "verification_uri_complete": "https://dev.thru.org/cli/keys?code=WXYZ-2345&ref=cli",
    "user_code": "WXYZ-2345",
    "expires_in": 600,
    "next": "thru auth keys create --resume"
  }
}
```

Show `verification_uri_complete` to a person, who opens it and approves. Then run `thru auth keys create --resume`. It uses the options you gave with `--no-wait`, so it takes no other flags. The pending request is kept in an owner-only file until it expires (10 minutes) or completes.

### `keys create` flags

| Flag | Meaning |
| - | - |
| `--name <NAME>` | Name of the key, for example the service or CI job that uses it. Default with `--agent`: `agent-<client>-<machine>`. |
| `--agent <CLIENT>` | Tag the key as an agent key for this client and install it for `claude-code`, `codex`, `cursor` or `vscode`. |
| `--print` | Print the key (and, with `--agent`, the MCP URL) instead of installing it. |
| `--no-skill` | With `--agent`, don’t install the Thru skill. |
| `--no-browser` | Print the approval link and code without opening a browser. |
| `--no-wait` | Print the approval link and code, save the pending request and exit. Never opens a browser. |
| `--resume` | Finish a request started with `--no-wait`. |

Pass `--name`, `--agent`, or both. `--resume` takes no other flags.

## Sign out

```bash
thru auth logout
```

`logout` revokes this machine’s sign-in and its `CLI on <machine>` key, and clears the local credentials. Named keys are not affected.

## When the CLI suggests signing in

- **First run without a key.** The first time you run a command against an official endpoint without a key, the CLI prints a one-time note.
- **After a rate-limit error without a key.** The CLI prints a hint: run `thru auth login`, or set `THRU_API_KEY`.

In an interactive terminal, both also ask `Sign in now? [Y/n]`. They never prompt with `--json` or `--quiet`, or when input or output is not a terminal.

For credential storage, `THRU_DEVELOPERS_URL` and the other environment variables, see [Global flags and configuration](https://thru.org/docs/cli-reference/global-flags-and-config.md#developers-authentication).
