@asteroidai/cli 1.8.193 → 1.8.204

package/dist/asteroid.js

@@ -4875,16 +4875,25 @@ function defineCommands(root, options, dotted = /* @__PURE__ */ new Map(), onInv
     const defaults = command.args.map(
       (arg) => options.defaultArg?.(command, arg)
     );
-    command.args.forEach((arg, i) => {
+    const defaulted = defaults[0] !== void 0;
+    command.args.forEach((arg) => {
       leaf.argument(
-        defaults[i] === void 0 ? `<${arg.flag}>` : `[${arg.flag}]`,
+        defaulted ? `[${arg.flag}]` : `<${arg.flag}>`,
         arg.description ?? ""
       );
     });
-    if (defaults.some((value2) => value2 !== void 0) && options.defaultArgNote) {
-      leaf.addHelpText("after", `
-${options.defaultArgNote}`);
+    if (defaulted) {
+      const names = command.args.map(
+        (arg, i) => i === 0 ? `[${arg.flag}]` : `<${arg.flag}>`
+      );
+      leaf.usage(`[options] ${names.join(" ")}`);
     }
+    const notes = [
+      defaults.some((value2) => value2 !== void 0) ? options.defaultArgNote : void 0,
+      options.helpNote?.(command)
+    ].filter(Boolean);
+    if (notes.length > 0) leaf.addHelpText("after", `
+${notes.join("\n")}`);
     leafOptions(leaf, command);
     leaf.action((...args) => {
       const cmd = args.at(-1);
@@ -4893,7 +4902,7 @@ ${options.defaultArgNote}`);
         positionals = [defaults[0], ...positionals];
       }
       if (positionals.length !== command.args.length) {
-        const expected = command.args.map((a) => `<${a.flag}>`).join(" ");
+        const expected = command.args.map((a, i) => i === 0 && defaulted ? `[${a.flag}]` : `<${a.flag}>`).join(" ");
         throw new UsageError(
           `expected ${expected}, got ${cmd.args.length} argument(s)`
         );
@@ -5192,6 +5201,8 @@ var CredentialStore = class {
 // src/auth/credentials.ts
 var AuthError = class extends Error {
 };
+var API_KEY_OVERRIDES = "ASTEROID_API_KEY is set, so the CLI uses that key and ignores `asteroid login`.";
+var UNSET_API_KEY = "Run `unset ASTEROID_API_KEY` to use your login instead.";
 function orgFromToken(token) {
   const claims = tokenClaims(token);
   if (!claims.org_id) return void 0;
@@ -5301,7 +5312,7 @@ var ApiError = class extends Error {
   status;
   body;
 };
-var VERSION = "1.8.193";
+var VERSION = "1.8.204";
 function problem(status, body, fallback) {
   if (body && typeof body === "object") {
     const record2 = body;
@@ -5368,11 +5379,13 @@ async function send(apiUrl, auth, request, binary, fetchImpl = fetch) {
     } catch {
       parsed = text2;
     }
-    throw new ApiError(
-      response.status,
-      problem(response.status, parsed, text2.slice(0, 200)),
-      parsed
-    );
+    let message = problem(response.status, parsed, text2.slice(0, 200));
+    const sentKey = "X-Api-Key" in hopHeaders;
+    if (sentKey && response.status === 401)
+      message = `ASTEROID_API_KEY was rejected: ${message}. Check the key. ${UNSET_API_KEY}`;
+    else if (sentKey && response.status === 403)
+      message = `${message} (sent with ASTEROID_API_KEY. ${UNSET_API_KEY})`;
+    throw new ApiError(response.status, message, parsed);
   }
   if (binary)
     return {
@@ -5401,7 +5414,8 @@ async function chooseOrg(deps, orgs2) {
 async function login(deps) {
   if (deps.env.apiKey)
     deps.stderr(
-      "Note: ASTEROID_API_KEY is set and takes precedence over this sign-in.\n"
+      `Warning: ${API_KEY_OVERRIDES} Every command will use the key, not this sign-in. ${UNSET_API_KEY}
+`
     );
   const client = {
     clientId: deps.env.workosClientId,
@@ -5467,7 +5481,7 @@ async function logout(deps) {
 async function orgs(deps, flagOrg, json) {
   if (deps.env.apiKey)
     throw new UsageError(
-      "ASTEROID_API_KEY acts in one organization. Run `asteroid whoami` to see it."
+      `${API_KEY_OVERRIDES} The key acts in one organization; \`asteroid whoami\` shows it. ${UNSET_API_KEY}`
     );
   const config = loadConfig(deps.env);
   const auth = await resolveAuth(
@@ -5497,7 +5511,7 @@ async function orgs(deps, flagOrg, json) {
 async function use(deps, ref) {
   if (deps.env.apiKey)
     throw new UsageError(
-      "ASTEROID_API_KEY is pinned to one organization; `use` needs `asteroid login`."
+      `${API_KEY_OVERRIDES} \`use\` only switches the login's organization. ${UNSET_API_KEY}`
     );
   const config = loadConfig(deps.env);
   if (!ref && deps.ui && (config.orgs?.length ?? 0) > 0) {
@@ -5556,6 +5570,7 @@ async function whoami(deps, flagOrg, json) {
       as: person?.email ?? body.id,
       kind: body.kind,
       credential: body.credential,
+      source: auth.kind === "api-key" ? "ASTEROID_API_KEY" : "asteroid login",
       organization,
       ...minutes === void 0 ? {} : { tokenExpiresIn: `${minutes}m` }
     })}
@@ -5765,7 +5780,7 @@ function rejectUnknown(flags) {
 function rejectOrgWithApiKey(deps, flagOrg) {
   if (deps.env.apiKey && (flagOrg || deps.env.org)) {
     throw new UsageError(
-      "ASTEROID_API_KEY acts in its own organization. Unset --org and ASTEROID_ORG, or sign in with `asteroid login`."
+      `${API_KEY_OVERRIDES} The key acts in its own organization, so drop --org and ASTEROID_ORG. ${UNSET_API_KEY}`
     );
   }
 }

package/dist/core.js

@@ -4808,16 +4808,25 @@ function defineCommands(root, options, dotted = /* @__PURE__ */ new Map(), onInv
     const defaults = command.args.map(
       (arg) => options.defaultArg?.(command, arg)
     );
-    command.args.forEach((arg, i) => {
+    const defaulted = defaults[0] !== void 0;
+    command.args.forEach((arg) => {
       leaf.argument(
-        defaults[i] === void 0 ? `<${arg.flag}>` : `[${arg.flag}]`,
+        defaulted ? `[${arg.flag}]` : `<${arg.flag}>`,
         arg.description ?? ""
       );
     });
-    if (defaults.some((value2) => value2 !== void 0) && options.defaultArgNote) {
-      leaf.addHelpText("after", `
-${options.defaultArgNote}`);
+    if (defaulted) {
+      const names = command.args.map(
+        (arg, i) => i === 0 ? `[${arg.flag}]` : `<${arg.flag}>`
+      );
+      leaf.usage(`[options] ${names.join(" ")}`);
     }
+    const notes = [
+      defaults.some((value2) => value2 !== void 0) ? options.defaultArgNote : void 0,
+      options.helpNote?.(command)
+    ].filter(Boolean);
+    if (notes.length > 0) leaf.addHelpText("after", `
+${notes.join("\n")}`);
     leafOptions(leaf, command);
     leaf.action((...args) => {
       const cmd = args.at(-1);
@@ -4826,7 +4835,7 @@ ${options.defaultArgNote}`);
         positionals = [defaults[0], ...positionals];
       }
       if (positionals.length !== command.args.length) {
-        const expected = command.args.map((a) => `<${a.flag}>`).join(" ");
+        const expected = command.args.map((a, i) => i === 0 && defaulted ? `[${a.flag}]` : `<${a.flag}>`).join(" ");
         throw new UsageError(
           `expected ${expected}, got ${cmd.args.length} argument(s)`
         );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asteroidai/cli",
-  "version": "1.8.193",
+  "version": "1.8.204",
   "description": "The asteroid command-line interface for the Asteroid platform.",
   "type": "module",
   "license": "MIT",

package/src/account.ts

@@ -1,9 +1,11 @@
 import { UsageError } from "./args";
 import {
+  API_KEY_OVERRIDES,
   AuthError,
   orgFromToken,
   rememberOrg,
   resolveAuth,
+  UNSET_API_KEY,
 } from "./auth/credentials";
 import { CredentialStore } from "./auth/store";
 import {
@@ -40,7 +42,7 @@ async function chooseOrg(deps: Deps, orgs: WorkosOrg[]): Promise<WorkosOrg> {
 export async function login(deps: Deps): Promise<number> {
   if (deps.env.apiKey)
     deps.stderr(
-      "Note: ASTEROID_API_KEY is set and takes precedence over this sign-in.\n",
+      `Warning: ${API_KEY_OVERRIDES} Every command will use the key, not this sign-in. ${UNSET_API_KEY}\n`,
     );
   const client = {
     clientId: deps.env.workosClientId,
@@ -116,7 +118,7 @@ export async function orgs(
 ): Promise<number> {
   if (deps.env.apiKey)
     throw new UsageError(
-      "ASTEROID_API_KEY acts in one organization. Run `asteroid whoami` to see it.",
+      `${API_KEY_OVERRIDES} The key acts in one organization; \`asteroid whoami\` shows it. ${UNSET_API_KEY}`,
     );
   const config = loadConfig(deps.env);
   const auth = await resolveAuth(
@@ -148,7 +150,7 @@ export async function use(
 ): Promise<number> {
   if (deps.env.apiKey)
     throw new UsageError(
-      "ASTEROID_API_KEY is pinned to one organization; `use` needs `asteroid login`.",
+      `${API_KEY_OVERRIDES} \`use\` only switches the login's organization. ${UNSET_API_KEY}`,
     );
   const config = loadConfig(deps.env);
   if (!ref && deps.ui && (config.orgs?.length ?? 0) > 0) {
@@ -213,6 +215,7 @@ export async function whoami(
       as: person?.email ?? body.id,
       kind: body.kind,
       credential: body.credential,
+      source: auth.kind === "api-key" ? "ASTEROID_API_KEY" : "asteroid login",
       organization,
       ...(minutes === undefined ? {} : { tokenExpiresIn: `${minutes}m` }),
     })}\n`,

package/src/auth/credentials.ts

@@ -12,6 +12,11 @@ import { refresh, tokenClaims, WorkosError } from "./workos";
 
 export class AuthError extends Error {}
 
+export const API_KEY_OVERRIDES =
+  "ASTEROID_API_KEY is set, so the CLI uses that key and ignores `asteroid login`.";
+export const UNSET_API_KEY =
+  "Run `unset ASTEROID_API_KEY` to use your login instead.";
+
 export interface Auth {
   kind: "api-key" | "bearer";
   headers: Record<string, string>;

package/src/http.ts

@@ -1,4 +1,4 @@
-import type { Auth } from "./auth/credentials";
+import { type Auth, UNSET_API_KEY } from "./auth/credentials";
 import type { BuiltRequest } from "./request";
 
 export class ApiError extends Error {
@@ -95,11 +95,13 @@ export async function send(
     } catch {
       parsed = text;
     }
-    throw new ApiError(
-      response.status,
-      problem(response.status, parsed, text.slice(0, 200)),
-      parsed,
-    );
+    let message = problem(response.status, parsed, text.slice(0, 200));
+    const sentKey = "X-Api-Key" in hopHeaders;
+    if (sentKey && response.status === 401)
+      message = `ASTEROID_API_KEY was rejected: ${message}. Check the key. ${UNSET_API_KEY}`;
+    else if (sentKey && response.status === 403)
+      message = `${message} (sent with ASTEROID_API_KEY. ${UNSET_API_KEY})`;
+    throw new ApiError(response.status, message, parsed);
   }
   if (binary)
     return {

package/src/program.test.ts

@@ -96,4 +96,41 @@ describe("parseInvocation", () => {
     );
     expect(got.parsed.positionals).toEqual(["chat-wf"]);
   });
+
+  it("adds a per-command help note", async () => {
+    const help = await parseInvocation(["workflow", "get", "--help"], {
+      commands: COMMANDS,
+      helpNote: (command) =>
+        command.tool === "workflow_get" ? "Note for get." : undefined,
+    });
+
+    expect(help.kind === "exit" && help.stdout).toContain("Note for get.");
+  });
+
+  it("fills a defaulted first argument ahead of a required one", async () => {
+    const options = {
+      commands: COMMANDS,
+      defaultArg: (_: unknown, arg: { name: string }) =>
+        arg.name === "workflowId" ? "chat-wf" : undefined,
+    };
+
+    const short = command(
+      await parseInvocation(["schedule", "get", "s-1"], options),
+    );
+    expect(short.parsed.positionals).toEqual(["chat-wf", "s-1"]);
+
+    const full = command(
+      await parseInvocation(["schedule", "get", "wf-2", "s-1"], options),
+    );
+    expect(full.parsed.positionals).toEqual(["wf-2", "s-1"]);
+
+    const help = await parseInvocation(["schedule", "get", "--help"], options);
+    expect(help.kind === "exit" && help.stdout).toContain(
+      "[workflow-id] <schedule-id>",
+    );
+
+    await expect(parseInvocation(["schedule", "get"], options)).rejects.toThrow(
+      "expected [workflow-id] <schedule-id>, got 0 argument(s)",
+    );
+  });
 });

package/src/program.ts

@@ -16,6 +16,7 @@ export interface ProgramOptions {
   description?: string;
   defaultArg?: (command: CliCommand, arg: Option) => string | undefined;
   defaultArgNote?: string;
+  helpNote?: (command: CliCommand) => string | undefined;
 }
 
 const DOTTED = /^--([a-z0-9-]+\.[a-z0-9.-]+)(?:=(.*))?$/;
@@ -155,18 +156,26 @@ export function defineCommands(
     const defaults = command.args.map((arg) =>
       options.defaultArg?.(command, arg),
     );
-    command.args.forEach((arg, i) => {
+    const defaulted = defaults[0] !== undefined;
+    command.args.forEach((arg) => {
       leaf.argument(
-        defaults[i] === undefined ? `<${arg.flag}>` : `[${arg.flag}]`,
+        defaulted ? `[${arg.flag}]` : `<${arg.flag}>`,
         arg.description ?? "",
       );
     });
-    if (
-      defaults.some((value) => value !== undefined) &&
-      options.defaultArgNote
-    ) {
-      leaf.addHelpText("after", `\n${options.defaultArgNote}`);
+    if (defaulted) {
+      const names = command.args.map((arg, i) =>
+        i === 0 ? `[${arg.flag}]` : `<${arg.flag}>`,
+      );
+      leaf.usage(`[options] ${names.join(" ")}`);
     }
+    const notes = [
+      defaults.some((value) => value !== undefined)
+        ? options.defaultArgNote
+        : undefined,
+      options.helpNote?.(command),
+    ].filter(Boolean);
+    if (notes.length > 0) leaf.addHelpText("after", `\n${notes.join("\n")}`);
     leafOptions(leaf, command);
     leaf.action((...args: unknown[]) => {
       const cmd = args.at(-1) as Command;
@@ -178,7 +187,9 @@ export function defineCommands(
         positionals = [defaults[0], ...positionals];
       }
       if (positionals.length !== command.args.length) {
-        const expected = command.args.map((a) => `<${a.flag}>`).join(" ");
+        const expected = command.args
+          .map((a, i) => (i === 0 && defaulted ? `[${a.flag}]` : `<${a.flag}>`))
+          .join(" ");
         throw new UsageError(
           `expected ${expected}, got ${cmd.args.length} argument(s)`,
         );

package/src/run.test.ts

@@ -184,6 +184,24 @@ describe("guards", () => {
     expect(h.calls).toHaveLength(0);
   });
 
+  it("tells a signed-in user that the API key overrides use", async () => {
+    const h = harness({ ASTEROID_API_KEY: "sk_test" }, () => json({}));
+    await new CredentialStore(h.deps.env).writeLogin({ refreshToken: "r1" });
+    expect(await run(["use", "org_A"], h.deps)).toBe(2);
+    expect(h.err.join("")).toContain("ignores `asteroid login`");
+    expect(h.err.join("")).toContain("unset ASTEROID_API_KEY");
+  });
+
+  it("names the API key when the API rejects it", async () => {
+    const h = harness({ ASTEROID_API_KEY: "sk_bad" }, () =>
+      json({ detail: "invalid API key" }, 401),
+    );
+    expect(await run(["workflow", "list"], h.deps)).toBe(1);
+    expect(h.err.join("")).toContain(
+      "401: ASTEROID_API_KEY was rejected: invalid API key.",
+    );
+  });
+
   it("rejects extra arguments and unknown flags on account commands", async () => {
     const h = harness({}, () => json({}));
     expect(await run(["use", "a", "b"], h.deps)).toBe(2);
@@ -209,6 +227,22 @@ describe("guards", () => {
     ).toBeUndefined();
   });
 
+  it("does not blame the API key for an error after a cross-host redirect", async () => {
+    const h = harness({ ASTEROID_API_KEY: "sk_test" }, (call) =>
+      call.url.startsWith("https://odyssey")
+        ? new Response(null, {
+            status: 303,
+            headers: { location: "https://storage.test/file" },
+          })
+        : new Response("expired", { status: 403 }),
+    );
+    expect(
+      await run(["execution", "file", "download", "e1", "f1"], h.deps),
+    ).toBe(1);
+    expect(h.err.join("")).toContain("403: expired");
+    expect(h.err.join("")).not.toContain("ASTEROID_API_KEY");
+  });
+
   it("keeps the method and body on a 307", async () => {
     const h = harness({ ASTEROID_API_KEY: "sk_test" }, (call) =>
       call.url.endsWith("/validate")

package/src/run.ts

@@ -2,7 +2,13 @@ import { writeFileSync } from "node:fs";
 
 import { login, logout, orgs, use, whoami } from "./account";
 import { type Parsed, UsageError } from "./args";
-import { type Auth, AuthError, resolveAuth } from "./auth/credentials";
+import {
+  API_KEY_OVERRIDES,
+  type Auth,
+  AuthError,
+  resolveAuth,
+  UNSET_API_KEY,
+} from "./auth/credentials";
 import { WorkosError } from "./auth/workos";
 import { type Env, loadConfig, orgLabel, requestedOrg } from "./config";
 import { COMMANDS } from "./generated/commands";
@@ -30,7 +36,7 @@ export interface Deps {
 function rejectOrgWithApiKey(deps: Deps, flagOrg: string | undefined) {
   if (deps.env.apiKey && (flagOrg || deps.env.org)) {
     throw new UsageError(
-      "ASTEROID_API_KEY acts in its own organization. Unset --org and ASTEROID_ORG, or sign in with `asteroid login`.",
+      `${API_KEY_OVERRIDES} The key acts in its own organization, so drop --org and ASTEROID_ORG. ${UNSET_API_KEY}`,
     );
   }
 }