@paneui/cli 0.0.9 → 0.0.11

package/README.md

@@ -34,11 +34,11 @@ Uniform `pane <noun> <verb> [options]`:
 ```
 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 create            Create a pane — returns pane_id, urls, tokens
+pane show <id>         Non-blocking snapshot: metadata + event log
+pane send <id>         Emit an agent event into a pane
+pane watch <id>        Stream a pane's events as JSON-lines on stdout
+pane delete <id>       Close / delete a pane
 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
@@ -56,12 +56,12 @@ stdout is machine-readable JSON. Errors go to stderr as
 `{"error":{"code","message"}}` with a non-zero exit.
 
 ```sh
-SESSION=$(pane surface create --template form --schema ./q.json | jq -r .surface_id)
-pane surface watch "$SESSION" | jq 'select(.type == "human_response")'
+SESSION=$(pane create --template ./form.html --name "Quick poll" --event-schema ./q.json | jq -r .pane_id)
+pane watch "$SESSION" | jq 'select(.type == "human_response")'
 ```
 
 ## Links
 
 - Repo: <https://github.com/aerolalit/paneui>
-- Spec: <https://github.com/aerolalit/paneui/attachment/main/docs/SPEC.md>
+- Spec: <https://github.com/aerolalit/paneui/blob/main/docs/SPEC.md>
 - License: MIT

package/dist/argv.js

@@ -89,7 +89,7 @@ export function parseArgs(tokens, booleanFlags) {
  * 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_FLAGS = ["url", "api-key", "profile"];
 const GLOBAL_BOOLS = ["help", "json"];
 /**
  * Reject anything the per-command allow-list (plus the globals above) does
@@ -104,7 +104,7 @@ const GLOBAL_BOOLS = ["help", "json"];
  *
  * 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
+ * known name there panes as "--name requires a value". This is what
  * keeps the error message uniform for a typo whether or not a value
  * follows it.
  */
@@ -129,7 +129,7 @@ export function assertKnownFlags(args, knownFlags, knownBools, helpCommand) {
         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
+    // a value. Pane 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) {

package/dist/commands/agent.js

@@ -10,6 +10,7 @@
 import { runRegister } from "./register.js";
 import { runLogout } from "./logout.js";
 import { runClaim } from "./claim.js";
+import { runSetKey } from "./set-key.js";
 import { fail } from "../output.js";
 export const agentHelp = `pane agent — manage this agent's identity on the relay
 
@@ -22,6 +23,10 @@ Verbs:
   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.
+  set-key <key>     Save a new API key into the CLI config file. Used after
+                    regenerating the agent's key in the relay's My-agents UI:
+                    the human pastes the new key here so subsequent commands
+                    authenticate as the same agent.
   logout            Clear the locally-saved relay URL + API key. Does NOT
                     revoke the key on the relay — use 'pane key revoke' for
                     that.
@@ -42,13 +47,16 @@ export async function runAgent(args) {
         case "claim":
             await runClaim(verbArgs);
             break;
+        case "set-key":
+            await runSetKey(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");
+            fail("missing verb — usage: pane agent <register|claim|set-key|logout> (run 'pane agent --help')", "invalid_args");
             break;
         default:
-            fail(`unknown agent verb '${verb}' — expected register|claim|logout (run 'pane agent --help')`, "invalid_args");
+            fail(`unknown agent verb '${verb}' — expected register|claim|set-key|logout (run 'pane agent --help')`, "invalid_args");
     }
 }

package/dist/commands/attachment-token.js

@@ -10,7 +10,7 @@
 // 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`.
+// pane participant`.
 import { assertKnownFlags } from "../argv.js";
 import { makeClient } from "../config.js";
 import { fail, failFromError, printJson } from "../output.js";
@@ -31,7 +31,7 @@ Usage:
 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
+                          30d template / pane TTL / 24h agent; the caller
                           can only shorten), --once (token self-deletes on
                           first successful GET). Returns { token, url,
                           expires_at, ... } — ONCE.

package/dist/commands/attachment-upload.js

@@ -7,7 +7,7 @@ import { fail, failFromError, printJson } from "../output.js";
 const KNOWN_FLAGS = [
     "file",
     "scope",
-    "surface-id",
+    "pane-id",
     "template-id",
     "filename",
     "mime",
@@ -22,8 +22,8 @@ Required:
   --file <path>          Local file to upload.
 
 Scope (default: agent):
-  --scope <s>            "agent" | "surface" | "template".
-  --surface-id <id>      Required when --scope=surface.
+  --scope <s>            "agent" | "pane" | "template".
+  --pane-id <id>      Required when --scope=pane.
   --template-id <id>     Required when --scope=template.
 
 Optional:
@@ -50,14 +50,12 @@ export async function runBlobUpload(args) {
         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");
+    if (scopeRaw !== "agent" && scopeRaw !== "pane" && scopeRaw !== "template") {
+        fail(`unknown --scope '${scopeRaw}' — expected one of: agent, pane, 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 === "pane" && !args.flags.get("pane-id")) {
+        fail("--scope=pane requires --pane-id <id>", "invalid_args");
     }
     if (scope === "template" && !args.flags.get("template-id")) {
         fail("--scope=template requires --template-id <id>", "invalid_args");
@@ -66,7 +64,7 @@ export async function runBlobUpload(args) {
     try {
         const ref = await client.uploadBlob(bytes, {
             scope,
-            surfaceId: args.flags.get("surface-id"),
+            paneId: args.flags.get("pane-id"),
             templateId: args.flags.get("template-id"),
             filename: args.flags.get("filename") ?? basename(filePath),
             mime: args.flags.get("mime"),

package/dist/commands/attachment.js

@@ -1,7 +1,7 @@
 // `pane attachment` — manage binary attachments (attachments) on the relay.
 //
 // A attachment is a typed binary file (image, PDF, audio, video, etc.) owned by an
-// agent and optionally bound to a surface or template. Pages reference attachments
+// agent and optionally bound to a pane or template. Pages reference attachments
 // by id with `format: pane-attachment-id`; participants can fetch a attachment through a
 // minted capability URL (/b/<token>) without needing the agent's API key.
 //
@@ -24,8 +24,8 @@ export const blobHelp = `pane attachment — manage attachments (binary attachme
 A attachment is a typed binary file (image, PDF, audio, video, ...) the agent has
 uploaded to the relay. Blobs are scoped:
 
-  agent     — reusable across the agent's surfaces (default)
-  surface   — bound to one surface; deleted with it
+  agent     — reusable across the agent's panes (default)
+  pane   — bound to one pane; deleted with it
   template  — bound to a reusable template; deleted with it
 
 Pages reference attachments by id (the relay's schema validates the id with
@@ -37,7 +37,7 @@ Usage:
 
 Verbs:
   upload                 Upload a local file. Required: --file. Optional:
-                         --scope, --surface-id, --template-id, --filename,
+                         --scope, --pane-id, --template-id, --filename,
                          --mime. Prints { attachment_id, scope, mime, size, sha256,
                          ... }.
 
@@ -66,12 +66,12 @@ Output: stdout is machine-readable JSON. Errors go to stderr as
  * Build a new ParsedArgs with the leading positional (the verb) stripped.
  * The downstream verb runners read their primary positional (the attachment_id)
  * at positionals[0], so we hand them an args object that looks exactly like
- * they were called directly — mirrors surface.ts's shiftPositionals.
+ * they were called directly — mirrors pane.ts's shiftPositionals.
  */
 function shiftPositionals(args) {
     // Propagate danglingValueFlags so the leaf runner's assertKnownFlags
     // can still distinguish "unknown flag" from "missing value" — see the
-    // matching note in surface.ts's shiftPositionals.
+    // matching note in pane.ts's shiftPositionals.
     const out = {
         positionals: args.positionals.slice(1),
         flags: args.flags,
@@ -95,7 +95,7 @@ export async function runBlob(args) {
         return;
     }
     // `pane attachment list --help` — same pattern (list takes no required positional
-    // so the general pre-empt would already fire, but for parity with surface.ts
+    // so the general pre-empt would already fire, but for parity with pane.ts
     // we route through here when args carry the "list" positional explicitly).
     if (verb === "list" &&
         args.bools.has("help") &&

package/dist/commands/claim.js

@@ -7,7 +7,7 @@
 //   2. Alice hands the code to the agent out-of-band (this CLI invocation
 //      is exactly that handoff).
 //   3. CLI calls POST /v1/agents/claim with the calling agent's API key.
-//   4. Relay binds Agent.ownerHumanId = alice.id, migrates surface ownership.
+//   4. Relay binds Agent.ownerHumanId = alice.id, migrates pane ownership.
 //
 // The CLI does NOT print the human's email or id — only the relay's response,
 // which is { ok, owner_human_id, claimed_at }. The agent's existing API key

package/dist/commands/config.js

@@ -1,50 +1,262 @@
-// `pane config show` — show the resolved relay config without a network call.
+// `pane config <verb>` — inspect and manage the multi-profile CLI config.
+//
+//   show              describe the resolved (url, api_key) the CLI would use
+//   list              list saved profiles (names + URLs + current marker)
+//   use <name>        switch the active profile
+//   add <name>        manually add a profile (for keys obtained out of band)
+//   rm <name>         delete a profile
+//
+// All four mutating verbs operate on the multi-profile store at
+// $XDG_CONFIG_HOME/pane/config.json. See store.ts for the layout. They make
+// NO network calls — purely local config management.
 import { assertKnownFlags } from "../argv.js";
 import { describeConfig } from "../config.js";
+import { isValidProfileName, readStore, removeProfile, setCurrentProfile, storePath, upsertProfile, } from "../store.js";
 import { printJson, fail } from "../output.js";
-const NO_FLAGS = [];
-const NO_BOOLS = [];
-export const configHelp = `pane config — show the resolved relay config
+const SHOW_FLAGS = [];
+const SHOW_BOOLS = [];
+const LIST_FLAGS = [];
+const LIST_BOOLS = [];
+const USE_FLAGS = [];
+const USE_BOOLS = [];
+const ADD_FLAGS = ["api-key"];
+const ADD_BOOLS = [];
+const RM_FLAGS = [];
+const RM_BOOLS = [];
+export const configHelp = `pane config — show and manage the CLI config (multi-profile)
+
+Usage:
+  pane config show                      Show the resolved relay config
+  pane config list                      List saved profiles
+  pane config use <profile>             Switch the active profile
+  pane config add <profile> --url <u> --api-key <k>
+                                        Add a profile manually
+  pane config rm <profile>              Delete a profile
+
+A profile is one (url, api_key) pair under a short name (dev, staging, prod).
+Switch via 'pane config use', '--profile <name>', or the PANE_PROFILE env var.
+The active profile's (url, api_key) is what every other command sees unless
+overridden by --url / --api-key or PANE_URL / PANE_API_KEY.
+
+Run \`pane config <verb> --help\` for verb-specific help. The full API key is
+never printed; only a short masked prefix.
+
+The config file lives at \${XDG_CONFIG_HOME:-~/.config}/pane/config.json
+(mode 0600).`;
+const showHelp = `pane config show — show the resolved relay config
 
 Usage:
   pane config show [options]
 
-Verbs:
-  show                Print the relay URL and API-key info the CLI would use,
-                      and where each value came from. Makes NO network call —
-                      purely inspects flags, env vars, and the saved config
-                      file.
+Reports the (url, api_key) the CLI would use right now, and where each value
+came from (flag / env / profile / none). Purely inspects flags + env + the
+saved config file; makes NO network call.
 
-The API key is never printed in full: only a short masked prefix.
+The API key is never printed in full — only a short masked prefix.
 
 Options:
   --url <url>         Relay base URL (overrides PANE_URL) — affects the report.
-  --api-key <key>     Agent API key (overrides PANE_API_KEY) — affects the
-                      report.
+  --api-key <key>     Agent API key (overrides PANE_API_KEY) — affects the report.
+  --profile <name>    Profile to resolve against — affects the report.
+  -h, --help          Show this help.
+
+Output (stdout, JSON):
+  {
+    url, url_source,        flag | env | profile | none
+    key_prefix, key_source, flag | env | profile | none
+    profile, profile_source,  active profile name + how it was chosen
+    config_path
+  }`;
+const listHelp = `pane config list — list saved profiles
+
+Usage:
+  pane config list [options]
+
+Prints every profile in the local config file, with its URL and a masked
+key prefix. The active profile carries 'current: true'.
+
+Options:
   -h, --help          Show this help.
 
 Output (stdout, JSON):
   {
-    url,            relay base URL, or null if unset
-    url_source,     "flag" | "env" | "store" | "none"
-    key_prefix,     first ~10 chars of the API key + "…", or null
-    key_source,     "flag" | "env" | "store" | "none"
-    config_path     absolute path to the CLI config file
+    current: <name|null>,
+    profiles: [ { name, url, key_prefix, current }, … ],
+    config_path
   }`;
+const useHelp = `pane config use <profile> — switch the active profile
+
+Usage:
+  pane config use <profile>
+
+Sets 'current_profile' in the config file. The named profile must exist
+(create it first with 'pane agent register --profile <name>' or
+'pane config add <name>').
+
+Options:
+  -h, --help          Show this help.
+
+Output (stdout, JSON):
+  { profile, saved_to }`;
+const addHelp = `pane config add <profile> — add a profile manually
+
+Usage:
+  pane config add <profile> --url <url> --api-key <api-key>
+
+Saves a (url, api_key) pair under <profile> without contacting the relay.
+Use this when an operator handed you an API key out of band (e.g. a closed-
+registration relay) — for self-register and secret-mode relays, prefer
+'pane agent register --profile <name>'.
+
+If <profile> already exists, the existing values are overwritten.
+
+Options:
+  --url <url>         Relay base URL.            REQUIRED.
+  --api-key <key>     Agent API key.             REQUIRED.
+  -h, --help          Show this help.
+
+Output (stdout, JSON):
+  { profile, saved_to }
+
+Does NOT change 'current_profile' unless this is the first profile being
+added. Use 'pane config use' afterwards to switch.`;
+const rmHelp = `pane config rm <profile> — delete a profile
+
+Usage:
+  pane config rm <profile>
+
+Removes the named profile from the config file. If it was the active profile,
+'current_profile' is cleared (the next command falls back to env / default
+URL until another profile is selected via --profile or 'pane config use').
+
+Options:
+  -h, --help          Show this help.
+
+Output (stdout, JSON):
+  { profile, was_current, path }`;
 async function runConfigShow(args) {
-    assertKnownFlags(args, NO_FLAGS, NO_BOOLS, "pane config show");
+    assertKnownFlags(args, SHOW_FLAGS, SHOW_BOOLS, "pane config show");
     printJson(describeConfig(args));
 }
+function maskKey(key) {
+    if (!key)
+        return null;
+    if (key.startsWith("pane_") && key.length >= 11)
+        return key.slice(0, 11) + "…";
+    return key.slice(0, 8) + "…";
+}
+async function runConfigList(args) {
+    assertKnownFlags(args, LIST_FLAGS, LIST_BOOLS, "pane config list");
+    const store = readStore();
+    const profiles = Object.entries(store.profiles)
+        .map(([name, p]) => ({
+        name,
+        url: p.url ?? null,
+        key_prefix: maskKey(p.apiKey),
+        current: name === store.currentProfile,
+    }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+    printJson({
+        current: store.currentProfile ?? null,
+        profiles,
+        config_path: storePath(),
+    });
+}
+async function runConfigUse(args) {
+    assertKnownFlags(args, USE_FLAGS, USE_BOOLS, "pane config use");
+    const name = args.positionals[1];
+    if (!name) {
+        fail("missing profile name — usage: pane config use <profile>", "invalid_args");
+    }
+    let savedTo;
+    try {
+        savedTo = setCurrentProfile(name);
+    }
+    catch (e) {
+        fail(e instanceof Error ? e.message : String(e), "config_error");
+    }
+    printJson({ profile: name, saved_to: savedTo });
+}
+async function runConfigAdd(args) {
+    assertKnownFlags(args, ADD_FLAGS, ADD_BOOLS, "pane config add");
+    const name = args.positionals[1];
+    if (!name) {
+        fail("missing profile name — usage: pane config add <profile> --url <url> --api-key <key>", "invalid_args");
+    }
+    if (!isValidProfileName(name)) {
+        fail(`invalid profile name '${name}' — letters, digits, _ and -, up to 32 chars`, "invalid_args");
+    }
+    const url = args.flags.get("url");
+    const apiKey = args.flags.get("api-key");
+    if (!url) {
+        fail("--url is required — usage: pane config add <profile> --url <url> --api-key <key>", "invalid_args");
+    }
+    if (!apiKey) {
+        fail("--api-key is required — usage: pane config add <profile> --url <url> --api-key <key>", "invalid_args");
+    }
+    // setCurrent=false: adding a profile shouldn't silently switch the user
+    // off whatever they were on. They use `pane config use` after to flip.
+    // EXCEPT: if there's no current profile yet (first add), upsertProfile
+    // sets it automatically — that's the correct fresh-install behaviour.
+    const savedTo = upsertProfile(name, { url: url.replace(/\/$/, ""), apiKey }, false);
+    printJson({ profile: name, saved_to: savedTo });
+}
+async function runConfigRm(args) {
+    assertKnownFlags(args, RM_FLAGS, RM_BOOLS, "pane config rm");
+    const name = args.positionals[1];
+    if (!name) {
+        fail("missing profile name — usage: pane config rm <profile>", "invalid_args");
+    }
+    let result;
+    try {
+        result = removeProfile(name);
+    }
+    catch (e) {
+        fail(e instanceof Error ? e.message : String(e), "config_error");
+    }
+    printJson({
+        profile: name,
+        was_current: result.was_current,
+        path: result.path,
+    });
+}
 export async function runConfig(args) {
     const verb = args.positionals[0];
+    // Per-verb --help: 'pane config show --help' etc. Caught before dispatch
+    // so each runner doesn't need to repeat the check.
+    if (args.bools.has("help") && verb !== undefined) {
+        const helps = {
+            show: showHelp,
+            list: listHelp,
+            use: useHelp,
+            add: addHelp,
+            rm: rmHelp,
+        };
+        if (helps[verb] !== undefined) {
+            process.stdout.write(helps[verb] + "\n");
+            return;
+        }
+    }
     switch (verb) {
         case "show":
             await runConfigShow(args);
             break;
+        case "list":
+            await runConfigList(args);
+            break;
+        case "use":
+            await runConfigUse(args);
+            break;
+        case "add":
+            await runConfigAdd(args);
+            break;
+        case "rm":
+            await runConfigRm(args);
+            break;
         case undefined:
-            fail("missing verb — usage: pane config show (run 'pane config --help')", "invalid_args");
+            fail("missing verb — usage: pane config <show|list|use|add|rm> (run 'pane config --help')", "invalid_args");
             break;
         default:
-            fail(`unknown config verb '${verb}' — expected show (run 'pane config --help')`, "invalid_args");
+            fail(`unknown config verb '${verb}' — expected show|list|use|add|rm (run 'pane config --help')`, "invalid_args");
     }
 }