Auth commands
thru auth signs this machine in to Thru Developers 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.
Sign in
Section titled “Sign in”thru auth login # Approve in your browserthru auth login --no-browser # Print the approval URL and code instead of opening a browserAfter 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
Section titled “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:
thru auth login --no-wait --json # Prints the approval URL and code, then exitsthru auth login --resume # Waits for approval and finishes signing in--no-wait prints:
{ "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
Section titled “Check status”thru auth statusstatus 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
Section titled “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:
thru auth keys create --name cithru auth keys listthru auth keys revoke <KEY_ID>listandrevokeuse 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.
Send a key as Authorization: Bearer thru_..., or set THRU_API_KEY for the CLI.
Create a key
Section titled “Create a key”thru auth keys create --name ciEvery key you create needs your approval in the browser, even when this machine is signed in:
- The CLI prints an approval link and code, and opens your browser (pass
--no-browserto only print them). - Sign in to Thru Developers. If you have no account, signing in creates one, so you don’t need to run
thru auth loginfirst. - Choose the organization the key belongs to. The page lists the organizations where you can manage keys.
- 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. thru auth keys create doesn’t accept --origin.
Create a key for an AI agent
Section titled “Create a key for an AI agent”--agent <client> creates a key for an AI agent and connects the agent to the Thru MCP server at https://mcp.thru.org/mcp:
thru auth keys create --name <name> --agent claude-code- The key is tagged as an agent key for that client. Without
--name, it’s namedagent-<client>-<machine>. <client>is 1 to 32 lowercase letters, digits or-, starting with a letter or digit.- For
claude-code,codex,cursorandvscode, 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 withnpx skills add https://thru.org. Pass--no-skillto skip it. - Afterwards, reload MCP servers in the client, for example by starting a new session, to get the
thrutools.
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
Section titled “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:
thru auth keys create --name <name> --agent claude-code --no-wait --json # Prints the approval link and code, then exitsthru auth keys create --resume # Waits for approval, then installs or prints the key--no-wait prints:
{ "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
Section titled “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
Section titled “Sign out”thru auth logoutlogout 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
Section titled “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 setTHRU_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.