@leeguoo/wrangler-accounts 1.2.0 → 1.2.2

package/README.md

@@ -74,15 +74,47 @@ wrangler-accounts exec <name> -- <cmd> [args]   # one command
 wrangler-accounts login <name>                  # isolated OAuth login
 wrangler-accounts default [name | --unset]      # manage persistent default
 wrangler-accounts whoami [--profile <name>]     # show resolved identity
-wrangler-accounts list
+wrangler-accounts list                          # fast table (name/status/expires/identity)
+wrangler-accounts list --deep                   # authoritative check via wrangler whoami
+wrangler-accounts list --json                   # structured output for scripts
 wrangler-accounts status
 wrangler-accounts save <name>                   # snapshot current Wrangler config
 wrangler-accounts sync <name>                   # refresh a profile from current login
 wrangler-accounts sync-default                  # refresh the default profile
 wrangler-accounts remove <name>
 wrangler-accounts gc [--older-than 1h]          # clean stale shadow HOMEs
+-v, --version                                   # print version
 ```
 
+### `list` output
+
+Fast default (no network calls — read from saved `config.toml` only):
+
+```
+Default: work
+
+  NAME            STATUS  EXPIRES              IDENTITY
+* work            valid   in 47m (2026-04-10)  work@example.com / 0123456789abcdef0123456789abcdef
+  personal        valid   in 53m (2026-04-10)  me@example.com / fedcba9876543210fedcba9876543210
+
+Legend: * = default profile, EXPIRED = access token past expiration_time (wrangler may still auto-refresh)
+        STATUS is derived from the saved file only. For a live check that runs 'wrangler whoami' against Cloudflare,
+        pass --deep (slower, makes network calls).
+```
+
+Authoritative `--deep` check (spawns `wrangler whoami` in a shadow HOME per profile, ~1s each, network required):
+
+```
+[wrangler-accounts] running deep check (wrangler whoami) for 2 profile(s)...
+  NAME            STATUS  EXPIRES              VERIFIED                                     IDENTITY
+* work            valid   in 47m (2026-04-10)  ✓ ok                                         work@example.com / ...
+  personal        valid   in 53m (2026-04-10)  ✗ not logged in (refresh token may be revoked) me@example.com / ...
+```
+
+**When to use `--deep`**: when you actually need to know whether a profile still works. The default fast check only reads the saved `expiration_time`, which can lie in both directions — it can't tell you if Cloudflare has revoked the refresh token, and it flags fine profiles as `EXPIRED` just because their access token is past its 1-hour lifetime (wrangler auto-refreshes those transparently).
+
+The `--json` output includes the same fields as the table plus raw `expirationTime`, `isDefault`, `isActive`, and (with `--deep`) `verified`, `verifyError`, and `liveIdentity`.
+
 ## Profile resolution order
 
 When you run `wrangler-accounts <wrangler-args>`, the active profile is resolved in this order:
@@ -114,7 +146,9 @@ When you run `wrangler-accounts <wrangler-args>`, the active profile is resolved
     --backup            Backup current config on use (default)
     --no-backup         Disable backup on use
     --unset             With 'default': clear the persistent default
+    --deep, --verify    With 'list': run wrangler whoami per profile for live verification
     --older-than <dur>  With 'gc': age threshold (e.g. 1h, 30m, 7d)
+-v, -V, --version       Print version
 -h, --help              Show help
 ```
 
@@ -130,10 +164,28 @@ Inside an isolated session, these are automatically set for the child process:
 - `HOME` — the shadow HOME
 - `WRANGLER_PROFILE` / `WRANGLER_ACCOUNT` — current profile name (useful for shell prompt integration)
 - `WRANGLER_ACCOUNT_REAL_HOME` — path to your real home (escape hatch)
-- `WRANGLER_REGISTRY_PATH`, `WRANGLER_CACHE_DIR`, `WRANGLER_LOG_PATH` — pointed back at real HOME so Miniflare dev registry, workerd cache, and debug logs are shared across profiles
+- `WRANGLER_CACHE_DIR` — **per-profile**, points at `<profilesDir>/<name>/cache/`. Holds wrangler's `wrangler-account.json` (selected account ID), `pages-config-cache.json`, etc. Isolating this is critical: see "What is and isn't isolated" below.
+- `WRANGLER_REGISTRY_PATH`, `WRANGLER_LOG_PATH` — pointed at real HOME so Miniflare dev registry and debug logs are shared across profiles (cross-profile dev worker discovery is intentional)
 - `CLOUDFLARED_PATH` — set when `cloudflared` is on your PATH
 - `WRANGLER_SEND_METRICS=false`
 
+## What is and isn't isolated
+
+`wrangler-accounts` isolates the things that determine **which account a wrangler command targets**, but deliberately shares some state for performance and ergonomics. Know the boundary:
+
+| State | Location | Isolated? |
+|---|---|---|
+| OAuth credentials (`config.toml`, refresh token) | shadow `$HOME/.wrangler/config/default.toml` → symlink to per-profile file | ✅ per profile |
+| Account-id cache (`wrangler-account.json`) | `WRANGLER_CACHE_DIR` = `<profilesDir>/<name>/cache/` | ✅ per profile |
+| Pages config cache | same as above | ✅ per profile |
+| Miniflare dev registry | `WRANGLER_REGISTRY_PATH` = `$HOME/.wrangler/registry` | ❌ **shared** (intentional — local dev workers discover each other across profiles) |
+| Wrangler debug logs | `WRANGLER_LOG_PATH` = `$HOME/.wrangler/logs` | ❌ **shared** (append-only) |
+| Project-local state (`./.wrangler/state/`, `./node_modules/.cache/wrangler`) | inside the project directory | ❌ **shared at project level** — same project from two profiles uses the same project-local state. If you hit a "wrong account" symptom, clearing `./.wrangler/state/` is a good first step. |
+| `cloudflared` binary cache | `~/.wrangler/cloudflared/` or `$CLOUDFLARED_PATH` | ❌ shared (binary, not account-scoped) |
+| Shell history, `.npmrc`, `.gitconfig`, `.ssh/` etc. | symlinked through to real `$HOME` | ❌ shared by design (so `exec` subshells feel like a normal terminal) |
+
+> **Why this matters**: in 1.2.1 and earlier, `WRANGLER_CACHE_DIR` was pointed at real `$HOME/.wrangler/cache`, which meant `wrangler-account.json` was shared across profiles. Profile A's OAuth token could end up paired with profile B's cached account ID, causing wrangler to write resources to the wrong account *silently*. Fixed in 1.2.2 by per-profile `WRANGLER_CACHE_DIR`. Upgrade if you're on ≤1.2.1.
+
 ## Breaking changes in 1.0
 
 - **`-p` is now `--profile`** (was `--profiles` in 0.1.x). Use the long form `--profiles <path>` to specify the profiles directory.
@@ -162,10 +214,76 @@ The profiles directory defaults to:
 - Saved OAuth sessions can expire. If a profile is expired, running it will stop and tell you to run `wrangler-accounts login <name>` again.
 - Backups from the deprecated `use` command are hidden from `list` and `status` unless you pass `--include-backups`.
 
-## Discoverability (SEO / GEO / AI search)
+## FAQ
+
+### How do I use Cloudflare Wrangler with multiple accounts?
+
+`wrangler` itself only supports one OAuth login at a time — running `wrangler login` overwrites `~/.wrangler/config/default.toml`, forcing you to re-login every time you switch accounts. `wrangler-accounts` saves each login as a named profile and runs `wrangler` inside a per-invocation **shadow HOME**, so different shells can use different Cloudflare accounts in parallel.
+
+```bash
+npm i -g @leeguoo/wrangler-accounts
+wrangler-accounts login work
+wrangler-accounts login personal
+wrangler-accounts --profile work deploy
+wrangler-accounts --profile personal tail my-worker
+```
+
+### How do I switch between Cloudflare Workers accounts without logging out?
+
+Use `wrangler-accounts --profile <name>` for a single command, or `wrangler-accounts default <name>` to set a persistent default. Neither touches your existing `~/.wrangler/config/default.toml`; profiles live in their own directory.
+
+### Can I run `wrangler dev` on one Cloudflare account while deploying to another?
+
+Yes. That's the whole point of the shadow HOME isolation — each shell gets its own temporary HOME with the profile's OAuth config, so two invocations never share state.
+
+```bash
+# terminal 1
+wrangler-accounts --profile work tail my-worker --format pretty
+
+# terminal 2
+wrangler-accounts --profile personal dev
+```
+
+### How do I use Wrangler with multiple accounts in CI?
+
+**Don't use `wrangler-accounts` in CI.** Use native env vars — `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` — with plain `wrangler`. That's what Cloudflare designed wrangler for; `wrangler-accounts` is a local developer convenience for juggling OAuth sessions on your workstation.
+
+### Is this like `aws-vault` / `aws --profile` but for Cloudflare?
+
+Yes. `wrangler-accounts` is to Cloudflare Wrangler what `aws --profile` and `aws-vault exec` are to the AWS CLI: named profiles, per-invocation isolation, subshell mode, AWS-style resolution order (`--profile` > `$WRANGLER_PROFILE` > persistent default). Unlike AWS CLI, `wrangler` has no native `--profile` flag, so `wrangler-accounts` sits in front of `wrangler` and sets up an isolated `HOME` per invocation.
+
+### How do I know if a saved profile still works?
+
+`wrangler-accounts list` shows a fast table with STATUS (derived from the saved `expiration_time`), but that can miss revoked refresh tokens. For an authoritative check, run:
+
+```bash
+wrangler-accounts list --deep
+```
+
+This spawns `wrangler whoami` inside each profile's shadow HOME and reports whether Cloudflare actually accepts the credentials.
+
+### I get "Not logged in" even though I just ran `wrangler login`
+
+If you used plain `wrangler login`, it wrote to your real `~/.wrangler/config/default.toml`. Capture that as a named profile before it gets overwritten:
+
+```bash
+wrangler-accounts save work
+```
+
+Or start fresh with `wrangler-accounts login work`, which does the OAuth flow inside an isolated shadow HOME and writes directly into the profile directory.
+
+## Discoverability
+
+Project: Cloudflare Wrangler multi-account manager — save and switch between multiple Cloudflare Workers OAuth logins without re-authenticating each time.
+
+**Search keywords**: cloudflare wrangler multi account, wrangler multiple accounts, cloudflare workers switch account, wrangler profile manager, wrangler login profiles, cloudflare account switcher, wrangler --profile, AWS-style profile for wrangler, aws-vault for cloudflare, wrangler oauth multi account, cloudflare workers different accounts, per-invocation isolation, shadow home, wrangler account management CLI.
+
+**AI agent keywords**: agent skill, skills.sh, Claude Code skill, Cursor skill, Codex skill, Gemini CLI skill — see "Install as an AI agent skill" above.
 
-Cloudflare Wrangler multi-account switcher for global teams.
-Keywords: Cloudflare Workers account manager, Wrangler login profiles, multi-account, account switcher, AWS-style profile, per-invocation isolation, OAuth profile management.
+Related tools / alternatives:
+- [AWS CLI `--profile`](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html) — same concept for AWS, natively supported
+- [aws-vault](https://github.com/99designs/aws-vault) — OAuth-safe AWS profile wrapper that inspired the `exec` design here
+- [direnv](https://direnv.net/) — directory-based env switching (orthogonal, can be combined)
 
 ## Shell completion (zsh)
 

package/bin/wrangler-accounts.js

@@ -706,33 +706,47 @@ function main() {
     const shadowWranglerConfig = path.join(shadow, ".wrangler", "config");
     fs.mkdirSync(shadowWranglerConfig, { recursive: true });
 
+    // Pre-create the profile dir so per-profile cache lands in the right
+    // place even though config.toml doesn't exist yet (login will write
+    // it). This makes WRANGLER_CACHE_DIR isolated from the very first
+    // command, including the login flow itself. We remember whether the
+    // dir existed before so we can clean it up if login fails.
+    const profileDir = path.join(profilesDir, name);
+    const existed = fs.existsSync(path.join(profileDir, "config.toml"));
+    const profileDirExistedBefore = fs.existsSync(profileDir);
+    ensureDir(profileDir);
+    const futureProfileCfg = path.join(profileDir, "config.toml");
+
     const env = buildIsolatedEnv({
       shadow,
       realHome,
       profile: name,
+      profileCfg: futureProfileCfg,
       baseEnv: process.env,
       cloudflaredPath: findCloudflared(),
     });
-
-    const profileDir = path.join(profilesDir, name);
-    const existed = fs.existsSync(profileDir);
     let identity = null;
+    let loginSucceeded = false;
 
+    // Use throw + catch + finally so cleanup always runs. die() calls
+    // process.exit() synchronously, which would skip the finally block —
+    // and that would leave a half-created profile dir behind on failure.
+    let errorMsg = null;
     try {
       const loginResult = spawnSync("wrangler", ["login"], {
         stdio: "inherit",
         env,
       });
       if (loginResult.error) {
-        die(`Failed to run 'wrangler login': ${loginResult.error.message}`);
+        throw new Error(`Failed to run 'wrangler login': ${loginResult.error.message}`);
       }
       if (loginResult.status !== 0) {
-        die(`'wrangler login' exited with code ${loginResult.status}`);
+        throw new Error(`'wrangler login' exited with code ${loginResult.status}`);
       }
 
       const freshCfg = path.join(shadowWranglerConfig, "default.toml");
       if (!fs.existsSync(freshCfg)) {
-        die(`wrangler login completed but no config was written at ${freshCfg}`);
+        throw new Error(`wrangler login completed but no config was written at ${freshCfg}`);
       }
 
       // Verify identity via `wrangler whoami` in the same shadow.
@@ -743,18 +757,30 @@ function main() {
       const output = `${whoamiResult.stdout || ""}\n${whoamiResult.stderr || ""}`;
       identity = parseWranglerWhoamiOutput(output);
       if (!identity) {
-        die("Login succeeded but could not parse 'wrangler whoami' output");
+        throw new Error("Login succeeded but could not parse 'wrangler whoami' output");
       }
 
       // Move the fresh config into the profile directory. Use writeFile
       // (copy) so the profile config is a real file, not a symlink.
-      ensureDir(profileDir);
+      // (profileDir was already pre-created above for cache isolation.)
       const destCfg = path.join(profileDir, "config.toml");
       fs.copyFileSync(freshCfg, destCfg);
       writeMeta(profileDir, name, destCfg, identity);
+      loginSucceeded = true;
+    } catch (err) {
+      errorMsg = err.message;
     } finally {
       cleanupShadow(shadow);
+      // If login failed AND we created the profile dir as a side effect
+      // of cache isolation (it didn't exist before), clean it up so the
+      // user doesn't see a half-empty profile.
+      if (!loginSucceeded && !profileDirExistedBefore) {
+        try {
+          fs.rmSync(profileDir, { recursive: true, force: true });
+        } catch {}
+      }
     }
+    if (errorMsg) die(errorMsg);
 
     const note = existed ? " (overwritten)" : "";
     if (opts.json) {

package/lib/isolation.js

@@ -85,12 +85,15 @@ function cleanupShadow(shadow) {
 
 /**
  * Build the environment variable set that every isolated child process gets.
- * This is a pure function — no I/O.
+ *
+ * Note: not pure — when profileCfg is provided, ensures the per-profile
+ * cache directory exists so wrangler doesn't ENOENT on first write.
  */
 function buildIsolatedEnv({
   shadow,
   realHome,
   profile,
+  profileCfg = null,
   baseEnv = process.env,
   cloudflaredPath = null,
 }) {
@@ -100,9 +103,40 @@ function buildIsolatedEnv({
   env.WRANGLER_ACCOUNT = profile;
   env.WRANGLER_ACCOUNT_REAL_HOME = realHome;
   env.WRANGLER_REGISTRY_PATH = path.join(realHome, '.wrangler', 'registry');
-  env.WRANGLER_CACHE_DIR = path.join(realHome, '.wrangler', 'cache');
   env.WRANGLER_LOG_PATH = path.join(realHome, '.wrangler', 'logs');
   env.WRANGLER_SEND_METRICS = 'false';
+
+  // CRITICAL: Wrangler caches the user's selected Cloudflare account ID
+  // in `wrangler-account.json` inside `getCacheFolder()`. If multiple
+  // profiles share one cache directory, profile A's OAuth token can be
+  // paired with profile B's cached account ID, causing wrangler to
+  // write to the WRONG ACCOUNT — silently, until something like an R2
+  // bucket gets created in the wrong place.
+  //
+  // The cache must be per-profile. We point WRANGLER_CACHE_DIR at a
+  // `cache/` directory next to the profile's config.toml. Wrangler's
+  // getCacheFolder() honors this env var and skips its own cwd-based
+  // discovery (cli.js:62549).
+  //
+  // Earlier versions of this tool (≤1.2.1) pointed WRANGLER_CACHE_DIR
+  // at real $HOME/.wrangler/cache hoping to "share workerd cache" —
+  // that was wrong. workerd/cloudflared binaries live elsewhere
+  // (CLOUDFLARED_PATH / node_modules); WRANGLER_CACHE_DIR is only for
+  // config-cache files like wrangler-account.json and
+  // pages-config-cache.json.
+  if (profileCfg) {
+    const profileDir = path.dirname(profileCfg);
+    const cacheDir = path.join(profileDir, 'cache');
+    try {
+      fs.mkdirSync(cacheDir, { recursive: true });
+    } catch (err) {
+      process.stderr.write(
+        `[wrangler-accounts] could not create per-profile cache dir ${cacheDir}: ${err.message}\n`,
+      );
+    }
+    env.WRANGLER_CACHE_DIR = cacheDir;
+  }
+
   if (cloudflaredPath) {
     env.CLOUDFLARED_PATH = cloudflaredPath;
   }
@@ -144,6 +178,7 @@ function runIsolated({
     shadow,
     realHome,
     profile,
+    profileCfg,
     baseEnv,
     cloudflaredPath,
   });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@leeguoo/wrangler-accounts",
-  "version": "1.2.0",
-  "description": "AWS-style multi-account convenience for Cloudflare Wrangler — per-invocation OAuth isolation via shadow HOME.",
+  "version": "1.2.2",
+  "description": "Cloudflare Wrangler multi-account manager — save, switch, and run wrangler against multiple Cloudflare Workers accounts with AWS-style --profile and per-invocation shadow HOME isolation.",
   "license": "MIT",
   "bin": {
     "wrangler-accounts": "bin/wrangler-accounts.js"
@@ -20,7 +20,26 @@
     "accounts",
     "multi-account",
     "account-switcher",
-    "cli"
+    "account-manager",
+    "profile",
+    "profiles",
+    "oauth",
+    "login",
+    "aws-style",
+    "aws-vault",
+    "wrangler-login",
+    "wrangler-profile",
+    "wrangler-accounts",
+    "cloudflare-account",
+    "multiple-accounts",
+    "agent-skill",
+    "skill",
+    "skills-sh",
+    "claude-code",
+    "cursor",
+    "codex",
+    "cli",
+    "devtools"
   ],
   "repository": {
     "type": "git",

package/skills/wrangler-accounts/SKILL.md

@@ -245,10 +245,25 @@ Intentional. By design the shadow HOME symlinks all top-level entries of real HO
 ## Invariants the AI should rely on
 
 - **Real `~/.wrangler/config/default.toml` is never written to by `wrangler-accounts`.** If a user reports that it changed, something else touched it (e.g. a direct `wrangler login` outside `wrangler-accounts`).
-- **Two `wrangler-accounts --profile A` and `wrangler-accounts --profile B` running in parallel never clobber each other.** Each gets its own `mkdtemp` shadow HOME.
+- **Two `wrangler-accounts --profile A` and `wrangler-accounts --profile B` running in parallel never clobber each other on credentials OR account-id cache.** Each gets its own `mkdtemp` shadow HOME, and each gets its own per-profile `WRANGLER_CACHE_DIR` (next to the profile's `config.toml`) so that wrangler's `wrangler-account.json` (which stores the selected Cloudflare account ID) is naturally isolated.
 - **OAuth token refresh inside a profile is automatic.** The shadow HOME contains a symlink from `.wrangler/config/default.toml` to the saved profile file, so Wrangler's in-place `fs.writeFileSync` during `refreshToken()` flows straight back to the profile.
 - **`wrangler-accounts <args>` without a management subcommand forwards everything to wrangler verbatim**, including `--env`, `--dry-run`, `--json`, and any wrangler-native flags. The only flags consumed by `wrangler-accounts` itself are the ones listed in "Paths and environment" below.
 
+## What is and isn't isolated
+
+| State | Location | Isolated? |
+|---|---|---|
+| OAuth credentials (`config.toml`) | shadow `$HOME/.wrangler/config/default.toml` → symlink to per-profile file | ✅ per profile |
+| Account-id cache (`wrangler-account.json`) | per-profile `WRANGLER_CACHE_DIR` (= `<profilesDir>/<name>/cache/`) | ✅ per profile |
+| Pages config cache (`pages-config-cache.json`) | same as above | ✅ per profile |
+| Miniflare dev registry | `WRANGLER_REGISTRY_PATH` = `$realHome/.wrangler/registry` | ❌ shared on purpose (cross-profile worker discovery during local dev) |
+| Wrangler debug logs | `WRANGLER_LOG_PATH` = `$realHome/.wrangler/logs` | ❌ shared (append-only, harmless) |
+| Project-local state (`./.wrangler/state/`, `./node_modules/.cache/wrangler`) | inside the project directory | ❌ shared at project level (per-project, but not per-profile) |
+| `cloudflared` binary | `CLOUDFLARED_PATH` or `~/.wrangler/cloudflared/` | ❌ shared (binary, not account-scoped) |
+| Shell history, npm cache, git config, ssh keys | symlinked through to real `$HOME` | ❌ shared by design (so `exec` subshells feel like a normal terminal) |
+
+If a user is hitting a "wrong account" symptom and the credentials look right, the most likely culprit is **project-local state** in `./.wrangler/state/` — clear that and re-run.
+
 ## CI guidance
 
 For CI and deploy pipelines, **use `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` with plain `wrangler`**, not saved OAuth profiles. `wrangler-accounts` is a local developer convenience for juggling OAuth sessions on your workstation, not a CI primitive.