[Feature] Allow switch from Max,etc to API and back w/o logout/login

[eoliphan]

It's a typical workflow during intense coding sessions, especially when running multiple claude code instances, to need to switch to API usage when you hit your Max (and presumably Pro) limits. Currently you have to logout and back in entirely to do this.

Also as i think about it, with that in place it'd be even more useful to have the ability to 'fall back' to API when you hit your Max/Pro limits. Presumably this would also have a couple options. Falling back when you hit the overall limit, or say when you want to stick to Opus and your Max config is about to fall back to Sonnet. Obviously with similar warnings to what we get today with the Opus->Sonnet model fallback , perhaps with a configurable confirmation as well.

[coygeek]

Hey, this is a fantastic feature request. I've run into this exact same workflow issue myself. When you're in the zone with a few instances running and hit the Max usage limit, having to /logout and then go through the /login process again really breaks the flow.

A simple command like /switch-auth or /use-api that lets you toggle to your pay-as-you-go API key for the current session would be a massive quality-of-life improvement.

Your idea for an automatic fallback is even better. I especially like the nuance you added:

• Fallback on limit: Automatically switch to the API key when the daily Max/Pro message limit is reached.
• Fallback to preserve model: This is the killer feature for me. I often want to stick with Opus, and getting the warning that I'm about to be downgraded to Sonnet is a workflow-stopper. Having an option to say "Yes, but use my API key to continue with Opus" would be perfect.

---

A possible workaround in the meantime

It's not as seamless as what you're proposing, but based on the docs, you could run two separate, parallel sessions with different authentication methods. The common-workflows documentation mentions using git worktree for this kind of isolation.

Here’s how you could set it up:

1. Create a separate worktree for your API-key-based work. This gives you a clean directory to work in that shares the same git history.

   # From your main project directory
   git worktree add ../my-project-api-key-session

2. Run your normal Max/Pro session in your primary project directory. Just cd into it and run claude as usual. You'll be logged in with your subscription.

   # --- Terminal 1 ---
   cd /path/to/my-project
   claude 
   # This instance uses your Max/Pro subscription

3. Run an API key session in the new worktree. In a second terminal, navigate to the new directory and set the ANTHROPIC_API_KEY environment variable before launching claude. The settings docs confirm this variable is used for authentication.

   # --- Terminal 2 ---
   cd ../my-project-api-key-session
   export ANTHROPIC_API_KEY="your-sk-ant-api-key-here"
   claude
   # This instance should now use your API key for billing

When you hit your limit in Terminal 1, you can just switch over to Terminal 2 to continue working without having to log out and back in.

It's definitely clunkier than a built-in feature, but it might save you some of the hassle of re-authenticating constantly.

But yeah, huge +1 from me on the core feature request. A seamless switch/fallback would be a game-changer. Hope the team sees this

[rthic23]

@coygeek using above setup 3 you posted doesn't pick up the api key when I use /logout in claude session and then export ANTHROPIC_API_KEY="your-sk-ant-api-key-here" and then use claude again. It brings back below screen and its not picking up the api key in env.

Steps below

# --- Terminal 2 ---
cd ../my-project-api-key-session
In claude session - hit /logout
export ANTHROPIC_API_KEY="your-sk-ant-api-key-here"
claude
# This instance should now use your API key for billing but rather goes the above onboarding screenshot

[coygeek]

@rthic23
Ah, great catch! Thanks for testing that out and reporting back. You've found a crucial detail I missed, and you're absolutely right. My apologies, my initial workaround was flawed.

Based on your screenshot and re-reading the docs, it seems the main interactive claude command prioritizes the OAuth login flow (the one triggered by /login) over the ANTHROPIC_API_KEY environment variable, especially after a /logout. When you log out, it clears the stored credentials, and on the next run, it defaults back to the interactive login prompt you screenshotted, ignoring the environment variable.

I think the key is in the settings documentation for ANTHROPIC_API_KEY: it says it's "typically for the Claude SDK (for interactive usage, run /login)". This suggests it's not meant as a standalone auth method to start an interactive session, but rather for headless/scripted use.

A better (though still imperfect) workaround

So, the git worktree idea is still good for file isolation, but we need to adjust the authentication part. The most reliable way to use the ANTHROPIC_API_KEY is with the non-interactive (-p or --print) flag.

Here’s an updated approach that should work:

1. Keep your main session (Terminal 1) as is. Run claude interactively, logged in with your Max/Pro subscription.

2. When you hit your usage limit, don't use /logout. Just leave that session running or exit it.

3. Open a second terminal (Terminal 2). In this terminal, you'll use the API key for one-off, "headless" commands.

   # --- Terminal 2 (for API usage) ---
   cd ../my-project-api-key-session
   
   # Set the API key for this terminal session
   export ANTHROPIC_API_KEY="your-sk-ant-api-key-here"
   
   # Now, run specific tasks using the -p flag. 
   # This WILL use the API key.
   claude -p "Refactor the authentication logic in user.ts and apply the changes." --allowedTools "Read,Edit"
   
   # Or pipe content to it
   cat src/utils.js | claude -p "Add JSDoc comments to this file." > src/utils_with_docs.js

This way, you never have to log out. Your primary terminal stays authenticated with your subscription, and your second terminal becomes your "API key toolkit" for running specific tasks when you're rate-limited.

This is obviously not as fluid as a full interactive session, which is exactly why your original feature request for a /switch-auth command or an automatic fallback mechanism is so needed. But hopefully, this headless approach provides a more reliable way to keep working without the constant re-authentication hassle.

Thanks again for pointing out the issue with the first suggestion! Definitely a +1 to getting this functionality built-in properly.

[rthic23]

@coygeek Thanks for the quick response! 👍 . Is there any workaround that I can make use of utilizing ANTHROPIC_API_KEY in interactive shell.

[coygeek]

@rthic23 Hey, great follow-up question! Yes, there is a way to get a full interactive shell using an API key, and you're right to ask—the headless (-p) mode is useful, but it's not the same as the real thing.

The interactive claude command prioritizes the standard login flow (the one that opens a browser). To override that and force it to use your ANTHROPIC_API_KEY for an interactive session, we need to use a more powerful feature from the settings called apiKeyHelper.

This is a bit of a setup.

Workaround: Using apiKeyHelper for an Interactive Session

The idea is to create a tiny script that just outputs your API key, and then tell Claude Code to run that script for authentication instead of asking you to log in.

Step 1: Create the Helper Script

This script's only job is to print your API key.

1. Create a dedicated script file in your user's Claude Code directory to keep things tidy:

   mkdir -p ~/.claude
   touch ~/.claude/get-api-key.sh

2. Open that file (~/.claude/get-api-key.sh) and add this content. Make sure to replace "your-sk-ant-api-key-here" with your actual key.

   #!/bin/bash
   echo "your-sk-ant-api-key-here"

3. This is a critical step: Make the script executable.

   chmod +x ~/.claude/get-api-key.sh

Step 2: Configure Your Project to Use the Script

Now, we'll tell Claude Code to use this script for this project only.

1. In your project's root directory, create a local settings file. This is perfect because it won't be committed to git.

   mkdir -p .claude
   touch .claude/settings.local.json

2. Open .claude/settings.local.json and add the following, pointing to the script we just made:

   {
     "apiKeyHelper": "~/.claude/get-api-key.sh"
   }

Step 3: Run Claude Code

Now, from that project directory, just run claude.

• If you're already logged in via the browser method, you should first run /logout.
• Then, when you start claude again, it should read your local settings, run the script to get the key, and drop you directly into an interactive session without opening a browser.

You can confirm it worked by running the /status command. It should show that you're authenticated via an API key instead of your usual Claude.ai or Console account email.

Hope this gets you the interactive workflow you're looking for! Let me know if it works.

[rthic23]

@coygeek awesome! I just tried it and works like a charm 🥇 . I have one last request. Now it works on project level with apiKeyHelper. Is there any way I can set this apiKeyHelper in global level?. So that api key is enabled in all sessions and projects. Sorry about back to back questions :(

[rthic23]

@coygeek Found it I got it working by setting the same apiKeyHelper in root ~/.claude/settings.json. Now it will use ANTHROPIC_API_KEY consistently for all sessions. Thank you so much. Great help 💯 !

[coygeek]

@rthic23 Awesome, you beat me to it! That's fantastic to hear.

Yep, you've nailed it. That's exactly the right way to do it. The settings files have a clear hierarchy, and you've found the correct spot for a user-level global default:

• ~/.claude/settings.json -> User Global: Applies to all your projects.
• .claude/settings.local.json -> Project Local: Applies only to that specific project and overrides the global setting.

So by putting the apiKeyHelper in your root ~/.claude/settings.json, you've effectively set your default authentication method to be your API key for any interactive session you start, which is exactly what you were looking for.

And absolutely no need to apologize for the questions! That's what these discussions are for. We're all figuring out the best workflows together. Your follow-up confirming the solution will probably help the next person who finds this thread.

Great detective work! Glad you got it all working. Cheers! 💯