claude setup-token: a one-year token for Claude Code

What claude setup-token does

claude setup-token runs your subscription sign-in once in a browser and gives you a long-lived token you can move to headless machines, containers and CI runners that don't have a browser. Here's how the command works at a glance.

Use the token in CI or on a server

1. On a machine that has a browser, run claude setup-token in your terminal and approve the sign-in in the browser window that opens, just like /login.
2. Copy the token printed to the terminal and save it in your CI system's secret store or server environment right away, because Claude Code doesn't save this token anywhere on disk.
3. Expose the secret to your job as the CLAUDE_CODE_OAUTH_TOKEN environment variable: run export CLAUDE_CODE_OAUTH_TOKEN=your-token on macOS, Linux and WSL, $env:CLAUDE_CODE_OAUTH_TOKEN = "your-token" in PowerShell, or set CLAUDE_CODE_OAUTH_TOKEN=your-token in Windows CMD.
4. Run Claude Code non-interactively with claude -p "query" (or pipe input in with cat file | claude -p "query"), which prints the response to stdout and exits.
5. Before the 1-year expiration is up, run claude setup-token again and replace the stored secret in your CI config, since each run generates a fresh one-year token.

# Once, on a computer with a browser
claude setup-token

# In the CI job, with the printed token stored as a secret
export CLAUDE_CODE_OAUTH_TOKEN="$CLAUDE_TOKEN_SECRET"
claude -p "Summarize the failing tests in this repository"

Use the token in GitHub Actions

1. Open claude inside a local clone of your repository and run /install-github-app (this only works with github.com repositories and requires the GitHub CLI signed in through gh auth login).
2. When prompted for authentication, choose to create a long-lived token with your Claude subscription; Claude Code will install the Claude GitHub App, save the token as the CLAUDE_CODE_OAUTH_TOKEN repository secret, push a branch with the workflow files, and open a pull request.
3. Merge that pull request into your repository.
4. Mention @claude in an issue or pull request comment to verify that the action responds.

If you'd rather set the workflow up by hand, install the Claude GitHub App on the repository, add the token from claude setup-token as the CLAUDE_CODE_OAUTH_TOKEN repository secret, and pass it to anthropics/claude-code-action@v1 using the claude_code_oauth_token input instead of anthropic_api_key, as the YAML example below shows.

name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
jobs:
  claude:
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
      id-token: write
      actions: read
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}

What a setup-token can't do

• It can only make model requests, so Remote Control sessions and claude.ai connectors don't work with it, though local MCP servers still do.
• Bare mode (claude --bare) doesn't read CLAUDE_CODE_OAUTH_TOKEN at all.
• Running /login while the variable is set switches only that active session, and Claude Code goes right back to reading CLAUDE_CODE_OAUTH_TOKEN the next time a session starts.
• It signs in with your own Claude subscription, so it requires a Pro, Max, Team or Enterprise plan and won't work on the Free plan.

Why Claude Code ignores your token

When more than one credential is present, Claude Code checks them in this order and uses the first one it finds:

1. Cloud provider credentials (Amazon Bedrock, Google Cloud, Microsoft Foundry)
2. ANTHROPIC_AUTH_TOKEN
3. ANTHROPIC_API_KEY
4. apiKeyHelper
5. CLAUDE_CODE_OAUTH_TOKEN
6. An Anthropic profile
7. The subscription login from /login

Limits, billing and other sign-ins

Every request the token makes counts against your subscription's Claude usage limits: the session limit that resets every five hours and the weekly limit. Both limits are shared across claude.ai, Claude Desktop and interactive Claude Code, so a busy CI pipeline will eat into the same allowance you use at your desk.

If you're on a Max plan, its monthly API credits ($100 on Max 5x, $200 on Max 20x) don't pay for claude -p when you're signed in with your subscription; those credits only cover claude -p when Claude Code runs with an API key from the Claude Console organization you linked. Organizations that want API-based billing can sign Claude Code in with a Claude Console account instead of a subscription.

Among all the ways to authenticate Claude Code, only the subscription sign-ins draw from your plan's usage limits:

Call Claude from your own code with your plan

A setup-token only signs in Claude Code. If you want to put your Claude Pro or Max plan behind an OpenAI-compatible API for your own scripts, apps and other tools, Plan2API turns your Claude subscription into an API by connecting your account at plan2api.com/connect through Claude's own sign-in page and giving you a p2a_ key for https://api.plan2api.com/v1, where requests run on the same plan limits.

Plan2API encrypts your connected login with HPKE (X25519) and AES-256-GCM so only your API key can unlock it, and it never stores your prompts or outputs (see the security details).