claude setup-token: Safely Hand Your Permissions to an Automation Server

Sometimes you want an automation server like GitHub Actions to call Claude on your behalf. But a person can't log in every single time. For this, claude setup-token issues "a key that can use your permissions in your place."

Definition (what it is)

claude setup-token is the command that issues a long-lived token for use in CI or scripts. The issued token is not saved anywhere — it's only printed to the screen. Using it requires a subscription.

Here, a token is best understood as "a digital key that lets something pass authentication in place of a person." CI is short for "Continuous Integration," an automation system that automatically checks and runs your code every time you push it. A long-lived token is a key that stays valid for a long time, so once you issue it, an automation server can call Claude under your account without needing a human's hands each time.

This command is for advanced automation, so there's little immediate need for it as a beginner — but it's good to know that "there's a proper way to hand permissions to automation."

How to use it (by difficulty)

Basic — Issuing a token

claude setup-token

Running this single line prints a long-lived OAuth token to the screen. OAuth can be understood as "a standard way to delegate permissions without handing over your password directly." Copy the printed token and register it on your automation server, and that server can use Claude with your account's permissions.

Common pitfalls

• A token is like a password. You must never post the printed value as-is on a blog, in chat, or in a public repository. When registering it, mask it with a placeholder like <your-token>, and put the actual value in a secure secret store (e.g., GitHub Secrets).
• This command doesn't save the token — it only prints it. Once you close the screen you can't see it again, so register it somewhere safe right after issuing it.
• It's a feature that requires a subscription, so issuance may fail if you don't have one.

Real-world example

When you want GitHub Actions to call Claude under your account for automatic reviews or tasks whenever code changes, issue a token with claude setup-token and register it in the Actions secret store. Then the automation runs smoothly under your permissions without anyone having to log in.

Taking it further

If you use this token for automation tasks that run on a schedule — for example, checking code or generating documents every night — the work proceeds even when no one is watching. That said, since you're handing over permissions, it's important to build the habit of storing tokens securely and revoking ones you no longer use.

Summary

claude setup-token is the command that issues a long-lived token for CI and scripts. Register the issued token on your automation server, and it can call Claude under your account without a human's involvement. Treat the token like a password — never expose it in a public place, and keep it in a secure secret store.

Based on: Claude Code v2.1.154 (2026.05)