@paneui/cli 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lalit Singh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,61 @@
+# @paneui/cli
+
+Command-line client for the [Pane](https://github.com/aerolalit/paneui) relay:
+hand a human a rich interactive UI by URL and capture their answer as structured
+data — from any agent (cron job, chat bot, CI, headless server).
+
+## Install
+
+```sh
+npm install -g @paneui/cli
+# or, no install:
+npx @paneui/cli <command>
+```
+
+The binary is `pane`.
+
+## Setup
+
+```sh
+export PANE_URL=https://relay.paneui.com   # or your self-hosted relay
+pane register --name "my-agent"            # provisions and saves an API key
+```
+
+`pane register` writes the URL + API key to
+`${XDG_CONFIG_HOME:-~/.config}/pane/config.json`. Subsequent commands need
+only `PANE_URL` (or nothing) in the environment.
+
+Override per-invocation with `--url <url>` and `--api-key <key>`.
+
+## Commands
+
+```
+pane register          Provision an agent API key and save it locally
+pane create            Create a session — returns session_id, urls, tokens
+pane artifact          Manage reusable, versioned artifacts
+pane state <id>        Non-blocking snapshot: metadata + event log
+pane send <id>         Emit an agent event into a session
+pane watch <id>        Stream a session's events as JSON-lines on stdout
+pane delete <id>       Close / delete a session
+pane keys              Inspect or revoke your agent's API key
+pane config            Show the resolved relay config (no network call)
+pane logout            Clear the locally-saved URL + API key
+```
+
+Run `pane <command> --help` for command-specific options.
+
+## Output
+
+stdout is machine-readable JSON. Errors go to stderr as
+`{"error":{"code","message"}}` with a non-zero exit.
+
+```sh
+SESSION=$(pane create --template form --schema ./q.json | jq -r .session_id)
+pane watch "$SESSION" | jq 'select(.type == "human_response")'
+```
+
+## Links
+
+- Repo: <https://github.com/aerolalit/paneui>
+- Spec: <https://github.com/aerolalit/paneui/blob/main/docs/SPEC.md>
+- License: MIT

package/dist/argv.js

@@ -0,0 +1,52 @@
+// Tiny hand-rolled argv parser. No CLI framework.
+//
+// Supports:
+//   --flag value      --flag=value      --bool      -h
+// Everything that isn't a flag (or a flag's value) is a positional.
+/** Thrown when a value-flag is given with no argument (e.g. trailing `--url`). */
+export class ArgvError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ArgvError";
+    }
+}
+/**
+ * Parse argv tokens. `booleanFlags` lists flags that never consume a value
+ * (e.g. --json, --once, --help); everything else with a `--name` form
+ * consumes the next token unless written as `--name=value`.
+ */
+export function parseArgs(tokens, booleanFlags) {
+    const positionals = [];
+    const flags = new Map();
+    const bools = new Set();
+    for (let i = 0; i < tokens.length; i++) {
+        const tok = tokens[i];
+        if (tok === "-h" || tok === "--help") {
+            bools.add("help");
+            continue;
+        }
+        if (tok.startsWith("--")) {
+            const body = tok.slice(2);
+            const eq = body.indexOf("=");
+            if (eq !== -1) {
+                flags.set(body.slice(0, eq), body.slice(eq + 1));
+                continue;
+            }
+            if (booleanFlags.has(body)) {
+                bools.add(body);
+                continue;
+            }
+            const next = tokens[i + 1];
+            if (next === undefined || next.startsWith("--")) {
+                // A value-flag with no argument is a user error — don't silently
+                // demote it to a boolean (which hides the mistake).
+                throw new ArgvError(`--${body} requires a value`);
+            }
+            flags.set(body, next);
+            i++;
+            continue;
+        }
+        positionals.push(tok);
+    }
+    return { positionals, flags, bools };
+}

package/dist/commands/artifact.js

@@ -0,0 +1,331 @@
+// `pane artifact` — manage reusable, versioned artifacts.
+//
+// Flat command namespace: `artifact` is one top-level command that branches on
+// a positional subcommand (create / version / update / search / list / show).
+// An artifact is a reusable UI template (HTML + event schema + optional input
+// schema); a session is one *use* of one version of it. Authoring an artifact
+// once and instancing it via `pane create --artifact-id` removes the per-use
+// cost of regenerating the same HTML.
+import { createArtifactSchema, createArtifactVersionSchema, patchArtifactMetadataSchema, } from "@paneui/core";
+import { makeClient } from "../config.js";
+import { resolveJson, resolveText } from "../input.js";
+import { printJson, fail, failFromError } from "../output.js";
+export const artifactHelp = `pane artifact — manage reusable, versioned artifacts
+
+An artifact is a reusable UI template: HTML + an event schema + an optional
+input schema. A session is one use of one version of it. Author an artifact
+once, then instance it many times with 'pane create --artifact-id <id|slug>'
+instead of regenerating the HTML on every session.
+
+Usage:
+  pane artifact <subcommand> [options]
+
+Subcommands:
+  create     Create a named, reusable artifact (its v1).
+  version    Append a new version to an existing artifact.
+  update     Update an artifact's head metadata (name/slug/description/tags).
+  search     Search the agent's named artifacts (lean — no HTML).
+  list       List the agent's named artifacts (search with no query).
+  show       Show a full artifact: head metadata + its version list.
+
+  pane artifact create --name <n> --artifact <path|inline>
+                       [--event-schema <path|json>] [--slug <s>]
+                       [--description <d>] [--tags <t1,t2>]
+                       [--input-schema <path|json>] [--artifact-type <t>]
+      Creates a named artifact. Prints { artifact_id, slug, version }.
+
+  pane artifact version <id|slug> --artifact <path|inline>
+                        [--event-schema <path|json>]
+                        [--input-schema <path|json>] [--artifact-type <t>]
+      Appends a new immutable version. Prints { artifact_id, version }.
+
+  pane artifact update <id|slug> [--name <n>] [--slug <s>]
+                       [--description <d>] [--tags <t1,t2>]
+      Updates head metadata only (never the content). Prints the lean summary.
+
+  pane artifact search [query]
+      Text search over name + description + tags, ranked by last_used_at.
+      Prints an array of { id, slug, name, description, tags,
+      latest_version, last_used_at }.
+
+  pane artifact list
+      Alias of 'search' with no query — lists all the agent's artifacts.
+
+  pane artifact show <id|slug>
+      Prints the full artifact: head metadata + every version's content.
+
+Options:
+  --name <n>          Artifact display name (required for 'create').
+  --slug <s>          Stable, agent-chosen handle (unique per agent). The
+                      durable way to reference the artifact later.
+  --description <d>   Prose: what the artifact is and does. Read by an agent
+                      deciding whether to reuse it.
+  --tags <t1,t2,...>  Comma-separated keywords for search.
+  --artifact <v>      HTML artifact body — a file path, or inline HTML.
+  --event-schema <v>  Event schema — a .json file path, or inline JSON.
+                      Optional: omit for a view-only artifact (a
+                      report/dashboard the human only views — no page/agent
+                      events).
+
+                      Shape — an object with an "events" map, keyed by event
+                      type. Each entry declares who may emit it and the JSON
+                      Schema for its payload:
+                          {
+                            "events": {
+                              "form.submitted": {
+                                "emittedBy": ["page"],
+                                "payload": {
+                                  "type": "object",
+                                  "properties": { "answer": { "type": "string" } },
+                                  "required": ["answer"]
+                                }
+                              }
+                            }
+                          }
+                      emittedBy is any non-empty subset of ["page", "agent"].
+                      payload is a JSON Schema; the relay validates every
+                      emit against it. See docs/SPEC.md for the full grammar.
+  --input-schema <v>  JSON Schema for this artifact's per-session input_data —
+                      a file path, or inline JSON. Optional.
+  --artifact-type <t> "html-inline" (default) or "html-ref".
+  --url <url>         Relay base URL (overrides PANE_URL).
+  --api-key <key>     Agent API key (overrides PANE_API_KEY).
+  -h, --help          Show this help.
+
+Output: stdout is machine-readable JSON.`;
+/** Resolve --artifact-type, defaulting to html-inline. */
+function resolveArtifactType(args) {
+    const t = (args.flags.get("artifact-type") ?? "html-inline");
+    if (t !== "html-inline" && t !== "html-ref") {
+        fail("--artifact-type must be 'html-inline' or 'html-ref'", "invalid_args");
+    }
+    return t;
+}
+/** Resolve the artifact HTML body (file or inline; verbatim URL for html-ref). */
+function resolveSource(args, type) {
+    const artifactVal = args.flags.get("artifact");
+    if (!artifactVal)
+        fail("missing --artifact", "invalid_args");
+    try {
+        return type === "html-ref" ? artifactVal : resolveText(artifactVal);
+    }
+    catch (e) {
+        fail(e instanceof Error ? e.message : String(e), "invalid_args");
+    }
+}
+/**
+ * Resolve --event-schema — file path or inline JSON. --event-schema is
+ * optional: when absent this returns `undefined`, which makes a view-only
+ * artifact (no event vocabulary — the human only views it). The caller must
+ * omit `event_schema` from the request entirely when this returns `undefined`.
+ */
+function resolveEventSchema(args) {
+    const schemaVal = args.flags.get("event-schema");
+    if (!schemaVal)
+        return undefined;
+    try {
+        return resolveJson(schemaVal, "--event-schema");
+    }
+    catch (e) {
+        fail(e instanceof Error ? e.message : String(e), "invalid_args");
+    }
+}
+/** Resolve the optional --input-schema — file path or inline JSON. */
+function resolveInputSchema(args) {
+    const raw = args.flags.get("input-schema");
+    if (raw === undefined)
+        return undefined;
+    try {
+        const v = resolveJson(raw, "--input-schema");
+        if (v === null || typeof v !== "object" || Array.isArray(v)) {
+            fail("--input-schema must be a JSON object", "invalid_args");
+        }
+        return v;
+    }
+    catch (e) {
+        fail(e instanceof Error ? e.message : String(e), "invalid_args");
+    }
+}
+/** Parse a comma-separated --tags flag into a string array. */
+function resolveTags(args) {
+    const raw = args.flags.get("tags");
+    if (raw === undefined)
+        return undefined;
+    const tags = raw
+        .split(",")
+        .map((t) => t.trim())
+        .filter((t) => t !== "");
+    return tags.length > 0 ? tags : undefined;
+}
+async function runArtifactCreate(args) {
+    const name = args.flags.get("name");
+    if (!name)
+        fail("missing --name", "invalid_args");
+    const type = resolveArtifactType(args);
+    const source = resolveSource(args, type);
+    const eventSchema = resolveEventSchema(args);
+    const inputSchema = resolveInputSchema(args);
+    const tags = resolveTags(args);
+    const slug = args.flags.get("slug");
+    const description = args.flags.get("description");
+    const candidate = {
+        name,
+        source,
+        type,
+    };
+    // event_schema is OMITTED entirely when --event-schema is absent — a view-only
+    // artifact. Setting it to `undefined` would still add the key.
+    if (eventSchema !== undefined)
+        candidate["event_schema"] = eventSchema;
+    if (slug !== undefined)
+        candidate["slug"] = slug;
+    if (description !== undefined)
+        candidate["description"] = description;
+    if (tags !== undefined)
+        candidate["tags"] = tags;
+    if (inputSchema !== undefined)
+        candidate["input_schema"] = inputSchema;
+    const parsed = createArtifactSchema.safeParse(candidate);
+    if (!parsed.success) {
+        const issue = parsed.error.issues[0];
+        const where = issue && issue.path.length > 0 ? issue.path.join(".") : "request";
+        fail(`invalid artifact: ${where}: ${issue ? issue.message : "validation failed"}`, "invalid_args", parsed.error.flatten());
+    }
+    const req = parsed.data;
+    const client = makeClient(args);
+    try {
+        const res = await client.createArtifact(req);
+        printJson({
+            artifact_id: res.artifact_id,
+            slug: slug ?? null,
+            version: res.version,
+        });
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+async function runArtifactVersion(args) {
+    const idOrSlug = args.positionals[1];
+    if (!idOrSlug) {
+        fail("missing artifact <id|slug> — usage: pane artifact version <id|slug>", "invalid_args");
+    }
+    const type = resolveArtifactType(args);
+    const source = resolveSource(args, type);
+    const eventSchema = resolveEventSchema(args);
+    const inputSchema = resolveInputSchema(args);
+    const candidate = {
+        source,
+        type,
+    };
+    // event_schema is OMITTED entirely when --event-schema is absent — a view-only
+    // version. Setting it to `undefined` would still add the key.
+    if (eventSchema !== undefined)
+        candidate["event_schema"] = eventSchema;
+    if (inputSchema !== undefined)
+        candidate["input_schema"] = inputSchema;
+    const parsed = createArtifactVersionSchema.safeParse(candidate);
+    if (!parsed.success) {
+        const issue = parsed.error.issues[0];
+        const where = issue && issue.path.length > 0 ? issue.path.join(".") : "request";
+        fail(`invalid version: ${where}: ${issue ? issue.message : "validation failed"}`, "invalid_args", parsed.error.flatten());
+    }
+    const req = parsed.data;
+    const client = makeClient(args);
+    try {
+        const res = await client.createArtifactVersion(idOrSlug, req);
+        printJson({ artifact_id: res.artifact_id, version: res.version });
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+async function runArtifactUpdate(args) {
+    const idOrSlug = args.positionals[1];
+    if (!idOrSlug) {
+        fail("missing artifact <id|slug> — usage: pane artifact update <id|slug>", "invalid_args");
+    }
+    const candidate = {};
+    const name = args.flags.get("name");
+    const slug = args.flags.get("slug");
+    const description = args.flags.get("description");
+    const tags = resolveTags(args);
+    if (name !== undefined)
+        candidate["name"] = name;
+    if (slug !== undefined)
+        candidate["slug"] = slug;
+    if (description !== undefined)
+        candidate["description"] = description;
+    if (tags !== undefined)
+        candidate["tags"] = tags;
+    if (Object.keys(candidate).length === 0) {
+        fail("nothing to update — pass at least one of --name / --slug / --description / --tags", "invalid_args");
+    }
+    const parsed = patchArtifactMetadataSchema.safeParse(candidate);
+    if (!parsed.success) {
+        const issue = parsed.error.issues[0];
+        const where = issue && issue.path.length > 0 ? issue.path.join(".") : "request";
+        fail(`invalid update: ${where}: ${issue ? issue.message : "validation failed"}`, "invalid_args", parsed.error.flatten());
+    }
+    const metadata = parsed.data;
+    const client = makeClient(args);
+    try {
+        const res = await client.updateArtifact(idOrSlug, metadata);
+        printJson(res);
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+async function runArtifactSearch(args, query) {
+    const client = makeClient(args);
+    try {
+        const res = await client.searchArtifacts(query);
+        printJson(res);
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+async function runArtifactShow(args) {
+    const idOrSlug = args.positionals[1];
+    if (!idOrSlug) {
+        fail("missing artifact <id|slug> — usage: pane artifact show <id|slug>", "invalid_args");
+    }
+    const client = makeClient(args);
+    try {
+        const res = await client.getArtifact(idOrSlug);
+        printJson(res);
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+export async function runArtifact(args) {
+    const sub = args.positionals[0];
+    switch (sub) {
+        case "create":
+            await runArtifactCreate(args);
+            break;
+        case "version":
+            await runArtifactVersion(args);
+            break;
+        case "update":
+            await runArtifactUpdate(args);
+            break;
+        case "search":
+            await runArtifactSearch(args, args.positionals[1]);
+            break;
+        case "list":
+            await runArtifactSearch(args, undefined);
+            break;
+        case "show":
+            await runArtifactShow(args);
+            break;
+        case undefined:
+            fail("missing subcommand — usage: pane artifact <create|version|update|search|list|show> (run 'pane artifact --help')", "invalid_args");
+            break;
+        default:
+            fail(`unknown artifact subcommand '${sub}' — expected create|version|update|search|list|show (run 'pane artifact --help')`, "invalid_args");
+    }
+}

package/dist/commands/config.js

@@ -0,0 +1,31 @@
+// `pane config` — show the resolved relay config without a network call.
+import { describeConfig } from "../config.js";
+import { printJson } from "../output.js";
+export const configHelp = `pane config — show the resolved relay config
+
+Usage:
+  pane config [options]
+
+Prints 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.
+
+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.
+  -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
+  }`;
+export async function runConfig(args) {
+    printJson(describeConfig(args));
+}