Feature request: Option to prefer subscription auth over ANTHROPIC_API_KEY

[gmelli]

Summary

Request native configuration option to prefer subscription auth over environment API key, eliminating the need for env -u ANTHROPIC_API_KEY workaround.

Current Behavior

When ANTHROPIC_API_KEY is set in the environment, Claude Code CLI uses it for authentication instead of the subscription-based OAuth flow.

Problem scenario:

• User has API key set for other tools (Python scripts, direct API calls)
• User wants Claude Code to use their Claude subscription auth
• No native way to tell Claude Code to ignore the env API key

Current workaround:

alias claude='env -u ANTHROPIC_API_KEY /opt/homebrew/bin/claude'

This works but is non-obvious and requires shell knowledge.

Requested Behavior

Add configuration option to prefer subscription auth even when API key is present.

Option A: Config file setting

// ~/.claude/settings.json
{
  "auth": {
    "prefer_subscription": true
  }
}

Option B: CLI flag

claude --prefer-subscription "query"

Option C: Environment variable

export CLAUDE_CODE_PREFER_SUBSCRIPTION=true

Rationale

1. Common use case: Power users often have API keys for multiple purposes
2. Subscription benefits: Better rate limits, included in plan, no separate billing
3. Discoverability: Native config is more discoverable than env -u trick

Acceptance Criteria

• User can configure Claude Code to prefer subscription auth
• Configuration persists across sessions
• Works regardless of ANTHROPIC_API_KEY being set
• Documentation updated to explain auth precedence

[Jaakkonen]

AFAIK it prefers subscription over the API key by default. It'll prompt whether you want to use subscription on the first startup if the ANTHROPIC_API_KEY env var is present.

[github-actions]

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.

[github-actions]

This issue has been automatically closed due to 60 days of inactivity. If you're still experiencing this issue, please open a new issue with updated information.

[github-actions]

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.