@paneui/cli 0.0.9 → 0.0.10

package/dist/commands/create.js

@@ -1,27 +1,37 @@
-// `pane surface create` — create a surface via POST /v1/surfaces.
-import { createSessionSchema } from "@paneui/core";
+// `pane create` — create a pane via POST /v1/panes.
+import { createPaneSchema } 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";
+import { formatPaneCreated } from "../format.js";
 const KNOWN_FLAGS = [
     "template",
     "template-id",
     "template-type",
+    "name",
+    "slug",
     "version",
     "event-schema",
     "input-schema",
     "title",
+    "preamble",
     "input-data",
     "ttl",
     "participants",
     "metadata",
     "callback",
+    "context-key",
+    "icon-emoji",
+    "icon-attachment-id",
 ];
-const KNOWN_BOOLS = [];
+// `--json` forces machine-readable output even on a TTY. Without it, an
+// interactive terminal gets the human-readable form (title + URLs + QR +
+// countdown); pipes and `--json` callers still get the legacy JSON shape.
+const KNOWN_BOOLS = ["json"];
 // Translate a Zod schema path (e.g. ["participants","humans"]) back to the
 // public CLI flag the user actually typed. Without this, a `--participants 0`
-// rejection surfaces as `participants.humans: ...` — which leaks the wire
+// rejection panes as `participants.humans: ...` — which leaks the wire
 // shape and refers to no flag the user could fix.
 //
 // Match strategy: longest prefix wins. Schema paths whose top segment isn't
@@ -37,9 +47,15 @@ const SCHEMA_PATH_TO_FLAG = {
     callback: "--callback",
     input_data: "--input-data",
     title: "--title",
+    preamble: "--preamble",
+    context_key: "--context-key",
+    icon_emoji: "--icon-emoji",
+    icon_attachment_id: "--icon-attachment-id",
     "template.id": "--template-id",
     "template.version": "--version",
     "template.type": "--template-type",
+    "template.name": "--name",
+    "template.slug": "--slug",
     "template.source": "--template",
     "template.event_schema": "--event-schema",
     "template.input_schema": "--input-schema",
@@ -57,16 +73,16 @@ function schemaPathToFlag(path) {
     }
     return dotted;
 }
-export const createHelp = `pane surface create — create a Pane surface
+export const createHelp = `pane create — create a Pane pane
 
-A surface is one use of an template. Supply the template in ONE of two ways:
+A pane is one use of an template. Supply the template in ONE of two ways:
 
   Reference form — instance an existing reusable template (the cheap path,
   no HTML re-sent):
-    pane surface create --template-id <id|slug> [--version <n>] [--input-data <v>]
+    pane create --template-id <id|slug> [--version <n>] [--input-data <v>]
 
   Inline form — a one-off template, defined on this call:
-    pane surface create --template <path|inline> [--event-schema <path|json>] [options]
+    pane create --template <path|inline> [--event-schema <path|json>] [options]
 
 Exactly one of --template-id / --template must be given.
 
@@ -79,6 +95,14 @@ Template (choose one):
                       the template's latest version.
   --template <v>      Inline HTML template. Either a file path / URL, or inline
                       HTML. Combine with --template-type to control reading.
+  --name <text>       Inline-form template name. REQUIRED with --template so
+                      the auto-created template carries a readable label in the
+                      owner-shell UI (and so --title can fall back to it).
+                      Rejected with --template-id (the reference form inherits
+                      the existing template's name).
+  --slug <text>       Inline-form template slug (optional). Must be unique among
+                      your templates; a collision is rejected. Rejected with
+                      --template-id.
   --event-schema <v>  Inline-form event schema. A .json file, or inline JSON.
                       Optional with --template. Omit for a view-only template
                       (a report/dashboard the human only views — no page/agent
@@ -105,7 +129,7 @@ Template (choose one):
   --input-schema <v>  Inline-form input schema. A .json file, or inline JSON.
                       Optional with --template, rejected with --template-id
                       (the schema comes from the pinned template version
-                      there). When present, the surface's --input-data is
+                      there). When present, the pane's --input-data is
                       validated against it AND any attachment ids declared at a
                       "format": "pane-attachment-id" site become reachable from the
                       page via window.pane.downloadBlob. Without it, attachment
@@ -114,10 +138,16 @@ Template (choose one):
 
 Options:
   --title <text>      Tab title shown to the human (max 80 chars, single
-                      line). Required, with one ergonomic exception: when
-                      --template-id references a named template, the relay
-                      falls back to Template.name. Inline (--template …) form
-                      always needs --title.
+                      line). Optional: when omitted, the relay falls back to
+                      the template's name — the existing Template.name for the
+                      reference form, or the --name you pass for the inline
+                      form.
+  --preamble <text>   Optional one- or two-line context message rendered in
+                      the shell band above the iframe — "who is asking, why".
+                      Max 280 chars after trim; a single \\n is allowed for a
+                      two-line message; other control chars are rejected. Pass
+                      this whenever the artifact itself doesn't make the
+                      request self-explanatory.
   --input-data <v>    This instance's seed data — a JSON object (file path or
                       inline JSON), validated by the relay against the template
                       version's input_schema. The page reads it as
@@ -125,24 +155,43 @@ Options:
   --template-type <t> "html-inline" (default) or "html-ref". With "html-ref"
                       the --template value is treated as a URL. Note: the relay
                       does not serve "html-ref" templates in this release and
-                      will reject the surface — use "html-inline".
-  --ttl <seconds>     Surface time-to-live in seconds. The relay clamps this
+                      will reject the pane — use "html-inline".
+  --ttl <seconds>     Pane time-to-live in seconds. The relay clamps this
                       to its configured MAX_TTL_SECONDS (defaults: 1 h
                       requested, 24 h max for self-host; hosted may differ).
                       The returned \`expires_at\` is the authoritative value.
   --participants <n>  Number of human participants (default 1).
   --metadata <path|json>  Arbitrary metadata object (file path or inline JSON).
   --callback <path|json>  Webhook callback config: { url, events[], secret }.
+  --context-key <key>  Natural key for "the same logical thing" — the relay
+                      dedups repeated creates with the same
+                      (template, owner, context_key) into one pane row,
+                      returning {created:false, pane_id:<existing>} on
+                      subsequent calls. Use this to make scripted creates
+                      idempotent (e.g. "pr-42", "deal-1138", "home"). Only
+                      meaningful when the calling agent is claimed by a
+                      human; omit otherwise. Allowed chars: A-Za-z0-9_:.-,
+                      max 256.
+  --icon-emoji <e>    Per-pane icon override — a single emoji grapheme. NULL/
+                      omitted = inherit the template's icon.
+  --icon-attachment-id <id>
+                      Per-pane icon override — a ready raster-image attachment
+                      (png/jpeg/webp/gif) accessible to this agent. No SVG, no
+                      URLs. Omitted = inherit the template's icon.
   --url <url>         Relay base URL (overrides PANE_URL).
   --api-key <key>     Agent API key (overrides PANE_API_KEY).
+  --json              Force JSON output even on a TTY. Default: JSON when
+                      stdout is piped; a human-readable summary (title, URL,
+                      QR code, expiry countdown) when stdout is a terminal.
   -h, --help          Show this help.
 
-Output (stdout, JSON):
-  { surface_id, urls, tokens, expires_at }
+Output:
+  - Piped (or --json): { pane_id, urls, tokens, expires_at } as JSON
+  - TTY: title + each human URL + a scannable QR code + expiry countdown
 
 Deliver urls.humans to the human(s); keep tokens.agent for the WS stream.`;
 export async function runCreate(args) {
-    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "pane surface create");
+    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "pane create");
     const artifactIdVal = args.flags.get("template-id");
     const artifactVal = args.flags.get("template");
     // Exactly one of the two template forms must be present.
@@ -164,6 +213,15 @@ export async function runCreate(args) {
         if (args.flags.get("input-schema") !== undefined) {
             fail("--input-schema is incompatible with --template-id — the input schema comes from the pinned template version. Author the schema on the template (`pane template create --input-schema …`) instead.", "invalid_args");
         }
+        // --name / --slug name the inline form's auto-created template. The
+        // reference form inherits the existing Template.name/slug, so they have
+        // no meaning here — reject rather than silently ignore.
+        if (args.flags.get("name") !== undefined) {
+            fail("--name is incompatible with --template-id — the reference form inherits the existing template's name. Use --name only with --template (inline form).", "invalid_args");
+        }
+        if (args.flags.get("slug") !== undefined) {
+            fail("--slug is incompatible with --template-id — the reference form inherits the existing template's slug. Use --slug only with --template (inline form).", "invalid_args");
+        }
         const ref = { id: artifactIdVal };
         const versionRaw = args.flags.get("version");
         if (versionRaw !== undefined) {
@@ -201,14 +259,28 @@ export async function runCreate(args) {
         catch (e) {
             fail(e instanceof Error ? e.message : String(e), "invalid_args");
         }
+        // --name is REQUIRED for the inline form: the relay names the
+        // auto-created template with it so the owner-shell UI has a readable
+        // label (the reference form inherits the existing Template.name instead).
+        // --slug is optional. Both are inline-only — they are rejected with
+        // --template-id below.
+        const nameVal = args.flags.get("name");
+        if (nameVal === undefined || nameVal === "") {
+            fail("--name is required with --template (inline form); it names the auto-created template so the UI shows a readable label", "invalid_args");
+        }
+        const slugVal = args.flags.get("slug");
         // Build the inline template object. event_schema / input_schema are
         // OMITTED entirely (not set to undefined) when their flags are absent —
         // omission is meaningful at the relay (view-only template / no input
         // contract).
         const inlineArtifact = {
+            name: nameVal,
             type: templateType,
             source,
         };
+        if (slugVal !== undefined) {
+            inlineArtifact["slug"] = slugVal;
+        }
         if (schemaVal !== undefined) {
             try {
                 inlineArtifact["event_schema"] = resolveJson(schemaVal, "--event-schema");
@@ -240,6 +312,13 @@ export async function runCreate(args) {
     if (titleRaw !== undefined) {
         candidate["title"] = titleRaw;
     }
+    // --preamble — passthrough. The relay trims, normalises CRLF, enforces
+    // ≤280 chars and rejects non-newline control chars; mirroring those
+    // checks here would just create drift on edge cases.
+    const preambleRaw = args.flags.get("preamble");
+    if (preambleRaw !== undefined) {
+        candidate["preamble"] = preambleRaw;
+    }
     // --input-data — per-instance seed data, applies to either form (the relay
     // validates it against the pinned version's input_schema).
     const inputDataRaw = args.flags.get("input-data");
@@ -283,7 +362,26 @@ export async function runCreate(args) {
             fail(e instanceof Error ? e.message : String(e), "invalid_args");
         }
     }
-    const parsed = createSessionSchema.safeParse(candidate);
+    // --context-key — natural-key dedup. Passthrough; the relay enforces
+    // length + charset (createPaneSchema in @paneui/core), so an invalid
+    // value panes as a schema rejection on the call below rather than
+    // a duplicated client-side guard that could drift.
+    const contextKey = args.flags.get("context-key");
+    if (contextKey !== undefined) {
+        candidate["context_key"] = contextKey;
+    }
+    // Per-pane icon override. Passthrough — the relay validates the emoji
+    // (single grapheme) and the attachment (ready raster image, accessible to
+    // the agent), so a bad value panes as a schema/route rejection rather than
+    // a duplicated client guard.
+    const iconEmoji = args.flags.get("icon-emoji");
+    if (iconEmoji !== undefined)
+        candidate["icon_emoji"] = iconEmoji;
+    const iconAttachmentId = args.flags.get("icon-attachment-id");
+    if (iconAttachmentId !== undefined) {
+        candidate["icon_attachment_id"] = iconAttachmentId;
+    }
+    const parsed = createPaneSchema.safeParse(candidate);
     if (!parsed.success) {
         const issue = parsed.error.issues[0];
         const where = issue && issue.path.length > 0 ? schemaPathToFlag(issue.path) : "request";
@@ -292,8 +390,21 @@ export async function runCreate(args) {
     const req = parsed.data;
     const client = makeClient(args);
     try {
-        const res = await client.createSession(req);
-        printJson(res);
+        const res = await client.createPane(req);
+        // Output mode:
+        //   --json explicit         → JSON
+        //   stdout NOT a TTY (pipe) → JSON (so scripts / agents stay parseable)
+        //   stdout IS a TTY         → human-readable (URL + QR + countdown)
+        // The TTY check matches the existing `pane taste` / `pane feedback`
+        // pattern: agents are non-interactive, humans are.
+        const forceJson = args.bools.has("json");
+        const isTty = Boolean(process.stdout.isTTY);
+        if (forceJson || !isTty) {
+            printJson(res);
+        }
+        else {
+            process.stdout.write(formatPaneCreated(res, { color: isTty }));
+        }
     }
     catch (e) {
         failFromError(e);

package/dist/commands/delete.js

@@ -1,16 +1,16 @@
-// `pane surface delete <id>` — close/delete a surface.
+// `pane delete <id>` — close/delete a pane.
 import { assertKnownFlags } from "../argv.js";
 import { makeClient } from "../config.js";
 import { printJson, fail, failFromError } from "../output.js";
 const KNOWN_FLAGS = [];
 const KNOWN_BOOLS = [];
-export const deleteHelp = `pane surface delete — close/delete a surface
+export const deleteHelp = `pane delete — close/delete a pane
 
 Usage:
-  pane surface delete <surface-id> [options]
+  pane delete <pane-id> [options]
 
-Closes and deletes the surface (DELETE /v1/surfaces/:id). Idempotent on the
-relay side — deleting an already-closed surface still succeeds.
+Closes and deletes the pane (DELETE /v1/panes/:id). Idempotent on the
+relay side — deleting an already-closed pane still succeeds.
 
 Options:
   --url <url>         Relay base URL (overrides PANE_URL).
@@ -18,16 +18,16 @@ Options:
   -h, --help          Show this help.
 
 Output (stdout, JSON):
-  { surface_id, deleted: true }`;
+  { pane_id, deleted: true }`;
 export async function runDelete(args) {
-    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "pane surface delete");
-    const surfaceId = args.positionals[0];
-    if (!surfaceId)
-        fail("missing <surface-id>", "invalid_args");
+    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "pane delete");
+    const paneId = args.positionals[0];
+    if (!paneId)
+        fail("missing <pane-id>", "invalid_args");
     const client = makeClient(args);
     try {
-        await client.deleteSession(surfaceId);
-        printJson({ surface_id: surfaceId, deleted: true });
+        await client.deletePane(paneId);
+        printJson({ pane_id: paneId, deleted: true });
     }
     catch (e) {
         failFromError(e);

package/dist/commands/feedback.js

@@ -1,7 +1,7 @@
 import { assertKnownFlags } from "../argv.js";
 import { makeClient } from "../config.js";
 import { printJson, fail, failFromError } from "../output.js";
-const CREATE_FLAGS = ["type", "message", "surface-id"];
+const CREATE_FLAGS = ["type", "message", "pane-id"];
 const LIST_FLAGS = ["limit", "before"];
 const NO_BOOLS = [];
 export const feedbackHelp = `pane feedback — submit / list feedback to the relay operator
@@ -25,7 +25,7 @@ Options for 'create':
   --type <bug|feature|note>   Feedback category. Required.
   --message <text|->          Message body. Pass '-' to read from stdin.
                               1..4000 chars after trim.
-  --surface-id <id>           Optional surface this feedback relates to;
+  --pane-id <id>           Optional pane this feedback relates to;
                               must belong to YOUR agent.
 
 Options for 'list':
@@ -38,7 +38,7 @@ Global:
   -h, --help                  Show this help.
 
 Examples:
-  pane feedback create --type bug --message "watch hangs on empty surface"
+  pane feedback create --type bug --message "watch hangs on empty pane"
   echo "long-form note..." | pane feedback create --type note --message -
   pane feedback list --limit 20
 
@@ -55,7 +55,7 @@ async function runFeedbackCreate(args) {
     assertKnownFlags(args, CREATE_FLAGS, NO_BOOLS, "pane feedback create");
     const type = args.flags.get("type");
     const rawMessage = args.flags.get("message");
-    const surfaceId = args.flags.get("surface-id");
+    const paneId = args.flags.get("pane-id");
     if (type === undefined) {
         fail("'pane feedback create' requires --type <bug|feature|note>", "invalid_args");
     }
@@ -83,7 +83,7 @@ async function runFeedbackCreate(args) {
         const res = await client.submitFeedback({
             type: type,
             message,
-            ...(surfaceId !== undefined ? { surfaceId } : {}),
+            ...(paneId !== undefined ? { paneId } : {}),
         });
         printJson(res);
     }

package/dist/commands/list.js

@@ -1,23 +1,23 @@
-// `pane surface list` — enumerate YOUR agent's surfaces.
+// `pane list` — enumerate YOUR agent's panes.
 //
 // The recovery primitive when the create-response was dropped: the URL itself
 // is unrecoverable (the relay stores only the token hash), but every other
-// field of the surface is intact and listable here. Pair with
-// `pane surface participant new` to mint a fresh URL on a surface whose
+// field of the pane is intact and listable here. Pair with
+// `pane participant new` to mint a fresh URL on a pane whose
 // original was lost.
 import { assertKnownFlags } from "../argv.js";
 import { makeClient } from "../config.js";
 import { printJson, fail, failFromError } from "../output.js";
 const KNOWN_FLAGS = ["status", "limit", "cursor", "template-id"];
 const KNOWN_BOOLS = [];
-export const listHelp = `pane surface list — list YOUR agent's surfaces
+export const listHelp = `pane list — list YOUR agent's panes
 
-Prints surfaces (newest first) with no secrets in the response. Participant
-tokens are stored hashed and CANNOT be recovered — if you lost a surface URL,
-mint a fresh one with 'pane surface participant new <surface-id>'.
+Prints panes (newest first) with no secrets in the response. Participant
+tokens are stored hashed and CANNOT be recovered — if you lost a pane URL,
+mint a fresh one with 'pane participant new <pane-id>'.
 
 Usage:
-  pane surface list [options]
+  pane list [options]
 
 Options:
   --status <s>      open | closed | all. Default: open. The status reported
@@ -25,7 +25,7 @@ Options:
                     is reported as 'closed' even if not yet swept.
   --limit <N>       Page size (default 50, max 200).
   --cursor <c>      Opaque cursor from a previous page's next_cursor.
-  --template-id <i> Filter to surfaces instantiated from a specific named
+  --template-id <i> Filter to panes instantiated from a specific named
                     template (head id; not version id). Inline (anonymous)
                     templates cannot be filtered this way — they have no
                     stable handle.
@@ -33,20 +33,20 @@ Options:
   --api-key <key>   Agent API key (overrides PANE_API_KEY).
   -h, --help        Show this help.
 
-Recovery recipe (lost the URL but the surface is still alive):
-  pane surface list                                       # find the
-                                                          #   surface_id +
+Recovery recipe (lost the URL but the pane is still alive):
+  pane list                                       # find the
+                                                          #   pane_id +
                                                           #   participant_id
                                                           #   you lost
-  pane surface participant new <surface-id>               # mint a fresh URL
-  pane surface participant revoke <surface-id> <p-id>     # invalidate the
+  pane participant new <pane-id>               # mint a fresh URL
+  pane participant revoke <pane-id> <p-id>     # invalidate the
                                                           #   old URL
 
 Output (stdout, JSON):
   {
     items: [
       {
-        surface_id, title, status, template_id, template_version_id,
+        pane_id, title, status, template_id, template_version_id,
         template_version, participants: [...], created_at, expires_at,
         has_callback
       },
@@ -56,7 +56,7 @@ Output (stdout, JSON):
   }`;
 const STATUSES = ["open", "closed", "all"];
 export async function runList(args) {
-    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "pane surface list");
+    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "pane list");
     const opts = {};
     const status = args.flags.get("status");
     if (status !== undefined) {
@@ -82,7 +82,7 @@ export async function runList(args) {
     }
     const client = makeClient(args);
     try {
-        const page = await client.listSessions(opts);
+        const page = await client.listPanes(opts);
         printJson(page);
     }
     catch (e) {

package/dist/commands/logout.js

@@ -1,29 +1,59 @@
-// `pane agent logout` — clear the locally-saved relay URL + API key.
+// `pane agent logout` — clear one (or all) saved profile(s).
 import { assertKnownFlags } from "../argv.js";
-import { clearStore } from "../store.js";
-import { printJson } from "../output.js";
+import { clearStore, readStore, removeProfile, resolveProfile, } from "../store.js";
+import { printJson, fail } from "../output.js";
 const NO_FLAGS = [];
-const NO_BOOLS = [];
-export const logoutHelp = `pane agent logout — clear the saved relay URL + API key
+const KNOWN_BOOLS = ["all"];
+export const logoutHelp = `pane agent logout — clear a saved profile (or all of them)
 
 Usage:
   pane agent logout [options]
 
-Deletes the CLI config file (\${XDG_CONFIG_HOME:-~/.config}/pane/config.json),
-which holds the relay URL and the agent API key saved by 'pane agent register'.
-Idempotent — no error if there is nothing to clear.
+By default this clears the ACTIVE profile only (the one selected by --profile
+/ PANE_PROFILE / the store's current_profile). The on-disk file keeps the
+other profiles, and 'current_profile' is unset so the next command falls back
+to env / default URL until another profile is selected.
+
+Pass --all to delete the whole config file (the pre-profile behaviour) — this
+wipes every profile, not just the active one. Idempotent — no error if there
+is nothing to clear.
 
 This only clears the LOCAL config. It does NOT revoke the key on the relay —
-the key keeps working until it is revoked. To revoke it on the relay, use
+keys keep working until revoked. To revoke a key server-side, use
 'pane key revoke'.
 
 Options:
+  --profile <name>    Target this profile instead of the active one.
+  --all               Delete every profile (the whole config file).
   -h, --help          Show this help.
 
 Output (stdout, JSON):
-  { cleared: true, path }`;
+  { cleared: true, profile, path }   (profile=null when --all)`;
 export async function runLogout(args) {
-    assertKnownFlags(args, NO_FLAGS, NO_BOOLS, "pane agent logout");
-    const path = clearStore();
-    printJson({ cleared: true, path });
+    assertKnownFlags(args, NO_FLAGS, KNOWN_BOOLS, "pane agent logout");
+    if (args.bools.has("all")) {
+        // Nuke everything — file gone, both legacy and new shape covered.
+        const path = clearStore();
+        printJson({ cleared: true, profile: null, path });
+        return;
+    }
+    const store = readStore();
+    const selector = args.flags.get("profile") ?? process.env.PANE_PROFILE;
+    let target;
+    try {
+        target = resolveProfile(store, selector);
+    }
+    catch (e) {
+        fail(e instanceof Error ? e.message : String(e), "config_error");
+    }
+    // Nothing to clear: empty store or legacy file with no migrate yet.
+    if (!target) {
+        // If there's literally nothing saved, mirror the legacy idempotent
+        // behaviour — delete the file (no-op if absent) and report cleared.
+        const path = clearStore();
+        printJson({ cleared: true, profile: null, path });
+        return;
+    }
+    const { path } = removeProfile(target.name);
+    printJson({ cleared: true, profile: target.name, path });
 }