@paneui/cli 0.0.4 → 0.0.6

package/dist/commands/taste.js

@@ -18,8 +18,13 @@
 // somewhere else. Today the blob is keyed by the agent's API key (per-agent);
 // when pane gains first-class humans, this may move to per-human.
 import { readFileSync } from "node:fs";
+import { assertKnownFlags } from "../argv.js";
 import { makeClient } from "../config.js";
 import { printJson, fail, failFromError } from "../output.js";
+const NO_FLAGS = [];
+const NO_BOOLS = [];
+const SET_FLAGS = ["file"];
+const CLEAR_BOOLS = ["yes"];
 export const tasteHelp = `pane taste — read / write / clear YOUR agent's UI taste notes
 
 Taste notes are a small markdown blob storing presentation preferences your
@@ -37,16 +42,18 @@ Subcommands:
              { taste: string|null, updated_at: string|null, bytes: number }.
              taste is null and bytes is 0 when notes have never been written.
 
-  set        Whole-blob replace. Read markdown from stdin OR --file <path>
-             (exactly one). The relay rejects empty/whitespace-only payloads
-             and caps the blob at MAX_TASTE_BYTES (utf8). To clear the notes,
+  set        Whole-blob replace. Source the markdown via --file <path>,
+             --file - (read stdin), or by piping into 'pane taste set' with
+             no flag. The relay rejects empty/whitespace-only payloads and
+             caps the blob at MAX_TASTE_BYTES (utf8). To clear the notes,
              use 'pane taste clear', not 'set' with an empty body.
 
   clear      Delete the notes. Requires --yes (it is destructive). Prints
              { cleared: true }.
 
 Options:
-  --file <path>       Read 'set' input from <path> (otherwise reads stdin).
+  --file <path|->     Source for 'set' — a file path, or '-' to read stdin
+                      explicitly. Omit to fall back to piped stdin.
   --yes               Confirm 'clear'.
   --url <url>         Relay base URL (overrides PANE_URL).
   --api-key <key>     Agent API key (overrides PANE_API_KEY).
@@ -54,17 +61,17 @@ Options:
 
 Examples:
   pane taste get
-  echo "- denser layout\\n- no rounded corners" | pane taste set
   pane taste set --file ./taste.md
+  pane taste set --file -            # explicit stdin
+  echo "- denser layout" | pane taste set
   pane taste clear --yes
 
 Output: stdout is machine-readable JSON.`;
-// Drain process.stdin to a utf8 string. Resolves to "" when stdin is a TTY
-// (i.e. nothing was piped in), so the caller can detect "no input" and emit a
-// proper error instead of hanging forever waiting for keystrokes.
+// Drain process.stdin to a utf8 string. The caller is responsible for
+// deciding that stdin should be read (e.g. an explicit `--file -`, or a
+// non-TTY stdin where data is actually piped). In a TTY this would block
+// waiting for ^D, so the caller MUST gate on `process.stdin.isTTY` first.
 async function readStdin() {
-    if (process.stdin.isTTY)
-        return "";
     const chunks = [];
     for await (const chunk of process.stdin) {
         chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
@@ -72,6 +79,7 @@ async function readStdin() {
     return Buffer.concat(chunks).toString("utf8");
 }
 async function runTasteGet(args) {
+    assertKnownFlags(args, NO_FLAGS, NO_BOOLS, "pane taste get");
     const client = makeClient(args);
     try {
         const info = await client.getTaste();
@@ -82,16 +90,21 @@ async function runTasteGet(args) {
     }
 }
 async function runTasteSet(args) {
+    assertKnownFlags(args, SET_FLAGS, NO_BOOLS, "pane taste set");
     const filePath = args.flags.get("file");
-    const hasStdin = !process.stdin.isTTY;
-    if (filePath !== undefined && hasStdin) {
-        fail("'pane taste set' takes input from EITHER stdin OR --file <path>, not both", "invalid_args");
-    }
-    if (filePath === undefined && !hasStdin) {
-        fail("'pane taste set' needs input — pipe markdown on stdin or pass --file <path>", "invalid_args");
-    }
+    // Source the blob deterministically — no isTTY-flag fusing, because
+    // `!process.stdin.isTTY` is true under every non-interactive caller
+    // (pipes, redirects, closed fd, CI, agent harnesses) and would wrongly
+    // reject `--file` for the entire target audience. See issue #148.
+    //
+    //   --file -        → explicit stdin sentinel
+    //   --file <path>   → read that path (works in TTY and non-TTY alike)
+    //   (no --file)     → fall back to stdin IF non-TTY; error in a TTY
     let taste;
-    if (filePath !== undefined) {
+    if (filePath === "-") {
+        taste = await readStdin();
+    }
+    else if (filePath !== undefined) {
         try {
             taste = readFileSync(filePath, "utf8");
         }
@@ -99,9 +112,12 @@ async function runTasteSet(args) {
             fail(`failed to read --file '${filePath}': ${e instanceof Error ? e.message : String(e)}`, "invalid_args");
         }
     }
-    else {
+    else if (!process.stdin.isTTY) {
         taste = await readStdin();
     }
+    else {
+        fail("'pane taste set' needs input — pass --file <path>, pipe markdown on stdin, or use --file -", "invalid_args");
+    }
     if (taste.trim().length === 0) {
         fail("'pane taste set' refuses an empty or whitespace-only blob — use 'pane taste clear --yes' to delete the notes", "invalid_args");
     }
@@ -115,6 +131,7 @@ async function runTasteSet(args) {
     }
 }
 async function runTasteClear(args) {
+    assertKnownFlags(args, NO_FLAGS, CLEAR_BOOLS, "pane taste clear");
     if (!args.bools.has("yes")) {
         fail("'pane taste clear' deletes YOUR agent's taste notes — it is destructive. Pass --yes to confirm.", "confirmation_required");
     }

package/dist/commands/watch.js

@@ -1,17 +1,20 @@
-// `pane watch <id>` — long-lived: hold a WebSocket and stream events as
+// `pane session 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 session watch — stream a session's events as JSON-lines
 
 Usage:
-  pane watch <session-id> [options]
+  pane session watch <session-id> [options]
 
 Holds a WebSocket to WS /v1/sessions/:id/stream. Prints ONE compact JSON
 object per line to stdout, flushing after each — designed to be piped into a
@@ -52,14 +55,14 @@ Options:
 Each line is one event envelope: { id, session_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 session 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 session 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 session 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,6 +91,7 @@ export function shouldPrintEvent(eventType, filterTypes) {
     return filterTypes.has(eventType);
 }
 export async function runWatch(args) {
+    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "pane session watch");
     const sessionId = args.positionals[0];
     if (!sessionId)
         fail("missing <session-id>", "invalid_args");

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.4";
+export const VERSION = "0.0.6";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paneui/cli",
-  "version": "0.0.4",
+  "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.4"
+    "@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"
   }
 }