@paneui/cli 0.0.1

package/dist/config.js

@@ -0,0 +1,77 @@
+// Relay connection config: PANE_URL / PANE_API_KEY from the environment,
+// overridable per-invocation with --url / --api-key.
+import { PaneClient } from "@paneui/core";
+import { fail } from "./output.js";
+import { readStore, storePath } from "./store.js";
+/**
+ * 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.
+ */
+export function describeConfig(args) {
+    const store = readStore();
+    let url = null;
+    let urlSource = "none";
+    if (args.flags.get("url")) {
+        url = args.flags.get("url");
+        urlSource = "flag";
+    }
+    else if (process.env.PANE_URL) {
+        url = process.env.PANE_URL;
+        urlSource = "env";
+    }
+    else if (store.url) {
+        url = store.url;
+        urlSource = "store";
+    }
+    let apiKey = null;
+    let keySource = "none";
+    if (args.flags.get("api-key")) {
+        apiKey = args.flags.get("api-key");
+        keySource = "flag";
+    }
+    else if (process.env.PANE_API_KEY) {
+        apiKey = process.env.PANE_API_KEY;
+        keySource = "env";
+    }
+    else if (store.apiKey) {
+        apiKey = store.apiKey;
+        keySource = "store";
+    }
+    return {
+        url: url ? url.replace(/\/$/, "") : null,
+        url_source: urlSource,
+        key_prefix: apiKey ? apiKey.slice(0, 10) + "…" : null,
+        key_source: keySource,
+        config_path: storePath(),
+    };
+}
+/**
+ * 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`.
+ */
+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.
+ */
+export function resolveConfig(args) {
+    const store = readStore();
+    const url = args.flags.get("url") ??
+        process.env.PANE_URL ??
+        store.url ??
+        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");
+    }
+    return { url: url.replace(/\/$/, ""), apiKey };
+}
+/** Build a PaneClient from resolved config. */
+export function makeClient(args) {
+    const cfg = resolveConfig(args);
+    return new PaneClient({ url: cfg.url, apiKey: cfg.apiKey });
+}

package/dist/index.js

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+// pane — command-line client for the Pane relay.
+//
+// Config: PANE_URL and PANE_API_KEY (env), overridable with --url / --api-key.
+// Output is JSON by default. Every command 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";
+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 { runDelete, deleteHelp } from "./commands/delete.js";
+const VERSION = "0.0.1";
+const ROOT_HELP = `pane — a round-trip UI channel between agents and humans
+
+Usage:
+  pane <command> [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).
+  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).
+  config            Show the resolved relay config (no network call).
+  logout            Clear the locally-saved relay URL + API key.
+
+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 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.
+
+Global flags:
+  -h, --help        Show help.
+  -v, --version     Print version.
+
+Output: stdout is machine-readable JSON; errors go to stderr as
+{"error":{"code","message"}} with a non-zero exit.`;
+// Flags that never take a value. `json` is kept here purely for forward-compat
+// (JSON is currently the only output mode): accepting `--json` as a no-op bool
+// means a future `--text`/`--json` toggle won't break existing invocations. It
+// is intentionally undocumented in --help.
+//
+// `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>` /
+// `pane artifact version` consume a value as a normal value-flag.
+const BOOLEAN_FLAGS = new Set(["json", "once", "help", "print-key", "yes"]);
+async function main() {
+    const rawArgv = process.argv.slice(2);
+    // Version: handle before anything else.
+    if (rawArgv[0] === "-v" || rawArgv[0] === "--version") {
+        process.stdout.write(VERSION + "\n");
+        return;
+    }
+    const command = rawArgv[0];
+    const rest = rawArgv.slice(1);
+    if (command === undefined ||
+        command === "-h" ||
+        command === "--help" ||
+        command === "help") {
+        process.stdout.write(ROOT_HELP + "\n");
+        return;
+    }
+    let args;
+    try {
+        args = parseArgs(rest, BOOLEAN_FLAGS);
+    }
+    catch (e) {
+        if (e instanceof ArgvError) {
+            process.stderr.write(JSON.stringify({
+                error: { code: "invalid_args", message: e.message },
+            }) + "\n");
+            process.exit(1);
+        }
+        throw e;
+    }
+    const helps = {
+        register: registerHelp,
+        create: createHelp,
+        artifact: artifactHelp,
+        state: stateHelp,
+        send: sendHelp,
+        watch: watchHelp,
+        delete: deleteHelp,
+        keys: keysHelp,
+        config: configHelp,
+        logout: logoutHelp,
+    };
+    if (!(command in helps)) {
+        process.stderr.write(JSON.stringify({
+            error: {
+                code: "unknown_command",
+                message: `unknown command '${command}' — run 'pane --help'`,
+            },
+        }) + "\n");
+        process.exit(1);
+    }
+    if (args.bools.has("help")) {
+        process.stdout.write(helps[command] + "\n");
+        return;
+    }
+    switch (command) {
+        case "register":
+            await runRegister(args);
+            break;
+        case "create":
+            await runCreate(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);
+            break;
+        case "config":
+            await runConfig(args);
+            break;
+        case "logout":
+            await runLogout();
+            break;
+    }
+}
+main().catch((err) => {
+    process.stderr.write(JSON.stringify({
+        error: {
+            code: "internal",
+            message: err instanceof Error ? err.message : String(err),
+        },
+    }) + "\n");
+    process.exit(1);
+});

package/dist/input.js

@@ -0,0 +1,42 @@
+// Helpers for reading CLI inputs that may be either a file path or an inline
+// literal (JSON, or raw text for an HTML artifact body).
+import { readFileSync, statSync } from "node:fs";
+/**
+ * True if `value` names an existing file. Only a missing path (ENOENT) is
+ * treated as "not a file" — any other fs error (EACCES, ELOOP, …) propagates
+ * with a labeled message rather than being misreported as inline content.
+ */
+function isFilePath(value) {
+    try {
+        return statSync(value).isFile();
+    }
+    catch (e) {
+        if (e &&
+            typeof e === "object" &&
+            e.code === "ENOENT") {
+            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)}`);
+    }
+}
+/**
+ * Resolve a value that is either a file path or an inline JSON literal.
+ * Returns the parsed JSON. Throws on parse failure.
+ */
+export function resolveJson(value, label) {
+    const raw = isFilePath(value) ? readFileSync(value, "utf8") : value;
+    try {
+        return JSON.parse(raw);
+    }
+    catch (e) {
+        throw new Error(`${label}: not valid JSON (${e instanceof Error ? e.message : String(e)})`);
+    }
+}
+/**
+ * Resolve raw text that is either a file path or an inline literal — no JSON
+ * parsing. Used for an inline HTML artifact body.
+ */
+export function resolveText(value) {
+    return isFilePath(value) ? readFileSync(value, "utf8") : value;
+}

package/dist/output.js

@@ -0,0 +1,40 @@
+// stdout/stderr helpers. The CLI is JSON-by-default: machine-readable on
+// stdout, human errors on stderr.
+import { PaneApiError } from "@paneui/core";
+/** Print a value as pretty JSON to stdout. */
+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`
+ * so a pipe-reader (e.g. Claude Code's Monitor tool) sees each event
+ * immediately, one event per line.
+ */
+export function printJsonLine(value) {
+    process.stdout.write(JSON.stringify(value) + "\n");
+}
+/** Print an error envelope to stderr and exit non-zero. */
+export function fail(message, code = "error", details, extra) {
+    const error = { code, message };
+    if (extra?.hint !== undefined)
+        error["hint"] = extra.hint;
+    if (extra?.retryable !== undefined)
+        error["retryable"] = extra.retryable;
+    if (extra?.docs_url !== undefined)
+        error["docs_url"] = extra.docs_url;
+    if (details !== undefined)
+        error["details"] = details;
+    process.stderr.write(JSON.stringify({ error }) + "\n");
+    process.exit(1);
+}
+/** Translate a thrown error (incl. PaneApiError) into a fail() exit. */
+export function failFromError(err) {
+    if (err instanceof PaneApiError) {
+        fail(err.message, err.code, err.details, {
+            hint: err.hint,
+            retryable: err.retryable,
+            docs_url: err.docsUrl,
+        });
+    }
+    fail(err instanceof Error ? err.message : String(err), "internal");
+}

package/dist/store.js

@@ -0,0 +1,64 @@
+// 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
+// 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";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+/** Absolute path to the config file (honours XDG_CONFIG_HOME). */
+export function storePath() {
+    const base = process.env.XDG_CONFIG_HOME && process.env.XDG_CONFIG_HOME.trim() !== ""
+        ? process.env.XDG_CONFIG_HOME
+        : join(homedir(), ".config");
+    return join(base, "pane", "config.json");
+}
+/** Read the persisted config. Returns {} if the file is missing or unparseable. */
+export function readStore() {
+    let text;
+    try {
+        text = readFileSync(storePath(), "utf8");
+    }
+    catch {
+        return {};
+    }
+    try {
+        const parsed = JSON.parse(text);
+        if (parsed === null ||
+            typeof parsed !== "object" ||
+            Array.isArray(parsed)) {
+            return {};
+        }
+        const out = {};
+        if (typeof parsed.url === "string")
+            out.url = parsed.url;
+        if (typeof parsed.apiKey === "string")
+            out.apiKey = parsed.apiKey;
+        return out;
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Merge `patch` into the existing config and write it back as pretty JSON.
+ * Creates the parent directory if needed; the file is written with mode 0600.
+ */
+export function writeStore(patch) {
+    const path = storePath();
+    const merged = { ...readStore(), ...patch };
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(merged, null, 2) + "\n", { mode: 0o600 });
+    // Ensure mode even if the file pre-existed with looser permissions.
+    chmodSync(path, 0o600);
+    return path;
+}
+/**
+ * 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`.
+ */
+export function clearStore() {
+    const path = storePath();
+    rmSync(path, { force: true });
+    return path;
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@paneui/cli",
+  "version": "0.0.1",
+  "description": "Command-line client for the Pane relay: create sessions, inspect state, send and watch events.",
+  "license": "MIT",
+  "type": "module",
+  "keywords": [
+    "pane",
+    "cli",
+    "agent",
+    "relay",
+    "human-in-the-loop"
+  ],
+  "homepage": "https://github.com/aerolalit/paneui#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aerolalit/paneui.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/aerolalit/paneui/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "pane": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:unit": "vitest run"
+  },
+  "dependencies": {
+    "@paneui/core": "^0.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.7.0",
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.6"
+  }
+}