Skip to main content
Most unblocked commands — including the MCP server and every context-* command — need to call the Unblocked API on your behalf. Authentication is how you grant that access.

​
Interactive auth

Runs the OAuth authentication flow:
  1. The CLI prints a login URL and, when a browser is available, opens it for you.
  2. You sign in to Unblocked and authorize the session.
  3. The CLI stores the resulting credential securely. Subsequent commands reuse it until it expires or you sign out with unblocked uninstall.
On headless Linux with a controlling terminal, the CLI skips browser launch. Open the printed URL on another device, then enter the displayed login code in the terminal. If no controlling terminal is available, use a personal or team API token instead. macOS stores the cached credential in Keychain. Linux stores the OAuth refresh credential at ~/.unblocked/auth/oauth-refresh-token, with the directory restricted to its owner and the file created with owner-only permissions. The install-mcp.sh quick install script triggers this flow automatically at the end of its run. If you installed with install.sh (CLI only), run unblocked auth manually before using any other command.

​
Headless authentication

In CI runners, containers, remote shells, and other noninteractive environments, use a personal or team API token. The same tokens that power Unblocked MCP in CI work with the CLI. Point the CLI at a file populated by your secret manager:
This works with Docker, Kubernetes, systemd credentials, CI secret files, and similar secret mounts. The secret manager can own the file; the CLI only needs permission to read it.

​
Unblocked credential file

To store a dedicated token on a persistent Linux host, pipe it to the CLI:
The CLI stores the token at ~/.unblocked/auth/agent-token, with the directory restricted to its owner and the file created with owner-only permissions. Piping the token avoids placing it in shell history or process arguments.

​
Environment variable

For short-lived jobs, you can provide the token directly in the environment:
Environment variables can be visible to child processes and debugging tools, so prefer a secret-mounted file when your platform supports one. The CLI does not automatically load .env files. If more than one source is configured, the CLI checks UNBLOCKED_API_TOKEN, then UNBLOCKED_API_TOKEN_FILE, then the Unblocked credential file. See the per-agent guides for creating tokens, including the Claude Code headless automation guide.

​
Signing out

To clear the cached credentials along with all other local Unblocked state, run unblocked uninstall.