@unikernelai/sandbox-cli 1.0.0 → 1.1.0

package/SKILL.md

@@ -0,0 +1,145 @@
+# SKILL: unik — Unikraft Sandbox CLI
+
+## Overview
+`unik` is a CLI for running code in unikernel-isolated sandboxes on Unikraft Cloud.
+It is designed to be used by autonomous AI agents as well as humans.
+
+## Agent Mode (automatic)
+When stdout is not a TTY (piped, redirected, or called by an agent), **all output is JSON by default**.
+No `--json` flag needed. Agents should always pipe output.
+
+```bash
+# Agent-style usage (JSON output automatic):
+unik run python 'print("hello")' | jq .stdout
+unik sandbox create | jq .id
+unik status | jq .checks.cloud.ok
+```
+
+## Invariants
+- All outputs are JSON when stdout is not a TTY.
+- Exit code **0** = success. Exit code **1** = error.
+- Errors always go to **stderr** as JSON: `{ "ok": false, "error": "..." }`.
+- Sandbox IDs always start with `sbx_`.
+- API keys always start with `uk_live_`.
+- Execution timeout max is **8000ms**.
+- `--dry-run` is safe and non-destructive on all delete/revoke operations.
+- Credentials live in `~/.unik/config.json`.
+
+## Onboarding a new agent (typical flow)
+```bash
+# 1. Set a JWT from your auth provider:
+unik auth set-token <jwt>
+
+# 2. Create an API key (auto-saved to ~/.unik/config.json):
+unik keys create --label "my-agent"
+# → prints { "ok": true, "key": "uk_live_...", "saved": true }
+# JWT is cleared; the new API key is used for all future calls.
+
+# 3. Verify:
+unik auth whoami
+unik status
+```
+
+## Self-discovery
+```bash
+# Machine-readable schema of all commands + I/O:
+unik schema
+```
+
+## Common agent patterns
+
+### Stateless execution (one-shot)
+```bash
+unik run python 'import math; print(math.sqrt(144))'
+unik run nodejs 'console.log(JSON.stringify({x: 1+1}))'
+echo 'print(sum(range(100)))' | unik run python
+cat script.py | unik run python
+```
+
+### Persistent sandbox (multi-step state)
+```bash
+# Create once, reuse for multiple executions
+SBX=$(unik sandbox create | jq -r .id)
+
+unik sandbox exec "$SBX" python 'x = 42'
+unik sandbox exec "$SBX" python 'print(x)'   # state persists within sandbox
+
+# Upload a file, then run it
+echo 'def greet(n): return f"hello {n}"' | unik sandbox upload "$SBX" /app/utils.py
+unik sandbox exec "$SBX" python 'import sys; sys.path.insert(0,"/app"); from utils import greet; print(greet("agent"))'
+
+unik sandbox ls "$SBX"
+unik sandbox delete "$SBX"
+```
+
+### API key management
+```bash
+unik keys list | jq '.items[] | {prefix, label, id}'
+unik keys revoke <id> --dry-run   # safe preview
+unik keys revoke <id>
+```
+
+### MCP server mode (for Claude Code / Cursor / other MCP clients)
+Add to your MCP config:
+```json
+{
+  "mcpServers": {
+    "unik": {
+      "command": "unik",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+Credentials from `~/.unik/config.json` are used automatically.
+
+## Output shapes
+
+### `unik run` / `unik sandbox exec`
+```json
+{
+  "ok": true,
+  "status": "success",
+  "stdout": "42\n",
+  "stderr": "",
+  "execution_time_ms": 45
+}
+```
+
+### `unik sandbox create`
+```json
+{ "ok": true, "id": "sbx_..." }
+```
+
+### `unik keys create`
+```json
+{
+  "ok": true,
+  "id": "uuid",
+  "key": "uk_live_...",
+  "prefix": "uk_live_XXXX",
+  "expires_at": null,
+  "saved": true
+}
+```
+
+### `unik status`
+```json
+{
+  "status": "ready",
+  "checks": { "cloud": { "ok": true }, "database": { "ok": true } }
+}
+```
+
+### Errors (stderr)
+```json
+{ "ok": false, "error": "no credentials found", "hint": "unik auth set-key <key>" }
+```
+
+## Best practices for agents
+- Always use `unik schema` at the start of a session to get current command shapes.
+- Use `--dry-run` before any destructive operation to verify intent.
+- Parse `ok` field first — if `false`, check `error` on stderr.
+- Sandbox TTL is 15 minutes. Re-create if `sandbox_not_found` is returned.
+- Pipe code via stdin for multi-line scripts: `cat script.py | unik run python`.
+- `unik run` is stateless. Use `unik sandbox exec` when you need to persist state between steps.

package/dist/cli.js

@@ -3,8 +3,12 @@ import { program } from "commander";
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
 import { homedir } from "os";
 import { join } from "path";
+import { createInterface } from "readline";
 import { UnikernelsClient, DEFAULT_BASE_URL, } from "@unikernelai/sandbox";
-// ─── Config file: ~/.unik/config.json ───────────────────────────────────────
+// ─── Agent mode detection ────────────────────────────────────────────────────
+// If stdout is not a TTY (piped, redirected, called by an agent), default to JSON.
+const AGENT_MODE = !process.stdout.isTTY;
+// ─── Config ───────────────────────────────────────────────────────────────────
 const CONFIG_DIR = join(homedir(), ".unik");
 const CONFIG_FILE = join(CONFIG_DIR, "config.json");
 function loadConfig() {
@@ -22,161 +26,139 @@ function saveConfig(cfg) {
         mkdirSync(CONFIG_DIR, { recursive: true });
     writeFileSync(CONFIG_FILE, JSON.stringify(cfg, null, 2) + "\n", "utf8");
 }
-function getClient(overrides = {}) {
+function getClient() {
     const cfg = loadConfig();
-    const apiKey = overrides.apiKey ?? cfg.api_key;
-    const authToken = overrides.authToken ?? cfg.auth_token;
-    const baseUrl = overrides.baseUrl ?? cfg.base_url ?? DEFAULT_BASE_URL;
-    if (!apiKey && !authToken) {
-        console.error("Error: no credentials found.\n" +
-            "  Set an API key:    unik auth set-key <key>\n" +
-            "  Or set a JWT:      unik auth set-token <jwt>\n" +
-            "  Or login:          unik auth login");
-        process.exit(1);
-    }
-    return new UnikernelsClient({ apiKey, authToken, baseUrl });
+    if (!cfg.api_key && !cfg.auth_token)
+        die("no credentials found", { hint: "unik auth set-key <key>  or  unik auth set-token <jwt>" });
+    return new UnikernelsClient({ apiKey: cfg.api_key, authToken: cfg.auth_token, baseUrl: cfg.base_url ?? DEFAULT_BASE_URL });
+}
+// ─── Output helpers ───────────────────────────────────────────────────────────
+function out(human, data) {
+    if (AGENT_MODE)
+        process.stdout.write(JSON.stringify(data) + "\n");
+    else
+        console.log(human);
 }
 function jsonOut(data) {
-    console.log(JSON.stringify(data, null, 2));
+    process.stdout.write(JSON.stringify(data) + "\n");
+}
+function die(message, extra) {
+    process.stderr.write(JSON.stringify({ ok: false, error: message, ...extra }) + "\n");
+    process.exit(1);
 }
 function readStdin() {
     return new Promise((resolve) => {
         let buf = "";
         process.stdin.setEncoding("utf8");
-        process.stdin.on("data", (chunk) => (buf += chunk));
+        process.stdin.on("data", (c) => (buf += c));
         process.stdin.on("end", () => resolve(buf.trim()));
     });
 }
-// ─── CLI definition ──────────────────────────────────────────────────────────
+// ─── CLI ──────────────────────────────────────────────────────────────────────
 program
     .name("unik")
-    .description("Unikraft sandbox CLI — run code in unikernel-isolated sandboxes")
-    .version("1.0.0");
-// ── auth ─────────────────────────────────────────────────────────────────────
+    .description("Unikraft sandbox CLI. JSON output auto-enabled in pipe/agent mode.")
+    .version("1.1.0");
+// schema ─────────────────────────────────────────────────────────────────────
+program.command("schema").description("Output a machine-readable JSON schema of all commands. For agents.").action(() => jsonOut(SCHEMA));
+// auth ────────────────────────────────────────────────────────────────────────
 const auth = program.command("auth").description("Manage credentials");
-auth
-    .command("set-key <key>")
-    .description("Save an API key to ~/.unik/config.json")
-    .action((key) => {
+auth.command("set-key <key>").description("Save an API key to ~/.unik/config.json").action((key) => {
     const cfg = loadConfig();
     cfg.api_key = key;
     delete cfg.auth_token;
     saveConfig(cfg);
-    console.log(`✓ API key saved (prefix: ${key.slice(0, 12)}...)`);
+    out(`✓ API key saved (prefix: ${key.slice(0, 12)}...)`, { ok: true, prefix: key.slice(0, 12) });
 });
-auth
-    .command("set-token <jwt>")
-    .description("Save a JWT bearer token (for admin operations like creating API keys)")
-    .action((jwt) => {
+auth.command("set-token <jwt>").description("Save a JWT bearer token (for creating API keys)").action((jwt) => {
     const cfg = loadConfig();
     cfg.auth_token = jwt;
     saveConfig(cfg);
-    console.log("✓ JWT saved");
+    out("✓ JWT saved", { ok: true });
 });
-auth
-    .command("set-url <url>")
-    .description("Override the base URL (default: DEFAULT_BASE_URL)")
-    .action((url) => {
+auth.command("set-url <url>").description("Override the API base URL").action((url) => {
     const cfg = loadConfig();
     cfg.base_url = url;
     saveConfig(cfg);
-    console.log(`✓ Base URL set to ${url}`);
+    out(`✓ Base URL set to ${url}`, { ok: true, base_url: url });
 });
-auth
-    .command("whoami")
-    .description("Show stored credentials")
-    .action(() => {
+auth.command("whoami").description("Show stored credentials").action(() => {
     const cfg = loadConfig();
-    console.log("Base URL:", cfg.base_url ?? DEFAULT_BASE_URL);
-    console.log("API key: ", cfg.api_key ? cfg.api_key.slice(0, 16) + "..." : "(none)");
-    console.log("JWT:     ", cfg.auth_token ? cfg.auth_token.slice(0, 20) + "..." : "(none)");
+    const data = { base_url: cfg.base_url ?? DEFAULT_BASE_URL, api_key_prefix: cfg.api_key ? cfg.api_key.slice(0, 16) : null, has_jwt: !!cfg.auth_token };
+    if (AGENT_MODE) {
+        jsonOut(data);
+        return;
+    }
+    console.log("Base URL:", data.base_url);
+    console.log("API key: ", data.api_key_prefix ? data.api_key_prefix + "..." : "(none)");
+    console.log("JWT:     ", data.has_jwt ? "(set)" : "(none)");
 });
-auth
-    .command("logout")
-    .description("Clear stored credentials")
-    .action(() => {
+auth.command("logout").description("Clear stored credentials").action(() => {
     saveConfig({});
-    console.log("✓ Credentials cleared");
+    out("✓ Credentials cleared", { ok: true });
 });
-// ── api-keys ─────────────────────────────────────────────────────────────────
+// keys ────────────────────────────────────────────────────────────────────────
 const keys = program.command("keys").description("Manage API keys (requires JWT)");
-keys
-    .command("create")
-    .description("Create a new API key and save it locally")
-    .option("-l, --label <label>", "Human-readable label for the key")
-    .option("-e, --expires <date>", "Expiry date (ISO 8601, e.g. 2026-12-31T00:00:00Z)")
-    .option("--no-save", "Print the key without saving to ~/.unik/config.json")
+keys.command("create")
+    .description("Create a new API key. Saves to ~/.unik/config.json by default.")
+    .option("-l, --label <label>", "Label for the key")
+    .option("-e, --expires <date>", "Expiry (ISO 8601)")
+    .option("--no-save", "Print only, don't save")
     .action(async (opts) => {
-    const client = getClient();
-    const key = await client.createApiKey({
-        label: opts.label,
-        expires_at: opts.expires,
-    });
-    console.log("\n✓ API key created:");
-    console.log("  Key:    ", key.key);
-    console.log("  ID:     ", key.id);
-    console.log("  Prefix: ", key.prefix);
-    if (key.expires_at)
-        console.log("  Expires:", key.expires_at);
+    const key = await getClient().createApiKey({ label: opts.label, expires_at: opts.expires });
     if (opts.save !== false) {
         const cfg = loadConfig();
         cfg.api_key = key.key;
         delete cfg.auth_token;
         saveConfig(cfg);
-        console.log("\n✓ Key saved to ~/.unik/config.json. Future commands will use it automatically.");
     }
-    else {
-        console.log("\n  ⚠  Store this key — it will NOT be shown again.");
+    if (AGENT_MODE) {
+        jsonOut({ ok: true, ...key, saved: opts.save !== false });
+        return;
     }
+    console.log("\n✓ API key created:");
+    console.log("  Key:    ", key.key);
+    console.log("  ID:     ", key.id);
+    console.log("  Prefix: ", key.prefix);
+    if (key.expires_at)
+        console.log("  Expires:", key.expires_at);
+    console.log(opts.save !== false ? "\n✓ Key saved to ~/.unik/config.json." : "\n  ⚠  Store this key — it will NOT be shown again.");
 });
-keys
-    .command("list")
-    .description("List all API keys for this account")
-    .action(async () => {
-    const client = getClient();
-    const list = await client.listApiKeys();
-    if (list.length === 0) {
-        console.log("No API keys found.");
+keys.command("list").description("List all API keys").action(async () => {
+    const list = await getClient().listApiKeys();
+    if (AGENT_MODE) {
+        jsonOut({ ok: true, count: list.length, items: list });
         return;
     }
-    console.log(`\n${list.length} key(s):\n`);
-    for (const k of list) {
-        const status = k.revoked_at ? "REVOKED" : "active";
-        console.log(`  ${k.prefix}...  [${status}]  id=${k.id}  label=${k.label ?? "-"}  created=${k.created_at.slice(0, 10)}`);
+    if (!list.length) {
+        console.log("No keys.");
+        return;
     }
+    for (const k of list)
+        console.log(`  ${k.prefix}...  [${k.revoked_at ? "REVOKED" : "active"}]  id=${k.id}  label=${k.label ?? "-"}  created=${k.created_at.slice(0, 10)}`);
 });
-keys
-    .command("revoke <id>")
-    .description("Revoke an API key by its ID")
-    .action(async (id) => {
-    const client = getClient();
-    await client.revokeApiKey(id);
-    console.log(`✓ Key ${id} revoked`);
+keys.command("revoke <id>").description("Revoke a key by ID").option("--dry-run", "Preview only").action(async (id, opts) => {
+    if (opts.dryRun) {
+        out(`[dry-run] Would revoke key id=${id}`, { ok: true, dry_run: true, id });
+        return;
+    }
+    await getClient().revokeApiKey(id);
+    out(`✓ Key ${id} revoked`, { ok: true, id, revoked: true });
 });
-// ── run ───────────────────────────────────────────────────────────────────────
-program
-    .command("run <language> [code]")
-    .description("Execute code directly (stateless). Language: python | nodejs | shell.\n" +
-    "  Pass code as argument or pipe via stdin:\n" +
-    "    unik run python 'print(\"hello\")'\n" +
-    "    echo 'print(1+1)' | unik run python\n" +
-    "    cat script.py | unik run python")
-    .option("-t, --timeout <ms>", "Timeout in milliseconds (max 8000)", "8000")
-    .option("--json", "Output raw JSON response")
+// run ─────────────────────────────────────────────────────────────────────────
+program.command("run <language> [code]")
+    .description("Stateless execution. Language: python | nodejs | shell. Reads stdin if code omitted.")
+    .option("-t, --timeout <ms>", "Max 8000ms", "8000")
+    .option("--json", "Force JSON output in interactive mode")
     .action(async (language, codeArg, opts) => {
     const code = codeArg ?? (await readStdin());
-    if (!code) {
-        console.error("Error: provide code as argument or pipe via stdin");
-        process.exit(1);
-    }
-    const client = getClient();
-    const result = await client.execute({
-        language: language,
-        code,
-        timeout_ms: parseInt(opts.timeout),
-    });
-    if (opts.json) {
-        jsonOut(result);
+    if (!code)
+        die("provide code as argument or pipe via stdin");
+    const result = await getClient().execute({ language: language, code, timeout_ms: parseInt(opts.timeout) });
+    if (AGENT_MODE || opts.json) {
+        jsonOut({ ok: result.status === "success", ...result });
+        if (result.status !== "success")
+            process.exit(1);
         return;
     }
     if (result.stdout)
@@ -184,46 +166,31 @@ program
     if (result.stderr)
         process.stderr.write(result.stderr);
     if (result.status !== "success") {
-        console.error(`\n✗ Exited with status: ${result.status} (${result.execution_time_ms}ms)`);
+        console.error(`✗ ${result.status} (${result.execution_time_ms}ms)`);
         process.exit(1);
     }
 });
-// ── sandbox ───────────────────────────────────────────────────────────────────
+// sandbox ─────────────────────────────────────────────────────────────────────
 const sbx = program.command("sandbox").description("Manage persistent sandbox sessions");
-sbx
-    .command("create")
-    .description("Create a new sandbox and print its ID")
-    .option("--json", "Output raw JSON")
-    .action(async (opts) => {
-    const client = getClient();
-    const sandbox = await client.createSandbox();
-    if (opts.json) {
-        jsonOut({ id: sandbox.id });
-    }
-    else {
+sbx.command("create").description("Create a sandbox (15 min TTL). Prints ID on stdout.").option("--json", "Force JSON").action(async (opts) => {
+    const sandbox = await getClient().createSandbox();
+    if (AGENT_MODE || opts.json)
+        jsonOut({ ok: true, id: sandbox.id });
+    else
         console.log(sandbox.id);
-    }
 });
-sbx
-    .command("exec <id> <language> [code]")
-    .description("Run code inside an existing sandbox")
-    .option("-t, --timeout <ms>", "Timeout in milliseconds (max 8000)", "8000")
-    .option("--json", "Output raw JSON")
+sbx.command("exec <id> <language> [code]").description("Run code in a sandbox. Reads stdin if code omitted.")
+    .option("-t, --timeout <ms>", "Max 8000ms", "8000")
+    .option("--json", "Force JSON")
     .action(async (id, language, codeArg, opts) => {
     const code = codeArg ?? (await readStdin());
-    if (!code) {
-        console.error("Error: provide code as argument or pipe via stdin");
-        process.exit(1);
-    }
-    const client = getClient();
-    const sandbox = client.getSandboxHandle(id);
-    const result = await sandbox.execute({
-        language: language,
-        code,
-        timeout_ms: parseInt(opts.timeout),
-    });
-    if (opts.json) {
-        jsonOut(result);
+    if (!code)
+        die("provide code as argument or pipe via stdin");
+    const result = await getClient().getSandboxHandle(id).execute({ language: language, code, timeout_ms: parseInt(opts.timeout) });
+    if (AGENT_MODE || opts.json) {
+        jsonOut({ ok: result.status === "success", sandbox_id: id, ...result });
+        if (result.status !== "success")
+            process.exit(1);
         return;
     }
     if (result.stdout)
@@ -233,58 +200,118 @@ sbx
     if (result.status !== "success")
         process.exit(1);
 });
-sbx
-    .command("delete <id>")
-    .description("Delete a sandbox")
-    .action(async (id) => {
-    const client = getClient();
-    await client.deleteSandbox(id);
-    console.log(`✓ Sandbox ${id} deleted`);
+sbx.command("delete <id>").description("Delete a sandbox").option("--dry-run", "Preview only").action(async (id, opts) => {
+    if (opts.dryRun) {
+        out(`[dry-run] Would delete sandbox id=${id}`, { ok: true, dry_run: true, id });
+        return;
+    }
+    await getClient().deleteSandbox(id);
+    out(`✓ Sandbox ${id} deleted`, { ok: true, id, deleted: true });
 });
-sbx
-    .command("upload <id> <path> [content]")
-    .description("Upload a file into a sandbox (base64 content, or pipe stdin)")
-    .action(async (id, path, contentArg) => {
-    const raw = contentArg ?? (await readStdin());
-    const b64 = Buffer.from(raw).toString("base64");
-    const client = getClient();
-    const sandbox = client.getSandboxHandle(id);
-    const file = await sandbox.uploadFile(path, b64);
-    console.log(`✓ Uploaded ${file.path} (${file.size_bytes} bytes)`);
+sbx.command("upload <id> <remote-path>").description("Upload a file. Pipe content to stdin or use -f <local>.")
+    .option("-f, --file <path>", "Local file path")
+    .action(async (id, remotePath, opts) => {
+    const raw = opts.file ? readFileSync(opts.file) : Buffer.from(await readStdin());
+    const file = await getClient().getSandboxHandle(id).uploadFile(remotePath, Buffer.from(raw).toString("base64"));
+    out(`✓ Uploaded ${file.path} (${file.size_bytes} bytes)`, { ok: true, file });
 });
-sbx
-    .command("ls <id> [path]")
-    .description("List files in a sandbox")
-    .action(async (id, path = "") => {
-    const client = getClient();
-    const sandbox = client.getSandboxHandle(id);
-    const files = await sandbox.listFiles(path);
-    if (files.length === 0) {
+sbx.command("ls <id> [path]").description("List files in a sandbox").action(async (id, path = "") => {
+    const files = await getClient().getSandboxHandle(id).listFiles(path);
+    if (AGENT_MODE) {
+        jsonOut({ ok: true, count: files.length, items: files });
+        return;
+    }
+    if (!files.length) {
         console.log("(empty)");
         return;
     }
-    for (const f of files) {
+    for (const f of files)
         console.log(`  ${f.path}  (${f.size_bytes}B)`);
-    }
 });
-// ── status ────────────────────────────────────────────────────────────────────
-program
-    .command("status")
-    .description("Check if the server is healthy")
-    .option("--json", "Output raw JSON")
-    .action(async (opts) => {
+// status ──────────────────────────────────────────────────────────────────────
+program.command("status").description("Check server health").option("--json", "Force JSON").action(async (opts) => {
     const cfg = loadConfig();
-    const baseUrl = cfg.base_url ?? DEFAULT_BASE_URL;
-    const res = await fetch(`${baseUrl}/readyz`).then((r) => r.json());
-    if (opts.json) {
+    const res = await fetch(`${cfg.base_url ?? DEFAULT_BASE_URL}/readyz`).then((r) => r.json());
+    if (AGENT_MODE || opts.json) {
         jsonOut(res);
+        return;
     }
-    else {
-        const r = res;
-        console.log("Status:", r.status);
-        for (const [name, check] of Object.entries(r.checks ?? {})) {
-            console.log(`  ${check.ok ? "✓" : "✗"} ${name}`);
+    console.log("Status:", res.status);
+    for (const [name, check] of Object.entries(res.checks ?? {}))
+        console.log(`  ${check.ok ? "✓" : "✗"} ${name}`);
+});
+// mcp ─────────────────────────────────────────────────────────────────────────
+// One binary = CLI + MCP server. Add to MCP config: { "command": "unik", "args": ["mcp"] }
+program.command("mcp")
+    .description('Run as an MCP server over stdio (JSON-RPC 2.0). Add to MCP config: { "command": "unik", "args": ["mcp"] }')
+    .action(async () => {
+    const cfg = loadConfig();
+    if (!cfg.api_key && !cfg.auth_token)
+        die("no credentials for MCP mode", { hint: "unik auth set-key <key>" });
+    const baseUrl = cfg.base_url ?? DEFAULT_BASE_URL;
+    const headers = { "Content-Type": "application/json" };
+    if (cfg.api_key)
+        headers["x-api-key"] = cfg.api_key;
+    if (cfg.auth_token)
+        headers["Authorization"] = `Bearer ${cfg.auth_token}`;
+    const rl = createInterface({ input: process.stdin, terminal: false });
+    rl.on("line", async (line) => {
+        const trimmed = line.trim();
+        if (!trimmed)
+            return;
+        let msg;
+        try {
+            msg = JSON.parse(trimmed);
         }
-    }
+        catch {
+            process.stdout.write(JSON.stringify({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "Parse error" } }) + "\n");
+            return;
+        }
+        try {
+            const resp = await fetch(`${baseUrl}/mcp`, { method: "POST", headers, body: JSON.stringify(msg) });
+            const body = await resp.text();
+            for (const chunk of body.split("\n").filter(Boolean))
+                process.stdout.write(chunk + "\n");
+        }
+        catch (err) {
+            const req = msg;
+            process.stdout.write(JSON.stringify({ jsonrpc: "2.0", id: req?.id ?? null, error: { code: -32603, message: String(err) } }) + "\n");
+        }
+    });
+    await new Promise((resolve) => rl.on("close", resolve));
 });
+// ─── Schema (for unik schema command) ────────────────────────────────────────
+const SCHEMA = {
+    name: "unik", version: "1.1.0",
+    description: "Unikraft sandbox CLI — unikernel-isolated code execution",
+    agent_note: "stdout is JSON when stdout is not a TTY. Exit 0 = success, exit 1 = error. Errors go to stderr as JSON { ok: false, error: string }.",
+    commands: [
+        { command: "unik run <language> [code]", description: "Stateless execution. Reads stdin if code omitted.", args: { language: "python|nodejs|shell", code: "string (optional)" }, options: { "--timeout <ms>": "max 8000 (default 8000)" }, output: { ok: "bool", status: "success|error|timeout", stdout: "string", stderr: "string", execution_time_ms: "number" } },
+        { command: "unik sandbox create", output: { ok: "bool", id: "sbx_..." } },
+        { command: "unik sandbox exec <id> <language> [code]", output: { ok: "bool", sandbox_id: "string", status: "success|error|timeout", stdout: "string", stderr: "string", execution_time_ms: "number" } },
+        { command: "unik sandbox delete <id>", options: { "--dry-run": "safe preview" }, output: { ok: "bool", id: "string", deleted: "bool" } },
+        { command: "unik sandbox upload <id> <remote-path>", options: { "-f <localPath>": "file path (else stdin)" }, output: { ok: "bool", file: { path: "string", size_bytes: "number" } } },
+        { command: "unik sandbox ls <id> [path]", output: { ok: "bool", count: "number", items: [{ path: "string", size_bytes: "number" }] } },
+        { command: "unik keys create", options: { "--label": "string", "--expires": "ISO 8601", "--no-save": "don't persist" }, output: { ok: "bool", id: "string", key: "uk_live_...", prefix: "string", saved: "bool" } },
+        { command: "unik keys list", output: { ok: "bool", count: "number", items: [{ id: "string", prefix: "string", label: "string|null", revoked_at: "string|null" }] } },
+        { command: "unik keys revoke <id>", options: { "--dry-run": "safe preview" }, output: { ok: "bool", revoked: "bool" } },
+        { command: "unik auth set-key <key>", output: { ok: "bool", prefix: "string" } },
+        { command: "unik auth set-token <jwt>", output: { ok: "bool" } },
+        { command: "unik auth set-url <url>", output: { ok: "bool", base_url: "string" } },
+        { command: "unik auth whoami", output: { base_url: "string", api_key_prefix: "string|null", has_jwt: "bool" } },
+        { command: "unik status", output: { status: "ready|not_ready", checks: { cloud: { ok: "bool" }, database: { ok: "bool" } } } },
+        { command: "unik mcp", description: "MCP server over stdio. Add to MCP config: { \"command\": \"unik\", \"args\": [\"mcp\"] }" },
+        { command: "unik schema", description: "Output this schema as JSON." },
+    ],
+    invariants: [
+        "All outputs are JSON when stdout is not a TTY.",
+        "Exit 0 = success. Exit 1 = error.",
+        "Errors go to stderr as JSON: { ok: false, error: string }.",
+        "sandbox IDs start with 'sbx_'.",
+        "API keys start with 'uk_live_'.",
+        "Execution timeout max is 8000ms.",
+        "--dry-run is safe on all destructive ops (delete, revoke).",
+        "Credentials live in ~/.unik/config.json.",
+    ],
+};
 program.parseAsync(process.argv);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unikernelai/sandbox-cli",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "CLI for the Unikraft sandbox API — run code, manage sandboxes, provision API keys",
   "type": "module",
   "bin": {
@@ -8,7 +8,8 @@
   },
   "main": "dist/cli.js",
   "files": [
-    "dist"
+    "dist",
+    "SKILL.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",