@paneui/cli 0.0.4 → 0.0.6

package/README.md

@@ -18,10 +18,10 @@ The binary is `pane`.
 
 ```sh
 export PANE_URL=https://relay.paneui.com   # or your self-hosted relay
-pane register --name "my-agent"            # provisions and saves an API key
+pane agent register --name "my-agent"            # provisions and saves an API key
 ```
 
-`pane register` writes the URL + API key to
+`pane agent register` writes the URL + API key to
 `${XDG_CONFIG_HOME:-~/.config}/pane/config.json`. Subsequent commands need
 only `PANE_URL` (or nothing) in the environment.
 
@@ -29,20 +29,26 @@ Override per-invocation with `--url <url>` and `--api-key <key>`.
 
 ## Commands
 
+Uniform `pane <noun> <verb> [options]`:
+
 ```
-pane register          Provision an agent API key and save it locally
-pane create            Create a session — returns session_id, urls, tokens
-pane artifact          Manage reusable, versioned artifacts
-pane state <id>        Non-blocking snapshot: metadata + event log
-pane send <id>         Emit an agent event into a session
-pane watch <id>        Stream a session's events as JSON-lines on stdout
-pane delete <id>       Close / delete a session
-pane keys              Inspect or revoke your agent's API key
-pane config            Show the resolved relay config (no network call)
-pane logout            Clear the locally-saved URL + API key
+pane agent register            Provision an agent API key and save it locally
+pane agent logout              Clear the locally-saved URL + API key
+pane session create            Create a session — returns session_id, urls, tokens
+pane session show <id>         Non-blocking snapshot: metadata + event log
+pane session send <id>         Emit an agent event into a session
+pane session watch <id>        Stream a session's events as JSON-lines on stdout
+pane session delete <id>       Close / delete a session
+pane artifact <verb>           Manage reusable, versioned artifacts
+pane key list | revoke         Inspect or revoke your agent's API key
+pane taste get | set | clear   Read / write / clear UI-taste notes
+pane feedback create | list    Submit / list one-shot feedback to the operator
+pane config show               Show the resolved relay config (no network call)
+pane skill show | version      Fetch the relay's SKILL.md (or its version)
 ```
 
-Run `pane <command> --help` for command-specific options.
+Run `pane <noun> --help` for that noun's verbs, and
+`pane <noun> <verb> --help` for verb-specific options.
 
 ## Output
 
@@ -50,8 +56,8 @@ stdout is machine-readable JSON. Errors go to stderr as
 `{"error":{"code","message"}}` with a non-zero exit.
 
 ```sh
-SESSION=$(pane create --template form --schema ./q.json | jq -r .session_id)
-pane watch "$SESSION" | jq 'select(.type == "human_response")'
+SESSION=$(pane session create --template form --schema ./q.json | jq -r .session_id)
+pane session watch "$SESSION" | jq 'select(.type == "human_response")'
 ```
 
 ## Links

package/dist/argv.js

@@ -3,22 +3,43 @@
 // Supports:
 //   --flag value      --flag=value      --bool      -h
 // Everything that isn't a flag (or a flag's value) is a positional.
-/** Thrown when a value-flag is given with no argument (e.g. trailing `--url`). */
+/**
+ * Thrown for any argv-level user error: missing value, duplicate flag, or
+ * (when a runner calls assertKnownFlags) an unknown flag. `hint` rides
+ * alongside the message and ends up in the error envelope so callers see a
+ * single line pointing them at the right --help.
+ */
 export class ArgvError extends Error {
-    constructor(message) {
+    hint;
+    constructor(message, hint) {
         super(message);
         this.name = "ArgvError";
+        if (hint !== undefined)
+            this.hint = hint;
     }
 }
 /**
  * Parse argv tokens. `booleanFlags` lists flags that never consume a value
  * (e.g. --json, --once, --help); everything else with a `--name` form
  * consumes the next token unless written as `--name=value`.
+ *
+ * Bails with ArgvError on the first duplicate (`--foo x --foo y` or
+ * `--once --once`) so a typo'd repeat doesn't silently overwrite the first
+ * value the way a plain `Map.set` would.
+ *
+ * Does NOT throw on a value-flag with no following value. Instead it
+ * records the name in `danglingValueFlags` so `assertKnownFlags` can
+ * produce the right message — "unknown flag(s)" for typos, "requires a
+ * value" for genuine known-flag-missing-value cases. Without this split,
+ * the message was non-uniform (a `--bogus` at end of argv said "requires
+ * a value" while `--bogus something` said "unknown flag(s)" — same root
+ * cause, two messages).
  */
 export function parseArgs(tokens, booleanFlags) {
     const positionals = [];
     const flags = new Map();
     const bools = new Set();
+    const danglingValueFlags = new Set();
     for (let i = 0; i < tokens.length; i++) {
         const tok = tokens[i];
         if (tok === "-h" || tok === "--help") {
@@ -29,18 +50,31 @@ export function parseArgs(tokens, booleanFlags) {
             const body = tok.slice(2);
             const eq = body.indexOf("=");
             if (eq !== -1) {
-                flags.set(body.slice(0, eq), body.slice(eq + 1));
+                const key = body.slice(0, eq);
+                if (flags.has(key)) {
+                    throw new ArgvError(`duplicate flag: --${key}`);
+                }
+                flags.set(key, body.slice(eq + 1));
                 continue;
             }
             if (booleanFlags.has(body)) {
+                if (bools.has(body)) {
+                    throw new ArgvError(`duplicate flag: --${body}`);
+                }
                 bools.add(body);
                 continue;
             }
             const next = tokens[i + 1];
             if (next === undefined || next.startsWith("--")) {
-                // A value-flag with no argument is a user error — don't silently
-                // demote it to a boolean (which hides the mistake).
-                throw new ArgvError(`--${body} requires a value`);
+                // No value follows. Don't decide whether this is a typo or a
+                // forgotten value — record it; assertKnownFlags resolves both
+                // with one consistent message shape (see the field doc on
+                // ParsedArgs).
+                danglingValueFlags.add(body);
+                continue;
+            }
+            if (flags.has(body)) {
+                throw new ArgvError(`duplicate flag: --${body}`);
             }
             flags.set(body, next);
             i++;
@@ -48,5 +82,59 @@ export function parseArgs(tokens, booleanFlags) {
         }
         positionals.push(tok);
     }
-    return { positionals, flags, bools };
+    return { positionals, flags, bools, danglingValueFlags };
+}
+/**
+ * Flags every command accepts. Kept here (not in each command's allow-list)
+ * so adding a new global flag updates one place. `url` / `api-key` are the
+ * relay-target overrides; `help` / `json` are universal display modes.
+ */
+const GLOBAL_FLAGS = ["url", "api-key"];
+const GLOBAL_BOOLS = ["help", "json"];
+/**
+ * Reject anything the per-command allow-list (plus the globals above) does
+ * not name. Run from each leaf runner before it starts pulling values out of
+ * `args`. The thrown ArgvError carries a hint pointing at the verb's own
+ * --help, so a user fixing a typo lands on the canonical list of flags.
+ *
+ * Why per-command and not at parse time: the parser is single-pass and
+ * generic on purpose — adding a new flag to one verb should not require a
+ * shared registry. Keeping the allow-list co-located with the runner that
+ * consumes it means the two cannot drift.
+ *
+ * Also resolves the parser's `danglingValueFlags`: an unknown name there
+ * is reported alongside other unknowns ("unknown flag(s): --bogus"); a
+ * known name there surfaces as "--name requires a value". This is what
+ * keeps the error message uniform for a typo whether or not a value
+ * follows it.
+ */
+export function assertKnownFlags(args, knownFlags, knownBools, helpCommand) {
+    const flagSet = new Set([...GLOBAL_FLAGS, ...knownFlags]);
+    const boolSet = new Set([...GLOBAL_BOOLS, ...knownBools]);
+    const dangling = args.danglingValueFlags ?? new Set();
+    const unknown = [];
+    for (const k of args.flags.keys()) {
+        if (!flagSet.has(k) && !boolSet.has(k))
+            unknown.push(`--${k}`);
+    }
+    for (const k of args.bools) {
+        if (!boolSet.has(k) && !flagSet.has(k))
+            unknown.push(`--${k}`);
+    }
+    for (const k of dangling) {
+        if (!flagSet.has(k) && !boolSet.has(k))
+            unknown.push(`--${k}`);
+    }
+    if (unknown.length > 0) {
+        throw new ArgvError(`unknown flag(s): ${unknown.join(", ")}`, `run \`${helpCommand} --help\` for the supported flags`);
+    }
+    // No unknowns — but a known value-flag may still have been left without
+    // a value. Surface the first such case with the pre-existing message
+    // shape ("--name requires a value"). Reporting only the first keeps the
+    // message simple; the user fixes that flag, re-runs, sees the next one.
+    for (const k of dangling) {
+        if (flagSet.has(k)) {
+            throw new ArgvError(`--${k} requires a value`);
+        }
+    }
 }

package/dist/commands/agent.js

@@ -0,0 +1,41 @@
+// `pane agent` — agent-lifecycle operations: register a new API key, or
+// clear the locally-saved one.
+//
+// Both verbs are about the calling agent's identity on this machine:
+//   register   provision an API key from the relay (one-shot bootstrap)
+//   logout     clear the locally-saved relay URL + API key
+//
+// This file is a thin dispatcher — actual logic lives in register.ts and
+// logout.ts.
+import { runRegister } from "./register.js";
+import { runLogout } from "./logout.js";
+import { fail } from "../output.js";
+export const agentHelp = `pane agent — manage this agent's identity on the relay
+
+Usage:
+  pane agent <verb> [options]
+
+Verbs:
+  register          Provision an agent API key (POST /v1/register) and save it
+                    to the CLI config file. Run this once before other commands.
+  logout            Clear the locally-saved relay URL + API key. Does NOT
+                    revoke the key on the relay — use 'pane key revoke' for
+                    that.
+
+Run \`pane agent <verb> --help\` for verb-specific options.`;
+export async function runAgent(args) {
+    const verb = args.positionals[0];
+    switch (verb) {
+        case "register":
+            await runRegister(args);
+            break;
+        case "logout":
+            await runLogout(args);
+            break;
+        case undefined:
+            fail("missing verb — usage: pane agent <register|logout> (run 'pane agent --help')", "invalid_args");
+            break;
+        default:
+            fail(`unknown agent verb '${verb}' — expected register|logout (run 'pane agent --help')`, "invalid_args");
+    }
+}

package/dist/commands/artifact.js

@@ -5,17 +5,38 @@
 // delete).
 // An artifact is a reusable UI template (HTML + event schema + optional input
 // schema); a session is one *use* of one version of it. Authoring an artifact
-// once and instancing it via `pane create --artifact-id` removes the per-use
-// cost of regenerating the same HTML.
+// once and instancing it via `pane session create --artifact-id` removes the
+// per-use cost of regenerating the same HTML.
 import { createArtifactSchema, createArtifactVersionSchema, patchArtifactMetadataSchema, } from "@paneui/core";
+import { assertKnownFlags } from "../argv.js";
 import { makeClient } from "../config.js";
 import { resolveJson, resolveText } from "../input.js";
 import { printJson, fail, failFromError } from "../output.js";
+const CREATE_FLAGS = [
+    "name",
+    "slug",
+    "description",
+    "tags",
+    "artifact",
+    "artifact-type",
+    "event-schema",
+    "input-schema",
+];
+const VERSION_FLAGS = [
+    "artifact",
+    "artifact-type",
+    "event-schema",
+    "input-schema",
+];
+const UPDATE_FLAGS = ["name", "slug", "description", "tags"];
+const NO_FLAGS = [];
+const NO_BOOLS = [];
+const DELETE_BOOLS = ["yes"];
 export const artifactHelp = `pane artifact — manage reusable, versioned artifacts
 
 An artifact is a reusable UI template: HTML + an event schema + an optional
 input schema. A session is one use of one version of it. Author an artifact
-once, then instance it many times with 'pane create --artifact-id <id|slug>'
+once, then instance it many times with 'pane session create --artifact-id <id|slug>'
 instead of regenerating the HTML on every session.
 
 Usage:
@@ -61,7 +82,7 @@ Subcommands:
   pane artifact delete <id|slug> --yes
       Permanently deletes the artifact and all its versions. Refused
       (409 conflict) if any session in any state still references one
-      of the artifact's versions — run 'pane delete <session-id>' on
+      of the artifact's versions — run 'pane session delete <session-id>' on
       each first, or wait for the relay's TTL sweeper to reclaim them.
       Prints { artifact, deleted: true } on success.
 
@@ -169,6 +190,7 @@ function resolveTags(args) {
     return tags.length > 0 ? tags : undefined;
 }
 async function runArtifactCreate(args) {
+    assertKnownFlags(args, CREATE_FLAGS, NO_BOOLS, "pane artifact create");
     const name = args.flags.get("name");
     if (!name)
         fail("missing --name", "invalid_args");
@@ -217,6 +239,7 @@ async function runArtifactCreate(args) {
     }
 }
 async function runArtifactVersion(args) {
+    assertKnownFlags(args, VERSION_FLAGS, NO_BOOLS, "pane artifact version");
     const idOrSlug = args.positionals[1];
     if (!idOrSlug) {
         fail("missing artifact <id|slug> — usage: pane artifact version <id|slug>", "invalid_args");
@@ -252,6 +275,7 @@ async function runArtifactVersion(args) {
     }
 }
 async function runArtifactUpdate(args) {
+    assertKnownFlags(args, UPDATE_FLAGS, NO_BOOLS, "pane artifact update");
     const idOrSlug = args.positionals[1];
     if (!idOrSlug) {
         fail("missing artifact <id|slug> — usage: pane artifact update <id|slug>", "invalid_args");
@@ -289,6 +313,7 @@ async function runArtifactUpdate(args) {
     }
 }
 async function runArtifactSearch(args, query) {
+    assertKnownFlags(args, NO_FLAGS, NO_BOOLS, query === undefined ? "pane artifact list" : "pane artifact search");
     const client = makeClient(args);
     try {
         const res = await client.searchArtifacts(query);
@@ -299,6 +324,7 @@ async function runArtifactSearch(args, query) {
     }
 }
 async function runArtifactShow(args) {
+    assertKnownFlags(args, NO_FLAGS, NO_BOOLS, "pane artifact show");
     const idOrSlug = args.positionals[1];
     if (!idOrSlug) {
         fail("missing artifact <id|slug> — usage: pane artifact show <id|slug>", "invalid_args");
@@ -318,6 +344,7 @@ async function runArtifactShow(args) {
 // envelope. `--yes` is required because there's no Undo button on a delete
 // and the same `pane artifact create` slug isn't reservable once gone.
 async function runArtifactDelete(args) {
+    assertKnownFlags(args, NO_FLAGS, DELETE_BOOLS, "pane artifact delete");
     const idOrSlug = args.positionals[1];
     if (!idOrSlug) {
         fail("missing artifact <id|slug> — usage: pane artifact delete <id|slug> --yes", "invalid_args");

package/dist/commands/blob-delete.js

@@ -0,0 +1,37 @@
+// `pane blob delete <blob-id>` — soft-delete a blob.
+import { assertKnownFlags } from "../argv.js";
+import { makeClient } from "../config.js";
+import { fail, failFromError, printJson } from "../output.js";
+const KNOWN_FLAGS = [];
+const KNOWN_BOOLS = [];
+export const blobDeleteHelp = `pane blob delete — soft-delete a blob
+
+Usage:
+  pane blob delete <blob-id> [options]
+
+Marks the blob as deleted (DELETE /v1/blobs/:id). Idempotent: deleting an
+already-deleted blob still returns success. Tokens minted against this blob
+become unusable.
+
+Options:
+  --url <url>            Relay base URL (overrides PANE_URL).
+  --api-key <key>        Agent API key (overrides PANE_API_KEY).
+  -h, --help             Show this help.
+
+Output (stdout, JSON):
+  { blob_id, deleted: true }`;
+export async function runBlobDelete(args) {
+    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "pane blob delete");
+    const blobId = args.positionals[0];
+    if (!blobId) {
+        fail("missing <blob-id> — 'pane blob delete <blob-id>'", "invalid_args");
+    }
+    const client = makeClient(args);
+    try {
+        const r = await client.deleteBlob(blobId);
+        printJson({ blob_id: blobId, ...r });
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}

package/dist/commands/blob-download.js

@@ -0,0 +1,49 @@
+// `pane blob download <blob-id>` — fetch blob bytes by id.
+import { writeFileSync } from "node:fs";
+import { assertKnownFlags } from "../argv.js";
+import { makeClient } from "../config.js";
+import { fail, failFromError, printJson } from "../output.js";
+const KNOWN_FLAGS = ["out"];
+const KNOWN_BOOLS = [];
+export const blobDownloadHelp = `pane blob download — fetch a blob's bytes
+
+Usage:
+  pane blob download <blob-id> [--out <path>] [options]
+
+GETs the blob bytes. With --out <path> the bytes are written to that file and
+a JSON summary is printed on stdout; without --out the bytes are written to
+stdout verbatim (useful for piping into another tool — but binary on a TTY
+is rarely useful).
+
+Options:
+  --out <path>           Write bytes to <path> instead of stdout.
+  --url <url>            Relay base URL (overrides PANE_URL).
+  --api-key <key>        Agent API key (overrides PANE_API_KEY).
+  -h, --help             Show this help.
+
+Output:
+  Without --out: raw bytes to stdout.
+  With --out:    { blob_id, written: <path>, bytes: <n> } to stdout.`;
+export async function runBlobDownload(args) {
+    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "pane blob download");
+    const blobId = args.positionals[0];
+    if (!blobId) {
+        fail("missing <blob-id> — 'pane blob download <blob-id>'", "invalid_args");
+    }
+    const out = args.flags.get("out");
+    const client = makeClient(args);
+    try {
+        const buf = await client.downloadBlob(blobId);
+        if (out) {
+            writeFileSync(out, Buffer.from(buf));
+            printJson({ blob_id: blobId, written: out, bytes: buf.byteLength });
+        }
+        else {
+            // Binary to stdout — useful for piping into another tool.
+            process.stdout.write(Buffer.from(buf));
+        }
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}

package/dist/commands/blob-list.js

@@ -0,0 +1,50 @@
+// `pane blob list` — enumerate YOUR agent's blobs.
+//
+// Lists blobs owned by the calling agent, newest first. Soft-deleted blobs
+// are excluded; tokens are not enumerated here (use 'pane blob token list
+// <blob-id>' for that).
+import { assertKnownFlags } from "../argv.js";
+import { makeClient } from "../config.js";
+import { fail, printJson, failFromError } from "../output.js";
+const KNOWN_FLAGS = ["cursor", "limit"];
+const KNOWN_BOOLS = [];
+export const blobListHelp = `pane blob list — enumerate YOUR agent's blobs
+
+Usage:
+  pane blob list [--cursor <token>] [--limit <n>] [options]
+
+Returns the agent's non-deleted blobs (newest first). Paginated via opaque
+cursor: when next_cursor is non-null in the response, pass it back as
+--cursor to get the next page.
+
+Options:
+  --cursor <token>       Opaque pagination cursor from a prior response.
+  --limit <n>            Page size (1..100). Defaults to the relay default
+                         (50).
+  --url <url>            Relay base URL (overrides PANE_URL).
+  --api-key <key>        Agent API key (overrides PANE_API_KEY).
+  -h, --help             Show this help.
+
+Output (stdout, JSON):
+  { items: BlobRef[], next_cursor: string | null }`;
+export async function runBlobList(args) {
+    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "pane blob list");
+    const cursor = args.flags.get("cursor");
+    const limitRaw = args.flags.get("limit");
+    let limit;
+    if (limitRaw !== undefined) {
+        const n = Number(limitRaw);
+        if (!Number.isInteger(n) || n < 1 || n > 100) {
+            fail("--limit must be an integer in 1..100", "invalid_args");
+        }
+        limit = n;
+    }
+    const client = makeClient(args);
+    try {
+        const r = await client.listBlobs({ cursor, limit });
+        printJson(r);
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}

package/dist/commands/blob-show.js

@@ -0,0 +1,37 @@
+// `pane blob show <blob-id>` — print a blob's metadata.
+import { assertKnownFlags } from "../argv.js";
+import { makeClient } from "../config.js";
+import { fail, failFromError, printJson } from "../output.js";
+const KNOWN_FLAGS = [];
+const KNOWN_BOOLS = [];
+export const blobShowHelp = `pane blob show — print a blob's metadata (no bytes)
+
+Usage:
+  pane blob show <blob-id> [options]
+
+Looks up the blob by id and prints its BlobRef metadata — owner, scope,
+mime, size, sha256, etc. Does NOT download the bytes; use 'pane blob
+download' for that.
+
+Options:
+  --url <url>            Relay base URL (overrides PANE_URL).
+  --api-key <key>        Agent API key (overrides PANE_API_KEY).
+  -h, --help             Show this help.
+
+Output (stdout, JSON):
+  BlobRef`;
+export async function runBlobShow(args) {
+    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "pane blob show");
+    const blobId = args.positionals[0];
+    if (!blobId) {
+        fail("missing <blob-id> — 'pane blob show <blob-id>'", "invalid_args");
+    }
+    const client = makeClient(args);
+    try {
+        const ref = await client.getBlob(blobId);
+        printJson(ref);
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}

package/dist/commands/blob-token.js

@@ -0,0 +1,133 @@
+// `pane blob token <mint|revoke|list>` — capability URLs for a blob.
+//
+// A capability URL (/b/<token>) is a participant-facing way to fetch a blob
+// without holding the agent's API key. Tokens are minted per-blob, can be
+// time-bound (--ttl) and/or single-use (--once), and are stored hashed on
+// the relay — the plaintext token is returned ONCE on 'mint' and cannot be
+// recovered.
+//
+// This file is a sub-noun dispatcher under `pane blob`. The blob dispatcher
+// hands us a ParsedArgs whose positionals[0] is "token" (our sub-noun
+// marker), so we read the verb from positionals[1] and the args from
+// positionals[2..]. Mirrors how participant.ts dispatches under `pane
+// session participant`.
+import { assertKnownFlags } from "../argv.js";
+import { makeClient } from "../config.js";
+import { fail, failFromError, printJson } from "../output.js";
+const MINT_FLAGS = ["ttl"];
+const MINT_BOOLS = ["once"];
+const NO_FLAGS = [];
+const NO_BOOLS = [];
+export const blobTokenHelp = `pane blob token — manage a blob's capability URLs
+
+Capability URLs let a participant (or any browser holding the URL) fetch a
+blob without the agent's API key. Tokens are stored HASHED on the relay; the
+plaintext token is returned only ONCE from 'mint' — save the response before
+delivering the URL.
+
+Usage:
+  pane blob token <verb> <args>
+
+Verbs:
+  mint <blob-id>          Mint a /b/<token> capability URL for one blob.
+                          Optional: --ttl <seconds> (defaults by scope:
+                          30d artifact / session TTL / 24h agent; the caller
+                          can only shorten), --once (token self-deletes on
+                          first successful GET). Returns { token, url,
+                          expires_at, ... } — ONCE.
+
+  revoke <blob-id> <token-id>
+                          Invalidate one previously-minted token by id.
+                          Idempotent: revoking twice still returns success.
+
+  list <blob-id>          Enumerate the tokens minted against one blob,
+                          including revoked rows (for audit). Returns
+                          { blob_id, items: [...] } where each item carries
+                          { token_id, token_prefix, expires_at, once,
+                          created_at, last_used_at, use_count, revoked_at }.
+                          The token plaintext is NEVER returned.
+
+Options:
+  --ttl <seconds>         (mint) per-token TTL; clamped by scope default.
+  --once                  (mint) token self-deletes on first GET.
+  --url <url>             Relay base URL (overrides PANE_URL).
+  --api-key <key>         Agent API key (overrides PANE_API_KEY).
+  -h, --help              Show this help.
+
+Output: stdout is machine-readable JSON.`;
+async function runBlobTokenMint(args) {
+    assertKnownFlags(args, MINT_FLAGS, MINT_BOOLS, "pane blob token mint");
+    const blobId = args.positionals[1];
+    if (!blobId) {
+        fail("missing <blob-id> — 'pane blob token mint <blob-id>'", "invalid_args");
+    }
+    const ttlRaw = args.flags.get("ttl");
+    const ttl = ttlRaw === undefined ? undefined : Number(ttlRaw);
+    if (ttlRaw !== undefined && (!Number.isInteger(ttl) || ttl <= 0)) {
+        fail("--ttl must be a positive integer (seconds)", "invalid_args");
+    }
+    const client = makeClient(args);
+    try {
+        const r = await client.mintBlobToken(blobId, {
+            ttlSeconds: ttl,
+            once: args.bools.has("once"),
+        });
+        printJson(r);
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+async function runBlobTokenRevoke(args) {
+    assertKnownFlags(args, NO_FLAGS, NO_BOOLS, "pane blob token revoke");
+    const blobId = args.positionals[1];
+    const tokenId = args.positionals[2];
+    if (!blobId || !tokenId) {
+        fail("missing arguments — 'pane blob token revoke <blob-id> <token-id>'", "invalid_args");
+    }
+    const client = makeClient(args);
+    try {
+        const r = await client.revokeBlobToken(blobId, tokenId);
+        printJson(r);
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+async function runBlobTokenList(args) {
+    assertKnownFlags(args, NO_FLAGS, NO_BOOLS, "pane blob token list");
+    const blobId = args.positionals[1];
+    if (!blobId) {
+        fail("missing <blob-id> — 'pane blob token list <blob-id>'", "invalid_args");
+    }
+    const client = makeClient(args);
+    try {
+        const r = await client.listBlobTokens(blobId);
+        printJson(r);
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+export async function runBlobToken(args) {
+    // positionals[0] is the verb (mint | revoke | list), positionals[1..] are
+    // the verb's args. (The blob.ts dispatcher already shifted off the "token"
+    // marker before calling us.)
+    const verb = args.positionals[0];
+    switch (verb) {
+        case "mint":
+            await runBlobTokenMint(args);
+            break;
+        case "revoke":
+            await runBlobTokenRevoke(args);
+            break;
+        case "list":
+            await runBlobTokenList(args);
+            break;
+        case undefined:
+            fail("missing verb — usage: pane blob token <mint|revoke|list> (run 'pane blob token --help')", "invalid_args");
+            break;
+        default:
+            fail(`unknown token verb '${verb}' — expected mint|revoke|list (run 'pane blob token --help')`, "invalid_args");
+    }
+}