@asteroidai/cli 1.9.11 → 1.9.27

package/src/generated/commands.ts

@@ -128,6 +128,7 @@ export const COMMANDS: CliCommand[] = [
     binary: false,
     readOnly: false,
     destructive: false,
+    capability: "run_execution",
   },
   {
     command: "context",
@@ -1092,6 +1093,7 @@ export const COMMANDS: CliCommand[] = [
       files: [],
       credentialOrganization: false,
     },
+    capability: "run_execution",
   },
   {
     command: "execution resume",
@@ -1113,6 +1115,7 @@ export const COMMANDS: CliCommand[] = [
     binary: false,
     readOnly: false,
     destructive: false,
+    capability: "run_execution",
   },
   {
     command: "insight get",
@@ -2004,6 +2007,7 @@ export const COMMANDS: CliCommand[] = [
       files: [],
       credentialOrganization: false,
     },
+    capability: "run_execution",
   },
   {
     command: "schedule delete",
@@ -2031,6 +2035,7 @@ export const COMMANDS: CliCommand[] = [
     binary: false,
     readOnly: false,
     destructive: true,
+    capability: "run_execution",
   },
   {
     command: "schedule get",
@@ -2222,6 +2227,7 @@ export const COMMANDS: CliCommand[] = [
       files: [],
       credentialOrganization: false,
     },
+    capability: "run_execution",
   },
   {
     command: "scheduled-execution cancel",
@@ -2243,6 +2249,7 @@ export const COMMANDS: CliCommand[] = [
     binary: false,
     readOnly: false,
     destructive: false,
+    capability: "run_execution",
   },
   {
     command: "scheduled-execution create",
@@ -2315,6 +2322,7 @@ export const COMMANDS: CliCommand[] = [
       files: [],
       credentialOrganization: false,
     },
+    capability: "run_execution",
   },
   {
     command: "scheduled-execution list",
@@ -2421,6 +2429,7 @@ export const COMMANDS: CliCommand[] = [
       files: [],
       credentialOrganization: false,
     },
+    capability: "run_execution",
   },
   {
     command: "schema validate",
@@ -3621,6 +3630,7 @@ export const COMMANDS: CliCommand[] = [
       files: [],
       credentialOrganization: false,
     },
+    capability: "run_execution",
   },
   {
     command: "workflow execute-sync",
@@ -3731,119 +3741,7 @@ export const COMMANDS: CliCommand[] = [
       files: [],
       credentialOrganization: false,
     },
-  },
-  {
-    command: "workflow file list",
-    tool: "workflow_files_list",
-    title: "List workflow files",
-    description:
-      "List the workflow's editable head as a directory of files: the graph rendered as structural files (settings.yaml, per-node instructions.md, scripts) alongside the workflow's own files. Those files are referenced by fileId unless contents=all is set. Pass paths to read named files only, or contents=none for a manifest with no bodies. The returned rev is what you pass as baseRev to write.",
-    method: "GET",
-    path: "/agents/v2/workflows/{workflowId}/head/files",
-    args: [
-      {
-        name: "workflowId",
-        flag: "workflow-id",
-        type: "string",
-        required: true,
-      },
-    ],
-    query: [
-      {
-        name: "contents",
-        flag: "contents",
-        type: "string",
-        required: false,
-        description:
-          "Which contents come inline: none (a pure manifest), structural (the default), or all (structural plus file bytes within the response budget).",
-        enum: ["none", "structural", "all"],
-      },
-      {
-        name: "paths",
-        flag: "paths",
-        type: "string[]",
-        required: false,
-        description:
-          "Return only the files at these exact tree paths. A path that names nothing yields no entry. The inline budget applies to the filtered set, so a narrow read can inline files a whole-tree read would have to skip.",
-      },
-      {
-        name: "variants",
-        flag: "variants",
-        type: "string",
-        required: false,
-        description:
-          'Narrow which variants/<key>/ files the tree carries: "none" strips every variant, a comma-separated list keeps only those variant keys. Files outside variants/ are always kept, and the response\'s variantKeys still names every variant. Ignored unless the workflow has variant mode enabled; absent keeps every variant.',
-      },
-      {
-        name: "maxFileBytes",
-        flag: "max-file-bytes",
-        type: "integer",
-        required: false,
-        description:
-          "Per-file ceiling, in bytes, for inlined file contents. Clamped to the server maximum. Files above the ceiling stay references.",
-      },
-      {
-        name: "maxTotalBytes",
-        flag: "max-total-bytes",
-        type: "integer",
-        required: false,
-        description:
-          "Ceiling, in bytes, on the total inlined file contents in one response. Clamped to the server maximum. Files are admitted in path order until the ceiling is reached; the rest stay references.",
-      },
-    ],
-    binary: false,
-    readOnly: true,
-    destructive: false,
-  },
-  {
-    command: "workflow file patch",
-    tool: "workflow_files_patch",
-    title: "Write workflow files",
-    description:
-      "Write and delete files on the workflow's editable head in one patch. Structural files re-derive the graph; the workflow's own files go to its file store, you just write paths. Pass the rev from `workflow_files_list` as baseRev; a stale value is rejected with 409, so re-read and retry. Editing a published or already-executed version forks a new one instead of rewriting it. Each write carries `contentBase64`: base64-encode the file content, plain text is rejected with 400.",
-    method: "PATCH",
-    path: "/agents/v2/workflows/{workflowId}/head/files",
-    args: [
-      {
-        name: "workflowId",
-        flag: "workflow-id",
-        type: "string",
-        required: true,
-      },
-    ],
-    query: [],
-    binary: false,
-    readOnly: false,
-    destructive: true,
-    body: {
-      required: true,
-      contentType: "application/json",
-      fields: [
-        {
-          name: "baseRev",
-          flag: "base-rev",
-          type: "integer",
-          required: true,
-          description:
-            "The revision this edit is based on. Agent-file-only patches overlay the current head even when this is stale. A structural-file patch is rejected with 409 when it does not match the stored head revision.",
-        },
-        {
-          name: "writes",
-          flag: "writes",
-          type: "json",
-          required: true,
-          description: "Files to upsert.",
-        },
-        {
-          name: "deletes",
-          flag: "deletes",
-          type: "string[]",
-          required: true,
-        },
-      ],
-      files: [],
-      credentialOrganization: false,
-    },
+    capability: "run_execution",
   },
   {
     command: "workflow get",
@@ -3894,6 +3792,7 @@ export const COMMANDS: CliCommand[] = [
     binary: false,
     readOnly: false,
     destructive: false,
+    capability: "publish",
   },
   {
     command: "workflow head revert",
@@ -4024,6 +3923,121 @@ export const COMMANDS: CliCommand[] = [
     readOnly: true,
     destructive: false,
   },
+  {
+    command: "workflow pull",
+    tool: "workflow_files_list",
+    title: "List workflow files",
+    description:
+      "List the workflow's editable head as a directory of files: the graph rendered as structural files (settings.yaml, per-node instructions.md, scripts) alongside the workflow's own files. Those files are referenced by fileId unless contents=all is set. Pass paths to read named files only, or contents=none for a manifest with no bodies. The returned rev is what you pass as baseRev to write.",
+    method: "GET",
+    path: "/agents/v2/workflows/{workflowId}/head/files",
+    args: [
+      {
+        name: "workflowId",
+        flag: "workflow-id",
+        type: "string",
+        required: true,
+      },
+    ],
+    query: [
+      {
+        name: "contents",
+        flag: "contents",
+        type: "string",
+        required: false,
+        description:
+          "Which contents come inline: none (a pure manifest), structural (the default), or all (structural plus file bytes within the response budget).",
+        enum: ["none", "structural", "all"],
+      },
+      {
+        name: "paths",
+        flag: "paths",
+        type: "string[]",
+        required: false,
+        description:
+          "Return only the files at these exact tree paths. A path that names nothing yields no entry. The inline budget applies to the filtered set, so a narrow read can inline files a whole-tree read would have to skip.",
+      },
+      {
+        name: "variants",
+        flag: "variants",
+        type: "string",
+        required: false,
+        description:
+          'Narrow which variants/<key>/ files the tree carries: "none" strips every variant, a comma-separated list keeps only those variant keys. Files outside variants/ are always kept, and the response\'s variantKeys still names every variant. Ignored unless the workflow has variant mode enabled; absent keeps every variant.',
+      },
+      {
+        name: "maxFileBytes",
+        flag: "max-file-bytes",
+        type: "integer",
+        required: false,
+        description:
+          "Per-file ceiling, in bytes, for inlined file contents. Clamped to the server maximum. Files above the ceiling stay references.",
+      },
+      {
+        name: "maxTotalBytes",
+        flag: "max-total-bytes",
+        type: "integer",
+        required: false,
+        description:
+          "Ceiling, in bytes, on the total inlined file contents in one response. Clamped to the server maximum. Files are admitted in path order until the ceiling is reached; the rest stay references.",
+      },
+    ],
+    binary: false,
+    readOnly: true,
+    destructive: false,
+    files: "pull",
+  },
+  {
+    command: "workflow push",
+    tool: "workflow_files_patch",
+    title: "Write workflow files",
+    description:
+      "Write and delete files on the workflow's editable head in one patch. Structural files re-derive the graph; the workflow's own files go to its file store, you just write paths. Pass the rev from `workflow_files_list` as baseRev; a stale value is rejected with 409, so re-read and retry. Editing a published or already-executed version forks a new one instead of rewriting it. Each write carries `contentBase64`: base64-encode the file content, plain text is rejected with 400.",
+    method: "PATCH",
+    path: "/agents/v2/workflows/{workflowId}/head/files",
+    args: [
+      {
+        name: "workflowId",
+        flag: "workflow-id",
+        type: "string",
+        required: true,
+      },
+    ],
+    query: [],
+    binary: false,
+    readOnly: false,
+    destructive: true,
+    body: {
+      required: true,
+      contentType: "application/json",
+      fields: [
+        {
+          name: "baseRev",
+          flag: "base-rev",
+          type: "integer",
+          required: true,
+          description:
+            "The revision this edit is based on. Agent-file-only patches overlay the current head even when this is stale. A structural-file patch is rejected with 409 when it does not match the stored head revision.",
+        },
+        {
+          name: "writes",
+          flag: "writes",
+          type: "json",
+          required: true,
+          description: "Files to upsert.",
+        },
+        {
+          name: "deletes",
+          flag: "deletes",
+          type: "string[]",
+          required: true,
+        },
+      ],
+      files: [],
+      credentialOrganization: false,
+    },
+    files: "push",
+  },
   {
     command: "workflow rename",
     tool: "workflow_rename",
@@ -4449,75 +4463,7 @@ export const COMMANDS: CliCommand[] = [
       files: [],
       credentialOrganization: false,
     },
-  },
-  {
-    command: "workflow version file list",
-    tool: "workflow_version_files_list",
-    title: "List workflow version files",
-    description:
-      "List a version's files, like `workflow_files_list` does for the editable head. Versions are immutable, so this is read-only.",
-    method: "GET",
-    path: "/agents/v2/workflows/{workflowId}/versions/{versionId}/files",
-    args: [
-      {
-        name: "workflowId",
-        flag: "workflow-id",
-        type: "string",
-        required: true,
-      },
-      {
-        name: "versionId",
-        flag: "version-id",
-        type: "string",
-        required: true,
-      },
-    ],
-    query: [
-      {
-        name: "contents",
-        flag: "contents",
-        type: "string",
-        required: false,
-        description:
-          "Which contents come inline: none (a pure manifest), structural (the default), or all (structural plus file bytes within the response budget).",
-        enum: ["none", "structural", "all"],
-      },
-      {
-        name: "paths",
-        flag: "paths",
-        type: "string[]",
-        required: false,
-        description:
-          "Return only the files at these exact tree paths. A path that names nothing yields no entry. The inline budget applies to the filtered set, so a narrow read can inline files a whole-tree read would have to skip.",
-      },
-      {
-        name: "variants",
-        flag: "variants",
-        type: "string",
-        required: false,
-        description:
-          'Narrow which variants/<key>/ files the tree carries: "none" strips every variant, a comma-separated list keeps only those variant keys. Files outside variants/ are always kept, and the response\'s variantKeys still names every variant. Ignored unless the workflow has variant mode enabled; absent keeps every variant.',
-      },
-      {
-        name: "maxFileBytes",
-        flag: "max-file-bytes",
-        type: "integer",
-        required: false,
-        description:
-          "Per-file ceiling, in bytes, for inlined file contents. Clamped to the server maximum. Files above the ceiling stay references.",
-      },
-      {
-        name: "maxTotalBytes",
-        flag: "max-total-bytes",
-        type: "integer",
-        required: false,
-        description:
-          "Ceiling, in bytes, on the total inlined file contents in one response. Clamped to the server maximum. Files are admitted in path order until the ceiling is reached; the rest stay references.",
-      },
-    ],
-    binary: false,
-    readOnly: true,
-    destructive: false,
+    capability: "run_execution",
   },
   {
     command: "workflow version file url",
@@ -4680,6 +4626,77 @@ export const COMMANDS: CliCommand[] = [
     binary: false,
     readOnly: false,
     destructive: false,
+    capability: "publish",
+  },
+  {
+    command: "workflow version pull",
+    tool: "workflow_version_files_list",
+    title: "List workflow version files",
+    description:
+      "List a version's files, like `workflow_files_list` does for the editable head. Versions are immutable, so this is read-only.",
+    method: "GET",
+    path: "/agents/v2/workflows/{workflowId}/versions/{versionId}/files",
+    args: [
+      {
+        name: "workflowId",
+        flag: "workflow-id",
+        type: "string",
+        required: true,
+      },
+      {
+        name: "versionId",
+        flag: "version-id",
+        type: "string",
+        required: true,
+      },
+    ],
+    query: [
+      {
+        name: "contents",
+        flag: "contents",
+        type: "string",
+        required: false,
+        description:
+          "Which contents come inline: none (a pure manifest), structural (the default), or all (structural plus file bytes within the response budget).",
+        enum: ["none", "structural", "all"],
+      },
+      {
+        name: "paths",
+        flag: "paths",
+        type: "string[]",
+        required: false,
+        description:
+          "Return only the files at these exact tree paths. A path that names nothing yields no entry. The inline budget applies to the filtered set, so a narrow read can inline files a whole-tree read would have to skip.",
+      },
+      {
+        name: "variants",
+        flag: "variants",
+        type: "string",
+        required: false,
+        description:
+          'Narrow which variants/<key>/ files the tree carries: "none" strips every variant, a comma-separated list keeps only those variant keys. Files outside variants/ are always kept, and the response\'s variantKeys still names every variant. Ignored unless the workflow has variant mode enabled; absent keeps every variant.',
+      },
+      {
+        name: "maxFileBytes",
+        flag: "max-file-bytes",
+        type: "integer",
+        required: false,
+        description:
+          "Per-file ceiling, in bytes, for inlined file contents. Clamped to the server maximum. Files above the ceiling stay references.",
+      },
+      {
+        name: "maxTotalBytes",
+        flag: "max-total-bytes",
+        type: "integer",
+        required: false,
+        description:
+          "Ceiling, in bytes, on the total inlined file contents in one response. Clamped to the server maximum. Files are admitted in path order until the ceiling is reached; the rest stay references.",
+      },
+    ],
+    binary: false,
+    readOnly: true,
+    destructive: false,
+    files: "pull",
   },
   {
     command: "workflow version validate",

package/src/program.ts

@@ -1,4 +1,4 @@
-import { Command, CommanderError } from "commander";
+import { Command, CommanderError, Option as Flag } from "commander";
 
 import { type Parsed, UsageError } from "./args";
 import { type BuiltinCommand, GLOBAL_FLAGS } from "./reference";
@@ -91,6 +91,16 @@ function leafOptions(leaf: Command, command: CliCommand) {
   for (const file of command.body?.files ?? []) {
     leaf.option(`--${file} <path>`, "File to upload. Repeatable.", collect);
   }
+  if (command.files === "pull")
+    leaf.option(
+      "--out <dir>",
+      "Write here instead of ./<workflow-name>/head (a version: ./<workflow-name>/.versions/...). --json prints the file listing instead.",
+    );
+  if (command.files === "push")
+    leaf.option(
+      "--from <dir>",
+      "The pulled head folder to push. Defaults to the current folder.",
+    );
 }
 
 function toParsed(
@@ -136,6 +146,8 @@ export function defineCommands(
   for (const builtin of options.builtins ?? []) {
     const leaf = root.command(builtin.command).description(builtin.description);
     if (builtin.arg) leaf.argument(`[${builtin.arg}]`);
+    for (const [flags, text] of builtin.hiddenOptions ?? [])
+      leaf.addOption(new Flag(flags, text).hideHelp());
     leaf.action((...args: unknown[]) => {
       const cmd = args.at(-1) as Command;
       onInvocation({

package/src/reference.ts

@@ -6,6 +6,8 @@ export interface BuiltinCommand {
   description: string;
   args: number;
   arg?: string;
+  /** Flags left out of `--help` and the reference: staff only. */
+  hiddenOptions?: [string, string][];
 }
 
 export const BUILTINS: BuiltinCommand[] = [
@@ -36,6 +38,16 @@ export const BUILTINS: BuiltinCommand[] = [
     description:
       "Make an organization, by id or name, the default for later commands. Without one, pick from a list.",
     args: 1,
+    hiddenOptions: [
+      [
+        "--reason <why>",
+        "Staff only. Why you need access to an organization you are not a member of, such as a ticket id. It is audited. Asked for in a terminal.",
+      ],
+      [
+        "--exit",
+        "Staff only. Revoke every staff token now and go back to your own organization.",
+      ],
+    ],
   },
   {
     command: "complete",
@@ -75,7 +87,11 @@ export const GLOBAL_FLAGS: [string, string][] = [
 ];
 
 export function usage(command: CliCommand): string {
-  const args = command.args.map((arg) => `<${arg.flag}>`).join(" ");
+  const args = command.args
+    .map((arg) =>
+      command.files === "push" ? `[${arg.flag}]` : `<${arg.flag}>`,
+    )
+    .join(" ");
   return `asteroid ${command.command}${args ? ` ${args}` : ""} [flags]`;
 }
 
@@ -109,6 +125,14 @@ export function flagLines(command: CliCommand): string[] {
   for (const file of command.body?.files ?? []) {
     lines.push(`--${file} <path>  File to upload (repeatable)`);
   }
+  if (command.files === "pull")
+    lines.push(
+      "--out <dir>  Write here instead of ./<workflow-name>/head (a version: ./<workflow-name>/.versions/...). --json prints the file listing instead",
+    );
+  if (command.files === "push")
+    lines.push(
+      "--from <dir>  The pulled head folder to push. Defaults to the current folder",
+    );
   return lines;
 }