Skip to content

Auth commands

View as Markdown

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.

Terminal window
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.

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:

Terminal window
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:

{
"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.

Terminal window
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.

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

Terminal window
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.

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

Terminal window
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. thru auth keys create doesn’t accept --origin.

--agent <client> creates a key for an AI agent and connects the agent to the Thru MCP server at https://mcp.thru.org/mcp:

Terminal window
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:
ClientWhat the CLI does
claude-codeRuns claude mcp add --scope user --transport http thru https://mcp.thru.org/mcp with the Authorization header.
codexAdds [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.
cursorAdds mcpServers.thru to ~/.cursor/mcp.json.
vscodeAdds 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.

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:

Terminal window
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:

{
"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.

FlagMeaning
--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.
--printPrint the key (and, with --agent, the MCP URL) instead of installing it.
--no-skillWith --agent, don’t install the Thru skill.
--no-browserPrint the approval link and code without opening a browser.
--no-waitPrint the approval link and code, save the pending request and exit. Never opens a browser.
--resumeFinish a request started with --no-wait.

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

Terminal window
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.

  • 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.