@paneui/cli 0.0.5 → 0.0.7

package/dist/commands/watch.js

@@ -1,21 +1,24 @@
-// `pane watch <id>` — long-lived: hold a WebSocket and stream events as
+// `pane surface watch <id>` — long-lived: hold a WebSocket and stream events as
 // JSON-lines on stdout. This harness-agnostic stdout is the core contract:
 // one compact JSON object per line, flushed after every event, so any
 // pipe-reader (Claude Code's Monitor tool, `while read line`, jq -c, ...)
 // sees each event the instant it lands.
 import { openStream } from "@paneui/core";
+import { assertKnownFlags } from "../argv.js";
 import { resolveConfig } from "../config.js";
 import { PaneClient } from "@paneui/core";
 import { printJsonLine, fail } from "../output.js";
 import { VERSION } from "../version.js";
-export const watchHelp = `pane watch — stream a session's events as JSON-lines
+const KNOWN_FLAGS = ["since", "type", "filter-type", "timeout"];
+const KNOWN_BOOLS = ["once"];
+export const watchHelp = `pane surface watch — stream a surface's events as JSON-lines
 
 Usage:
-  pane watch <session-id> [options]
+  pane surface watch <surface-id> [options]
 
-Holds a WebSocket to WS /v1/sessions/:id/stream. Prints ONE compact JSON
+Holds a WebSocket to WS /v1/surfaces/:id/stream. Prints ONE compact JSON
 object per line to stdout, flushing after each — designed to be piped into a
-line-reader. On session close, prints a final {"type":"_closed"} line and
+line-reader. On surface close, prints a final {"type":"_closed"} line and
 exits 0.
 
 Modes:
@@ -31,7 +34,7 @@ Options:
   --filter-type <t[,t2,…]>
                       Print only events whose type is in this set.
                       system.* events (lifecycle: participant.joined,
-                      session.expired, …) and the terminal {"type":
+                      surface.expired, …) and the terminal {"type":
                       "_closed"} line always pass through, so the
                       harness still sees them. Combine with --type X
                       --filter-type X for "stream only X events and
@@ -39,7 +42,7 @@ Options:
                       --type alone that agents often expect.
   --since <cursor>    Replay only events after this opaque cursor.
   --timeout <secs>    Wall-clock max wait. Fail with code ws_timeout if
-                      the natural exit condition (--once, --type, session
+                      the natural exit condition (--once, --type, surface
                       close) doesn't happen within this many seconds.
                       Frames arriving DO NOT reset the timer — this is
                       the budget for "give up on the human", not an idle
@@ -49,17 +52,17 @@ Options:
   --api-key <key>     Agent API key (overrides PANE_API_KEY).
   -h, --help          Show this help.
 
-Each line is one event envelope: { id, session_id, author, ts, type, data,
+Each line is one event envelope: { id, surface_id, author, ts, type, data,
 causation_id, idempotency_key }. The terminal line is {"type":"_closed"}.
 
-Pattern — Claude Code Monitor tool: run \`pane watch <id> --type form.submitted\`
+Pattern — Claude Code Monitor tool: run \`pane surface watch <id> --type form.submitted\`
 as a monitored process; the harness re-invokes the model when the line lands.
 
 Wait for any of several events:
-  pane watch <id> --type form.submitted,form.cancelled --timeout 60
+  pane surface watch <id> --type form.submitted,form.cancelled --timeout 60
 
 Stream only matching events to stdout, exit on the first:
-  pane watch <id> --type form.submitted --filter-type form.submitted`;
+  pane surface watch <id> --type form.submitted --filter-type form.submitted`;
 // Parse a comma-separated event-type list (e.g. "form.submitted,form.cancelled")
 // into a Set. Empty/whitespace entries are dropped. Returns null when the flag
 // wasn't given (so callers can distinguish "no filter" from "empty filter").
@@ -88,9 +91,10 @@ export function shouldPrintEvent(eventType, filterTypes) {
     return filterTypes.has(eventType);
 }
 export async function runWatch(args) {
-    const sessionId = args.positionals[0];
-    if (!sessionId)
-        fail("missing <session-id>", "invalid_args");
+    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "pane surface watch");
+    const surfaceId = args.positionals[0];
+    if (!surfaceId)
+        fail("missing <surface-id>", "invalid_args");
     const cfg = resolveConfig(args);
     const since = args.flags.get("since") ?? null;
     // --type controls the EXIT condition (set of types that trigger exit 0
@@ -131,7 +135,7 @@ export async function runWatch(args) {
         }
         finish(0);
     };
-    // Track whether the relay told us the session expired before the socket
+    // Track whether the relay told us the surface expired before the socket
     // closed — a 1006/1008/1011 close after that is still a clean shutdown.
     let sawSessionExpired = false;
     // Wall-clock timeout. The reporter's mental model (#137) and the skill
@@ -141,7 +145,7 @@ export async function runWatch(args) {
     // useless once any frame arrived, even a system.participant.joined
     // emitted the moment a human connected. Frames now DO NOT reset the
     // timer; the only ways `--timeout` doesn't fire are the natural exit
-    // conditions (--once, --type match, session close) finishing first.
+    // conditions (--once, --type match, surface close) finishing first.
     let timer;
     if (timeoutSec !== null) {
         timer = setTimeout(() => {
@@ -150,7 +154,7 @@ export async function runWatch(args) {
     }
     const handle = openStream({
         wsBaseUrl: client.wsBaseUrl,
-        sessionId: sessionId,
+        surfaceId: surfaceId,
         token: cfg.apiKey,
         since,
     }, {
@@ -163,8 +167,8 @@ export async function runWatch(args) {
             if (shouldPrintEvent(event.type, filterTypes)) {
                 printJsonLine(event);
             }
-            // A system.session.expired event means the session is closing.
-            if (event.type === "system.session.expired") {
+            // A system.surface.expired event means the surface is closing.
+            if (event.type === "system.surface.expired") {
                 sawSessionExpired = true;
                 emitClosed();
                 return;
@@ -180,8 +184,8 @@ export async function runWatch(args) {
         onClose: ({ code, reason }) => {
             // A clean close is 1000 (normal) or 1001 (going away). Any other code
             // — 1006 abnormal, 1008 policy/auth, 1011 server error — is a failure
-            // UNLESS we already saw system.session.expired, which means the relay
-            // closed us on purpose after a clean session end.
+            // UNLESS we already saw system.surface.expired, which means the relay
+            // closed us on purpose after a clean surface end.
             if (code === 1000 || code === 1001 || sawSessionExpired) {
                 emitClosed();
                 return;

package/dist/config.js

@@ -49,15 +49,15 @@ export function describeConfig(args) {
 }
 /**
  * The hosted Pane relay. Used as the relay-URL fallback so a fresh user only
- * needs an API key — `pane register` against the hosted relay, then go. A
- * self-hoster overrides it with `--url` / `PANE_URL` / `pane register --url`.
+ * needs an API key — `pane agent register` against the hosted relay, then go. A
+ * self-hoster overrides it with `--url` / `PANE_URL` / `pane agent register --url`.
  */
 export const DEFAULT_RELAY_URL = "https://relay.paneui.com";
 /**
  * Resolve relay URL + API key. Precedence (highest first):
  *   url:    --url flag  → PANE_URL env      → store.url  → DEFAULT_RELAY_URL
  *   apiKey: --api-key   → PANE_API_KEY env  → store.apiKey
- * The store is written by `pane register`, so later commands need no env vars.
+ * The store is written by `pane agent register`, so later commands need no env vars.
  */
 export function resolveConfig(args) {
     const store = readStore();
@@ -67,7 +67,7 @@ export function resolveConfig(args) {
         DEFAULT_RELAY_URL;
     const apiKey = args.flags.get("api-key") ?? process.env.PANE_API_KEY ?? store.apiKey ?? "";
     if (!apiKey) {
-        fail("missing API key: set PANE_API_KEY, pass --api-key <key>, or run 'pane register'", "config_error");
+        fail("missing API key: set PANE_API_KEY, pass --api-key <key>, or run 'pane agent register'", "config_error");
     }
     return { url: url.replace(/\/$/, ""), apiKey };
 }

package/dist/index.js

@@ -1,21 +1,36 @@
 #!/usr/bin/env node
 // pane — command-line client for the Pane relay.
 //
+// Shape: uniform `pane <noun> <verb> [options]`. Every command lives under a
+// noun; nothing is a bare top-level verb. See issue #163 for the rationale
+// behind the shape and the rename from the older flat layout.
+//
 // Config: PANE_URL and PANE_API_KEY (env), overridable with --url / --api-key.
-// Output is JSON by default. Every command self-documents via --help.
+// Output is JSON by default. Every noun self-documents via --help.
 import { parseArgs, ArgvError } from "./argv.js";
-import { runCreate, createHelp } from "./commands/create.js";
-import { runState, stateHelp } from "./commands/state.js";
-import { runSend, sendHelp } from "./commands/send.js";
-import { runWatch, watchHelp } from "./commands/watch.js";
-import { runRegister, registerHelp } from "./commands/register.js";
-import { runArtifact, artifactHelp } from "./commands/artifact.js";
-import { runConfig, configHelp } from "./commands/config.js";
-import { runLogout, logoutHelp } from "./commands/logout.js";
-import { runKeys, keysHelp } from "./commands/keys.js";
+/**
+ * Translate an ArgvError into the canonical `invalid_args` envelope and exit
+ * non-zero. The parser throws ArgvError up-front; assertKnownFlags throws it
+ * from inside a runner. Both paths funnel here so the on-wire shape is one.
+ */
+function failArgvError(e) {
+    const error = {
+        code: "invalid_args",
+        message: e.message,
+    };
+    if (e.hint !== undefined)
+        error["hint"] = e.hint;
+    process.stderr.write(JSON.stringify({ error }) + "\n");
+    process.exit(1);
+}
+import { runSession, sessionHelp } from "./commands/surface.js";
+import { runArtifact, artifactHelp } from "./commands/template.js";
+import { runAgent, agentHelp } from "./commands/agent.js";
+import { runKey, keyHelp } from "./commands/key.js";
 import { runTaste, tasteHelp } from "./commands/taste.js";
 import { runFeedback, feedbackHelp } from "./commands/feedback.js";
-import { runDelete, deleteHelp } from "./commands/delete.js";
+import { runConfig, configHelp } from "./commands/config.js";
+import { runBlob, blobHelp } from "./commands/attachment.js";
 import { runSkill, skillHelp } from "./commands/skill.js";
 import { VERSION } from "./version.js";
 import { PaneApiError } from "@paneui/core";
@@ -23,39 +38,37 @@ import { failUpgradeRequired } from "./output.js";
 const ROOT_HELP = `pane — a round-trip UI channel between agents and humans
 
 Usage:
-  pane <command> [options]
+  pane <noun> <verb> [options]
 
-Commands:
-  register          Provision an agent API key (POST /v1/register) and save it
-                    to the CLI config file. Run this once before other commands.
-  create            Create a session (POST /v1/sessions). Prints session_id,
-                    urls, tokens, expires_at.
-  artifact          Manage reusable, versioned artifacts (create / version /
-                    update / search / list / show / delete).
-  state <id>        Non-blocking snapshot: session metadata + event log.
-  send <id>         Emit an agent event into a session.
-  watch <id>        Stream a session's events as JSON-lines on stdout
-                    (long-lived; the building block for pipe-readers).
-  delete <id>       Close/delete a session (DELETE /v1/sessions/:id).
-  keys              Inspect or revoke YOUR agent's API key (list / revoke).
-  taste             Read / write / clear YOUR agent's UI taste notes
-                    (get / set / clear) — presentation preferences the agent
+Nouns:
+  surface           Open / observe / send to / close surfaces
+                    (create | list | show | send | watch | delete |
+                     participant <list|new|revoke>).
+  template          Reusable, versioned UI templates
+                    (create | version | update | search | list | show | delete).
+  key               YOUR agent's API key (list | revoke).
+  taste             YOUR agent's freeform UI taste notes
+                    (get | set | clear) — presentation preferences the agent
                     has learned from human feedback and reads before
-                    generating a pane artifact.
-  feedback          Submit / list one-shot feedback to the relay operator
-                    (create / list) — bug reports, feature requests, notes.
-  config            Show the resolved relay config (no network call).
-  logout            Clear the locally-saved relay URL + API key.
-  skill             Fetch the relay's SKILL.md to stdout, or just its
-                    version with 'pane skill version'. Used to install
-                    and keep the local skill copy in sync; no API key.
+                    generating a pane template.
+  feedback          One-shot feedback to the relay operator
+                    (create | list) — bug reports, feature requests, notes.
+  attachment              Binary attachments (upload | download | show | list |
+                    delete | token <mint|revoke|list>). Blobs are scoped to
+                    an agent, a surface, or an template, and can be referenced
+                    from event payloads + input_data via
+                    \`format: pane-attachment-id\`.
+  agent             Agent identity on this machine (register | logout).
+  config            CLI config inspection (show).
+  skill             The relay's SKILL.md (show | version) — auto-updating;
+                    no API key required.
 
-Run \`pane <command> --help\` for command-specific options.
+Run \`pane <noun> --help\` for that noun's verbs.
 
 Config:
   PANE_URL          Relay base URL.        Override: --url <url>
   PANE_API_KEY      Agent API key.         Override: --api-key <key>
-  'pane register' provisions the API key and saves it (with the URL) to
+  'pane agent register' provisions the API key and saves it (with the URL) to
   \${XDG_CONFIG_HOME:-~/.config}/pane/config.json — afterwards commands need
   only PANE_URL (or nothing) set.
 
@@ -72,8 +85,8 @@ Output: stdout is machine-readable JSON; errors go to stderr as
 //
 // `version` is deliberately NOT here: the top-level `-v` / `--version` is
 // handled from rawArgv[0] before parseArgs runs, so it never needs to be a
-// boolean flag — and keeping it out lets `pane create --version <n>` /
-// `pane artifact version` consume a value as a normal value-flag.
+// boolean flag — and keeping it out lets `pane surface create --version <n>` /
+// `pane template version` consume a value as a normal value-flag.
 const BOOLEAN_FLAGS = new Set([
     "json",
     "once",
@@ -89,12 +102,12 @@ async function main() {
         process.stdout.write(VERSION + "\n");
         return;
     }
-    const command = rawArgv[0];
+    const noun = rawArgv[0];
     const rest = rawArgv.slice(1);
-    if (command === undefined ||
-        command === "-h" ||
-        command === "--help" ||
-        command === "help") {
+    if (noun === undefined ||
+        noun === "-h" ||
+        noun === "--help" ||
+        noun === "help") {
         process.stdout.write(ROOT_HELP + "\n");
         return;
     }
@@ -104,65 +117,47 @@ async function main() {
     }
     catch (e) {
         if (e instanceof ArgvError) {
-            process.stderr.write(JSON.stringify({
-                error: { code: "invalid_args", message: e.message },
-            }) + "\n");
-            process.exit(1);
+            failArgvError(e);
         }
         throw e;
     }
     const helps = {
-        register: registerHelp,
-        create: createHelp,
-        artifact: artifactHelp,
-        state: stateHelp,
-        send: sendHelp,
-        watch: watchHelp,
-        delete: deleteHelp,
-        keys: keysHelp,
+        surface: sessionHelp,
+        template: artifactHelp,
+        key: keyHelp,
         taste: tasteHelp,
         feedback: feedbackHelp,
+        attachment: blobHelp,
+        agent: agentHelp,
         config: configHelp,
-        logout: logoutHelp,
         skill: skillHelp,
     };
-    if (!(command in helps)) {
+    if (!(noun in helps)) {
         process.stderr.write(JSON.stringify({
             error: {
                 code: "unknown_command",
-                message: `unknown command '${command}' — run 'pane --help'`,
+                message: `unknown command '${noun}' — run 'pane --help'`,
             },
         }) + "\n");
         process.exit(1);
     }
-    if (args.bools.has("help")) {
-        process.stdout.write(helps[command] + "\n");
+    // `pane <noun> --help` with no verb prints the noun-level help. A verb-level
+    // --help is the responsibility of each runner (e.g. runSession dispatches to
+    // the verb runner which reads its own xxxHelp). This pre-empt only fires
+    // when --help is the FIRST positional-equivalent — i.e. no verb given.
+    if (args.bools.has("help") && args.positionals.length === 0) {
+        process.stdout.write(helps[noun] + "\n");
         return;
     }
-    switch (command) {
-        case "register":
-            await runRegister(args);
+    switch (noun) {
+        case "surface":
+            await runSession(args);
             break;
-        case "create":
-            await runCreate(args);
-            break;
-        case "artifact":
+        case "template":
             await runArtifact(args);
             break;
-        case "state":
-            await runState(args);
-            break;
-        case "send":
-            await runSend(args);
-            break;
-        case "watch":
-            await runWatch(args);
-            break;
-        case "delete":
-            await runDelete(args);
-            break;
-        case "keys":
-            await runKeys(args);
+        case "key":
+            await runKey(args);
             break;
         case "taste":
             await runTaste(args);
@@ -170,18 +165,28 @@ async function main() {
         case "feedback":
             await runFeedback(args);
             break;
+        case "attachment":
+            await runBlob(args);
+            break;
+        case "agent":
+            await runAgent(args);
+            break;
         case "config":
             await runConfig(args);
             break;
-        case "logout":
-            await runLogout();
-            break;
         case "skill":
             await runSkill(args);
             break;
     }
 }
 main().catch((err) => {
+    // ArgvError thrown from a runner (e.g. assertKnownFlags) reaches here —
+    // funnel it through the same invalid_args envelope as the parse-time path
+    // so unknown-flag rejection looks identical no matter which layer caught
+    // the user error.
+    if (err instanceof ArgvError) {
+        failArgvError(err);
+    }
     // Funnel 426 cli_upgrade_required through the dedicated upgrade-message
     // path so a command that throws raw (instead of going through
     // failFromError) still produces the exact stderr block + exit 75 the

package/dist/input.js

@@ -1,5 +1,5 @@
 // Helpers for reading CLI inputs that may be either a file path or an inline
-// literal (JSON, or raw text for an HTML artifact body).
+// literal (JSON, or raw text for an HTML template body).
 import { readFileSync, statSync } from "node:fs";
 /**
  * True if `value` names an existing file. Only a missing path (ENOENT) is
@@ -17,7 +17,7 @@ function isFilePath(value) {
             return false;
         }
         const code = e && typeof e === "object" ? e.code : undefined;
-        throw new Error(`cannot stat '${value}'${code ? ` (${code})` : ""}: ${e instanceof Error ? e.message : String(e)}`);
+        throw new Error(`cannot stat '${value}'${code ? ` (${code})` : ""}: ${e instanceof Error ? e.message : String(e)}`, { cause: e });
     }
 }
 /**
@@ -30,12 +30,12 @@ export function resolveJson(value, label) {
         return JSON.parse(raw);
     }
     catch (e) {
-        throw new Error(`${label}: not valid JSON (${e instanceof Error ? e.message : String(e)})`);
+        throw new Error(`${label}: not valid JSON (${e instanceof Error ? e.message : String(e)})`, { cause: e });
     }
 }
 /**
  * Resolve raw text that is either a file path or an inline literal — no JSON
- * parsing. Used for an inline HTML artifact body.
+ * parsing. Used for an inline HTML template body.
  */
 export function resolveText(value) {
     return isFilePath(value) ? readFileSync(value, "utf8") : value;

package/dist/output.js

@@ -8,7 +8,7 @@ export function printJson(value) {
     process.stdout.write(JSON.stringify(value, null, 2) + "\n");
 }
 /**
- * Print a single compact JSON line to stdout and flush. Used by `pane watch`
+ * Print a single compact JSON line to stdout and flush. Used by `pane surface watch`
  * so a pipe-reader (e.g. Claude Code's Monitor tool) sees each event
  * immediately, one event per line.
  */

package/dist/store.js

@@ -1,6 +1,6 @@
 // Persisted CLI config: ${XDG_CONFIG_HOME or ~/.config}/pane/config.json.
 //
-// Holds the relay URL and the agent API key obtained via `pane register`, so
+// Holds the relay URL and the agent API key obtained via `pane agent register`, so
 // later commands need no env vars. The file holds a secret — it is written
 // 0600. Tiny and synchronous; no deps.
 import { readFileSync, writeFileSync, mkdirSync, chmodSync, rmSync, } from "node:fs";
@@ -55,7 +55,7 @@ export function writeStore(patch) {
 }
 /**
  * Delete the persisted config file (URL + API key). Idempotent — no error if
- * the file never existed. Returns the path it targeted. Used by `pane logout`.
+ * the file never existed. Returns the path it targeted. Used by `pane agent logout`.
  */
 export function clearStore() {
     const path = storePath();

package/dist/version.js

@@ -8,4 +8,4 @@
 // Keep this in lockstep with packages/cli/package.json's `version` field;
 // they're consulted in different places (here for the runtime header,
 // package.json for npm publish + dependency resolution).
-export const VERSION = "0.0.5";
+export const VERSION = "0.0.7";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@paneui/cli",
-  "version": "0.0.5",
-  "description": "Command-line client for the Pane relay: create sessions, inspect state, send and watch events.",
+  "version": "0.0.7",
+  "description": "Command-line client for the Pane relay: create surfaces, inspect state, send and watch events.",
   "license": "MIT",
   "type": "module",
   "keywords": [
@@ -41,11 +41,11 @@
     "test:unit": "vitest run"
   },
   "dependencies": {
-    "@paneui/core": "^0.0.5"
+    "@paneui/core": "^0.0.7"
   },
   "devDependencies": {
-    "@types/node": "^22.7.0",
-    "typescript": "^5.6.0",
+    "@types/node": "^25.9.1",
+    "typescript": "^6.0.3",
     "vitest": "^4.1.6"
   }
 }