@paneui/cli 0.0.5 → 0.0.7

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 surface create            Create a surface — returns surface_id, urls, tokens
+pane surface show <id>         Non-blocking snapshot: metadata + event log
+pane surface send <id>         Emit an agent event into a surface
+pane surface watch <id>        Stream a surface's events as JSON-lines on stdout
+pane surface delete <id>       Close / delete a surface
+pane template <verb>           Manage reusable, versioned templates
+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,12 +56,12 @@ 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 surface create --template form --schema ./q.json | jq -r .surface_id)
+pane surface watch "$SESSION" | jq 'select(.type == "human_response")'
 ```
 
 ## Links
 
 - Repo: <https://github.com/aerolalit/paneui>
-- Spec: <https://github.com/aerolalit/paneui/blob/main/docs/SPEC.md>
+- Spec: <https://github.com/aerolalit/paneui/attachment/main/docs/SPEC.md>
 - License: MIT

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,54 @@
+// `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 { runClaim } from "./claim.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.
+  claim <code>      Bind this agent to a human via a one-shot claim code the
+                    human generated in their Settings UI (POST /v1/agents/claim).
+                    One-way; no unclaim in v1.
+  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) {
+    // Strip the first positional (the verb) so each verb runner sees its
+    // own arguments at positionals[0..n].
+    const verbArgs = {
+        ...args,
+        positionals: args.positionals.slice(1),
+    };
+    const verb = args.positionals[0];
+    switch (verb) {
+        case "register":
+            await runRegister(verbArgs);
+            break;
+        case "claim":
+            await runClaim(verbArgs);
+            break;
+        case "logout":
+            await runLogout(verbArgs);
+            break;
+        case undefined:
+            fail("missing verb — usage: pane agent <register|claim|logout> (run 'pane agent --help')", "invalid_args");
+            break;
+        default:
+            fail(`unknown agent verb '${verb}' — expected register|claim|logout (run 'pane agent --help')`, "invalid_args");
+    }
+}

package/dist/commands/attachment-delete.js

@@ -0,0 +1,37 @@
+// `pane attachment delete <attachment-id>` — soft-delete a attachment.
+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 attachment delete — soft-delete a attachment
+
+Usage:
+  pane attachment delete <attachment-id> [options]
+
+Marks the attachment as deleted (DELETE /v1/attachments/:id). Idempotent: deleting an
+already-deleted attachment still returns success. Tokens minted against this attachment
+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):
+  { attachment_id, deleted: true }`;
+export async function runBlobDelete(args) {
+    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "pane attachment delete");
+    const attachmentId = args.positionals[0];
+    if (!attachmentId) {
+        fail("missing <attachment-id> — 'pane attachment delete <attachment-id>'", "invalid_args");
+    }
+    const client = makeClient(args);
+    try {
+        const r = await client.deleteBlob(attachmentId);
+        printJson({ attachment_id: attachmentId, ...r });
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}

package/dist/commands/attachment-download.js

@@ -0,0 +1,53 @@
+// `pane attachment download <attachment-id>` — fetch attachment 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 attachment download — fetch a attachment's bytes
+
+Usage:
+  pane attachment download <attachment-id> [--out <path>] [options]
+
+GETs the attachment 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:    { attachment_id, written: <path>, bytes: <n> } to stdout.`;
+export async function runBlobDownload(args) {
+    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "pane attachment download");
+    const attachmentId = args.positionals[0];
+    if (!attachmentId) {
+        fail("missing <attachment-id> — 'pane attachment download <attachment-id>'", "invalid_args");
+    }
+    const out = args.flags.get("out");
+    const client = makeClient(args);
+    try {
+        const buf = await client.downloadBlob(attachmentId);
+        if (out) {
+            writeFileSync(out, Buffer.from(buf));
+            printJson({
+                attachment_id: attachmentId,
+                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/attachment-list.js

@@ -0,0 +1,50 @@
+// `pane attachment list` — enumerate YOUR agent's attachments.
+//
+// Lists attachments owned by the calling agent, newest first. Soft-deleted attachments
+// are excluded; tokens are not enumerated here (use 'pane attachment token list
+// <attachment-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 attachment list — enumerate YOUR agent's attachments
+
+Usage:
+  pane attachment list [--cursor <token>] [--limit <n>] [options]
+
+Returns the agent's non-deleted attachments (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: AttachmentRef[], next_cursor: string | null }`;
+export async function runBlobList(args) {
+    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "pane attachment 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/attachment-show.js

@@ -0,0 +1,37 @@
+// `pane attachment show <attachment-id>` — print a attachment'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 attachment show — print a attachment's metadata (no bytes)
+
+Usage:
+  pane attachment show <attachment-id> [options]
+
+Looks up the attachment by id and prints its AttachmentRef metadata — owner, scope,
+mime, size, sha256, etc. Does NOT download the bytes; use 'pane attachment
+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):
+  AttachmentRef`;
+export async function runBlobShow(args) {
+    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "pane attachment show");
+    const attachmentId = args.positionals[0];
+    if (!attachmentId) {
+        fail("missing <attachment-id> — 'pane attachment show <attachment-id>'", "invalid_args");
+    }
+    const client = makeClient(args);
+    try {
+        const ref = await client.getBlob(attachmentId);
+        printJson(ref);
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}

package/dist/commands/attachment-token.js

@@ -0,0 +1,133 @@
+// `pane attachment token <mint|revoke|list>` — capability URLs for a attachment.
+//
+// A capability URL (/b/<token>) is a participant-facing way to fetch a attachment
+// without holding the agent's API key. Tokens are minted per-attachment, 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 attachment`. The attachment 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
+// surface 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 attachment token — manage a attachment's capability URLs
+
+Capability URLs let a participant (or any browser holding the URL) fetch a
+attachment 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 attachment token <verb> <args>
+
+Verbs:
+  mint <attachment-id>          Mint a /b/<token> capability URL for one attachment.
+                          Optional: --ttl <seconds> (defaults by scope:
+                          30d template / surface TTL / 24h agent; the caller
+                          can only shorten), --once (token self-deletes on
+                          first successful GET). Returns { token, url,
+                          expires_at, ... } — ONCE.
+
+  revoke <attachment-id> <token-id>
+                          Invalidate one previously-minted token by id.
+                          Idempotent: revoking twice still returns success.
+
+  list <attachment-id>          Enumerate the tokens minted against one attachment,
+                          including revoked rows (for audit). Returns
+                          { attachment_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 attachment token mint");
+    const attachmentId = args.positionals[1];
+    if (!attachmentId) {
+        fail("missing <attachment-id> — 'pane attachment token mint <attachment-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(attachmentId, {
+            ttlSeconds: ttl,
+            once: args.bools.has("once"),
+        });
+        printJson(r);
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+async function runBlobTokenRevoke(args) {
+    assertKnownFlags(args, NO_FLAGS, NO_BOOLS, "pane attachment token revoke");
+    const attachmentId = args.positionals[1];
+    const tokenId = args.positionals[2];
+    if (!attachmentId || !tokenId) {
+        fail("missing arguments — 'pane attachment token revoke <attachment-id> <token-id>'", "invalid_args");
+    }
+    const client = makeClient(args);
+    try {
+        const r = await client.revokeBlobToken(attachmentId, tokenId);
+        printJson(r);
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+async function runBlobTokenList(args) {
+    assertKnownFlags(args, NO_FLAGS, NO_BOOLS, "pane attachment token list");
+    const attachmentId = args.positionals[1];
+    if (!attachmentId) {
+        fail("missing <attachment-id> — 'pane attachment token list <attachment-id>'", "invalid_args");
+    }
+    const client = makeClient(args);
+    try {
+        const r = await client.listBlobTokens(attachmentId);
+        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 attachment.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 attachment token <mint|revoke|list> (run 'pane attachment token --help')", "invalid_args");
+            break;
+        default:
+            fail(`unknown token verb '${verb}' — expected mint|revoke|list (run 'pane attachment token --help')`, "invalid_args");
+    }
+}

package/dist/commands/attachment-upload.js

@@ -0,0 +1,79 @@
+// `pane attachment upload` — POST /v1/attachments (multipart), three scopes.
+import { readFileSync } from "node:fs";
+import { basename } from "node:path";
+import { assertKnownFlags } from "../argv.js";
+import { makeClient } from "../config.js";
+import { fail, failFromError, printJson } from "../output.js";
+const KNOWN_FLAGS = [
+    "file",
+    "scope",
+    "surface-id",
+    "template-id",
+    "filename",
+    "mime",
+];
+const KNOWN_BOOLS = [];
+export const blobUploadHelp = `pane attachment upload — upload a local file as a attachment
+
+Usage:
+  pane attachment upload --file <path> [options]
+
+Required:
+  --file <path>          Local file to upload.
+
+Scope (default: agent):
+  --scope <s>            "agent" | "surface" | "template".
+  --surface-id <id>      Required when --scope=surface.
+  --template-id <id>     Required when --scope=template.
+
+Optional:
+  --filename <name>      Display filename (otherwise basename of --file).
+  --mime <type>          Declared Content-Type. The relay sniffs the bytes
+                         regardless — this is advisory.
+  --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):
+  AttachmentRef — { attachment_id, scope, mime, size, sha256, ... }`;
+export async function runBlobUpload(args) {
+    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "pane attachment upload");
+    const filePath = args.flags.get("file");
+    if (!filePath) {
+        fail("missing --file <path> — 'pane attachment upload' requires a local file to upload", "invalid_args");
+    }
+    let bytes;
+    try {
+        bytes = readFileSync(filePath);
+    }
+    catch (e) {
+        fail(`failed to read --file '${filePath}': ${e instanceof Error ? e.message : String(e)}`, "invalid_args");
+    }
+    const scopeRaw = args.flags.get("scope") ?? "agent";
+    if (scopeRaw !== "agent" &&
+        scopeRaw !== "surface" &&
+        scopeRaw !== "template") {
+        fail(`unknown --scope '${scopeRaw}' — expected one of: agent, surface, template`, "invalid_args");
+    }
+    const scope = scopeRaw;
+    if (scope === "surface" && !args.flags.get("surface-id")) {
+        fail("--scope=surface requires --surface-id <id>", "invalid_args");
+    }
+    if (scope === "template" && !args.flags.get("template-id")) {
+        fail("--scope=template requires --template-id <id>", "invalid_args");
+    }
+    const client = makeClient(args);
+    try {
+        const ref = await client.uploadBlob(bytes, {
+            scope,
+            surfaceId: args.flags.get("surface-id"),
+            templateId: args.flags.get("template-id"),
+            filename: args.flags.get("filename") ?? basename(filePath),
+            mime: args.flags.get("mime"),
+        });
+        printJson(ref);
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}