@eigenpal/cli 0.12.2 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @eigenpal/cli
 
+## 0.13.0
+
+### Minor Changes
+
+- aaf5a04: `eigenpal workflow versions` can now create, promote, and restore YAML workflow versions through the public API. Tag a candidate from a YAML file or an existing snapshot with an explicit semver, keep it off live traffic with `--no-activate`, then promote that exact version when it qualifies. Restoring still rolls a workflow back by copying a snapshot into a new current version — lists now show that untagged HEAD clearly instead of hiding it.
+
+  `workflow versions list --limit` and `--offset` page that full public list locally. `--json` prints the sliced `{ data, total, limit, offset }` envelope (`total` is the unsliced count), not the raw server payload.
+
 ## 0.11.0
 
 ### Minor Changes

package/dist/cli.js

@@ -67452,10 +67452,16 @@ var init_workflow_tool_metadata = __esm(() => {
       description: "Download eval results in CSV or JSON."
     },
     workflow_list_versions: {
-      description: "List historical workflow versions, newest first."
+      description: "List tagged workflow versions plus the current untagged snapshot when HEAD is untagged, newest first."
+    },
+    workflow_create_version: {
+      description: "Create a tagged workflow version from YAML or by copying an existing snapshot."
+    },
+    workflow_promote_version: {
+      description: "Make an existing tagged workflow version current without creating another snapshot."
     },
     workflow_restore_version: {
-      description: "Restore the workflow to a previous version."
+      description: "Restore a previous snapshot as a new untagged current version. Does not retag the source."
     },
     workflow_list_step_types: {
       description: "List every step type the deployment supports."
@@ -191393,7 +191399,7 @@ import { fileURLToPath as fileURLToPath9 } from "url";
 // package.json
 var package_default = {
   name: "@eigenpal/cli",
-  version: "0.12.2",
+  version: "0.13.0",
   description: "Eigenpal CLI — author and run document workflows from your terminal. Agent-ready.",
   keywords: [
     "eigenpal",
@@ -201016,6 +201022,45 @@ version: ${next}`);
   return `version: ${next}
 ${yaml}`;
 }
+function automationVersionsPath(workflowId, suffix = "") {
+  return `/v1/automations/${encodeURIComponent(workflowId)}/versions${suffix}`;
+}
+function formatWorkflowVersionLabel(version2) {
+  return typeof version2 === "string" && version2.length > 0 ? version2 : "untagged";
+}
+function paginatePublicVersionList(raw, opts) {
+  const payload = raw;
+  const all = Array.isArray(payload.data) ? payload.data : [];
+  const offset = Number.isFinite(opts.offset) ? Math.max(0, Math.trunc(opts.offset)) : 0;
+  const limit = Number.isFinite(opts.limit) ? Math.max(0, Math.trunc(opts.limit)) : 0;
+  return {
+    data: all.slice(offset, offset + limit),
+    total: all.length,
+    limit,
+    offset
+  };
+}
+function resolveWorkflowVersionCreateRequest(opts) {
+  const hasFile2 = Boolean(opts.file);
+  const hasFrom = Boolean(opts.from);
+  if (hasFile2 && hasFrom) {
+    throw new Error("Pass either --file or --from, not both.");
+  }
+  if (!hasFile2 && !hasFrom) {
+    throw new Error("Pass --file <yaml> or --from <version-id> to create a tagged version.");
+  }
+  if (opts.setVersion && opts.yamlVersion) {
+    throw new Error(`--set-version conflicts with the top-level \`version: ${opts.yamlVersion}\` in the YAML. Remove the YAML field, or omit the flag.`);
+  }
+  const version2 = opts.setVersion ?? (hasFile2 ? opts.yamlVersion ?? undefined : undefined);
+  if (!version2) {
+    throw new Error(hasFrom ? "Pass --set-version <X.Y.Z> when copying an existing version." : "Pass --set-version <X.Y.Z>, or add a top-level `version: X.Y.Z` to the YAML.");
+  }
+  if (!SEMVER_RE.test(version2)) {
+    throw new Error(`${opts.setVersion ? "--set-version" : "YAML version"} must be bare semver X.Y.Z (got "${version2}").`);
+  }
+  return { source: hasFile2 ? "yaml" : "history", version: version2 };
+}
 function registerClearLocalCommand(parent) {
   parent.command("clear-local [examples...]").description("Delete local execution artifacts under ./dataset/examples/. Keeps the latest run per example by default.").option("--dir <dir>", "Local eigenpal directory", undefined).option("--all", "Remove all artifacts, including the latest kept by default", false).action(async (examples, opts) => {
     const config2 = resolveConfig(opts);
@@ -201791,31 +201836,131 @@ async function pollExperimentUntilTerminal({
   }
 }
 function registerVersionsCommands(parent) {
-  const versions3 = parent.command("versions").description("Inspect and restore historical workflow versions.");
+  const versions3 = parent.command("versions").description("Create, list, promote, and restore YAML workflow versions.").addHelpText("after", `
+Examples:
+  $ eigenpal workflow versions list wf_abc123
+  $ eigenpal workflow versions create wf_abc123 --file workflow.yaml --set-version 1.4.0
+  $ eigenpal workflow versions create wf_abc123 --file workflow.yaml --set-version 1.4.1 --no-activate
+  $ eigenpal workflow versions create wf_abc123 --from wh_abc --set-version 1.5.0 --no-activate
+  $ eigenpal workflow versions promote wf_abc123 wh_abc
+  $ eigenpal workflow versions restore wf_abc123 wh_old
+
+Create publishes a tagged candidate. It becomes current unless you pass
+\`--no-activate\`. Promote makes an existing tagged candidate current without
+creating another snapshot. Restore copies a snapshot into a new untagged
+current HEAD; the source tag is left unchanged and the new row cannot be
+promoted until you create a tagged copy.
+`);
   const listCmd = versions3.command("list <workflow-id>").description(descriptionFor("workflow_list_versions"));
-  addJsonFlag(withBaseUrl(withPagination(listCmd))).action(action(async (workflow2, opts) => {
+  withBaseUrl(withPagination(listCmd)).option("--json", "Print the sliced { data, total, limit, offset } envelope as JSON (not the raw server payload)").addHelpText("after", `
+Examples:
+  $ eigenpal workflow versions list wf_abc123
+  $ eigenpal workflow versions list wf_abc123 --json | jq '.data[] | {id, version, isCurrent}'
+  $ eigenpal workflow versions list wf_abc123 --limit 1 --offset 0 --json
+
+The public list includes tagged releases and, after restore, the untagged
+current snapshot (\`version: null\`, rendered as \`untagged\`). The public
+endpoint returns the full set; \`--limit\` / \`--offset\` slice it
+client-side so HEAD is never dropped unless it is off the requested page.
+\`--json\` prints \`{ data, total, limit, offset }\` after that slice —
+\`total\` is the unsliced count.
+`).action(action(async (workflow2, opts) => {
     const { client, workflowId } = await buildClientForWorkflow(workflow2, opts);
-    const raw = await client.get(`/api/workflows/${workflowId}/versions`, {
-      limit: String(opts.limit),
-      offset: String(opts.offset)
+    const raw = await client.get(automationVersionsPath(workflowId));
+    const paged = paginatePublicVersionList(raw, {
+      limit: opts.limit,
+      offset: opts.offset
     });
-    renderListResult(raw, [
-      { key: "version", header: "version" },
+    renderListResult(paged, [
+      {
+        key: "version",
+        header: "version",
+        format: (value) => formatWorkflowVersionLabel(typeof value === "string" ? value : null)
+      },
       { key: "id", header: "versionId" },
       { key: "isCurrent", header: "current", format: (v11) => v11 ? "yes" : "-" },
       { key: "createdAt", header: "createdAt", format: formatTimestamp }
     ], { ...opts, entityLabel: "version" });
   }));
-  const restoreCmd = versions3.command("restore <workflow-id> <versionId>").description(descriptionFor("workflow_restore_version"));
-  addJsonFlag(withBaseUrl(restoreCmd)).action(action(async (workflow2, versionId, opts) => {
+  const createCmd = versions3.command("create <workflow-id>").description(descriptionFor("workflow_create_version")).option("--file <yaml>", "Path to workflow YAML. Mutually exclusive with --from.").option("--from <version-id>", "Existing version id to copy into a new tagged snapshot. Leaves the source tag unchanged. Mutually exclusive with --file.").option("--set-version <semver>", "Bare semver tag such as 1.4.0. Required when copying with --from. For --file, omit this flag if the YAML already has a top-level version: field. (Named --set-version to avoid the global -v, --version flag.)").option("--no-activate", "Keep the tagged version off live traffic until you promote it. Default is to make it current. Requires an existing current version.").addHelpText("after", `
+Examples:
+  $ eigenpal workflow versions create wf_abc123 --file workflow.yaml --set-version 1.4.0
+  $ eigenpal workflow versions create wf_abc123 --file workflow.yaml --set-version 1.4.1 --no-activate
+  $ eigenpal workflow versions create wf_abc123 --from wh_abc --set-version 1.5.0 --no-activate
+  $ eigenpal workflow versions create wf_abc123 --file workflow.yaml --set-version 1.4.0 --json | jq '.id'
+
+Pass exactly one of \`--file\` or \`--from\`. \`--set-version\` is the tag on
+the new row; copying never retags the source. Default is to activate the new
+version (same as the public API). \`--no-activate\` keeps a detached candidate
+off live traffic until \`workflow versions promote\`.
+`);
+  addJsonFlag(withBaseUrl(createCmd)).action(action(async (workflow2, opts) => {
+    let yaml;
+    if (opts.file) {
+      yaml = await fs17.readFile(opts.file, "utf8");
+    }
+    const resolved = resolveWorkflowVersionCreateRequest({
+      file: opts.file,
+      from: opts.from,
+      setVersion: opts.setVersion,
+      yamlVersion: yaml ? extractWorkflowVersion(yaml) : null
+    });
+    const activate = opts.activate !== false;
+    const body = resolved.source === "yaml" ? { yaml, version: resolved.version, activate } : { historyId: opts.from, version: resolved.version, activate };
+    const { client, workflowId } = await buildClientForWorkflow(workflow2, opts);
+    const result = await client.post(automationVersionsPath(workflowId), body);
+    if (opts.json) {
+      printJson2(result);
+      return;
+    }
+    const id2 = typeof result.id === "string" ? result.id : "?";
+    if (activate) {
+      success2(`Created v${resolved.version} as current for ${ui.bold(workflowId)} ${ui.dim(`(${id2})`)}`);
+    } else {
+      success2(`Created v${resolved.version} as a detached candidate for ${ui.bold(workflowId)} ${ui.dim(`(${id2})`)}`);
+      dim(`Promote it with: eigenpal workflow versions promote ${workflowId} ${id2}`);
+    }
+  }));
+  const promoteCmd = versions3.command("promote <workflow-id> <versionId>").description(descriptionFor("workflow_promote_version"));
+  addJsonFlag(withBaseUrl(promoteCmd)).addHelpText("after", `
+Examples:
+  $ eigenpal workflow versions promote wf_abc123 wh_abc
+  $ eigenpal workflow versions promote wf_abc123 wh_abc --json | jq '{id, version, isCurrent}'
+
+Only tagged version rows can be promoted. Untagged snapshots (including
+restore HEAD) return 404 — create a tagged copy first.
+`).action(action(async (workflow2, versionId, opts) => {
+    const { client, workflowId } = await buildClientForWorkflow(workflow2, opts);
+    const result = await client.post(automationVersionsPath(workflowId, `/${encodeURIComponent(versionId)}/promote`));
+    if (opts.json) {
+      printJson2(result);
+      return;
+    }
+    const label2 = formatWorkflowVersionLabel(result.version);
+    const id2 = typeof result.id === "string" ? result.id : versionId;
+    success2(`Promoted ${label2 === "untagged" ? "untagged version" : `v${label2}`} to current for ${ui.bold(workflowId)} ${ui.dim(`(${id2})`)}`);
+  }));
+  const restoreCmd = versions3.command("restore <workflow-id> <versionId>").description(descriptionFor("workflow_restore_version")).option("--message <text>", "Optional restore note stored on the new snapshot");
+  addJsonFlag(withBaseUrl(restoreCmd)).addHelpText("after", `
+Examples:
+  $ eigenpal workflow versions restore wf_abc123 wh_old
+  $ eigenpal workflow versions restore wf_abc123 wh_old --message "roll back Friday change"
+  $ eigenpal workflow versions restore wf_abc123 wh_old --json | jq '{id, version, isCurrent}'
+
+Restore copies the selected snapshot into a new untagged current version. It
+does not retag or delete the source. The new HEAD appears in
+\`workflow versions list\` as \`untagged\` / \`version: null\` and cannot be
+promoted until you create a tagged copy.
+`).action(action(async (workflow2, versionId, opts) => {
     const { client, workflowId } = await buildClientForWorkflow(workflow2, opts);
-    const result = await client.post(`/api/workflows/${workflowId}/history/${versionId}/restore`, {});
+    const body = opts.message ? { message: opts.message } : {};
+    const result = await client.post(automationVersionsPath(workflowId, `/${encodeURIComponent(versionId)}/restore`), body);
     if (opts.json) {
       printJson2(result);
       return;
     }
-    const newVersion = result.version ?? "?";
-    success2(`Restored ${ui.bold(workflowId)} to v${newVersion} ${ui.dim(`(history ${versionId})`)}`);
+    const id2 = typeof result.id === "string" ? result.id : "?";
+    success2(`Restored ${ui.bold(workflowId)} to a new untagged current version ${ui.dim(`(${id2})`)} from ${versionId}`);
   }));
 }
 function registerStepTypeCommands(parent) {

package/dist/skill/SKILL.md

@@ -80,6 +80,13 @@ eigenpal workflow evaluators push <workflow-id> --file ./evaluators.yaml
 eigenpal workflow experiment run <workflow-id>
 eigenpal workflow experiment watch <workflow-id> <batch-id>
 eigenpal workflow experiment results <workflow-id> <batch-id> --format csv --out results.csv
+
+# Create a tagged candidate without moving live traffic, then promote it.
+eigenpal workflow versions create <workflow-id> --file workflow.yaml --set-version 1.4.0 --no-activate
+eigenpal workflow versions list <workflow-id>
+eigenpal workflow versions promote <workflow-id> <version-id>
+# Restore copies a snapshot into a new untagged current HEAD.
+eigenpal workflow versions restore <workflow-id> <version-id>
 ```
 
 Folders are server metadata, not `workflow.yaml` content:

package/dist/skill/reference/cli/surface.md

@@ -42,6 +42,8 @@ eigenpal
 │   │   └── watch <workflow-id> <batchId>
 │   ├── versions
 │   │   ├── list|ls <workflow-id>
+│   │   ├── create <workflow-id>
+│   │   ├── promote <workflow-id> <versionId>
 │   │   └── restore <workflow-id> <versionId>
 │   ├── step-type
 │   │   ├── list|ls

package/dist/skill/reference/cli/workflow.md

@@ -41,6 +41,8 @@ Manage workflows: push, pull, and evaluate.
   - [`eigenpal workflow experiment|exp compare|diff [options] <batchIdA> <batchIdB>`](#eigenpal-workflow-experimentexp-comparediff-options-batchida-batchidb)
   - [`eigenpal workflow experiment|exp watch [options] <workflow-id> <batchId>`](#eigenpal-workflow-experimentexp-watch-options-workflow-id-batchid)
   - [`eigenpal workflow versions list|ls [options] <workflow-id>`](#eigenpal-workflow-versions-listls-options-workflow-id)
+  - [`eigenpal workflow versions create [options] <workflow-id>`](#eigenpal-workflow-versions-create-options-workflow-id)
+  - [`eigenpal workflow versions promote [options] <workflow-id> <versionId>`](#eigenpal-workflow-versions-promote-options-workflow-id-versionid)
   - [`eigenpal workflow versions restore [options] <workflow-id> <versionId>`](#eigenpal-workflow-versions-restore-options-workflow-id-versionid)
   - [`eigenpal workflow step-type list|ls [options]`](#eigenpal-workflow-step-type-listls-options)
   - [`eigenpal workflow step-type get [options] <type>`](#eigenpal-workflow-step-type-get-options-type)
@@ -81,6 +83,8 @@ workflow
 │   └── watch <workflow-id> <batchId>
 ├── versions
 │   ├── list|ls <workflow-id>
+│   ├── create <workflow-id>
+│   ├── promote <workflow-id> <versionId>
 │   └── restore <workflow-id> <versionId>
 ├── step-type
 │   ├── list|ls
@@ -143,10 +147,12 @@ workflow
 
 ### Versions
 
-| Command                                                                  | Description                                      |
-| ------------------------------------------------------------------------ | ------------------------------------------------ |
-| `eigenpal workflow versions list\|ls [options] <workflow-id>`            | List historical workflow versions, newest first. |
-| `eigenpal workflow versions restore [options] <workflow-id> <versionId>` | Restore the workflow to a previous version.      |
+| Command                                                                  | Description                                                                                           |
+| ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
+| `eigenpal workflow versions list\|ls [options] <workflow-id>`            | List tagged workflow versions plus the current untagged snapshot when HEAD is untagged, newest first. |
+| `eigenpal workflow versions create [options] <workflow-id>`              | Create a tagged workflow version from YAML or by copying an existing snapshot.                        |
+| `eigenpal workflow versions promote [options] <workflow-id> <versionId>` | Make an existing tagged workflow version current without creating another snapshot.                   |
+| `eigenpal workflow versions restore [options] <workflow-id> <versionId>` | Restore a previous snapshot as a new untagged current version. Does not retag the source.             |
 
 ### Step-type
 
@@ -629,7 +635,7 @@ Poll until terminal, then auto-pull results — replaces `status --watch` + `res
 
 ### `eigenpal workflow versions list|ls [options] <workflow-id>`
 
-List historical workflow versions, newest first.
+List tagged workflow versions plus the current untagged snapshot when HEAD is untagged, newest first.
 
 ### Arguments
 
@@ -639,16 +645,55 @@ List historical workflow versions, newest first.
 
 ### Options
 
+| Flag               | Required | Default | Description                                                                                   |
+| ------------------ | -------- | ------- | --------------------------------------------------------------------------------------------- |
+| `--limit <n>`      | no       | `50`    | Page size                                                                                     |
+| `--offset <n>`     | no       | `0`     | Page offset                                                                                   |
+| `--base-url <url>` | no       |         | Server base URL                                                                               |
+| `--json`           | no       |         | Print the sliced { data, total, limit, offset } envelope as JSON (not the raw server payload) |
+
+### `eigenpal workflow versions create [options] <workflow-id>`
+
+Create a tagged workflow version from YAML or by copying an existing snapshot.
+
+### Arguments
+
+| Name          | Required | Variadic | Description |
+| ------------- | -------- | -------- | ----------- |
+| `workflow-id` | yes      | no       |             |
+
+### Options
+
+| Flag                     | Required | Default | Description                                                                                                                                                                                                    |
+| ------------------------ | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--file <yaml>`          | no       |         | Path to workflow YAML. Mutually exclusive with --from.                                                                                                                                                         |
+| `--from <version-id>`    | no       |         | Existing version id to copy into a new tagged snapshot. Leaves the source tag unchanged. Mutually exclusive with --file.                                                                                       |
+| `--set-version <semver>` | no       |         | Bare semver tag such as 1.4.0. Required when copying with --from. For --file, omit this flag if the YAML already has a top-level version: field. (Named --set-version to avoid the global -v, --version flag.) |
+| `--no-activate`          | no       |         | Keep the tagged version off live traffic until you promote it. Default is to make it current. Requires an existing current version.                                                                            |
+| `--base-url <url>`       | no       |         | Server base URL                                                                                                                                                                                                |
+| `--json`                 | no       |         | Output the raw server response as JSON                                                                                                                                                                         |
+
+### `eigenpal workflow versions promote [options] <workflow-id> <versionId>`
+
+Make an existing tagged workflow version current without creating another snapshot.
+
+### Arguments
+
+| Name          | Required | Variadic | Description |
+| ------------- | -------- | -------- | ----------- |
+| `workflow-id` | yes      | no       |             |
+| `versionId`   | yes      | no       |             |
+
+### Options
+
 | Flag               | Required | Default | Description                            |
 | ------------------ | -------- | ------- | -------------------------------------- |
-| `--limit <n>`      | no       | `50`    | Page size                              |
-| `--offset <n>`     | no       | `0`     | Page offset                            |
 | `--base-url <url>` | no       |         | Server base URL                        |
 | `--json`           | no       |         | Output the raw server response as JSON |
 
 ### `eigenpal workflow versions restore [options] <workflow-id> <versionId>`
 
-Restore the workflow to a previous version.
+Restore a previous snapshot as a new untagged current version. Does not retag the source.
 
 ### Arguments
 
@@ -659,10 +704,11 @@ Restore the workflow to a previous version.
 
 ### Options
 
-| Flag               | Required | Default | Description                            |
-| ------------------ | -------- | ------- | -------------------------------------- |
-| `--base-url <url>` | no       |         | Server base URL                        |
-| `--json`           | no       |         | Output the raw server response as JSON |
+| Flag               | Required | Default | Description                                      |
+| ------------------ | -------- | ------- | ------------------------------------------------ |
+| `--message <text>` | no       |         | Optional restore note stored on the new snapshot |
+| `--base-url <url>` | no       |         | Server base URL                                  |
+| `--json`           | no       |         | Output the raw server response as JSON           |
 
 ### `eigenpal workflow step-type list|ls [options]`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eigenpal/cli",
-  "version": "0.12.2",
+  "version": "0.13.0",
   "description": "Eigenpal CLI — author and run document workflows from your terminal. Agent-ready.",
   "keywords": [
     "eigenpal",