@paneui/cli 0.0.9 → 0.0.10

package/dist/config.js

@@ -1,16 +1,65 @@
 // Relay connection config: PANE_URL / PANE_API_KEY from the environment,
-// overridable per-invocation with --url / --api-key.
+// overridable per-invocation with --url / --api-key. Profile selection via
+// --profile / PANE_PROFILE picks WHICH (url, api_key) pair to load from
+// the saved store. See store.ts for the on-disk layout.
 import { PaneClient } from "@paneui/core";
 import { fail } from "./output.js";
-import { readStore, storePath } from "./store.js";
+import { readStore, resolveProfile, storePath } from "./store.js";
 import { VERSION } from "./version.js";
+/**
+ * The hosted Pane relay. Used as the relay-URL fallback so a fresh user only
+ * 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";
+/**
+ * Pick the profile-selector source — explicit flag wins over env, env wins
+ * over the store's `current_profile`. Returns both the selector value and
+ * where it came from so `describeConfig` can report it.
+ */
+function pickProfileSelector(args) {
+    const flag = args.flags.get("profile");
+    if (flag !== undefined && flag !== "") {
+        return { selector: flag, source: "flag" };
+    }
+    const env = process.env.PANE_PROFILE;
+    if (env !== undefined && env !== "") {
+        return { selector: env, source: "env" };
+    }
+    return { selector: undefined, source: "none" };
+}
 /**
  * Resolve url + apiKey and report the SOURCE of each, WITHOUT making a network
  * call and WITHOUT failing on a missing value (unlike `resolveConfig`). The
  * full API key is never returned — only a short, masked prefix.
+ *
+ * Resolution model:
+ *   - `--url` / `PANE_URL` and `--api-key` / `PANE_API_KEY` are DIRECT values:
+ *     they override everything, including any active profile. CI scripts that
+ *     set those env vars never need to think about profiles.
+ *   - Otherwise the profile selector (`--profile` flag → `PANE_PROFILE` env →
+ *     store's `current_profile`) picks one profile out of the store; the
+ *     selected profile's `url` and `api_key` are used.
+ *   - Final fallback for URL is `DEFAULT_RELAY_URL`.
  */
 export function describeConfig(args) {
     const store = readStore();
+    const { selector, source: selectorSource } = pickProfileSelector(args);
+    // The store gets visited only if --profile flag is set (explicit
+    // selector) and the store has a matching profile, OR the store has a
+    // current_profile and no explicit selector overrides it. `resolveProfile`
+    // throws on a typo'd selector; we swallow that here so describeConfig
+    // can't crash a `pane config show` — resolveConfig() is the one that
+    // surfaces the error when the caller actually needs a key.
+    let active;
+    try {
+        active = resolveProfile(store, selector);
+    }
+    catch {
+        active = null;
+    }
+    // URL precedence: --url flag > PANE_URL env > active profile's url.
+    // The default URL is shown only when nothing else is set.
     let url = null;
     let urlSource = "none";
     if (args.flags.get("url")) {
@@ -21,10 +70,11 @@ export function describeConfig(args) {
         url = process.env.PANE_URL;
         urlSource = "env";
     }
-    else if (store.url) {
-        url = store.url;
-        urlSource = "store";
+    else if (active && active.profile.url) {
+        url = active.profile.url;
+        urlSource = "profile";
     }
+    // API key precedence: --api-key flag > PANE_API_KEY env > active profile's api_key.
     let apiKey = null;
     let keySource = "none";
     if (args.flags.get("api-key")) {
@@ -35,37 +85,46 @@ export function describeConfig(args) {
         apiKey = process.env.PANE_API_KEY;
         keySource = "env";
     }
-    else if (store.apiKey) {
-        apiKey = store.apiKey;
-        keySource = "store";
+    else if (active && active.profile.apiKey) {
+        apiKey = active.profile.apiKey;
+        keySource = "profile";
     }
     return {
         url: url ? url.replace(/\/$/, "") : null,
         url_source: urlSource,
         key_prefix: apiKey ? apiKey.slice(0, 10) + "…" : null,
         key_source: keySource,
+        profile: active ? active.name : null,
+        profile_source: selectorSource,
         config_path: storePath(),
     };
 }
-/**
- * The hosted Pane relay. Used as the relay-URL fallback so a fresh user only
- * 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 agent register`, so later commands need no env vars.
+ *   url:    --url flag  → PANE_URL env  → active profile's url   → DEFAULT_RELAY_URL
+ *   apiKey: --api-key   → PANE_API_KEY  → active profile's api_key
+ * "Active profile" is chosen by `--profile` / `PANE_PROFILE` / the store's
+ * `current_profile`. A typo'd `--profile dev` fails fast with `config_error`
+ * — we never silently fall back to a different relay.
  */
 export function resolveConfig(args) {
     const store = readStore();
+    const { selector } = pickProfileSelector(args);
+    let active;
+    try {
+        active = resolveProfile(store, selector);
+    }
+    catch (e) {
+        fail(e instanceof Error ? e.message : String(e), "config_error");
+    }
     const url = args.flags.get("url") ??
         process.env.PANE_URL ??
-        store.url ??
+        active?.profile.url ??
         DEFAULT_RELAY_URL;
-    const apiKey = args.flags.get("api-key") ?? process.env.PANE_API_KEY ?? store.apiKey ?? "";
+    const apiKey = args.flags.get("api-key") ??
+        process.env.PANE_API_KEY ??
+        active?.profile.apiKey ??
+        "";
     if (!apiKey) {
         fail("missing API key: set PANE_API_KEY, pass --api-key <key>, or run 'pane agent register'", "config_error");
     }
@@ -90,9 +149,17 @@ export function makeClient(args) {
  */
 export function resolveRelayUrl(args) {
     const store = readStore();
+    const { selector } = pickProfileSelector(args);
+    let active;
+    try {
+        active = resolveProfile(store, selector);
+    }
+    catch (e) {
+        fail(e instanceof Error ? e.message : String(e), "config_error");
+    }
     const url = args.flags.get("url") ??
         process.env.PANE_URL ??
-        store.url ??
+        active?.profile.url ??
         DEFAULT_RELAY_URL;
     return url.replace(/\/$/, "");
 }

package/dist/format.js

@@ -0,0 +1,133 @@
+// Human-readable formatter for `pane create` output.
+//
+// The CLI is JSON-first — that's how agents call it. But humans run it too:
+// the agent dev iterating on a template, the operator smoke-testing a relay,
+// the developer who fires `pane create` once a day to grab a URL and hand
+// it to themselves on their phone. Dumping `{ pane_id, urls, tokens, ... }`
+// at them is a downgrade in every case where the next step is "open the
+// URL in a browser".
+//
+// In a TTY (and without `--json` on the CLI), this module renders:
+//   - the title prominently
+//   - each human URL on its own line, copy-friendly
+//   - a QR code for the first human URL, scannable from a phone
+//   - the expiry as a countdown ("in 1h 0m") + ISO timestamp
+//   - the agent stream URL on a dim line (less important for humans)
+//
+// Trust boundary: every interpolated value is a server response or a string
+// the caller asked us to render. No HTML escaping needed — terminal output.
+// We DO neutralise stray ANSI escape characters (a malicious title could
+// otherwise inject colour codes); see stripAnsi.
+import qrcode from "qrcode-terminal";
+/** ANSI helpers. Only applied when writing to a TTY; harmless characters
+ *  otherwise. We deliberately don't pull in a colour library — the CLI has
+ *  one runtime dep today (qrcode-terminal) and we'd like to keep the
+ *  pane area tight. */
+const ANSI = {
+    reset: "\x1b[0m",
+    bold: "\x1b[1m",
+    dim: "\x1b[2m",
+    cyan: "\x1b[36m",
+    green: "\x1b[32m",
+    yellow: "\x1b[33m",
+};
+// Strip control chars from interpolated strings. Defends against a relay
+// response (or, more realistically, an echoed title in some future field)
+// carrying ANSI escapes that would otherwise change the user's terminal
+// colour after our output ends.
+// eslint-disable-next-line no-control-regex
+const CTRL_RX = /[\x00-\x08\x0b-\x1f\x7f]/g;
+function safe(s) {
+    return s.replace(CTRL_RX, "");
+}
+/** Generate the QR-code string for `text` using qrcode-terminal's `small`
+ *  rendering (one terminal char per QR module, ~half the height of the
+ *  default). Returns the multi-line string, ready to write to stdout. */
+function qrToString(text) {
+    let out = "";
+    qrcode.generate(text, { small: true }, (s) => {
+        out = s;
+    });
+    return out;
+}
+/** Human-friendly countdown from now to `iso`. Returns "in 1h 0m" /
+ *  "in 45m" / "in 30s" / "expired". Stable enough to test as a string. */
+export function humanCountdown(iso, nowMs = Date.now()) {
+    const delta = new Date(iso).getTime() - nowMs;
+    if (!Number.isFinite(delta) || delta <= 0)
+        return "expired";
+    const totalSec = Math.floor(delta / 1000);
+    const days = Math.floor(totalSec / 86400);
+    const hours = Math.floor((totalSec % 86400) / 3600);
+    const mins = Math.floor((totalSec % 3600) / 60);
+    const secs = totalSec % 60;
+    if (days > 0)
+        return `in ${days}d ${hours}h`;
+    if (hours > 0)
+        return `in ${hours}h ${mins}m`;
+    if (mins > 0)
+        return `in ${mins}m`;
+    return `in ${secs}s`;
+}
+/** Render the pane-created response for a human reader. Returns the
+ *  full multi-line string; the caller writes it to stdout. */
+export function formatPaneCreated(res, opts = {}) {
+    const c = opts.color ?? false;
+    const b = c ? ANSI.bold : "";
+    const d = c ? ANSI.dim : "";
+    const cy = c ? ANSI.cyan : "";
+    const g = c ? ANSI.green : "";
+    const r = c ? ANSI.reset : "";
+    const title = safe(res.title);
+    const paneId = safe(res.pane_id);
+    const expiresIn = humanCountdown(res.expires_at);
+    const expiresAt = safe(res.expires_at);
+    const humanUrls = res.urls.humans.map(safe);
+    const agentStream = safe(res.urls.agent_stream);
+    const lines = [];
+    // Header — "Pane created" vs. "Existing pane reused" if `created`
+    // is explicitly false. Dedup hits from #262 carry created=false and the
+    // human shouldn't think they made a fresh row.
+    const headline = res.created === false
+        ? `${b}${cy}Existing pane reused${r}`
+        : `${b}${g}Pane pane created${r}`;
+    lines.push(headline);
+    lines.push("");
+    lines.push(`  ${d}Title:${r}    ${title}`);
+    lines.push(`  ${d}Pane:${r}  ${paneId}`);
+    lines.push(`  ${d}Expires:${r}  ${expiresIn} ${d}(${expiresAt})${r}`);
+    if (res.context_key) {
+        lines.push(`  ${d}Key:${r}      ${safe(res.context_key)}`);
+    }
+    lines.push("");
+    if (humanUrls.length === 0) {
+        // Dedup-on-existing-pane path doesn't re-mint human URLs. Pane
+        // the situation explicitly rather than rendering a blank section.
+        lines.push(`${d}No human URLs minted on this response — fetch them with ` +
+            `\`pane participants ${paneId}\`.${r}`);
+    }
+    else {
+        const label = humanUrls.length === 1 ? "Open this link" : "Open these links";
+        lines.push(`${label} in a browser:`);
+        lines.push("");
+        for (const u of humanUrls) {
+            lines.push(`  ${b}${u}${r}`);
+        }
+        lines.push("");
+        // Show a QR for the first URL — scannable from a phone. The other
+        // URLs (if any) are visible above; one QR keeps the output compact.
+        lines.push(`Or scan this QR code with your phone:`);
+        lines.push("");
+        const qr = qrToString(humanUrls[0]);
+        // Indent each QR line by two spaces so it sits inside the same gutter
+        // as the rest of the body.
+        for (const ln of qr.split("\n")) {
+            if (ln.length === 0)
+                continue;
+            lines.push(`  ${ln}`);
+        }
+        lines.push("");
+    }
+    lines.push(`${d}Agent stream:${r}  ${agentStream}`);
+    return lines.join("\n") + "\n";
+}

package/dist/index.js

@@ -6,6 +6,8 @@
 // behind the shape and the rename from the older flat layout.
 //
 // Config: PANE_URL and PANE_API_KEY (env), overridable with --url / --api-key.
+// Multiple environments live as named profiles in
+// $XDG_CONFIG_HOME/pane/config.json; pick one with --profile or PANE_PROFILE.
 // Output is JSON by default. Every noun self-documents via --help.
 import { parseArgs, ArgvError } from "./argv.js";
 /**
@@ -23,8 +25,14 @@ function failArgvError(e) {
     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 { runCreate, createHelp } from "./commands/create.js";
+import { runList, listHelp } from "./commands/list.js";
+import { runState, stateHelp } from "./commands/state.js";
+import { runSend, sendHelp } from "./commands/send.js";
+import { runWatch, watchHelp } from "./commands/watch.js";
+import { runDelete, deleteHelp } from "./commands/delete.js";
+import { runParticipant, participantHelp } from "./commands/participant.js";
+import { runTemplate, 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";
@@ -32,20 +40,35 @@ import { runFeedback, feedbackHelp } from "./commands/feedback.js";
 import { runConfig, configHelp } from "./commands/config.js";
 import { runBlob, blobHelp } from "./commands/attachment.js";
 import { runSkill, skillHelp } from "./commands/skill.js";
+import { runRecords, recordsHelp } from "./commands/records.js";
+import { runTemplateRecords, templateRecordsHelp, } from "./commands/template-records.js";
+import { runQuery, queryHelp } from "./commands/query.js";
+import { runTrash, trashHelp } from "./commands/trash.js";
 import { VERSION } from "./version.js";
 import { PaneApiError } from "@paneui/core";
 import { failUpgradeRequired } from "./output.js";
 const ROOT_HELP = `pane — a round-trip UI channel between agents and humans
 
 Usage:
-  pane <noun> <verb> [options]
+  pane <command> [options]
 
-Nouns:
-  surface           Open / observe / send to / close surfaces
-                    (create | list | show | send | watch | delete |
-                     participant <list|new|revoke>).
+Pane commands (operate on the core noun — a live UI channel):
+  create            Create a pane (POST /v1/panes). Prints pane_id, urls,
+                    tokens, expires_at.
+  list              Enumerate YOUR agent's panes.
+  show <id>         Non-blocking snapshot: pane metadata + event log.
+  send <id>         Emit an agent event into a pane.
+  watch <id>        Stream a pane's events as JSON-lines on stdout.
+  delete <id>       Close/delete a pane (DELETE /v1/panes/:id).
+  participant       Manage participant URLs on an existing pane
+    <list|new|revoke> (list | mint a fresh URL | revoke one URL).
+
+Other noun groups:
   template          Reusable, versioned UI templates
                     (create | version | update | search | list | show | delete).
+  template-records  Owner-curated content scoped to a Template head
+                    (list | get | upsert | update | delete), visible to
+                    every pane derived from any version of the template.
   key               YOUR agent's API key (list | revoke).
   taste             YOUR agent's freeform UI taste notes
                     (get | set | clear) — presentation preferences the agent
@@ -53,28 +76,38 @@ Nouns:
                     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
+  attachment        Binary attachments (upload | download | show | list |
+                    delete | token <mint|revoke|list>). Attachments are
+                    scoped to an agent, a pane, or a 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.
+  trash             Manage soft-deleted panes / templates
+                    (list | restore | restore-template | purge | purge-template).
+  query             Run read-only SQL over your scoped panes / records /
+                    events. JSON / CSV / TSV / table output.
 
-Run \`pane <noun> --help\` for that noun's verbs.
+Run \`pane <command> --help\` for command-specific options.
 
 Config:
   PANE_URL          Relay base URL.        Override: --url <url>
   PANE_API_KEY      Agent API key.         Override: --api-key <key>
+  PANE_PROFILE      Active profile name.   Override: --profile <name>
   '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.
+  \${XDG_CONFIG_HOME:-~/.config}/pane/config.json under a named profile —
+  afterwards commands need no env vars. Manage multiple environments
+  (dev/staging/prod) with 'pane config list / use / add / rm'.
 
 Global flags:
   -h, --help        Show help.
   -v, --version     Print version.
+  --profile <name>  Pick a saved profile for this invocation (overrides
+                    PANE_PROFILE and the saved 'current_profile').
+  --url <url>       Relay base URL — bypasses profile selection entirely.
+  --api-key <key>   Agent API key — bypasses profile selection entirely.
 
 Output: stdout is machine-readable JSON; errors go to stderr as
 {"error":{"code","message"}} with a non-zero exit.`;
@@ -85,7 +118,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 surface create --version <n>` /
+// boolean flag — and keeping it out lets `pane create --version <n>` /
 // `pane template version` consume a value as a normal value-flag.
 const BOOLEAN_FLAGS = new Set([
     "json",
@@ -122,7 +155,15 @@ async function main() {
         throw e;
     }
     const helps = {
-        surface: sessionHelp,
+        // Top-level pane verbs (formerly `pane surface <verb>` — see #163 follow-up).
+        create: createHelp,
+        list: listHelp,
+        show: stateHelp,
+        send: sendHelp,
+        watch: watchHelp,
+        delete: deleteHelp,
+        participant: participantHelp,
+        // Other noun groups.
         template: artifactHelp,
         key: keyHelp,
         taste: tasteHelp,
@@ -131,6 +172,10 @@ async function main() {
         agent: agentHelp,
         config: configHelp,
         skill: skillHelp,
+        records: recordsHelp,
+        "template-records": templateRecordsHelp,
+        query: queryHelp,
+        trash: trashHelp,
     };
     if (!(noun in helps)) {
         process.stderr.write(JSON.stringify({
@@ -142,7 +187,7 @@ async function main() {
         process.exit(1);
     }
     // `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
+    // --help is the responsibility of each runner (e.g. runPane 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) {
@@ -150,11 +195,31 @@ async function main() {
         return;
     }
     switch (noun) {
-        case "surface":
-            await runSession(args);
+        // Top-level pane verbs.
+        case "create":
+            await runCreate(args);
+            break;
+        case "list":
+            await runList(args);
+            break;
+        case "show":
+            await runState(args);
+            break;
+        case "send":
+            await runSend(args);
+            break;
+        case "watch":
+            await runWatch(args);
+            break;
+        case "delete":
+            await runDelete(args);
             break;
+        case "participant":
+            await runParticipant(args);
+            break;
+        // Other noun groups.
         case "template":
-            await runArtifact(args);
+            await runTemplate(args);
             break;
         case "key":
             await runKey(args);
@@ -177,6 +242,18 @@ async function main() {
         case "skill":
             await runSkill(args);
             break;
+        case "records":
+            await runRecords(args);
+            break;
+        case "template-records":
+            await runTemplateRecords(args);
+            break;
+        case "query":
+            await runQuery(args);
+            break;
+        case "trash":
+            await runTrash(args);
+            break;
     }
 }
 main().catch((err) => {

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 surface watch`
+ * Print a single compact JSON line to stdout and flush. Used by `pane watch`
  * so a pipe-reader (e.g. Claude Code's Monitor tool) sees each event
  * immediately, one event per line.
  */