@brainbase-labs/cli 0.22.0 → 0.23.0

package/README.md

@@ -144,7 +144,7 @@ Playbook files carry a small YAML frontmatter (`title`, `description`) — the C
 | `BRAINBASE_API_URL` | Legacy KLS host override. Control requests use `/api/cli`; it is also the fallback for model-proxy and registry traffic. |
 | `BRAINBASE_PROXY_URL` | Override the model-proxy host used when enabling harness tracking. |
 | `BRAINBASE_REGISTRY_URL` | Override the registry API host. |
-| `BRAINBASE_TOKEN` | Use a PAT instead of the stored login session |
+| `BRAINBASE_TOKEN` | Use a PAT instead of the stored login session. The only way a PAT authenticates a control-plane command — see [Auth](#auth). |
 | `BRAINBASE_HOME` | Where local state lives (default: `~/.brainbase`) |
 
 Model-proxy and registry traffic fall back through `BRAINBASE_API_URL`,
@@ -152,11 +152,29 @@ the server captured at login, and finally `https://api.v1.brainbaselabs.com`.
 
 ## Auth
 
-Managed task creation uses this authentication precedence:
+Three credentials, and which ones a command considers depends on the service
+it talks to:
 
-1. `BRAINBASE_TOKEN` — an explicit PAT from the environment.
-2. `brainbase login` — a Supabase session stored in `~/.brainbase/auth.json`.
-3. `brainbase token create --scopes read,publish` — a PAT stored in `~/.brainbase/token.json` when no login session is configured.
+| Commands | Credentials tried, in order |
+|-|-|
+| `agent`, `orchestration`, `link`, `unlink`, `sync`, `status`, `team` | `BRAINBASE_TOKEN`, then the `auth.json` session |
+| `template`, `skill`, `token` | `BRAINBASE_TOKEN`, then the session, then `token.json` |
+| `task create` | `BRAINBASE_TOKEN`, then the session, then `token.json` — the last only when no session is configured |
+
+`brainbase whoami` (or `--json`) reports which one is active.
+
+**For CI:** `brainbase token create` saves the PAT to `~/.brainbase/token.json`,
+and control-plane commands never read that file — `brainbase agent push` needs
+the token in `BRAINBASE_TOKEN`:
+
+```bash
+export BRAINBASE_TOKEN=bbpat_…
+brainbase agent push
+```
+
+Do not bake a `~/.brainbase` directory into a build image: a leftover
+`auth.json` outranks the stored PAT, and every control-plane command starts
+failing once its session expires.
 
 An explicit PAT does not inherit routing from a stored login. Set
 `BRAINBASE_CONTROL_PLANE_URL` when using a PAT against a non-default MAS host.

package/dist/index.js

@@ -36008,7 +36008,7 @@ function padStart(s, n) {
 // package.json
 var package_default = {
   name: "@brainbase-labs/cli",
-  version: "0.22.0",
+  version: "0.23.0",
   description: "Pack, share, and install agent templates across harnesses (Claude Code, Codex, ...).",
   type: "module",
   bin: {
@@ -53931,6 +53931,76 @@ function clearTokenIfMatches(prefix) {
   });
 }
 
+// src/core/credentials.ts
+var REGISTRY_COMMANDS = "template, skill, token";
+var CONTROL_PLANE_COMMANDS = "agent, orchestration, link, unlink, sync, status, team";
+var NOT_A_PAT = "(not a bbpat_… token)";
+function maskPat(token) {
+  if (!isValidTokenFormat(token))
+    return NOT_A_PAT;
+  return token.slice(0, TOKEN_PREFIX_LEN);
+}
+function readEnvPat() {
+  const value = process.env.BRAINBASE_TOKEN?.trim();
+  if (!value)
+    return null;
+  return { prefix: maskPat(value), malformed: !isValidTokenFormat(value) };
+}
+function storedPatIgnoredHint(client) {
+  const setEnv = `Set BRAINBASE_TOKEN to that token's value to authenticate with it here, ` + "or run `brainbase login` to refresh the session";
+  switch (client) {
+    case "control-plane":
+      return `The PAT saved in ${TOKEN_FILE} is never used by control-plane ` + `commands (${CONTROL_PLANE_COMMANDS}). ${setEnv}.`;
+    case "managed-task":
+      return `The PAT saved in ${TOKEN_FILE} is not used while a login session is ` + `configured. ${setEnv} — or \`brainbase logout\`, which leaves the ` + "PAT as the only credential.";
+    default: {
+      const exhaustive = client;
+      throw new Error(`unhandled credential client: ${String(exhaustive)}`);
+    }
+  }
+}
+function withStoredPatHint(reason, client) {
+  if (!readToken())
+    return reason;
+  const trimmed = reason.trimEnd();
+  const separator = /[.!?:]$/.test(trimmed) ? " " : ". ";
+  return `${trimmed}${separator}${storedPatIgnoredHint(client)}`;
+}
+function withRejectedSessionHint(message, source, client) {
+  if (source !== "session")
+    return message;
+  return withStoredPatHint(message, client);
+}
+function isRefreshable(session) {
+  return Boolean(session.refresh_token && session.supabase_url && session.supabase_anon_key);
+}
+function describeCredentials() {
+  const env3 = readEnvPat();
+  const status = authStatus();
+  const stored = readToken();
+  const refreshable = Boolean(status.session && !status.ok && isRefreshable(status.session));
+  const session = status.session ? {
+    email: status.session.email ?? null,
+    userId: status.session.user_id,
+    expiresAt: status.session.expires_at ?? null,
+    expired: !status.ok,
+    refreshable
+  } : null;
+  let active = null;
+  if (env3)
+    active = "env_pat";
+  else if (status.ok || refreshable)
+    active = "session";
+  else if (stored)
+    active = "stored_pat";
+  return {
+    active,
+    envPat: env3,
+    session,
+    storedPat: stored ? { name: stored.name ?? null, prefix: stored.prefix } : null
+  };
+}
+
 // src/core/api.ts
 var DEFAULT_CONTROL_PLANE_BASE = "https://api.brainbaselabs.com";
 var DEFAULT_PROXY_BASE = "https://api.v1.brainbaselabs.com";
@@ -54005,7 +54075,7 @@ function legacyScheduleError() {
 function legacyAgentConfigError() {
   return new ApiError("Declarative machine/model config requires the MAS control plane. Set BRAINBASE_CONTROL_PLANE_URL or unset the legacy BRAINBASE_API_URL override.", 400);
 }
-async function resolveCredential() {
+async function resolveCredential(storedPatHint = "control-plane") {
   const envToken = process.env.BRAINBASE_TOKEN;
   if (envToken && envToken.trim()) {
     return {
@@ -54023,19 +54093,20 @@ async function resolveCredential() {
     };
   }
   const status = authStatus();
-  throw new ApiError(status.ok ? "CLI authentication changed while this command was starting; retry it" : status.reason ?? "not logged in", 401);
+  const reason = status.reason ?? "not logged in";
+  throw new ApiError(status.ok ? "CLI authentication changed while this command was starting; retry it" : storedPatHint ? withStoredPatHint(reason, storedPatHint) : reason, 401);
 }
 async function resolveMasCredential() {
   const configuredSession = readAuth();
   try {
-    return await resolveCredential();
+    return await resolveCredential(null);
   } catch (error) {
     if (!(error instanceof ApiError && error.status === 401)) {
       throw error;
     }
     if (configuredSession || readAuth()) {
       if (readToken()) {
-        throw new ApiError(`${error.message}. A stored PAT is available but will not be used while a login session is configured. Run \`brainbase logout\` to use the stored PAT, or \`brainbase login\` to refresh the session.`, 401);
+        throw new ApiError(`${error.message}. ${storedPatIgnoredHint("managed-task")}`, 401);
       }
       throw error;
     }
@@ -54134,7 +54205,8 @@ async function request(pathname, init = {}) {
     body = text2 ? JSON.parse(text2) : null;
   } catch {}
   if (!res.ok) {
-    throw new ApiError(apiErrorMessage(body, res.status), res.status, body);
+    const message = apiErrorMessage(body, res.status);
+    throw new ApiError(res.status === 401 ? withRejectedSessionHint(message, credential.source, "control-plane") : message, res.status, body);
   }
   return body;
 }
@@ -54277,7 +54349,7 @@ async function masRequest(pathname, init) {
     }
     if (!res.ok) {
       const message = masApiErrorMessage(body, res.status);
-      throw new ApiError(res.status >= 500 ? `${message} Task creation may still be processing; check your tasks before running this command again.` : message, res.status, body);
+      throw new ApiError(res.status >= 500 ? `${message} Task creation may still be processing; check your tasks before running this command again.` : res.status === 401 ? withRejectedSessionHint(message, credential.source, "managed-task") : message, res.status, body);
     }
     return body;
   }
@@ -61658,12 +61730,13 @@ async function runLogin(_cwd, args) {
 // src/ui/ink/IdentityCard.tsx
 var jsx_dev_runtime15 = __toESM(require_jsx_dev_runtime(), 1);
 function IdentityCard(props) {
+  const hasRows = Boolean(props.rows?.length || props.controlPlaneUrl || props.expiresAt);
   return /* @__PURE__ */ jsx_dev_runtime15.jsxDEV(Card, {
     title: props.title,
     tone: props.tone ?? "info",
     children: [
       props.email && /* @__PURE__ */ jsx_dev_runtime15.jsxDEV(Box_default, {
-        marginBottom: props.controlPlaneUrl || props.expiresAt ? 1 : 0,
+        marginBottom: hasRows ? 1 : 0,
         children: /* @__PURE__ */ jsx_dev_runtime15.jsxDEV(Text, {
           bold: true,
           children: props.email
@@ -61672,6 +61745,20 @@ function IdentityCard(props) {
       /* @__PURE__ */ jsx_dev_runtime15.jsxDEV(Box_default, {
         flexDirection: "column",
         children: [
+          props.rows?.map(([label, value]) => /* @__PURE__ */ jsx_dev_runtime15.jsxDEV(Box_default, {
+            children: [
+              /* @__PURE__ */ jsx_dev_runtime15.jsxDEV(Box_default, {
+                width: 15,
+                children: /* @__PURE__ */ jsx_dev_runtime15.jsxDEV(Text, {
+                  dimColor: true,
+                  children: label
+                }, undefined, false, undefined, this)
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsx_dev_runtime15.jsxDEV(Text, {
+                children: value
+              }, undefined, false, undefined, this)
+            ]
+          }, label, true, undefined, this)),
           props.controlPlaneUrl && /* @__PURE__ */ jsx_dev_runtime15.jsxDEV(Box_default, {
             children: [
               /* @__PURE__ */ jsx_dev_runtime15.jsxDEV(Box_default, {
@@ -61739,22 +61826,117 @@ async function runLogout() {
 }
 
 // src/cli/whoami.ts
-async function runWhoami() {
-  const { ok, session, reason } = authStatus();
-  if (!ok || !session) {
-    await showIdentityCard({
-      title: "NOT SIGNED IN",
-      tone: "warn",
-      message: `${reason ?? "not logged in"}. Run \`brainbase login\` to connect this device.`
-    });
-    process.exit(1);
+function usableForControlPlane(report) {
+  switch (report.active) {
+    case "env_pat":
+      return !report.envPat?.malformed;
+    case "session":
+      return true;
+    case "stored_pat":
+    case null:
+      return false;
+    default: {
+      const exhaustive = report.active;
+      throw new Error(`unhandled credential: ${String(exhaustive)}`);
+    }
+  }
+}
+function exitCodeFor(report) {
+  return usableForControlPlane(report) ? 0 : 1;
+}
+function reasonFor(report) {
+  switch (report.active) {
+    case "env_pat":
+      return report.envPat?.malformed ? "BRAINBASE_TOKEN is set to something that is not a `bbpat_…` token, " + "and it outranks every other credential — so every request will fail " + "until it is corrected or unset. Mint one with `brainbase token create`." : null;
+    case "session":
+      return null;
+    case "stored_pat":
+      return `The stored PAT authenticates registry commands (${REGISTRY_COMMANDS}) only. ` + `Set BRAINBASE_TOKEN to its value for ${CONTROL_PLANE_COMMANDS}, ` + "or run `brainbase login`.";
+    case null:
+      return report.session?.expired ? "Session expired. Run `brainbase login` to connect this device." : "Not logged in. Run `brainbase login` to connect this device.";
+    default: {
+      const exhaustive = report.active;
+      throw new Error(`unhandled credential: ${String(exhaustive)}`);
+    }
+  }
+}
+function toJson(report, reason) {
+  const usingSession = report.active === "session";
+  return {
+    credential: report.active,
+    authenticated: report.active !== null && !report.envPat?.malformed,
+    control_plane: usableForControlPlane(report),
+    email: usingSession ? report.session?.email ?? null : null,
+    user_id: usingSession ? report.session?.userId ?? null : null,
+    expires_at: usingSession ? report.session?.expiresAt ?? null : null,
+    token_prefix: report.active === "env_pat" ? report.envPat?.prefix ?? null : report.active === "stored_pat" ? report.storedPat?.prefix ?? null : null,
+    control_plane_url: controlPlaneBaseUrl(usingSession ? readAuth() : null),
+    session: report.session ? {
+      present: true,
+      expired: report.session.expired,
+      refreshable: report.session.refreshable
+    } : { present: false, expired: false, refreshable: false },
+    stored_pat: report.storedPat ? { present: true, name: report.storedPat.name } : { present: false, name: null },
+    reason
+  };
+}
+function displayPrefix(prefix) {
+  return prefix === NOT_A_PAT ? prefix : `${prefix}…`;
+}
+function cardRows(report) {
+  const rows = [];
+  switch (report.active) {
+    case "env_pat":
+      rows.push(["credential", "BRAINBASE_TOKEN (env PAT)"]);
+      if (report.envPat) {
+        rows.push(["token", displayPrefix(report.envPat.prefix)]);
+      }
+      break;
+    case "session":
+      rows.push([
+        "credential",
+        report.session?.refreshable ? "login session (auth.json) — expired, renews on next use" : "login session (auth.json)"
+      ]);
+      break;
+    case "stored_pat":
+      rows.push(["credential", "stored PAT (token.json)"]);
+      rows.push([
+        "token",
+        report.storedPat?.name ? `${displayPrefix(report.storedPat.prefix)} (${report.storedPat.name})` : displayPrefix(report.storedPat?.prefix ?? "?")
+      ]);
+      break;
+    case null:
+      break;
+    default: {
+      const exhaustive = report.active;
+      throw new Error(`unhandled credential: ${String(exhaustive)}`);
+    }
+  }
+  if (report.session && report.active !== "session") {
+    rows.push([
+      "session",
+      `${report.session.email ?? report.session.userId} (${report.session.expired ? "expired" : "not used — env PAT wins"})`
+    ]);
+  }
+  return rows;
+}
+async function runWhoami(args = {}) {
+  const report = describeCredentials();
+  const reason = reasonFor(report);
+  process.exitCode = exitCodeFor(report);
+  if (args.json) {
+    console.log(JSON.stringify(toJson(report, reason), null, 2));
+    return;
   }
+  const signedIn = report.active !== null;
   await showIdentityCard({
-    title: "WHOAMI",
-    tone: "ok",
-    email: session.email ?? session.user_id,
-    controlPlaneUrl: controlPlaneBaseUrl(session),
-    expiresAt: session.expires_at
+    title: signedIn ? "WHOAMI" : "NOT SIGNED IN",
+    tone: process.exitCode === 0 ? "ok" : "warn",
+    email: report.active === "session" ? report.session?.email ?? report.session?.userId ?? null : null,
+    controlPlaneUrl: signedIn ? controlPlaneBaseUrl(report.active === "session" ? readAuth() : null) : null,
+    expiresAt: report.active === "session" ? report.session?.expiresAt : null,
+    rows: cardRows(report),
+    message: reason ?? undefined
   });
 }
 
@@ -68922,14 +69104,6 @@ function TokenCreatedCard(props) {
     tone: "warn",
     subtitle: "shown ONCE — copy it now",
     children: [
-      /* @__PURE__ */ jsx_dev_runtime17.jsxDEV(Box_default, {
-        marginBottom: 1,
-        children: /* @__PURE__ */ jsx_dev_runtime17.jsxDEV(Text, {
-          bold: true,
-          color: "yellow",
-          children: props.token
-        }, undefined, false, undefined, this)
-      }, undefined, false, undefined, this),
       /* @__PURE__ */ jsx_dev_runtime17.jsxDEV(Box_default, {
         flexDirection: "column",
         marginBottom: 1,
@@ -68990,20 +69164,22 @@ function TokenCreatedCard(props) {
           /* @__PURE__ */ jsx_dev_runtime17.jsxDEV(Text, {
             dimColor: true,
             children: [
-              "saved locally to ",
+              "saved to ",
               props.storedAt,
-              " (mode 0600)"
+              " (mode 0600) — covers ",
+              REGISTRY_COMMANDS
             ]
           }, undefined, true, undefined, this),
           /* @__PURE__ */ jsx_dev_runtime17.jsxDEV(Text, {
             dimColor: true,
             children: [
-              "for CI: set ",
+              CONTROL_PLANE_COMMANDS,
+              " do ",
               /* @__PURE__ */ jsx_dev_runtime17.jsxDEV(Text, {
                 bold: true,
-                children: "BRAINBASE_TOKEN"
+                children: "not"
               }, undefined, false, undefined, this),
-              " instead of relying on token.json"
+              " read that file — export it instead:"
             ]
           }, undefined, true, undefined, this)
         ]
@@ -69012,9 +69188,12 @@ function TokenCreatedCard(props) {
   }, undefined, true, undefined, this);
 }
 async function showTokenCreatedCard(props) {
+  const { token, ...card } = props;
   await renderStatic(/* @__PURE__ */ jsx_dev_runtime17.jsxDEV(TokenCreatedCard, {
-    ...props
+    ...card
   }, undefined, false, undefined, this));
+  console.log(`  export BRAINBASE_TOKEN=${token}`);
+  console.log("");
 }
 function TokenListCard(props) {
   if (props.active.length === 0) {
@@ -69180,11 +69359,32 @@ function isAllowedScope(value) {
 function isExpired2(token) {
   return Boolean(token.expires_at && Date.parse(token.expires_at) <= Date.now());
 }
+function isJwtRequired(body) {
+  if (!body || typeof body !== "object")
+    return false;
+  const detail = body.detail;
+  if (!detail || typeof detail !== "object")
+    return false;
+  return detail.code === "jwt_required";
+}
+function sessionWouldBeUsed() {
+  const { ok, session } = authStatus();
+  if (ok)
+    return true;
+  return Boolean(session?.refresh_token && session.supabase_url && session.supabase_anon_key);
+}
 function withLoginHint(error) {
-  if (error instanceof ApiError && error.status === 403) {
-    return new Error("Managing tokens needs a logged-in session; a PAT (BRAINBASE_TOKEN) cannot. " + "Run `brainbase login` and try again.");
-  }
-  return error;
+  if (!(error instanceof ApiError) || error.status !== 403)
+    return error;
+  if (!isJwtRequired(error.body))
+    return error;
+  if (!process.env.BRAINBASE_TOKEN?.trim()) {
+    if (sessionWouldBeUsed() || !readToken())
+      return error;
+    return new Error("Managing tokens needs a logged-in session; the stored PAT cannot. " + "Run `brainbase login` and try again.");
+  }
+  const lead = "Managing tokens needs a logged-in session, and BRAINBASE_TOKEN is set — " + "that PAT is being used instead.";
+  return new Error(sessionWouldBeUsed() ? `${lead} Run \`unset BRAINBASE_TOKEN\` and try again.` : `${lead} Run \`unset BRAINBASE_TOKEN\`, then \`brainbase login\`.`);
 }
 async function runTokenCreate(args) {
   banner("token create — make a long-lived CLI key");
@@ -69207,10 +69407,16 @@ async function runTokenCreate(args) {
   }
   const spinner = de();
   spinner.start("Creating token…");
-  const created = await registryApi.createCliToken({
-    name,
-    scopes
-  });
+  let created;
+  try {
+    created = await registryApi.createCliToken({
+      name,
+      scopes
+    });
+  } catch (error) {
+    spinner.stop("Could not create token.");
+    throw withLoginHint(error);
+  }
   spinner.stop("Token created.");
   try {
     writeToken(created.token, name);
@@ -69231,7 +69437,12 @@ async function runTokenCreate(args) {
 }
 async function runTokenList() {
   banner("tokens");
-  const tokens = await registryApi.listCliTokens();
+  let tokens;
+  try {
+    tokens = await registryApi.listCliTokens();
+  } catch (error) {
+    throw withLoginHint(error);
+  }
   const active = tokens.filter((t) => !t.revoked_at);
   const revoked = tokens.filter((t) => t.revoked_at);
   const local = readToken();
@@ -69354,7 +69565,7 @@ async function runTokenRevoke(args) {
       }
       throw new Error(`The server reported no active token with id ${args.id}, but it listed one a moment ago. ` + "The local token has been left alone, since that key may still work. " + "If this server predates `DELETE /v1/registry/cli-tokens/{id}`, revoke from the web app instead.");
     }
-    throw error;
+    throw withLoginHint(error);
   }
   reconcileDeadToken(target, `Revoked ${import_picocolors48.default.bold(target.name)}.`);
 }
@@ -80201,7 +80412,7 @@ function help() {
   out.push("");
   out.push(`  ${import_picocolors52.default.cyan("login")}     ${import_picocolors52.default.dim("  open the web app and connect this device")}`);
   out.push(`  ${import_picocolors52.default.cyan("logout")}    ${import_picocolors52.default.dim("  clear the local session")}`);
-  out.push(`  ${import_picocolors52.default.cyan("whoami")}    ${import_picocolors52.default.dim("  show the current user")}`);
+  out.push(`  ${import_picocolors52.default.cyan("whoami")} ${import_picocolors52.default.dim("[--json]")} ${import_picocolors52.default.dim(" show which credential is in use and what it covers")}`);
   out.push("");
   out.push(divider("DISCOVERY"));
   out.push("");
@@ -80304,7 +80515,7 @@ function help() {
   out.push(`  ${import_picocolors52.default.dim("BRAINBASE_API_URL")}      legacy KLS host override (uses /api/cli; proxy/registry fallback)`);
   out.push(`  ${import_picocolors52.default.dim("BRAINBASE_PROXY_URL")}    override the model-proxy URL used by harness traffic (default https://api.v1.brainbaselabs.com)`);
   out.push(`  ${import_picocolors52.default.dim("BRAINBASE_REGISTRY_URL")} override the registry API URL (default https://api.v1.brainbaselabs.com)`);
-  out.push(`  ${import_picocolors52.default.dim("BRAINBASE_TOKEN")}        long-lived CLI PAT (overrides token.json)`);
+  out.push(`  ${import_picocolors52.default.dim("BRAINBASE_TOKEN")}        long-lived CLI PAT; the only PAT control-plane commands accept (token.json is not read there)`);
   out.push(`  ${import_picocolors52.default.dim("BRAINBASE_SKIP_AUTH")}    bypass the auth gate for development`);
   out.push(`  ${import_picocolors52.default.dim("BRAINBASE_NON_INTERACTIVE")} force non-interactive mode — skip/auto-default prompts (CI & agents)`);
   out.push(`  ${import_picocolors52.default.dim("BRAINBASE_RUN_ENTRYPOINT")} =1 → agent pull executes the agent entrypoint (sandbox boots; or pass --run-entrypoint)`);
@@ -80556,7 +80767,7 @@ async function main() {
         break;
       }
       case "whoami": {
-        await runWhoami();
+        await runWhoami({ json: jsonFlag });
         break;
       }
       case "template": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainbase-labs/cli",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Pack, share, and install agent templates across harnesses (Claude Code, Codex, ...).",
   "type": "module",
   "bin": {