CLI authentication

Before interacting with the Sanity CLI, you need to login.

The Sanity CLI authenticates against your account through a browser-based OAuth flow, and stores the resulting session token in a single configuration file on your machine. This page covers the auth surface end-to-end: signing in, managing tokens, signing out, switching accounts, where the token is stored, and signing in through an SSO provider.

Sign in with sanity login

Run npx sanity login to open a browser window where you can choose an identity provider, sign in, and return to the CLI with an active session. After a successful login the CLI writes the session token to your local configuration file.

# Open the browser-based login flow
npx sanity login

# Sign in with a specific identity provider directly
npx sanity login --provider google

# Sign in with SSO using your organization slug
npx sanity login --sso my-org

# Print the login URL without opening a browser (useful on headless machines)
npx sanity login --no-open

# Authenticate non-interactively by piping a token to stdin
echo "$SANITY_AUTH_TOKEN" | npx sanity login --with-token

Useful flags: --sso <org-slug> for organizations that sign in through an identity provider, --sso-provider <name> to target a specific provider, --provider <name> to skip the picker for a known account, --with-token to read a token from stdin, and --no-open to print the login URL instead of launching a browser. See the login reference for a full list of options.

Sign out with sanity logout

Run npx sanity logout to invalidate the active session on the server and clear the local token. If the server reports the session was already invalid, the CLI still clears the local token and exits successfully.

Cannot delete session for robot user error

If npx sanity logout returns Cannot delete session for robot user - use delete token endpoint, your CLI is configured with a robot token (a long-lived API token) rather than a user session. Robot tokens do not have a server-side logout, so they have to be revoked through the tokens API instead:

# List robot tokens to find the ID you want to revoke
npx sanity tokens list

# Revoke the robot token by ID
npx sanity tokens delete <token-id>

Manage robot tokens with sanity tokens

Use the npx sanity tokens command to manage robot tokens (long-lived API credentials) from the CLI. The command has three subcommands:

  • npx sanity tokens list: list robot tokens in your project, with their IDs and labels.
  • npx sanity tokens add: create a new robot token with a label and a role.
  • npx sanity tokens delete <id>: revoke a robot token by ID.

For the full flag reference and command output, see Tokens CLI command reference.

Switch to a different account

To sign in as a different user, run npx sanity login again. The CLI invalidates your previous session, clears the local token, and writes the new session token in one step. You do not need to run npx sanity logout first.

Where the CLI stores your token

The Sanity CLI stores your session token in a single JSON file at ~/.config/sanity/config.json. This path is the same on macOS, Linux, and Windows. The CLI does not use OS-specific configuration directories.

The file is a JSON object. After signing in, it contains your authToken alongside the CLI's telemetry-consent record. Other transient fields (for example, telemetryDisclosed) may also be present:

{
  "authToken": "sk...",
  "telemetryConsent": "..."
}

To use a different config location (for testing, dev environments, or staging), set the SANITY_CLI_CONFIG_PATH environment variable to your chosen path. The CLI also reads ~/.config/sanity-staging/ when configured to use the staging environment.

Sign in through SSO

If your organization signs in through an identity provider, pass --sso <org-slug> to route the login flow to your IdP. The org slug is the short identifier used in your organization's Sanity URL.

# Sign in through your organization's SSO
npx sanity login --sso my-org

# Target a specific SSO provider configured for the organization
npx sanity login --sso my-org --sso-provider okta

Was this page helpful?

Previous

Introduction

Next

Generating types