@leeguoo/wrangler-accounts 1.5.1 → 1.6.2

package/.claude-plugin/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "wrangler-accounts",
+  "description": "Cloudflare Wrangler multi-account helper with a bundled skill and Bash guard hook for Claude Code.",
+  "version": "1.5.1",
+  "author": {
+    "name": "Lee Guo"
+  },
+  "homepage": "https://github.com/leeguooooo/wrangler-accounts#readme",
+  "repository": "https://github.com/leeguooooo/wrangler-accounts",
+  "license": "MIT"
+}

package/README.md

@@ -111,7 +111,8 @@ WRANGLER_PROFILE=<name> wrangler-accounts <wrangler-args...>
 wrangler-accounts exec <name>                   # interactive subshell
 wrangler-accounts exec <name> -- <cmd> [args]   # one command
 
-wrangler-accounts login <name>                  # isolated OAuth login
+wrangler-accounts login <name>                  # isolated OAuth login (browser)
+wrangler-accounts token-add <name> <api-token> <account-id> [--force]  # API token profile (no browser)
 wrangler-accounts default [name | --unset]      # manage persistent default
 wrangler-accounts whoami [--profile <name>]     # show resolved identity
 wrangler-accounts list                          # fast table (name/status/expires/identity)
@@ -165,12 +166,32 @@ When you run `wrangler-accounts <wrangler-args>`, the active profile is resolved
 4. `profilesDir/default` (set via `wrangler-accounts default <name>`)
 5. Hard error with actionable hint
 
-## When to use `wrangler-accounts` vs. native env vars
+## API token profiles (no browser required)
+
+Since 1.6.0 you can save a Cloudflare API token + account ID as a named profile — no OAuth browser flow:
+
+```bash
+# Get your API token: Cloudflare dashboard → My Profile → API Tokens
+wrangler-accounts token-add work CF_TOKEN_HERE ACCOUNT_ID_HERE
+
+# Use exactly like an OAuth profile
+wrangler-accounts --profile work deploy
+wrangler-accounts work r2 list
+```
 
-`wrangler-accounts` is a **local developer convenience** for juggling multiple OAuth sessions on your workstation. It is not the right primitive for CI.
+Token profiles appear in `list` with `[token]` type and `STATUS: token`. There's no expiration; they're always ready.
+
+**Env-var pass-through:** if `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` are already in the environment, no profile selection is needed at all:
+
+```bash
+CLOUDFLARE_API_TOKEN=xxx CLOUDFLARE_ACCOUNT_ID=yyy wrangler-accounts deploy
+```
+
+## When to use `wrangler-accounts` vs. native env vars
 
-- **Local dev, multiple accounts** → `wrangler-accounts`
-- **CI / deploy pipelines** → **`CLOUDFLARE_API_TOKEN` + `CLOUDFLARE_ACCOUNT_ID` with plain `wrangler`**. Wrangler is designed to read those env vars natively. Create an API token in the Cloudflare dashboard with the scopes your pipeline needs, set the two env vars in your CI secrets, and call `wrangler deploy` directly — no `wrangler-accounts` involved.
+- **Local dev, multiple OAuth accounts** → `wrangler-accounts login <name>` (the classic use case)
+- **Local dev, API token accounts** → `wrangler-accounts token-add <name> <token> <account-id>` (1.6.0+)
+- **CI / deploy pipelines** → either `CLOUDFLARE_API_TOKEN` + `CLOUDFLARE_ACCOUNT_ID` with plain `wrangler`, or the env-var pass-through mode above
 - **Shared scripts** that run locally or in CI → parameterize on `WRANGLER_PROFILE` so devs can run them with `WRANGLER_PROFILE=work wrangler-accounts ./deploy.sh`.
 
 ## Options

package/bin/wrangler-accounts.js

@@ -18,9 +18,11 @@ const {
   isValidName,
   isBackupName,
   listProfiles,
+  getProfileType,
   fileHash,
   readExpirationTime,
   readSessionState,
+  readTokenSessionState,
   filesEqual,
   writeMeta,
   readMeta,
@@ -33,6 +35,8 @@ const {
   backupCurrentConfig,
   findMatchingProfile,
   saveProfile: saveProfileImpl,
+  saveTokenProfile: saveTokenProfileImpl,
+  readTokenCredentials,
   removeProfile: removeProfileImpl,
 } = require("../lib/profile-store");
 const {
@@ -62,6 +66,7 @@ const MANAGEMENT_SUBCOMMANDS = new Set([
   "login",
   "remove",
   "default",
+  "token-add",
   "whoami",
   "gc",
   "use",
@@ -129,6 +134,10 @@ function removeProfile(...args) {
   try { return removeProfileImpl(...args); }
   catch (err) { die(err.message); }
 }
+function saveTokenProfile(...args) {
+  try { return saveTokenProfileImpl(...args); }
+  catch (err) { die(err.message); }
+}
 
 let outputJson = false;
 
@@ -141,6 +150,156 @@ function die(message, exitCode = 1) {
   process.exit(exitCode);
 }
 
+function profileTypeForName(profilesDir, name) {
+  return getProfileType(path.join(profilesDir, name));
+}
+
+function tokenProfileExists(profilesDir, name) {
+  return profileTypeForName(profilesDir, name) !== null;
+}
+
+function noProfileMessage() {
+  return [
+    'No profile specified. Options:',
+    '  - wrangler-accounts --profile <name> ...',
+    '  - WRANGLER_PROFILE=<name> wrangler-accounts ...',
+    '  - wrangler-accounts default <name>   (set a persistent default)',
+  ].join('\n');
+}
+
+function resolveProfileAny({
+  cliProfile,
+  positional,
+  env,
+  profilesDir,
+  managementSubcommands,
+}) {
+  try {
+    return resolveProfile({
+      cliProfile,
+      positional,
+      env,
+      profilesDir,
+      managementSubcommands,
+    });
+  } catch (err) {
+    if (!(err instanceof ResolveError)) throw err;
+    if (err.code === "INVALID_NAME") throw err;
+  }
+
+  if (cliProfile) {
+    if (!isValidName(cliProfile)) {
+      throw new ResolveError(`Invalid profile name: ${cliProfile}`, "INVALID_NAME");
+    }
+    if (tokenProfileExists(profilesDir, cliProfile)) {
+      return { name: cliProfile, source: "cli" };
+    }
+    throw new ResolveError(`Profile not found: ${cliProfile}`, "PROFILE_NOT_FOUND");
+  }
+
+  if (positional && !managementSubcommands.has(positional)) {
+    if (isValidName(positional) && tokenProfileExists(profilesDir, positional)) {
+      return { name: positional, source: "positional" };
+    }
+  }
+
+  const envProfile = env && env.WRANGLER_PROFILE;
+  if (envProfile && envProfile.length) {
+    if (!isValidName(envProfile)) {
+      throw new ResolveError(`Invalid profile name: ${envProfile}`, "INVALID_NAME");
+    }
+    if (tokenProfileExists(profilesDir, envProfile)) {
+      return { name: envProfile, source: "env" };
+    }
+    throw new ResolveError(`Profile not found: ${envProfile}`, "PROFILE_NOT_FOUND");
+  }
+
+  const def = getDefaultProfile(profilesDir);
+  if (def) {
+    if (!isValidName(def)) {
+      throw new ResolveError(`Invalid profile name: ${def}`, "INVALID_NAME");
+    }
+    if (tokenProfileExists(profilesDir, def)) {
+      return { name: def, source: "default" };
+    }
+    throw new ResolveError(`Profile not found: ${def}`, "PROFILE_NOT_FOUND");
+  }
+
+  throw new ResolveError(noProfileMessage(), "NO_PROFILE");
+}
+
+function runAnonymousTokenMode({
+  command,
+  args,
+  captureStdout = false,
+}) {
+  return runIsolated({
+    profile: "token-env",
+    profileCfg: null,
+    profileDir: null,
+    realHome: os.homedir(),
+    command,
+    args,
+    apiToken: process.env.CLOUDFLARE_API_TOKEN || null,
+    accountId: process.env.CLOUDFLARE_ACCOUNT_ID || null,
+    baseEnv: process.env,
+    captureStdout,
+    cloudflaredPath: findCloudflared(),
+  });
+}
+
+function runResolvedProfileCommand({
+  resolved,
+  profilesDir,
+  command,
+  args,
+  captureStdout = false,
+}) {
+  const profileDir = path.join(profilesDir, resolved.name);
+  const profileType = getProfileType(profileDir);
+
+  if (profileType === "token") {
+    const creds = readTokenCredentials(profileDir);
+    if (!creds || !creds.apiToken) {
+      die(`Token profile '${resolved.name}' is missing token.json credentials.`);
+    }
+    return runIsolated({
+      profile: resolved.name,
+      profileCfg: null,
+      profileDir,
+      realHome: os.homedir(),
+      command,
+      args,
+      apiToken: creds.apiToken,
+      accountId: creds.accountId || null,
+      baseEnv: process.env,
+      captureStdout,
+      cloudflaredPath: findCloudflared(),
+    });
+  }
+
+  const profileCfg = path.join(profileDir, "config.toml");
+  const session = readSessionState(profileCfg);
+  if (session.effective === 'expired') {
+    die(
+      `Profile '${resolved.name}' has expired Wrangler OAuth credentials and no refresh_token to renew them (expiration_time: ${session.expirationTime}). Run 'wrangler-accounts login ${resolved.name}' to re-authenticate.`,
+      3
+    );
+  }
+
+  return runIsolated({
+    profile: resolved.name,
+    profileCfg,
+    profileDir,
+    realHome: os.homedir(),
+    command,
+    args,
+    baseEnv: process.env,
+    captureStdout,
+    cloudflaredPath: findCloudflared(),
+  });
+}
+
 function printHelp(exitCode = 0) {
   const text = `wrangler-accounts - manage multiple Wrangler login profiles
 
@@ -152,6 +311,7 @@ Commands:
   status
   login <name>
   save <name>
+  token-add <name> <api-token> <account-id>
   sync <name>
   sync-active
   use <name>
@@ -391,7 +551,7 @@ function main() {
 
     let resolved;
     try {
-      resolved = resolveProfile({
+      resolved = resolveProfileAny({
         cliProfile: profileArg,
         positional,
         env: process.env,
@@ -400,6 +560,13 @@ function main() {
       });
     } catch (err) {
       if (err instanceof ResolveError) {
+        if (err.code === "NO_PROFILE" && process.env.CLOUDFLARE_API_TOKEN) {
+          const result = runAnonymousTokenMode({
+            command: "wrangler",
+            args: rest,
+          });
+          process.exit(result.exitCode);
+        }
         const exitCode =
           err.code === "NO_PROFILE" || err.code === "PROFILE_NOT_FOUND" ? 2 : 1;
         die(err.message, exitCode);
@@ -407,26 +574,14 @@ function main() {
       throw err;
     }
 
-    const profileCfg = path.join(profilesDir, resolved.name, "config.toml");
-    const session = readSessionState(profileCfg);
-    if (session.effective === 'expired') {
-      die(
-        `Profile '${resolved.name}' has expired Wrangler OAuth credentials and no refresh_token to renew them (expiration_time: ${session.expirationTime}). Run 'wrangler-accounts login ${resolved.name}' to re-authenticate.`,
-        3
-      );
-    }
-
     // If positional was consumed as profile, drop it from wrangler argv
     const wranglerArgs = resolved.source === "positional" ? rest.slice(1) : rest;
 
-    const result = runIsolated({
-      profile: resolved.name,
-      profileCfg,
-      realHome: os.homedir(),
+    const result = runResolvedProfileCommand({
+      resolved,
+      profilesDir,
       command: "wrangler",
       args: wranglerArgs,
-      baseEnv: process.env,
-      cloudflaredPath: findCloudflared(),
     });
     process.exit(result.exitCode);
   }
@@ -438,12 +593,15 @@ function main() {
 
     const entries = profiles.map((name) => {
       const profileDir = path.join(profilesDir, name);
+      const type = getProfileType(profileDir) || "oauth";
       const cfgPath = path.join(profileDir, "config.toml");
-      const session = readSessionState(cfgPath);
+      const session =
+        type === "token" ? readTokenSessionState() : readSessionState(cfgPath);
       const meta = readMeta(profileDir);
       const identity = getMetaIdentity(meta);
       return {
         name,
+        type,
         isDefault: name === defaultName,
         isActive: name === activeName,
         status: session.effective, // 'valid' | 'refreshable' | 'expired' | 'unknown'
@@ -468,17 +626,14 @@ function main() {
       }
       const cloudflaredPath = findCloudflared();
       for (const e of entries) {
-        const profileCfg = path.join(profilesDir, e.name, "config.toml");
         try {
-          const r = runIsolated({
-            profile: e.name,
-            profileCfg,
-            realHome: os.homedir(),
+          const resolved = { name: e.name, source: "deep" };
+          const r = runResolvedProfileCommand({
+            resolved,
+            profilesDir,
             command: "wrangler",
             args: ["whoami"],
-            baseEnv: process.env,
             captureStdout: true,
-            cloudflaredPath,
           });
           const output = `${r.stdout || ""}\n${r.stderr || ""}`;
           if (r.exitCode === 0) {
@@ -522,13 +677,14 @@ function main() {
     if (defaultName) console.log(`Default: ${defaultName}\n`);
     const rows = entries.map((e) => ({
       marker: e.isDefault ? "*" : " ",
-      name: e.name,
+      name: `${e.name} [${e.type}]`,
       status:
         e.status === "expired" ? "EXPIRED"
         : e.status === "refreshable" ? "valid*"
         : e.status === "valid" ? "valid"
+        : e.status === "token" ? "token"
         : "unknown",
-      expires: formatExpiry(e.expirationTime),
+      expires: e.type === "token" ? "—" : formatExpiry(e.expirationTime),
       verified:
         e.verified === true ? "✓ ok"
         : e.verified === false ? `✗ ${e.verifyError || "failed"}`
@@ -594,12 +750,15 @@ function main() {
     const matchType = exactMatch ? "hash" : identityMatches.length === 1 ? "identity" : null;
     const profileStates = Object.fromEntries(
       profiles.map((name) => {
-        const profileConfig = path.join(profilesDir, name, "config.toml");
-        const meta = readMeta(path.join(profilesDir, name));
+        const profileDir = path.join(profilesDir, name);
+        const type = getProfileType(profileDir) || "oauth";
+        const profileConfig = path.join(profileDir, "config.toml");
+        const meta = readMeta(profileDir);
         return [
           name,
           {
-            ...readSessionState(profileConfig),
+            ...(type === "token" ? readTokenSessionState() : readSessionState(profileConfig)),
+            type,
             identity: getMetaIdentity(meta),
           },
         ];
@@ -651,10 +810,13 @@ function main() {
       }
       for (const name of profiles) {
         const profileSession = profileStates[name];
-        if (!profileSession.expirationTime) continue;
-        const state = profileSession.expired ? "expired" : "valid";
+        const state =
+          profileSession.effective === "token"
+            ? "token"
+            : profileSession.expired ? "expired" : "valid";
         const suffix = profileSession.identity ? `, ${describeIdentity(profileSession.identity)}` : "";
-        console.log(`- ${name}: ${profileSession.expirationTime} (${state}${suffix ? suffix : ""})`);
+        const expiry = profileSession.expirationTime || "(n/a)";
+        console.log(`- ${name} [${profileSession.type}]: ${expiry} (${state}${suffix ? suffix : ""})`);
       }
     }
     return;
@@ -689,6 +851,19 @@ function main() {
     return;
   }
 
+  if (command === "token-add") {
+    const name = rest[1];
+    const apiToken = rest[2];
+    const accountId = rest[3];
+    if (!name) die("Missing profile name for token-add");
+    if (!apiToken) die("Missing API token for token-add");
+    if (!accountId) die("Missing account ID for token-add");
+    ensureDir(profilesDir);
+    saveTokenProfile(name, apiToken, accountId, profilesDir, opts.force);
+    console.log(`Saved token profile '${name}'`);
+    return;
+  }
+
   if (command === "login") {
     const name = rest[1];
     if (!name) die("Missing profile name for login");
@@ -983,7 +1158,7 @@ function main() {
     const profileArg = opts.profile || rest[1] || null;
     let resolved;
     try {
-      resolved = resolveProfile({
+      resolved = resolveProfileAny({
         cliProfile: profileArg,
         positional: null,
         env: process.env,
@@ -991,10 +1166,29 @@ function main() {
         managementSubcommands: MANAGEMENT_SUBCOMMANDS,
       });
     } catch (err) {
-      if (err instanceof ResolveError) die(err.message, 2);
+      if (err instanceof ResolveError) {
+        if (err.code === "NO_PROFILE" && process.env.CLOUDFLARE_API_TOKEN) {
+          const result = runAnonymousTokenMode({
+            command: "wrangler",
+            args: ["whoami"],
+          });
+          process.exit(result.exitCode);
+        }
+        die(err.message, 2);
+      }
       throw err;
     }
     const profileDir = path.join(profilesDir, resolved.name);
+    const profileType = getProfileType(profileDir) || "oauth";
+    if (profileType === "token") {
+      const result = runResolvedProfileCommand({
+        resolved,
+        profilesDir,
+        command: "wrangler",
+        args: ["whoami"],
+      });
+      process.exit(result.exitCode);
+    }
     const meta = readMeta(profileDir);
     const identity = getMetaIdentity(meta);
     if (opts.json) {
@@ -1004,6 +1198,7 @@ function main() {
             command: "whoami",
             profile: resolved.name,
             source: resolved.source,
+            type: profileType,
             identity,
           },
           null,
@@ -1061,7 +1256,7 @@ function main() {
 
     let resolved;
     try {
-      resolved = resolveProfile({
+      resolved = resolveProfileAny({
         cliProfile: profileName,
         positional: null,
         env: process.env,
@@ -1073,15 +1268,6 @@ function main() {
       throw err;
     }
 
-    const profileCfg = path.join(profilesDir, resolved.name, "config.toml");
-    const session = readSessionState(profileCfg);
-    if (session.effective === 'expired') {
-      die(
-        `Profile '${resolved.name}' has expired Wrangler OAuth credentials and no refresh_token to renew them. Run 'wrangler-accounts login ${resolved.name}' to re-authenticate.`,
-        3
-      );
-    }
-
     // Everything after `--` is the user command. Without `--`, launch $SHELL -i.
     const dashDashIdx = rest.indexOf("--", 2);
     let cmd;
@@ -1095,14 +1281,11 @@ function main() {
       cmdArgs = ["-i"];
     }
 
-    const result = runIsolated({
-      profile: resolved.name,
-      profileCfg,
-      realHome: os.homedir(),
+    const result = runResolvedProfileCommand({
+      resolved,
+      profilesDir,
       command: cmd,
       args: cmdArgs,
-      baseEnv: process.env,
-      cloudflaredPath: findCloudflared(),
     });
     process.exit(result.exitCode);
   }
@@ -1138,8 +1321,7 @@ function main() {
     }
     // Set the default profile
     if (!isValidName(name)) die(`Invalid profile name: ${name}`);
-    const cfg = path.join(profilesDir, name, "config.toml");
-    if (!fs.existsSync(cfg)) die(`Profile not found: ${name}`, 2);
+    if (!tokenProfileExists(profilesDir, name)) die(`Profile not found: ${name}`, 2);
     setDefaultProfile(profilesDir, name);
     if (opts.json) {
       console.log(JSON.stringify({ command: "default", name }, null, 2));

package/lib/isolation.js

@@ -21,15 +21,15 @@ const { spawnSync } = require('node:child_process');
  *
  * @param {object} args
  * @param {string} args.realHome
- * @param {string} args.profileCfg - path to the profile's config.toml file
+ * @param {string|null} [args.profileCfg] - path to the profile's config.toml file
  * @param {string} [args.label] - optional label for the tmpdir name
  * @returns {string} path to the shadow HOME
  */
-function createShadowHome({ realHome, profileCfg, label = 'wa' }) {
+function createShadowHome({ realHome, profileCfg = null, label = 'wa' }) {
   if (!realHome || !fs.existsSync(realHome)) {
     throw new Error(`real HOME does not exist: ${realHome}`);
   }
-  if (!profileCfg || !fs.existsSync(profileCfg)) {
+  if (profileCfg && !fs.existsSync(profileCfg)) {
     throw new Error(`profile config does not exist: ${profileCfg}`);
   }
 
@@ -59,10 +59,12 @@ function createShadowHome({ realHome, profileCfg, label = 'wa' }) {
   // saved profile automatically.
   const shadowWranglerConfig = path.join(shadow, '.wrangler', 'config');
   fs.mkdirSync(shadowWranglerConfig, { recursive: true });
-  fs.symlinkSync(
-    profileCfg,
-    path.join(shadowWranglerConfig, 'default.toml'),
-  );
+  const defaultConfigPath = path.join(shadowWranglerConfig, 'default.toml');
+  if (profileCfg) {
+    fs.symlinkSync(profileCfg, defaultConfigPath);
+  } else {
+    fs.writeFileSync(defaultConfigPath, '');
+  }
 
   return shadow;
 }
@@ -94,6 +96,9 @@ function buildIsolatedEnv({
   realHome,
   profile,
   profileCfg = null,
+  profileDir = null,
+  apiToken = null,
+  accountId = null,
   baseEnv = process.env,
   cloudflaredPath = null,
 }) {
@@ -105,6 +110,9 @@ function buildIsolatedEnv({
   env.WRANGLER_REGISTRY_PATH = path.join(realHome, '.wrangler', 'registry');
   env.WRANGLER_LOG_PATH = path.join(realHome, '.wrangler', 'logs');
   env.WRANGLER_SEND_METRICS = 'false';
+  if (!env.WA_TEST_OUT) {
+    env.WA_TEST_OUT = path.join(shadow, '.wrangler', 'wa-test-out.json');
+  }
 
   // CRITICAL: Wrangler caches the user's selected Cloudflare account ID
   // in `wrangler-account.json` inside `getCacheFolder()`. If multiple
@@ -124,9 +132,9 @@ function buildIsolatedEnv({
   // (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');
+  const cacheRoot = profileDir || (profileCfg ? path.dirname(profileCfg) : null);
+  if (cacheRoot) {
+    const cacheDir = path.join(cacheRoot, 'cache');
     try {
       fs.mkdirSync(cacheDir, { recursive: true });
     } catch (err) {
@@ -137,6 +145,14 @@ function buildIsolatedEnv({
     env.WRANGLER_CACHE_DIR = cacheDir;
   }
 
+  if (apiToken) {
+    env.CLOUDFLARE_API_TOKEN = apiToken;
+  }
+
+  if (accountId) {
+    env.CLOUDFLARE_ACCOUNT_ID = accountId;
+  }
+
   if (cloudflaredPath) {
     env.CLOUDFLARED_PATH = cloudflaredPath;
   }
@@ -162,9 +178,12 @@ function buildIsolatedEnv({
 function runIsolated({
   profile,
   profileCfg,
+  profileDir = null,
   realHome,
   command,
   args,
+  apiToken = null,
+  accountId = null,
   baseEnv = process.env,
   captureStdout = false,
   cloudflaredPath = null,
@@ -179,6 +198,9 @@ function runIsolated({
     realHome,
     profile,
     profileCfg,
+    profileDir,
+    apiToken,
+    accountId,
     baseEnv,
     cloudflaredPath,
   });

package/lib/profile-store.js

@@ -16,6 +16,13 @@ function isBackupName(name) {
   return name.startsWith('__backup-');
 }
 
+function getProfileType(profileDir) {
+  if (!profileDir || !fs.existsSync(profileDir)) return null;
+  if (fs.existsSync(path.join(profileDir, 'config.toml'))) return 'oauth';
+  if (fs.existsSync(path.join(profileDir, 'token.json'))) return 'token';
+  return null;
+}
+
 function listProfiles(profilesDir, { includeBackups = false } = {}) {
   if (!fs.existsSync(profilesDir)) return [];
   const entries = fs.readdirSync(profilesDir, { withFileTypes: true });
@@ -23,7 +30,7 @@ function listProfiles(profilesDir, { includeBackups = false } = {}) {
     .filter((entry) => entry.isDirectory())
     .map((entry) => entry.name)
     .filter((name) => includeBackups || !isBackupName(name))
-    .filter((name) => fs.existsSync(path.join(profilesDir, name, 'config.toml')))
+    .filter((name) => getProfileType(path.join(profilesDir, name)) !== null)
     .sort();
 }
 
@@ -199,7 +206,9 @@ function findMatchingProfile(profilesDir, configPath, { includeBackups = false }
   const configHash = fileHash(configPath);
   const profiles = listProfiles(profilesDir, { includeBackups });
   for (const name of profiles) {
-    const profileConfig = path.join(profilesDir, name, 'config.toml');
+    const profileDir = path.join(profilesDir, name);
+    if (getProfileType(profileDir) !== 'oauth') continue;
+    const profileConfig = path.join(profileDir, 'config.toml');
     if (fileHash(profileConfig) === configHash) return name;
   }
   return null;
@@ -223,6 +232,59 @@ function saveProfile(name, configPath, profilesDir, force, identity = null) {
   writeMeta(profileDir, name, configPath, identity);
 }
 
+function saveTokenProfile(name, apiToken, accountId, profilesDir, force) {
+  if (!isValidName(name)) {
+    throw new Error(`Invalid profile name: ${name}`);
+  }
+
+  const profileDir = path.join(profilesDir, name);
+  if (fs.existsSync(profileDir) && !force) {
+    throw new Error(`Profile exists: ${name} (use --force to overwrite)`);
+  }
+
+  ensureDir(profileDir);
+
+  const tokenPath = path.join(profileDir, 'token.json');
+  fs.writeFileSync(
+    tokenPath,
+    JSON.stringify({ apiToken, accountId }, null, 2),
+  );
+  fs.chmodSync(tokenPath, 0o600);
+
+  fs.writeFileSync(
+    path.join(profileDir, 'meta.json'),
+    JSON.stringify(
+      {
+        name,
+        savedAt: new Date().toISOString(),
+        type: 'token',
+        accountId,
+      },
+      null,
+      2,
+    ),
+  );
+}
+
+function readTokenCredentials(profileDir) {
+  const tokenPath = path.join(profileDir, 'token.json');
+  if (!fs.existsSync(tokenPath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(tokenPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function readTokenSessionState() {
+  return {
+    expirationTime: null,
+    expired: null,
+    hasRefreshToken: false,
+    effective: 'token',
+  };
+}
+
 function removeProfile(name, profilesDir) {
   if (!isValidName(name)) {
     throw new Error(`Invalid profile name: ${name}`);
@@ -245,10 +307,12 @@ module.exports = {
   ensureDir,
   isValidName,
   isBackupName,
+  getProfileType,
   listProfiles,
   fileHash,
   readExpirationTime,
   readSessionState,
+  readTokenSessionState,
   filesEqual,
   writeMeta,
   readMeta,
@@ -261,5 +325,7 @@ module.exports = {
   backupCurrentConfig,
   findMatchingProfile,
   saveProfile,
+  saveTokenProfile,
+  readTokenCredentials,
   removeProfile,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leeguoo/wrangler-accounts",
-  "version": "1.5.1",
+  "version": "1.6.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": {

package/plugins/wrangler-accounts/skills/wrangler-accounts/SKILL.md

@@ -66,6 +66,7 @@ If `wrangler-accounts --version` is below any of these, **upgrade first** before
 | **≥ 1.2.2** | per-profile `WRANGLER_CACHE_DIR`, fixes account-id leak across profiles | `d1`/`r2 object` commands return `7403 not authorized` even though OAuth is valid; deploys silently land in the wrong account |
 | **≥ 1.3.0** | STATUS column distinguishes `valid` / `valid*` / `EXPIRED` (refresh-token-aware) | `list` shows `EXPIRED` for healthy profiles, scaring you into running `login` for no reason |
 | **≥ 1.4.0** | `login` refuses non-TTY contexts and accidental overwrites | `login <name>` hangs forever in non-interactive contexts; reflexive `login` overwrites a healthy profile |
+| **≥ 1.6.0** | API token profiles (`token-add`) + anonymous env-var pass-through | only OAuth profiles existed; `CLOUDFLARE_API_TOKEN` in env still required a named profile to be selected |
 
 ```bash
 npm i -g @leeguoo/wrangler-accounts@latest    # always-safe upgrade
@@ -108,6 +109,7 @@ How to read `list --deep` output:
 ## Quick Start
 
 - `wrangler-accounts login <name>` — interactive OAuth login into a new profile (never touches real `~/.wrangler`)
+- `wrangler-accounts token-add <name> <api-token> <account-id>` — save an API token profile (no browser login needed)
 - `wrangler-accounts default <name>` — set the persistent default profile
 - `wrangler-accounts deploy` — run `wrangler deploy` under the default profile
 - `wrangler-accounts --profile personal deploy` — one-shot override
@@ -169,6 +171,7 @@ Use `--json` for structured output.
 | `valid*` / `refreshable` | access_token past expiry **BUT** refresh_token present; wrangler will auto-refresh on next use | **none** — this is fine, don't scare the user |
 | `EXPIRED` / `expired` | access_token expired **AND** no refresh_token saved; profile is genuinely broken | `wrangler-accounts login <name>` |
 | `unknown` | profile file has no `expiration_time` field | run `list --deep` to verify live |
+| `token` | API token profile (1.6.0+) — no expiration concept, always ready | none |
 
 **Cloudflare OAuth lifecycle reference:** access tokens are short-lived (~1 hour) by design. Every profile with `offline_access` in its scopes also has a long-lived refresh_token (~30 days, silently extended on use). Wrangler refreshes access tokens automatically whenever it runs a command and the current one is past expiry. **Do not tell the user to re-login just because `list` shows an expired access token** — check `hasRefreshToken` first. If the profile's STATUS is `valid*` / `refreshable`, nothing is wrong.
 
@@ -176,13 +179,36 @@ The only time a user actually needs `wrangler-accounts login <name>` again is:
 1. STATUS is `EXPIRED` (no refresh_token at all — profile was saved without `offline_access` scope)
 2. OR `list --deep` returns `✗` with "Not logged in" / "refresh token may be revoked" (refresh token itself got invalidated)
 
+### Save an API token profile (no browser required)
+
+`wrangler-accounts token-add <name> <api-token> <account-id> [--force]`
+
+Saves a Cloudflare API token + account ID as a named profile. No OAuth browser flow needed. The credentials are stored in `token.json` (mode 0600) inside the profile directory.
+
+```bash
+# Get your API token from: Cloudflare dashboard → My Profile → API Tokens
+wrangler-accounts token-add work CF_TOKEN_HERE ACCOUNT_ID_HERE
+
+# Use identically to OAuth profiles
+wrangler-accounts --profile work deploy
+wrangler-accounts work r2 list
+```
+
+Token profiles appear in `list` with a `[token]` type indicator and `STATUS: token` — there is no expiration concept, so they are always ready to use. `remove` works the same as for OAuth profiles.
+
+**Env-var pass-through (1.6.0+):** when `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` are already set in the environment and no profile is specified, `wrangler-accounts` runs in anonymous-token mode (no named profile needed). Useful for CI jobs that inject credentials via secrets:
+
+```bash
+CLOUDFLARE_API_TOKEN=xxx CLOUDFLARE_ACCOUNT_ID=yyy wrangler-accounts deploy
+```
+
 ### Save, sync, login, remove
 
 - `wrangler-accounts save <name>` — snapshot current Wrangler config as a profile
 - `wrangler-accounts sync <name>` — refresh a specific profile from the current login
 - `wrangler-accounts sync-default` — refresh the default profile
 - `wrangler-accounts login <name>` — fresh isolated OAuth login
-- `wrangler-accounts remove <name>` — delete a profile
+- `wrangler-accounts remove <name>` — delete a profile (works for both OAuth and token profiles)
 
 ### Clean up stale shadow HOMEs
 
@@ -327,11 +353,13 @@ This overwrites the existing profile with a fresh OAuth session. Any saved metad
 The user ran `wrangler-accounts <wrangler-args>` without a resolvable profile. Fix one of:
 
 ```bash
-wrangler-accounts --profile <name> <args>       # one-shot
+wrangler-accounts --profile <name> <args>        # one-shot
 WRANGLER_PROFILE=<name> wrangler-accounts <args> # env var
-wrangler-accounts default <name>                # persistent default
+wrangler-accounts default <name>                 # persistent default
 ```
 
+**1.6.0+**: if `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` are both present in the environment, this error no longer fires — the tool runs in anonymous-token mode automatically.
+
 ### "Profile not found: X"
 
 The profile name doesn't exist in `profilesDir`. Check what's saved:
@@ -437,7 +465,32 @@ If a user is hitting a "wrong account" symptom and the credentials look right, t
 
 ## 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.
+For CI and deploy pipelines you have two options:
+
+**Option 1 — plain `wrangler` with env vars (simplest for CI):**
+
+```bash
+CLOUDFLARE_API_TOKEN=<token>
+CLOUDFLARE_ACCOUNT_ID=<account-id>
+wrangler deploy
+```
+
+**Option 2 — `wrangler-accounts` with a token profile (useful when you want the same CLI both locally and in CI):**
+
+```bash
+# Save once (locally or during CI bootstrap):
+wrangler-accounts token-add work "$CF_TOKEN" "$CF_ACCOUNT_ID"
+# Use the same commands locally and in CI:
+wrangler-accounts --profile work deploy
+```
+
+Or use the anonymous pass-through (no profile needed if env vars are present):
+
+```bash
+CLOUDFLARE_API_TOKEN="$CF_TOKEN" CLOUDFLARE_ACCOUNT_ID="$CF_ACCOUNT_ID" wrangler-accounts deploy
+```
+
+`wrangler-accounts` is primarily a local developer convenience for juggling OAuth sessions on your workstation, but since 1.6.0 it also supports API token profiles for teams that want a consistent CLI interface across local and CI environments.
 
 ## Paths and environment
 
@@ -453,7 +506,7 @@ Use `--json` when another tool needs to parse results. All v1.0 commands that pr
 
 ## Naming rules
 
-Profile names: letters, numbers, dot, underscore, dash only. Names matching management subcommand names (`exec`, `default`, `whoami`, `gc`, `login`, `list`, `status`, `save`, `sync`, `sync-default`, `remove`, `use`, `sync-active`) cannot be reached via positional shorthand — use `--profile <name>` for those.
+Profile names: letters, numbers, dot, underscore, dash only. Names matching management subcommand names (`exec`, `default`, `whoami`, `gc`, `login`, `token-add`, `list`, `status`, `save`, `sync`, `sync-default`, `remove`, `use`, `sync-active`) cannot be reached via positional shorthand — use `--profile <name>` for those.
 
 ## Deprecated
 

package/skills/wrangler-accounts/SKILL.md

@@ -1,461 +0,0 @@
----
-name: wrangler-accounts
-description: AWS-style multi-account convenience for Cloudflare Wrangler. Use when you need to run wrangler commands against a specific Cloudflare account, manage saved OAuth profiles, set or switch the persistent default profile, or open an isolated subshell for a profile. Prefer --json for machine-readable output.
----
-
-# Wrangler Accounts
-
-## Overview
-
-`wrangler-accounts` runs `wrangler` under per-invocation **shadow HOME** isolation, so multiple shells can use different Cloudflare accounts in parallel without any global switching. Profile resolution order: `--profile` / `-p` > positional shorthand > `$WRANGLER_PROFILE` > `profilesDir/default` > hard error.
-
-## Installation
-
-For Claude Code users, prefer the plugin marketplace install path because it ships this skill and the raw-`wrangler` guard hook together:
-
-```text
-/plugin marketplace add leeguooooo/wrangler-accounts
-/plugin install wrangler-accounts@leeguoo-tools
-```
-
-The plugin does **not** replace the CLI binary. The actual `wrangler-accounts` executable still must be installed on `PATH`:
-
-```bash
-npm i -g @leeguoo/wrangler-accounts
-```
-
-Non-Claude-Code users can keep using the `skills.sh` distribution path for this same `SKILL.md` mirror:
-
-```bash
-npx skills add leeguooooo/wrangler-accounts -g -y
-```
-
-If a Claude Code user previously installed via `skills.sh`, removing the standalone copy avoids a duplicate `/wrangler-accounts` entry in the command picker:
-
-```bash
-npx skills remove wrangler-accounts
-# or: rm -rf ~/.agents/skills/wrangler-accounts
-```
-
-## Prerequisites (check before running any recipe below)
-
-This skill is only documentation — the actual `wrangler-accounts` binary must also be installed on the user's `PATH`. Before running any command below, verify:
-
-```bash
-command -v wrangler-accounts && wrangler-accounts --version
-```
-
-If the command is missing, tell the user to install the CLI first:
-
-```bash
-npm i -g @leeguoo/wrangler-accounts
-```
-
-`wrangler` itself (the Cloudflare CLI) must also be on `PATH`. If missing:
-
-```bash
-npm i -g wrangler
-```
-
-### Minimum versions you should ask the user to upgrade past
-
-If `wrangler-accounts --version` is below any of these, **upgrade first** before debugging anything else — older versions have real bugs that will misdirect you:
-
-| Version | What it fixed | Symptom on older versions |
-|---|---|---|
-| **≥ 1.2.2** | per-profile `WRANGLER_CACHE_DIR`, fixes account-id leak across profiles | `d1`/`r2 object` commands return `7403 not authorized` even though OAuth is valid; deploys silently land in the wrong account |
-| **≥ 1.3.0** | STATUS column distinguishes `valid` / `valid*` / `EXPIRED` (refresh-token-aware) | `list` shows `EXPIRED` for healthy profiles, scaring you into running `login` for no reason |
-| **≥ 1.4.0** | `login` refuses non-TTY contexts and accidental overwrites | `login <name>` hangs forever in non-interactive contexts; reflexive `login` overwrites a healthy profile |
-
-```bash
-npm i -g @leeguoo/wrangler-accounts@latest    # always-safe upgrade
-```
-
-## Triage flow — when something looks wrong
-
-**Run these in order before reaching for `login` or any destructive command.** The agent who skipped this step in a recent incident ended up overwriting a perfectly healthy profile in a sub-shell where the browser couldn't even open.
-
-```bash
-# 1. Verify your binary is recent enough (see version table above)
-wrangler-accounts --version
-
-# 2. Authoritative state of every profile (hits Cloudflare API per profile)
-wrangler-accounts list --deep
-```
-
-How to read `list --deep` output:
-
-| You see | Meaning | What to do |
-|---|---|---|
-| `STATUS valid`  + `VERIFIED ✓ ok` | profile is fine | nothing — proceed with whatever the user actually asked |
-| `STATUS valid*` + `VERIFIED ✓ ok` | profile is fine; access token will auto-refresh on next use | nothing — **`valid*` is healthy, do NOT re-login** |
-| `STATUS EXPIRED` + `VERIFIED ✓ ok` | rare; only on `< 1.3.0` binaries — STATUS is lying | upgrade the CLI; profile is fine |
-| `STATUS EXPIRED` + `VERIFIED ✗ Not logged in` | profile is genuinely broken | `wrangler-accounts login <name>` (interactive only) |
-| `STATUS valid` + `VERIFIED ✗` of any kind | refresh token revoked server-side | `wrangler-accounts login <name>` (interactive only) |
-| `STATUS unknown` | profile file lacks `expiration_time` | run `--deep` (already did) — trust VERIFIED |
-
-**Rule**: only suggest `wrangler-accounts login <name>` when at least one of:
-1. `list --deep` showed `VERIFIED ✗` for that profile, OR
-2. The profile doesn't exist at all yet, OR
-3. The user explicitly says "re-authenticate" / "log me in again"
-
-**If `list --deep` shows everything ✓ but a wrangler command still fails**, the root cause is somewhere other than wrangler-accounts — most likely:
-- Project-local `./.wrangler/state/` is sharing data across profiles (see "What is and isn't isolated")
-- The project's `wrangler.toml` has the wrong `account_id` hardcoded
-- The user is on a CLI version below 1.2.2 (account-id cache leak)
-- The wrangler subcommand actually needs `--remote` or `--local` and you forgot
-
-## Quick Start
-
-- `wrangler-accounts login <name>` — interactive OAuth login into a new profile (never touches real `~/.wrangler`)
-- `wrangler-accounts default <name>` — set the persistent default profile
-- `wrangler-accounts deploy` — run `wrangler deploy` under the default profile
-- `wrangler-accounts --profile personal deploy` — one-shot override
-- `wrangler-accounts exec work -- npm run release` — run a command in an isolated subshell for the `work` profile
-
-> 💡 **Reading the STATUS column**: `valid` = healthy, `valid*` = healthy (will auto-refresh on next use, **don't re-login**), `EXPIRED` = truly broken (need login), `unknown` = run `--deep` to find out. Full table below in "List and inspect profiles".
-
-## Tasks
-
-### Run wrangler against a profile
-
-Per-invocation (preferred for scripts):
-
-`wrangler-accounts --profile <name> <wrangler-args...>`
-
-Or with env var:
-
-`WRANGLER_PROFILE=<name> wrangler-accounts <wrangler-args...>`
-
-Or positional shorthand (only when `<name>` is a saved profile name, not a management subcommand):
-
-`wrangler-accounts <name> <wrangler-args...>`
-
-### Open a subshell for a profile
-
-`wrangler-accounts exec <name>` — launches `$SHELL -i` with isolated `HOME` and `WRANGLER_PROFILE` set. Everything inside the subshell sees the profile, including nested `npm run` scripts, Makefiles, and `npx wrangler`.
-
-Run a single command instead:
-
-`wrangler-accounts exec <name> -- <cmd> [args]`
-
-### Manage the persistent default profile
-
-- `wrangler-accounts default` — print current default (exit 1 if none set)
-- `wrangler-accounts default <name>` — set the default
-- `wrangler-accounts default --unset` — clear the default
-- `wrangler-accounts default --json` — JSON output
-
-### Show the resolved identity for a profile
-
-`wrangler-accounts whoami [--profile <name>]` — reports the profile name, source tier (cli / positional / env / default), and identity from `meta.json`. Does not spawn wrangler.
-
-Use `--json` for structured output.
-
-### List and inspect profiles
-
-- `wrangler-accounts list` — text table with NAME / STATUS / EXPIRES / IDENTITY columns
-- `wrangler-accounts list --json` — structured: array of `{name, isDefault, isActive, status, expirationTime, hasRefreshToken, identity, verified, verifyError}`
-- `wrangler-accounts list --plain` — one profile name per line (scriptable)
-- `wrangler-accounts list --deep` — **authoritative** check: spawns `wrangler whoami` in a shadow HOME for every profile and reports whether Cloudflare actually accepts the credentials. Slower (makes network calls), but the only way to catch revoked refresh tokens or broken profile files.
-- `wrangler-accounts status` / `status --json`
-- Pass `--include-backups` to show hidden backup profiles.
-
-**STATUS values (1.3.0+):**
-
-| value | meaning | user action |
-|---|---|---|
-| `valid` | access_token is currently valid | none |
-| `valid*` / `refreshable` | access_token past expiry **BUT** refresh_token present; wrangler will auto-refresh on next use | **none** — this is fine, don't scare the user |
-| `EXPIRED` / `expired` | access_token expired **AND** no refresh_token saved; profile is genuinely broken | `wrangler-accounts login <name>` |
-| `unknown` | profile file has no `expiration_time` field | run `list --deep` to verify live |
-
-**Cloudflare OAuth lifecycle reference:** access tokens are short-lived (~1 hour) by design. Every profile with `offline_access` in its scopes also has a long-lived refresh_token (~30 days, silently extended on use). Wrangler refreshes access tokens automatically whenever it runs a command and the current one is past expiry. **Do not tell the user to re-login just because `list` shows an expired access token** — check `hasRefreshToken` first. If the profile's STATUS is `valid*` / `refreshable`, nothing is wrong.
-
-The only time a user actually needs `wrangler-accounts login <name>` again is:
-1. STATUS is `EXPIRED` (no refresh_token at all — profile was saved without `offline_access` scope)
-2. OR `list --deep` returns `✗` with "Not logged in" / "refresh token may be revoked" (refresh token itself got invalidated)
-
-### Save, sync, login, remove
-
-- `wrangler-accounts save <name>` — snapshot current Wrangler config as a profile
-- `wrangler-accounts sync <name>` — refresh a specific profile from the current login
-- `wrangler-accounts sync-default` — refresh the default profile
-- `wrangler-accounts login <name>` — fresh isolated OAuth login
-- `wrangler-accounts remove <name>` — delete a profile
-
-### Clean up stale shadow HOMEs
-
-`wrangler-accounts gc [--older-than 1h]` — removes `wa-*` directories under `$TMPDIR` older than the threshold (default 1h). Safe to run at any time.
-
-## Common Recipes
-
-These are the patterns the user is most likely asking about when they mention "Cloudflare accounts", "wrangler", or "multi-account deploys". Pick the one that matches intent.
-
-### User wants: deploy a worker to a specific account
-
-```bash
-wrangler-accounts --profile work deploy
-```
-
-Or, when the user will be on this account for a while:
-
-```bash
-wrangler-accounts default work          # set once
-wrangler-accounts deploy                # uses work from now on
-wrangler-accounts deploy --env staging  # wrangler flags pass through unchanged
-```
-
-### User wants: tail production logs on one account while developing on another
-
-```bash
-# shell 1
-wrangler-accounts --profile work tail my-worker --format pretty
-
-# shell 2 (simultaneously, zero interference)
-wrangler-accounts --profile personal dev
-```
-
-The two shells each get their own shadow `HOME`, so there's no global state for the other to clobber.
-
-### User wants: run a deploy script / npm script / Makefile against a specific account
-
-```bash
-wrangler-accounts exec work -- npm run deploy
-wrangler-accounts exec work -- make release
-wrangler-accounts exec work -- bash scripts/deploy.sh
-```
-
-Anything inside the subshell that calls `wrangler` (directly, via `npx`, via `pnpm`, via a package.json script) automatically uses the `work` profile.
-
-### User wants: set up a new Cloudflare account from scratch
-
-```bash
-wrangler-accounts login new-account    # opens the browser OAuth flow
-wrangler-accounts whoami --profile new-account   # verify identity
-wrangler-accounts list                 # confirm the profile is saved
-```
-
-The login flow runs inside an isolated shadow `HOME`, so the user's real `~/.wrangler/config/default.toml` is never touched.
-
-> ⚠️ **`login` is destructive.** It opens a browser, requires the user to click "Authorize" interactively, and **OVERWRITES** the named profile. As of 1.4.0, `wrangler-accounts login <name>` refuses to run if (a) stdin is not a TTY, or (b) the profile already exists and looks healthy — both unless you pass `--force`. **Never run `login` to "verify" or "refresh" a profile** — see the antipattern below.
-
-### ❌ Antipattern: running `login` to verify a profile works
-
-This is wrong:
-```bash
-wrangler-accounts login Xdreamstar2025   # ❌ DON'T do this just to check
-```
-
-Reasons:
-1. `login` is **destructive** — it overwrites the saved profile with a brand new OAuth flow.
-2. `login` requires a **browser and an interactive terminal** — it cannot complete in a Bash sub-shell, CI runner, or sub-agent context. The command will hang waiting for the user.
-3. The Cloudflare access token in a healthy profile auto-refreshes via `refresh_token` — there is **nothing to "log in to"** when the profile already works.
-
-Use one of these instead:
-
-```bash
-wrangler-accounts whoami --profile Xdreamstar2025   # fast, reads meta.json, no network
-wrangler-accounts list --deep                       # authoritative, runs wrangler whoami per profile
-wrangler-accounts list                              # quick STATUS overview (valid / valid* / EXPIRED / unknown)
-```
-
-Only fall back to `wrangler-accounts login <name>` when:
-- The profile **does not exist yet** (creating a new account profile from scratch)
-- The profile shows `EXPIRED` (truly expired, no refresh_token left) — see STATUS table above
-- `list --deep` returns `✗` with "Not logged in" / "refresh token may be revoked" (server-side revocation)
-- The user **explicitly says** "re-authenticate this profile" / "log me in again"
-
-### User wants: check which account a profile is tied to, without running wrangler
-
-```bash
-wrangler-accounts whoami --profile <name>           # text
-wrangler-accounts whoami --profile <name> --json    # structured
-```
-
-Returns the email + account ID from the saved `meta.json`. No network call.
-
-### User wants: swap between many accounts quickly in one shell
-
-Use `default` as a "current" setting:
-
-```bash
-wrangler-accounts default work
-wrangler-accounts deploy               # work
-wrangler-accounts default personal
-wrangler-accounts dev                  # personal
-```
-
-Or use positional shorthand inline:
-
-```bash
-wrangler-accounts work deploy          # one-shot, no persistent default
-wrangler-accounts personal dev
-```
-
-### User wants: run wrangler in CI with multiple accounts
-
-**Don't use `wrangler-accounts` in CI.** Use native env vars:
-
-```bash
-# In CI secrets:
-CLOUDFLARE_API_TOKEN=<token-with-workers-deploy-scope>
-CLOUDFLARE_ACCOUNT_ID=<account-id>
-
-# In the pipeline:
-wrangler deploy
-```
-
-`wrangler-accounts` is for **local developer** OAuth sessions. CI should use long-lived API tokens directly with plain `wrangler`. Recommend this even if the user asks to use `wrangler-accounts` in CI.
-
-## Troubleshooting
-
-### "Profile 'X' has expired Wrangler OAuth credentials and no refresh_token to renew them"
-
-The saved OAuth access_token is past its `expiration_time` AND there is no `refresh_token` in the profile config (no `offline_access` scope at login time, or the token was revoked). The profile is genuinely broken; only re-authenticating fixes it:
-
-```bash
-wrangler-accounts login <name>
-```
-
-This overwrites the existing profile with a fresh OAuth session. Any saved metadata (identity, etc.) is re-verified.
-
-**Note:** If you see this error in 1.5.0 or earlier, you may be hitting a known regression: any profile whose access_token had passed expiration was blocked even when a refresh_token was present. Upgrade to 1.5.1+ — `wrangler` itself silently refreshes those tokens on the next call, so wrangler-accounts no longer pre-flights against `expiration_time` alone.
-
-### "No profile specified. Options: ..."
-
-The user ran `wrangler-accounts <wrangler-args>` without a resolvable profile. Fix one of:
-
-```bash
-wrangler-accounts --profile <name> <args>       # one-shot
-WRANGLER_PROFILE=<name> wrangler-accounts <args> # env var
-wrangler-accounts default <name>                # persistent default
-```
-
-### "Profile not found: X"
-
-The profile name doesn't exist in `profilesDir`. Check what's saved:
-
-```bash
-wrangler-accounts list
-```
-
-Create it with `wrangler-accounts login <name>` or copy an existing Wrangler login with `wrangler-accounts save <name>`.
-
-### Inside `wrangler-accounts exec`, `cd ~` lands in a weird tmpdir
-
-Expected. Inside an `exec` session, `$HOME` is the shadow HOME. The real home is still accessible:
-
-```bash
-cd "$WRANGLER_ACCOUNT_REAL_HOME"
-```
-
-Or users can add a shell alias: `alias realhome='cd "$WRANGLER_ACCOUNT_REAL_HOME"'`.
-
-### Deprecated `use` command warning
-
-`wrangler-accounts use <name>` still works but prints a deprecation warning. Suggest the replacement based on intent:
-
-- "I want this account to stick for a while" → `wrangler-accounts default <name>`
-- "Just this one command" → `wrangler-accounts --profile <name> <wrangler-args>`
-
-### `[ERROR] A request to the Cloudflare API ... Authentication error [code: 10000]` with `code: 7403` ("not authorized to access this service")
-
-The OAuth token is fine but **the URL contains the wrong account ID**. wrangler caches the user's selected account in `wrangler-account.json`. If that cache file is shared across profiles, profile A's OAuth token gets paired with profile B's cached account ID, sending API calls to the wrong account. Symptoms:
-
-- `deploy` and `secret put` succeed (they don't put account ID in the URL path)
-- `d1 execute --remote`, `r2 object get/put`, anything else with `/accounts/<id>/...` in the URL fails with 7403
-
-**Fix path** (in order):
-
-1. **Are you on wrangler-accounts ≥ 1.2.2?** Run `wrangler-accounts --version`. If `< 1.2.2`, upgrade — earlier versions pointed `WRANGLER_CACHE_DIR` at a shared global path. 1.2.2 isolates the cache per profile.
-2. **Clear the polluted shared cache** (one-time, even after upgrading):
-   ```bash
-   rm -f ~/.wrangler/cache/wrangler-account.json
-   rm -f ~/Library/Preferences/.wrangler/cache/wrangler-account.json   # macOS env-paths fallback
-   ```
-3. **Verify with `wrangler-accounts list --deep`** — the VERIFIED column for each profile should be `✓ ok`. If `✗`, the underlying OAuth session itself is broken; run `wrangler-accounts login <name>`.
-4. **Defense in depth**: set `CLOUDFLARE_ACCOUNT_ID=<correct-id>` in the calling environment. wrangler reads this env var directly and bypasses the cache entirely. Useful for scripts or one-off recovery commands:
-   ```bash
-   CLOUDFLARE_ACCOUNT_ID=<id> wrangler-accounts <profile> r2 object put ...
-   ```
-
-**What to tell the user**: "wrangler returned 7403 because it cached the wrong account ID alongside your OAuth token. This was a real bug in wrangler-accounts ≤ 1.2.1 (shared cache directory across profiles). Upgrade to 1.2.2 and clear the polluted cache."
-
-### "The OAuth config seems right, but the wrong account is being used"
-
-Same root cause as the 7403 above. Default to the same fix path.
-
-### `wrangler dev` (or any `--local` command) shows stale data after switching profiles
-
-Project-local state at `<project>/.wrangler/state/` is **NOT** isolated per profile — wrangler's `getLocalPersistencePath` (cli.js:149025) hardcodes the path next to `wrangler.toml` and the only override is the `--persist-to` CLI flag (no env var hook). So if profile A's `wrangler dev` populated a local D1 emulation, then you switch to profile B and run `wrangler dev` in the same directory, B sees A's emulated rows.
-
-This only affects `--local` simulations. **`--remote` commands hit Cloudflare directly and are unaffected** — that's the common case for d1/r2 work in a multi-account setup.
-
-Two clean fixes:
-
-1. **Use git worktrees** (recommended for any serious multi-profile dev workflow):
-   ```bash
-   git worktree add ../my-project-work main
-   git worktree add ../my-project-personal main
-   cd ../my-project-work && wrangler-accounts exec work     # isolated .wrangler/state/
-   cd ../my-project-personal && wrangler-accounts exec personal
-   ```
-2. **Clear state manually before switching**:
-   ```bash
-   rm -rf .wrangler/state
-   wrangler-accounts --profile <new> dev
-   ```
-
-`wrangler-accounts` does not auto-isolate `.wrangler/state/` because the only mechanism would be argv injection of `--persist-to`, which has too many failure modes (different subcommands accept persistTo at different positions, can't override user-supplied flags, path selection is ambiguous between per-profile and per-profile-per-project). The honest tradeoff is documented in the "What is and isn't isolated" table above — partial isolation with hidden gotchas would be worse than honest sharing.
-
-### Shell history / `.zsh_history` seems to grow when running `exec`
-
-Intentional. By design the shadow HOME symlinks all top-level entries of real HOME except `.wrangler`, so shell history writes pass through to the real file. This is a **convenience** bias, not a clean-room sandbox — the goal is that `exec` subshells feel like a normal terminal with a different Cloudflare account, not a jail.
-
-## 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 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.
-
-## Paths and environment
-
-- `--profile <name>` / `-p <name>` — profile for this invocation (v1.0: `-p` means `--profile`)
-- `--profiles <path>` — profiles directory (long form only since v1.0)
-- `-c, --config <path>` — Wrangler config path
-- `WRANGLER_PROFILE` — profile to use when no `--profile` flag is given
-- `WRANGLER_CONFIG_PATH`, `WRANGLER_ACCOUNTS_DIR`, `XDG_CONFIG_HOME` — path overrides
-
-## Output conventions
-
-Use `--json` when another tool needs to parse results. All v1.0 commands that produce structured data support `--json`.
-
-## Naming rules
-
-Profile names: letters, numbers, dot, underscore, dash only. Names matching management subcommand names (`exec`, `default`, `whoami`, `gc`, `login`, `list`, `status`, `save`, `sync`, `sync-default`, `remove`, `use`, `sync-active`) cannot be reached via positional shorthand — use `--profile <name>` for those.
-
-## Deprecated
-
-- `wrangler-accounts use <name>` — deprecated, prints warning. Use `default <name>` for persistence or `--profile <name>` for one-shot.
-- `wrangler-accounts sync-active` — deprecated alias for `sync-default`.