@paneui/cli 0.0.5 → 0.0.6

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";
+/**
+ * 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/session.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";
+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/blob.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:
+  session           Open / observe / send to / close sessions
+                    (create | list | show | send | watch | delete |
+                     participant <list|new|revoke>).
+  artifact          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.
+  feedback          One-shot feedback to the relay operator
+                    (create | list) — bug reports, feature requests, notes.
+  blob              Binary attachments (upload | download | show | list |
+                    delete | token <mint|revoke|list>). Blobs are scoped to
+                    an agent, a session, or an artifact, and can be referenced
+                    from event payloads + input_data via
+                    \`format: pane-blob-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,7 +85,7 @@ 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>` /
+// boolean flag — and keeping it out lets `pane session create --version <n>` /
 // `pane artifact version` consume a value as a normal value-flag.
 const BOOLEAN_FLAGS = new Set([
     "json",
@@ -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,
+        session: sessionHelp,
         artifact: artifactHelp,
-        state: stateHelp,
-        send: sendHelp,
-        watch: watchHelp,
-        delete: deleteHelp,
-        keys: keysHelp,
+        key: keyHelp,
         taste: tasteHelp,
         feedback: feedbackHelp,
+        blob: 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);
-            break;
-        case "create":
-            await runCreate(args);
+    switch (noun) {
+        case "session":
+            await runSession(args);
             break;
         case "artifact":
             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 "blob":
+            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

@@ -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,7 +30,7 @@ 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 });
     }
 }
 /**

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 session 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.6";

package/package.json

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