claude-code - 💡(How to fix) Fix [DOCS] Authentication docs omit `/login` behavior when `CLAUDE_CODE_OAUTH_TOKEN` is set [1 participants]

Documentation Type

Unclear/confusing documentation

Documentation Location

https://code.claude.com/docs/en/authentication

Section/Topic

Credential management / Authentication precedence

Current Documentation

The authentication docs currently say:

When multiple credentials are present, Claude Code chooses one in this order:

1. CLAUDE_CODE_OAUTH_TOKEN environment variable. A long-lived OAuth token generated by claude setup-token. Use this for CI pipelines and scripts where browser login isn't available.
2. Subscription OAuth credentials from /login. This is the default for Claude Pro, Max, Team, and Enterprise users.

The environment variable reference also says:

CLAUDE_CODE_OAUTH_TOKEN | OAuth access token for Claude.ai authentication. Alternative to /login for SDK and automated environments. Takes precedence over keychain-stored credentials.

The quickstart page says:

Once logged in, your credentials are stored and you won't need to log in again. To switch accounts later, use the /login command.

These pages do not explain what happens if an interactive session starts with CLAUDE_CODE_OAUTH_TOKEN and the user then runs /login.

What's Wrong or Missing?

Claude Code v2.1.118 fixed /login having no effect in a session launched with CLAUDE_CODE_OAUTH_TOKEN by clearing the env token so stored disk credentials take effect.

The current docs describe credential precedence and /login separately, but they do not document this interaction. As written, the docs imply that CLAUDE_CODE_OAUTH_TOKEN simply outranks stored /login credentials, without explaining that an interactive re-login now clears the session's env-token auth so the newly stored credentials become active.

That leaves an important user-visible behavior undocumented:

• CLAUDE_CODE_OAUTH_TOKEN is presented as an alternative to /login for automation
• /login is presented as the way to switch accounts later
• but the docs never explain how /login behaves when the current session was launched with CLAUDE_CODE_OAUTH_TOKEN

Suggested Improvement

Add a short note under Authentication precedence (and mirror it in the env var reference) explaining that:

1. CLAUDE_CODE_OAUTH_TOKEN is primarily for CI, scripts, and automated environments.
2. If an interactive Claude Code session was launched with CLAUDE_CODE_OAUTH_TOKEN and the user runs /login or claude auth login, Claude Code clears that session's env-token auth so the newly stored disk credentials take effect.
3. Users who want to switch accounts interactively should use /login, then verify the active auth method with /status.

This would make the precedence docs and the quickstart guidance consistent with the v2.1.118 behavior.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 3 pages affected

Source: Changelog v2.1.118

Exact changelog entry:

Fixed /login having no effect in a session launched with CLAUDE_CODE_OAUTH_TOKEN — the env token is now cleared so disk credentials take effect