@ghostystudio/cli 0.9.0 → 0.10.0

package/README.md

@@ -8,24 +8,32 @@ npx -y @ghostystudio/cli login
 npm i -g @ghostystudio/cli && ghosty login
 ```
 
-`ghosty login` opens your browser (OAuth2 + PKCE). If you already have a session on ghosty.studio, opening the link is all it takes. A coding agent can drive it for you: `ghosty login --json` prints `{"event":"login_url","url":…}` first so the agent can hand you the link.
+`ghosty login` opens your browser (OAuth2 + PKCE). If you already have a session on ghosty.studio, opening the link is all it takes. A coding agent can drive it for you: `ghosty login --json` prints `{"event":"login_url","url":…}` first so the agent can hand you the link. Over SSH, CI or from another device, `ghosty login --device` gives you a link + code instead (automatic when there is no local browser).
 
 ## Commands
 
 ```bash
 ghosty whoami
+ghosty usage                                          # plan and usage this week / month (also: ghosty me usage)
 ghosty agents ls
+ghosty agents create --name NAME [--engine E] [--model M] [--prompt TEXT | --prompt-file FILE] [--env K=V,…]
 ghosty agents get <id> [--fields name,model,prompt]
-ghosty agents set <id> [--name] [--model] [--prompt | --prompt-file FILE]
+ghosty agents set <id> [--name] [--engine] [--model] [--prompt | --prompt-file FILE] [--env K=V,…] [--connect ID,…] [--disconnect ID,…]
+ghosty agents rm <id> [--yes]
 ghosty agents restart <id>
+ghosty agents box <id> [--check PATH]… [--contains PATH=TEXT]… [--recycle]   # is its machine on the new image?
+ghosty agents demo <id> [--slug NAME] [--on | --off] [--vence "YYYY-MM-DDTHH:MM"|no] [--turns N] [--per-ip N]
+                        [--welcome TEXT] [--starter TEXT] [--chips "a|b|c"] [--sponsor on|off] [--rotate]   # public /p/ link, no account needed
 ghosty agents doctor <id> [--verbose]                 # exits 1 when it finds a problem
 ghosty agents docs ls|grant|revoke <id> [doc]         [--write] [--no-deliver]
 ghosty agents set <id> --voice elevenlabs:ID --voice-replies auto --auto-stage on
 
 ghosty files ls|get|put|rm <id> [path]   [--file LOCAL] [--out LOCAL]
-ghosty skills ls|get|add|rm <id> [slug]  [--file SKILL.md | --dir FOLDER] [--out DIR]
-ghosty dbs ls|tables|query|import|grant|revoke <id> [db]   [--write] [--external-write t1,t2] [--from easybits:ID --dry-run]
-ghosty turns ls <id>                     [--errors] [--since 1h] [--limit N]
+ghosty skills ls|get|add|rm <id> [slug]  [--file SKILL.md | --dir FOLDER] [--out DIR]   # get without --out only lists
+ghosty skills templates <id>             # pdf-doc templates: its own and Ghosty's, and which folder wins
+ghosty dbs ls|tables|query|import|grant|revoke <id> [db]   [--write] [--arg V]… [--external-write t1,t2] [--from easybits:ID --tables a,b --append --dry-run]
+ghosty turns ls <id>                     [--errors | --status running|done|stopped|error] [--since 1h] [--limit N]
+ghosty turns show <id> [turn-id|last]    # where a turn's time went: each tool with its seconds, output tokens
 ghosty channels whatsapp ls|enable|disable <id> [number]   [--dry-run]
 ghosty board archive <id>                --integration X | --column X | --before 30d   [--dry-run]
 ghosty mcp get|set <id>                  [--file servers.json]
@@ -43,20 +51,36 @@ ghosty schedule rm <id> <schedule-id>
 ghosty me files ls|upload|rm             [--kind image|video|audio|document|other]
 ghosty credentials ls|set|rm [provider]  [--from-env VAR]   # never as an argument
 ghosty docs
+
+ghosty partner ls|enable|credentials|agent|tenants|audit|try   # one agent for each of YOUR customers: ghosty partner --help
 ```
 
-Global: `--json` (stdout is JSON only), `--token <token>` / `GHOSTY_TOKEN` (a `gat_…` agent token reaches only that agent), `--help`, `--version`.
+Global: `--json` (stdout is JSON only), `--token <token>` / `GHOSTY_TOKEN` (a `gat_…` agent token reaches only that agent), `--profile <name>` / `GHOSTY_PROFILE` (a separate saved session, e.g. one per account), `--yes`, `--help`, `--version`. Env: `GHOSTY_URL`, `XDG_CONFIG_HOME`, `NO_COLOR`, `GHOSTY_NO_UPDATE_CHECK`; partner commands sign with `GHOSTY_PARTNER_KEY` + `GHOSTY_PARTNER_SECRET` when set.
+
+Aliases: `creds` = `credentials`, `db` = `dbs`, `dbs sql` = `dbs query`.
 
 Every command has its own help with examples: `ghosty <command> --help` or `ghosty help <command>`.
 
 Exit codes: `0` ok · `1` API error · `2` usage error · `3` not signed in.
 
+### Changes in 0.9.1
+
+- `ghosty agents --help` describes every `agents demo` flag; `ghosty usage --help` has its own page.
+- "Learn more" links point to the exact section of https://www.ghosty.studio/docs/cli/comandos; `partner --help` links to /docs/cli/partners.
+
 ### Changes in 0.9.0
 
 - `try --waba`: a test turn through the **real** WhatsApp Business path (inherited context, price rule, board, voice decision). It prints what it would have sent (text, voice note, files) and sends nothing. `--media` for photos/audio/PDF and `--history` to seed what was said before. `--whatsapp` is now an alias.
 - `try --replay FILE --out DIR`: replays real conversations from your machine. The report is written after every step, survives Ghosty deploys (it honors `Retry-After`), and `--resume` continues a partial run.
 - `agents doctor` speaks English like the rest of the CLI; `channels whatsapp ls` returns a full URL.
 
+### Changes in 0.10.0
+
+- Tells you when a new version is out (checks npm once a day, on stderr; `GHOSTY_NO_UPDATE_CHECK=1` or `CI` turns it off). An unknown option on an old version says to update.
+- `skills get` without `--out` only lists the files; with `--out` it prints the absolute path. It no longer writes into the current folder silently.
+- New: `turns show` (timeline of one turn), `skills templates` (pdf-doc templates and their source), `agents box` (check / recycle the machine serving an agent).
+- `agents get` includes `env` (secret-looking values masked).
+
 ### Changes in 0.8.0
 
 - Destructive commands (`agents rm`, `files rm`, `skills rm`, `credentials rm`, `board archive`, `dbs import` over existing rows, `channels whatsapp enable`) ask first. **Without a terminal they need `--yes`** or exit `2`.

package/dist/index.js

@@ -129,7 +129,7 @@ async function login() {
   const verifier = b64url(randomBytes(32));
   const challenge = b64url(createHash("sha256").update(verifier).digest());
   const state = b64url(randomBytes(16));
-  const { code, redirectUri } = await new Promise((resolve, reject) => {
+  const { code, redirectUri } = await new Promise((resolve2, reject) => {
     const server = createServer((req, res) => {
       const u = new URL(req.url ?? "/", "http://127.0.0.1");
       if (u.pathname !== "/cb") {
@@ -140,7 +140,7 @@ async function login() {
       res.writeHead(ok ? 200 : 400, { "content-type": "text/html; charset=utf-8" }).end(CLOSE_PAGE(ok, base));
       clearTimeout(timer);
       server.close();
-      if (ok) resolve({ code: u.searchParams.get("code"), redirectUri: redirectUri2 });
+      if (ok) resolve2({ code: u.searchParams.get("code"), redirectUri: redirectUri2 });
       else reject(new CliError(`Login was not completed (${u.searchParams.get("error") ?? "state mismatch"}).`, EXIT.AUTH, "Run: ghosty login"));
     });
     let redirectUri2 = "";
@@ -278,11 +278,11 @@ async function postLong(path, body, timeoutMs = 9e5) {
   const token = await currentToken();
   const httpsRequest = base.startsWith("https:") ? (await import("node:https")).request : (await import("node:http")).request;
   const data = JSON.stringify(body);
-  return new Promise((resolve) => {
+  return new Promise((resolve2) => {
     const req = httpsRequest(`${base}${path}`, {
       method: "POST",
       timeout: timeoutMs,
-      headers: { authorization: `Bearer ${token}`, "user-agent": `ghosty-cli/${"0.9.0"}`, "content-type": "application/json", "content-length": Buffer.byteLength(data) }
+      headers: { authorization: `Bearer ${token}`, "user-agent": `ghosty-cli/${"0.10.0"}`, "content-type": "application/json", "content-length": Buffer.byteLength(data) }
     }, (res) => {
       let buf = "";
       res.on("data", (c) => buf += c);
@@ -293,11 +293,11 @@ async function postLong(path, body, timeoutMs = 9e5) {
         } catch {
           parsed = { error: buf.slice(0, 300) };
         }
-        resolve({ status: res.statusCode ?? 0, retryAfter: retryAfterSeconds(res.headers["retry-after"]), body: parsed });
+        resolve2({ status: res.statusCode ?? 0, retryAfter: retryAfterSeconds(res.headers["retry-after"]), body: parsed });
       });
     });
     req.on("timeout", () => req.destroy(new Error(`no answer in ${Math.round(timeoutMs / 6e4)} min`)));
-    req.on("error", (e) => resolve({ status: 0, retryAfter: null, body: { error: String(e) } }));
+    req.on("error", (e) => resolve2({ status: 0, retryAfter: null, body: { error: String(e) } }));
     req.end(data);
   });
 }
@@ -324,7 +324,7 @@ async function request(path, opts = {}, retried = false) {
     method: opts.method ?? (opts.body !== void 0 || opts.raw !== void 0 ? "POST" : "GET"),
     headers: {
       authorization: `Bearer ${token}`,
-      "user-agent": `ghosty-cli/${"0.9.0"}`,
+      "user-agent": `ghosty-cli/${"0.10.0"}`,
       ...opts.body !== void 0 ? { "content-type": "application/json" } : {},
       ...opts.headers
     },
@@ -358,7 +358,7 @@ async function toError(res) {
 // src/commands/agents.ts
 import { mkdir as mkdir3, readdir, readFile as readFile3, writeFile as writeFile3 } from "node:fs/promises";
 import { homedir as homedir2 } from "node:os";
-import { dirname as dirname2, join as join3, relative } from "node:path";
+import { dirname as dirname2, join as join3, relative, resolve } from "node:path";
 
 // src/prompt.ts
 import { createInterface } from "node:readline/promises";
@@ -672,7 +672,7 @@ async function readSkillDir(dir) {
 }
 var trashDir = (id, slug) => join3(process.env.XDG_CONFIG_HOME || join3(homedir2(), ".config"), "ghosty", "trash", id, `${slug}-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")}`);
 async function skillsCmd(sub, id, slug, v) {
-  const ex = "ghosty skills ls <agent-id> | get <agent-id> <slug> | add <agent-id> <slug> [--file SKILL.md | --dir FOLDER] | rm <agent-id> <slug>";
+  const ex = "ghosty skills ls <agent-id> | get <agent-id> <slug> [--out DIR] | templates <agent-id> | add <agent-id> <slug> [--file SKILL.md | --dir FOLDER] | rm <agent-id> <slug>";
   id = need(id, "agent id", ex);
   switch (sub ?? "ls") {
     case "ls":
@@ -691,7 +691,13 @@ ${dim(`${more} more in the community catalog: ghosty skills add <agent-id> <slug
     case "get": {
       slug = need(slug, "skill slug", "ghosty skills get <agent-id> <slug> [--out DIR]");
       const sk = await api(agentPath(id, `/skills/${enc2(slug)}`));
-      const dir = v.out ?? slug;
+      if (!v.out) {
+        const files = sk.files.map((f) => ({ path: f.path, bytes: Buffer.from(f.contentBase64, "base64").length }));
+        out({ slug, files, saved: null }, () => `${table(files, ["path", "bytes"])}
+${dim(`Download: ghosty skills get ${id} ${slug} --out DIR`)}`);
+        return;
+      }
+      const dir = resolve(v.out);
       const bytes = await writeSkill(dir, sk);
       out({ slug, saved: dir, files: sk.files.map((f) => f.path), bytes }, () => `${lavender("\u2713")} ${slug} \u2192 ${dir}/ ${dim(`(${sk.files.length} file(s), ${bytes} bytes)`)}`);
       return;
@@ -704,6 +710,13 @@ ${dim(`${more} more in the community catalog: ghosty skills add <agent-id> <slug
       out(r, () => `${lavender("\u2713")} Skill ${slug} installed.${r?.nota ? dim(` (${r.nota})`) : ""}`);
       return;
     }
+    case "templates": {
+      const r = await api(agentPath(id, "/templates"));
+      const rows = r.templates.map((t) => ({ name: t.name, source: t.source, used: t.active ? "yes" : "no (shadowed)", description: (t.description ?? "").replace(/\s+/g, " ").slice(0, 60) }));
+      out(r, () => `${table(rows, ["name", "source", "used", "description"])}
+${dim(`pdf-doc reads from: ${r.active ?? "(not found)"}`)}`);
+      return;
+    }
     case "rm":
     case "remove": {
       slug = need(slug, "skill slug", ex);
@@ -744,7 +757,7 @@ async function agentsDemo(id, v) {
   if (v.on) body.enabled = true;
   if (v.off) body.enabled = false;
   if (v.turns) body.maxTurns = Number(v.turns);
-  if (v.hours) body.trialHours = Number(v.hours);
+  if (v.vence !== void 0) body.venceEl = v.vence === "no" ? null : new Date(v.vence).toISOString();
   if (v["per-ip"]) body.perIpDay = Number(v["per-ip"]);
   if (v.welcome !== void 0) body.welcome = v.welcome;
   if (v.chips !== void 0) body.chips = v.chips.split("|").map((c) => c.trim()).filter(Boolean);
@@ -759,7 +772,7 @@ async function agentsDemo(id, v) {
     d,
     () => [
       `${d.enabled ? lavender("\u25CF on") : dim("\u25CB off")}  ${d.url ?? dim("(no link yet: --slug NAME)")}`,
-      dim(`trial: ${d.trialHours} h from the first message \xB7 cap ${d.maxTurns} messages per visitor \xB7 ${d.perIpDay} per IP per day`),
+      dim(`expires: ${d.venceEl ? new Date(d.venceEl).toLocaleString("es-MX") : "never"} \xB7 cap ${d.maxTurns} messages per visitor \xB7 ${d.perIpDay} per IP per day`),
       d.welcome ? `welcome: ${d.welcome}` : dim("welcome: (default greeting)"),
       d.starter ? `starter: \u2728 ${d.starter}` : dim("starter: (none)"),
       d.chips.length ? `chips: ${d.chips.join(" | ")}` : dim("chips: (default)"),
@@ -768,6 +781,28 @@ async function agentsDemo(id, v) {
     ].join("\n")
   );
 }
+async function agentsBox(id, v) {
+  id = need(id, "agent id", "ghosty agents box <agent-id> [--check /opt/claude-worker/skills/pdf-doc/templates/calendario.html] [--recycle]");
+  if (v.recycle) {
+    const r2 = await api(agentPath(id, "/box"), { method: "POST", body: { recycle: true } });
+    out(r2, () => `${lavender("\u2713")} Recycled. ${dim(r2?.note ?? "")}
+${dim(`Verify after one turn: ghosty agents box ${id} --check <path>`)}`);
+    return;
+  }
+  const q = new URLSearchParams();
+  for (const c of v.check ?? []) q.append("check", c);
+  for (const c of v.contains ?? []) q.append("contains", c);
+  const r = await api(agentPath(id, `/box?${q}`));
+  out(r, () => {
+    if (!r.boxes.length) return dim(r.note ?? "No live box.");
+    const lines = r.boxes.flatMap((b) => [
+      `${bold(b.sandboxId)} ${dim(b.lastMessageAt ? `last message ${b.lastMessageAt}` : r.kind)}${b.error ? ` ${red(b.error)}` : ""}`,
+      ...b.checks.map((c) => `  ${c.ok ? lavender("\u2713") : red("\u2717")} ${c.path}${c.contains !== void 0 ? ` \u220B ${c.contains}` : ""}`)
+    ]);
+    const verdict = !(v.check?.length || v.contains?.length) ? dim("Alive. Add --check PATH to confirm the new image.") : r.stale ? red(`${r.stale} box(es) on an OLD image: ghosty agents box ${id} --recycle`) : `${lavender("\u2713")} Serving with the expected image.`;
+    return [...lines, verdict].join("\n");
+  });
+}
 
 // src/commands/chat.ts
 import { randomUUID } from "node:crypto";
@@ -1069,7 +1104,7 @@ ${bold("Options")}
   --json             Machine-readable output
 
 ${bold("Server credential mode")}  GHOSTY_PARTNER_KEY=gpk_\u2026 GHOSTY_PARTNER_SECRET=gps_\u2026 ghosty partner agent get
-${dim("Docs: https://www.ghosty.studio/docs/cli")}`;
+${dim("Docs: https://www.ghosty.studio/docs/cli/partners")}`;
 var enc5 = encodeURIComponent;
 function partnerCreds() {
   const key = process.env.GHOSTY_PARTNER_KEY;
@@ -1090,7 +1125,7 @@ async function call(path, v, init = {}) {
         "x-ghosty-ts": ts,
         "x-ghosty-sig": sig,
         "content-type": "application/json",
-        "user-agent": `ghosty-cli/${"0.9.0"}`
+        "user-agent": `ghosty-cli/${"0.10.0"}`
       },
       body: method === "GET" ? void 0 : raw
     });
@@ -1364,8 +1399,9 @@ async function agentDocsCmd(sub, id, doc, v) {
       throw usage(`Unknown agents docs subcommand: ${sub}.`, "Try: ghosty agents docs ls | grant | revoke");
   }
 }
-async function turnsCmd(sub, id, v) {
-  if (sub && sub !== "ls" && sub !== "list") throw usage(`Unknown turns subcommand: ${sub}.`, "Try: ghosty turns ls <agent-id> --errors --since 1h");
+async function turnsCmd(sub, id, turnId, v) {
+  if (sub === "show") return turnShow(id, turnId);
+  if (sub && sub !== "ls" && sub !== "list") throw usage(`Unknown turns subcommand: ${sub}.`, "Try: ghosty turns ls <agent-id> --errors --since 1h \xB7 ghosty turns show <agent-id> [turn-id|last]");
   id = need2(id, "agent id", "ghosty turns ls <agent-id> --errors --since 1h");
   const q = new URLSearchParams();
   const status = v.errors ? "error" : v.status;
@@ -1375,6 +1411,7 @@ async function turnsCmd(sub, id, v) {
   const r = await api(agentPath2(id, `/turns?${q}`));
   const when = (s) => s.slice(0, 16).replace("T", " ");
   const rows = r.turns.map((t) => ({
+    id: t.id,
     started: when(t.startedAt),
     state: t.state === "error" ? red(t.state) : t.state,
     secs: t.ms == null ? "" : Math.round(t.ms / 1e3),
@@ -1383,8 +1420,24 @@ async function turnsCmd(sub, id, v) {
     error: (t.error ?? "").replace(/\s+/g, " ").slice(0, 90)
   }));
   const tally = Object.entries(r.counts).map(([k, n]) => `${k} ${n}`).join(" \xB7 ");
-  out(r, () => rows.length ? `${table(rows, ["started", "state", "secs", "from", "session", "error"])}
-${dim(`${v.since ? `since ${v.since}: ` : ""}${tally}`)}` : dim(`No ${status ?? ""} turns${v.since ? ` since ${v.since}` : ""}.`));
+  out(r, () => rows.length ? `${table(rows, ["id", "started", "state", "secs", "from", "session", "error"])}
+${dim(`${v.since ? `since ${v.since}: ` : ""}${tally} \xB7 where the time went: ghosty turns show ${id} <turn-id>`)}` : dim(`No ${status ?? ""} turns${v.since ? ` since ${v.since}` : ""}.`));
+}
+async function turnShow(id, turnId) {
+  id = need2(id, "agent id", "ghosty turns show <agent-id> [turn-id|last]");
+  const r = await api(agentPath2(id, `/turns/${enc6(turnId ?? "last")}`));
+  out(r, () => {
+    const t = r.turn;
+    const head = `${bold(t.id)}  ${t.state === "error" ? red(t.state) : t.state}  ${t.secs ?? "?"} s  ${dim(`${r.totals.model ?? ""} \xB7 ${r.totals.modelCalls} model calls \xB7 ${r.totals.outputTokens} output tokens \xB7 ${r.totals.toolSecs} s in tools`)}`;
+    const line = (s) => {
+      const at = `+${s.at.toFixed(1)}s`.padStart(8);
+      if (s.kind === "tool") return `${at}  ${bold(s.tool ?? "?")} ${dim(s.input ?? "")}  ${s.secs === void 0 ? red("(no result)") : `${s.secs} s`}${s.error ? red(" error") : ""}`;
+      const tok = s.outTokens ? dim(` [${s.outTokens} out]`) : "";
+      return s.kind === "thinking" ? `${at}  ${dim("thinking")}${tok}` : `${at}  ${s.text}${tok}`;
+    };
+    const top = r.byTool.slice(0, 5).map((b) => `${b.tool} ${b.secs} s (${b.calls})`).join(" \xB7 ");
+    return [head, ...r.steps.map(line), dim(`slowest: ${top || "\u2014"}`)].join("\n");
+  });
 }
 async function agentsDoctor(id, v) {
   id = need2(id, "agent id", "ghosty agents doctor <agent-id>");
@@ -1416,7 +1469,7 @@ async function hiddenPrompt(label) {
   stdin.setRawMode(true);
   stdin.resume();
   stdin.setEncoding("utf8");
-  return new Promise((resolve, reject) => {
+  return new Promise((resolve2, reject) => {
     let value = "";
     const onData = (chunk) => {
       for (const ch of chunk) {
@@ -1425,7 +1478,7 @@ async function hiddenPrompt(label) {
           stdin.pause();
           stdin.off("data", onData);
           process.stderr.write("\n");
-          return resolve(value);
+          return resolve2(value);
         }
         if (ch === "") {
           stdin.setRawMode(false);
@@ -1537,6 +1590,7 @@ Archive ${plan.matched} card(s) on \xAB${plan.board}\xBB? (reversible: a new mes
 
 // src/help.ts
 var DOCS = "https://www.ghosty.studio/docs/cli";
+var REF = `${DOCS}/comandos`;
 var HELPS = {
   agents: {
     summary: "Create, inspect, change, check and delete agents.",
@@ -1548,7 +1602,8 @@ var HELPS = {
       "ghosty agents doctor <agent-id> [--verbose]",
       "ghosty agents docs ls|grant|revoke <agent-id> [doc] [--write] [--no-deliver]",
       "ghosty agents restart <agent-id>",
-      "ghosty agents demo <agent-id> [--slug NAME] [--on | --off] \u2026",
+      "ghosty agents box <agent-id> [--check PATH]\u2026 [--contains PATH=TEXT]\u2026 [--recycle]",
+      'ghosty agents demo <agent-id> [--slug NAME] [--on | --off] [--vence "YYYY-MM-DDTHH:MM"|no] [--turns N] [--per-ip N] [--welcome TEXT] [--starter TEXT] [--chips "a|b|c"] [--sponsor on|off] [--rotate]',
       "ghosty agents rm <agent-id> [--yes]"
     ],
     flags: [
@@ -1559,28 +1614,44 @@ var HELPS = {
       ["--verbose", "doctor: also list the checks that passed"],
       ["--write", "docs grant: the agent may replace the document (default: read only)"],
       ["--no-deliver", "docs grant: it can read it but never send it to whoever writes"],
-      ["--yes", "rm: skip the confirmation (required without a terminal)"]
+      ["--yes", "rm: skip the confirmation (required without a terminal)"],
+      ["--slug NAME", "demo: link name; a 6-char code is appended (/p/NAME-CODE)"],
+      ["--on | --off", "demo: turn the public link on or off"],
+      ["--vence DATE|no", `demo: fixed expiry in your machine's time ("2026-10-15T20:00"); no = never`],
+      ["--turns N", "demo: messages per visitor (default 150)"],
+      ["--per-ip N", "demo: messages per IP per day (default 30)"],
+      ["--welcome TEXT", "demo: chat greeting (empty = default)"],
+      ["--starter TEXT", 'demo: highlighted first suggestion ("" removes it)'],
+      ['--chips "a|b|c"', "demo: suggestions, separated by |"],
+      ["--sponsor on|off", "demo: copies people keep run on YOUR engine key"],
+      ["--rotate", "demo: new code; the old link stops working"],
+      ["--check PATH", "box: this file must exist in the machine (repeatable), e.g. a file the new image brings"],
+      ["--contains PATH=TEXT", "box: that file must contain TEXT (a change that adds no files)"],
+      ["--recycle", "box: replace its machines (not mid-turn); the new one starts on the next turn. ACP: use restart"]
     ],
     examples: [
       "ghosty agents doctor cmu7pgbyr0001gee3ruk172mm",
       "ghosty agents set <id> --prompt-file PROMPT.md",
       "ghosty agents set <id> --voice elevenlabs:21m00Tcm4TlvDq8ikWAM --voice-replies auto --auto-stage on",
       'ghosty agents docs grant <id> "Cat\xE1logo 2026.pdf"',
-      "ghosty agents docs grant <id> precios.xlsx --write --no-deliver"
+      "ghosty agents docs grant <id> precios.xlsx --write --no-deliver",
+      'ghosty agents demo <id> --slug guardias --on --vence "2026-10-15T20:00" --starter "Ens\xE9\xF1ame c\xF3mo empezar"',
+      "ghosty agents box <id> --check /opt/claude-worker/skills/pdf-doc/templates/calendario.html"
     ],
-    notes: ["doctor exits 1 when it finds a problem, so it can gate a script or CI."],
-    learn: `${DOCS}#agents`
+    notes: ["doctor exits 1 when it finds a problem, so it can gate a script or CI.", "demo with no flags only prints its status: link, expiry, caps and numbers."],
+    learn: `${REF}#agentes`
   },
   skills: {
     summary: "Skills of an agent (agentskills.io format: a folder with SKILL.md).",
     usage: [
       "ghosty skills ls <agent-id>",
       "ghosty skills get <agent-id> <slug> [--out DIR]",
+      "ghosty skills templates <agent-id>",
       "ghosty skills add <agent-id> <slug> [--file SKILL.md | --dir FOLDER]",
       "ghosty skills rm <agent-id> <slug> [--yes]"
     ],
     flags: [
-      ["--out DIR", "get: folder to write into (default ./<slug>)"],
+      ["--out DIR", "get: folder to write into; without it, get only lists the files"],
       ["--file FILE", "add: upload one SKILL.md"],
       ["--dir FOLDER", "add: upload a whole skill folder (SKILL.md + assets); restores a backup"],
       ["--yes", "rm: skip the confirmation (required without a terminal)"]
@@ -1591,8 +1662,11 @@ var HELPS = {
       "ghosty skills add <id> pdf-doc          # from the community catalog",
       "ghosty skills rm <id> cotizacion        # keeps a local copy first"
     ],
-    notes: ["rm saves a copy under ~/.config/ghosty/trash/ and prints the command that restores it."],
-    learn: `${DOCS}#skills`
+    notes: [
+      "rm saves a copy under ~/.config/ghosty/trash/ and prints the command that restores it.",
+      "templates reads a live machine (run one turn first). pdf-doc uses the FIRST folder with print.css: a full skill of your own shadows Ghosty's templates."
+    ],
+    learn: `${REF}#skills`
   },
   dbs: {
     summary: "Databases an agent can use, and what it may write from customer channels.",
@@ -1621,31 +1695,32 @@ var HELPS = {
       "ghosty dbs import <id> totequim --from easybits:6a10c84c\u2026 --dry-run   # reads $EASYBITS_API_KEY"
     ],
     notes: ["<db> is the database id or its name. From owner channels the agent reads and writes everything granted."],
-    learn: `${DOCS}#dbs`
+    learn: `${REF}#bases-de-datos`
   },
   turns: {
-    summary: "An agent's recent turns: what answered, what failed and why.",
-    usage: ["ghosty turns ls <agent-id> [--errors | --status STATE] [--since 1h] [--limit N]"],
+    summary: "An agent's recent turns: what answered, what failed and why, and where one turn's time went.",
+    usage: ["ghosty turns ls <agent-id> [--errors | --status STATE] [--since 1h] [--limit N]", "ghosty turns show <agent-id> [turn-id | last]"],
     flags: [
       ["--errors", "only failed turns (same as --status error)"],
       ["--status S", "running | done | stopped | error"],
       ["--since T", "30m, 1h, 2d or an ISO date"],
       ["--limit N", "max rows (default 20, max 500)"]
     ],
-    examples: ["ghosty turns ls <id> --errors --since 1h", "ghosty turns ls <id> --json --limit 100"],
-    learn: `${DOCS}#turns`
+    examples: ["ghosty turns ls <id> --errors --since 1h", "ghosty turns ls <id> --json --limit 100", "ghosty turns show <id>            # last turn: each tool, its seconds, output tokens"],
+    notes: ["show reads the worker's transcript: pool engines only (not ACP/goose)."],
+    learn: `${REF}#turnos`
   },
   files: {
     summary: "Files in the agent's machine.",
     usage: ["ghosty files ls <agent-id> [dir]", "ghosty files get <agent-id> <path> [--out LOCAL]", "ghosty files put <agent-id> <path> [--file LOCAL | < stdin]", "ghosty files rm <agent-id> <path> [--yes]"],
     examples: ["ghosty files put <id> knowledge/precios.md --file precios.md", "cat notas.md | ghosty files put <id> notas.md"],
-    learn: `${DOCS}#files`
+    learn: `${REF}#archivos`
   },
   mcp: {
     summary: "MCP servers of an agent. set REPLACES the whole list.",
     usage: ["ghosty mcp get <agent-id>", "ghosty mcp set <agent-id> --file servers.json"],
     examples: ["ghosty mcp get <id> > servers.json && $EDITOR servers.json && ghosty mcp set <id> --file servers.json"],
-    learn: `${DOCS}#mcp`
+    learn: `${REF}#servidores-mcp`
   },
   try: {
     summary: "Test turns: plain, through the real WhatsApp path (nothing is sent), or a replay of real conversations.",
@@ -1676,25 +1751,25 @@ var HELPS = {
       "Replays survive Ghosty deploys: a 503 is retried after its Retry-After; the report lives on your disk.",
       "--whatsapp is now an alias of --waba."
     ],
-    learn: `${DOCS}#try`
+    learn: `${REF}#turnos-de-prueba`
   },
   chat: {
     summary: "Stream a conversation; with no message it is interactive.",
     usage: ['ghosty chat <agent-id> ["message"] [--conversation ID]', "ghosty conversations ls <agent-id>"],
     examples: ['ghosty chat <id> "hola"', "ghosty chat <id>"],
-    learn: `${DOCS}#chat`
+    learn: `${REF}#conversaciones`
   },
   schedule: {
     summary: "Turns that run later, on the agent's own clock.",
     usage: ['ghosty schedule add <agent-id> "what to do" --in 30m | --at ISO [--every 12h --until ISO] [--conversation ID] [--title T]', "ghosty schedule ls <agent-id>", "ghosty schedule rm <agent-id> <schedule-id>"],
     examples: ['ghosty schedule add <id> "revisa pedidos pendientes" --every 12h --in 1h'],
-    learn: `${DOCS}#schedule`
+    learn: `${REF}#programar-turnos`
   },
   me: {
     summary: "Your account: files and usage.",
     usage: ["ghosty me files ls|upload|rm [--kind image|video|audio|document|other]", "ghosty usage"],
     examples: ["ghosty me files ls --kind document"],
-    learn: `${DOCS}#me`
+    learn: `${REF}#tu-cuenta`
   }
 };
 HELPS.credentials = {
@@ -1710,7 +1785,7 @@ HELPS.credentials = {
     "op read op://vault/claude/token | ghosty credentials set anthropic-oauth"
   ],
   notes: ["The key is never accepted as an argument: it would stay in your shell history and in `ps`."],
-  learn: `${DOCS}#credentials`
+  learn: `${REF}#credenciales`
 };
 HELPS.creds = HELPS.credentials;
 HELPS.channels = {
@@ -1722,7 +1797,7 @@ HELPS.channels = {
   ],
   examples: ["ghosty channels whatsapp ls <id>", "ghosty channels whatsapp enable <id> 5512345678 --dry-run", "ghosty channels whatsapp disable <id> 5512345678"],
   notes: ["<number> is its id, its label or its last digits. One number, one agent: enabling it takes it from the other agent.", "Disabling keeps logging messages; nobody answers them."],
-  learn: `${DOCS}#channels`
+  learn: `${REF}#canales-de-whatsapp`
 };
 HELPS.board = {
   summary: "The agent's sales board. It belongs to the WORKSPACE: you must be a member, a shared agent is not enough.",
@@ -1736,10 +1811,10 @@ HELPS.board = {
   ],
   examples: ["ghosty board archive <id> --integration prueba --dry-run", "ghosty board archive <id> --column Perdido --before 30d --yes"],
   notes: ["Archiving is reversible: when the customer writes again the card comes back. At least one filter is required."],
-  learn: `${DOCS}#board`
+  learn: `${REF}#tablero`
 };
 HELPS.conversations = HELPS.chat;
-HELPS.usage = HELPS.me;
+HELPS.usage = { ...HELPS.me, summary: "Your plan and how much you've used this week and month.", usage: ["ghosty usage", "ghosty me usage"], examples: ["ghosty usage", "ghosty usage --json"], learn: `${REF}#uso` };
 function helpText(cmd) {
   const h = HELPS[cmd];
   if (!h) return void 0;
@@ -1758,6 +1833,43 @@ function helpText(cmd) {
   ].join("\n");
 }
 
+// src/update.ts
+import { mkdir as mkdir4, readFile as readFile6, writeFile as writeFile4 } from "node:fs/promises";
+import { homedir as homedir3 } from "node:os";
+import { dirname as dirname3, join as join4 } from "node:path";
+var FILE = join4(process.env.XDG_CONFIG_HOME || join4(homedir3(), ".config"), "ghosty", "update.json");
+var DAY = 24 * 60 * 60 * 1e3;
+var UPGRADE = "npm i -g @ghostystudio/cli@latest";
+function newer(a, b) {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0; i < 3; i++) if ((pa[i] ?? 0) !== (pb[i] ?? 0)) return (pa[i] ?? 0) > (pb[i] ?? 0);
+  return false;
+}
+async function latestVersion() {
+  if (process.env.GHOSTY_NO_UPDATE_CHECK || process.env.CI) return null;
+  let cache = {};
+  try {
+    cache = JSON.parse(await readFile6(FILE, "utf8"));
+  } catch {
+  }
+  if (!cache.checkedAt || Date.now() - cache.checkedAt > DAY) {
+    try {
+      const r = await fetch("https://registry.npmjs.org/@ghostystudio/cli/latest", { signal: AbortSignal.timeout(1500) });
+      const latest = (await r.json()).version;
+      if (latest) cache = { latest, checkedAt: Date.now() };
+      await mkdir4(dirname3(FILE), { recursive: true });
+      await writeFile4(FILE, JSON.stringify(cache));
+    } catch {
+    }
+  }
+  return cache.latest ?? null;
+}
+async function updateNotice(current) {
+  const latest = await latestVersion();
+  return latest && newer(latest, current) ? `Update available: ${current} \u2192 ${latest}. Run: ${UPGRADE}` : null;
+}
+
 // src/index.ts
 var HELP = `${bold("Usage:")} ghosty <command> [options]
 
@@ -1779,12 +1891,14 @@ ${bold("Agents")}
   agents docs ls|grant|revoke <id> [doc]   Documents it reads and may send   [--write] [--no-deliver]
   agents rm <id>            Delete an agent (owner only; asks you to type its name, or --yes)
   agents restart <id>       Restart an ACP agent (needsRestart) so it loads new skills
+  agents box <id>           The machine serving it: is it on the new image?   [--check PATH]\u2026 [--contains PATH=TEXT]\u2026 [--recycle]
   agents demo <id>          Public demo link /p/<slug>: anyone tries it without an account, "Keep it" clones it to theirs
-                            [--slug NAME] [--on | --off] [--hours N] [--turns N] [--per-ip N] [--welcome TEXT] [--chips "a|b|c"] [--starter TEXT] [--sponsor on|off] [--rotate]
+                            [--slug NAME] [--on | --off] [--vence "YYYY-MM-DDTHH:MM"|no] [--turns N] [--per-ip N] [--welcome TEXT] [--chips "a|b|c"] [--starter TEXT] [--sponsor on|off] [--rotate]
 
 ${bold("Configure an agent")}
   files ls|get|put|rm <id> [path]    Files in the agent's machine   [--file LOCAL] [--out LOCAL]
-  skills ls|get|add|rm <id> [slug]   Skills (add from catalog, --file SKILL.md or --dir FOLDER; rm keeps a copy)
+  skills ls|get|add|rm <id> [slug]   Skills (add from catalog, --file SKILL.md or --dir FOLDER; get lists, --out DIR saves; rm keeps a copy)
+  skills templates <id>              pdf-doc templates it sees: its own and Ghosty's, and which folder wins
   dbs ls|tables|query|import|grant|revoke <id> [db]   Databases it uses   [--write] [--external-write t1,t2] [--from easybits:ID --dry-run]
   mcp get|set <id>                   MCP servers                    [--file servers.json]
   channels whatsapp ls|enable|disable <id> [number]   Which WhatsApp Business numbers it answers   [--dry-run]
@@ -1797,6 +1911,7 @@ ${bold("Talk to an agent")}
   chat <id> ["message"]     Stream a conversation (no message = interactive)   [--conversation ID]
   conversations ls <id>     List conversations
   turns ls <id>             Recent turns and why they failed   [--errors] [--since 1h] [--limit N]
+  turns show <id> [turn]    Where a turn's time went: each tool with its seconds, output tokens (default: last)
 
 ${bold("Schedule turns")}  ${dim("(each run lands in a conversation and notifies your phone; an answer of exactly OK stays silent)")}
   schedule ls <id>                   Pending turns and recent runs
@@ -1823,7 +1938,7 @@ ${bold("Exit codes")}  0 ok \xB7 1 API error \xB7 2 usage error \xB7 3 not signe
 ${dim("Note: `ghosty` may collide with another binary on your PATH (e.g. the Ghosty TUI). Check with `which -a ghosty`; run `npx @ghostystudio/cli` to be sure.")}
 ${dim("Docs: https://www.ghosty.studio/docs/cli")}`;
 var COMMANDS = ["login", "logout", "whoami", "usage", "agents", "files", "skills", "mcp", "dbs", "turns", "try", "chat", "conversations", "schedule", "partner", "me", "channels", "board", "credentials", "docs", "help"];
-var AGENTS_SUBS = ["ls", "create", "get", "set", "doctor", "docs", "rm", "restart", "demo"];
+var AGENTS_SUBS = ["ls", "create", "get", "set", "doctor", "docs", "rm", "restart", "demo", "box"];
 function unknown(what, input, known, helpCmd) {
   const s = suggest(input, known);
   return usage(`Unknown command: ${what}.`, s ? `Did you mean "${s}"? Run: ${helpCmd}` : `Run: ${helpCmd}`);
@@ -1881,7 +1996,7 @@ async function main() {
       on: { type: "boolean" },
       off: { type: "boolean" },
       turns: { type: "string" },
-      hours: { type: "string" },
+      vence: { type: "string" },
       "per-ip": { type: "string" },
       welcome: { type: "string" },
       chips: { type: "string" },
@@ -1910,14 +2025,17 @@ async function main() {
       tables: { type: "string" },
       append: { type: "boolean" },
       column: { type: "string" },
-      before: { type: "string" }
+      before: { type: "string" },
+      recycle: { type: "boolean" },
+      check: { type: "string", multiple: true },
+      contains: { type: "string", multiple: true }
     }
   });
   globals.json = Boolean(v.json);
   const tokens = splitTokens(pos, v);
   globals.token = tokens.session;
   globals.profile = v.profile;
-  if (v.version) return out({ version: "0.9.0" }, () => "0.9.0");
+  if (v.version) return out({ version: "0.10.0" }, () => "0.10.0");
   const [cmd, sub, a1, a2] = pos;
   if (cmd === "partner" && (v.help || !sub || sub === "help")) return out({ help: PARTNER_HELP }, () => PARTNER_HELP);
   const topic = cmd === "help" ? sub : v.help ? cmd : void 0;
@@ -1953,6 +2071,7 @@ async function main() {
       if (sub === "docs" || sub === "documents") return agentDocsCmd(a1, a2, pos[4], v);
       if (sub === "restart") return agentsRestart(a1);
       if (sub === "demo") return agentsDemo(a1, v);
+      if (sub === "box") return agentsBox(a1, v);
       throw unknown(`agents ${sub}`, sub, AGENTS_SUBS, "ghosty agents --help");
     case "files":
       return filesCmd(sub, a1, a2, v);
@@ -1964,7 +2083,7 @@ async function main() {
     case "db":
       return dbsCmd(sub, a1, a2, pos.slice(4).filter((x) => x !== void 0), v);
     case "turns":
-      return turnsCmd(sub, a1, v);
+      return turnsCmd(sub, a1, a2, v);
     case "board":
       return boardCmd(sub, a1, v);
     case "channels":
@@ -1999,11 +2118,18 @@ async function main() {
       throw unknown(cmd, cmd, COMMANDS, "ghosty --help");
   }
 }
+var notice = updateNotice("0.10.0").catch(() => null);
 main().then(
-  () => process.exit(EXIT.OK),
-  (e) => {
+  async () => {
+    const n = await notice;
+    if (n) info(dim(n));
+    process.exit(EXIT.OK);
+  },
+  async (e) => {
     if (e && typeof e === "object" && "code" in e && String(e.code).startsWith("ERR_PARSE_ARGS")) {
-      fail(usage(e.message, "Run: ghosty --help"));
+      const n = await notice;
+      fail(usage(e.message, n ? `${n}
+This option may exist in the new version.` : `Run: ghosty --help   (or update: ${UPGRADE})`));
     }
     fail(e);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ghostystudio/cli",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Official Ghosty Studio CLI — configure, test and chat with your agents from the terminal. Built for humans and coding agents.",
   "type": "module",
   "bin": {