@leeguoo/wrangler-accounts 1.5.1 → 1.6.0

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,7 +677,7 @@ 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*"
@@ -594,12 +749,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 +809,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 +850,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 +1157,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 +1165,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 +1197,7 @@ function main() {
             command: "whoami",
             profile: resolved.name,
             source: resolved.source,
+            type: profileType,
             identity,
           },
           null,
@@ -1061,7 +1255,7 @@ function main() {
 
     let resolved;
     try {
-      resolved = resolveProfile({
+      resolved = resolveProfileAny({
         cliProfile: profileName,
         positional: null,
         env: process.env,
@@ -1073,15 +1267,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 +1280,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 +1320,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.0",
   "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

@@ -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