Wrangler profiles - scoped authentication switching

[MattieTK]

Motivation

Wrangler authenticates one user at a time. Developers working across several accounts – personal, employer, multiple clients, staging versus production – re-run wrangler login to switch and lose the previous session each time. Workarounds abound: swapping ~/.wrangler config files by hand (community thread #189290), third-party tools such as CFMan and wrangler-accounts, and keeping separate Cloudflare users with narrowly-scoped roles. Two contributors have independently opened profile PRs (#11780, #12217), both citing AWS CLI profiles.

An OAuth login historically reached every account the user could touch, which is why #11513 asked for account-scoped tokens and why many people fell back to dashboard API keys (#13744). A login can now be scoped to specific accounts, so a profile can carry that narrower scope rather than reaching everything. Users can now authenticate to specific accounts on a user, but still have to run the login command every time they want to change what scopes they have access to, or use API keys. We want to make this easier to set up.

Proposal

A profile is a named login scoped to a chosen set of accounts, under wrangler auth:

• create [name] / delete [name] manage profiles. Creating or activating a missing or expired profile starts that profile's login, where you choose which accounts it may reach.
• activate [name] [dir=.] use a profile in a directory and its subdirectories.
• deactivate remove the profile from a directory and return to the next level up or the default, with a warning.
• login / logout operate on the default profile, as today; disallowed inside an activated directory.
• whoami / list show the active profile, its account, and where it was set; list profiles.

Resolution, highest first: CLOUDFLARE_API_TOKEN in the environment (effectively overrides profiles and uses that key), then an explicit --profile flag; then the nearest activated ancestor directory; then the default profile, which applies at the filesystem root and to anything not overridden. A subdirectory can override the profile above it by using activate on a different profile.

Within a profile, the account is chosen by the existing rule: the account_id in the Wrangler config, otherwise the user's locked selection. A command targeting an account outside the active profile fails with a clear, machine-readable error naming the account and profile, rather than falling back to another account. The same holds in an activated directory with an expired token: re-authenticate the profile, never silently switch.

The directory→profile binding is stored in a central per-machine registry.

Prior art

Directory-scoped credential selection is novel among cloud CLIs (AWS, gcloud and kubectl use one global context). Our motivation here is to enhance the ability for users to set up environments on their machine for agents to operate without having to actively switch profiles or provide such capabilities to their agent.

Non-goals

• Portable identity. Profiles are a local-machine convenience; CI, containers and other environments authenticate per-environment, typically with CLOUDFLARE_API_TOKEN.
• Resource-level scoping within an account, or custom roles. A profile uses the roles the user already holds; deeper account scoping is not yet complete.
• Secure token storage at rest, which is a separate workstream.
• Team-shared or committed profiles.

Note

We will not be removing wrangler login/logout at this stage nor any of the other top level scoped auth comments (eg. wrangler whoami) though this is the future direction for cf to nest authentication commands under auth.

[LukasMurdock]

Love this, direnv auth.

One thing I’d like to clarify is what “nearest activated ancestor directory” is relative to. Two coherent models: always resolve from the effective cwd, or for config-loading commands resolve from the selected config file’s directory. I think the least surprising Wrangler-specific behavior would be:

• For commands that load a Wrangler config, directory-profile resolution starts from the directory containing the resolved config file.
• For commands that do not load a Wrangler config, directory-profile resolution starts from the current working directory, after applying --cwd if present.

For example:

cd repo
wrangler deploy --config apps/site/wrangler.toml

If the bindings are:

repo/           → profile-a
repo/apps/site/ → profile-b

I would expect this command to use profile-b, since the selected config lives under repo/apps/site/.

For the user-facing CLI, would the help output look something like this?

ACCOUNT
  wrangler auth                   🔐 Manage authentication
  wrangler login                  🔓 Login to the default profile
  wrangler logout                 🚪 Logout from the default profile
  wrangler whoami                 🕵️ Retrieve your user information

wrangler auth

🔐 Manage authentication

PROFILE MANAGEMENT
  wrangler auth create <name>              ✨ Create a named profile and log in
  wrangler auth delete <name>              🗑️ Delete a named profile
  wrangler auth list                       📋 List profiles

DIRECTORY BINDINGS
  wrangler auth activate <name> [dir=.]    📌 Bind a profile to a directory and its subdirectories
  wrangler auth deactivate [dir=.]         ↩️ Unbind the profile from a directory

DEFAULT PROFILE
  wrangler auth login                      🔓 Login to the default profile
  wrangler auth logout                     🚪 Logout from the default profile

INSPECTION
  wrangler auth whoami                     🕵️ Show active profile, account, and where it was selected
  wrangler auth token                      🔑 Retrieve the current authentication token or credentials

Thank you for your work!

[MattieTK]

Thanks @LukasMurdock - from talking to @emily-shen I think we can support this expectation around config file locations so the profile activated at the location of the config file overrides the --cwd active profile if selected.

[emily-shen]

although i do want to add that all commands currently load config, regardless of whether or not that is 'necessary' from a user perspective 😅 - so to clarify, i think we should probably just always respect the cwd, unless --config is explicitly provided. does that track with your expectations?

[LukasMurdock]

Ah that makes sense. Thanks! My understanding is:

1. Resolve auth/profile
   1. CLOUDFLARE_API_TOKEN
   2. --profile
   3. nearest ancestor directory with an activated profile, starting from:
      • the config file’s directory, if --config is provided
      • otherwise, --cwd if provided
      • otherwise, cwd
   4. default profile
2. Resolve target account
   1. account_id in Wrangler config, or CLOUDFLARE_ACCOUNT_ID
   2. otherwise, the account selected by the resolved Wrangler login/profile

[xTudoS]

Within a profile, the account is chosen by the existing rule: the account_id in the Wrangler config, otherwise the user's locked selection.

Just for clarification: would we be able to set the account_id in wrangler.jsonc/wrangler.toml at both the global scope and per environment?

OAuth allows adding permission to all accounts that I have access within cloudflare when generating the token. Will be possible for the same Token deploy to all this accounts choosing via account_id , so one profile would have multiple account access?

[MattieTK]

Yes, a single profile would be able to be authorised against multiple accounts that a single user has access to.

And you can use the account_id in the wrangler configuration file as a failsafe against your profile having more access than one particular environment requires.

[xTudoS]

I can't wait to see that!