@ghostystudio/cli 0.9.1 → 0.10.0

package/README.md

@@ -21,6 +21,7 @@ ghosty agents get <id> [--fields name,model,prompt]
 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
@@ -28,9 +29,11 @@ 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 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]
@@ -52,7 +55,7 @@ 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), `--profile <name>` / `GHOSTY_PROFILE` (a separate saved session, e.g. one per account), `--yes`, `--help`, `--version`. Env: `GHOSTY_URL`, `XDG_CONFIG_HOME`, `NO_COLOR`; partner commands sign with `GHOSTY_PARTNER_KEY` + `GHOSTY_PARTNER_SECRET` when set.
+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`.
 
@@ -71,6 +74,13 @@ Exit codes: `0` ok · `1` API error · `2` usage error · `3` not signed in.
 - `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.1"}`, "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.1"}`,
+      "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);
@@ -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";
@@ -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.1"}`
+        "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);
@@ -1549,6 +1602,7 @@ 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 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]"
     ],
@@ -1570,7 +1624,10 @@ var HELPS = {
       ["--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"]
+      ["--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",
@@ -1578,7 +1635,8 @@ var HELPS = {
       "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 demo <id> --slug guardias --on --vence "2026-10-15T20:00" --starter "Ens\xE9\xF1ame c\xF3mo empezar"'
+      '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.", "demo with no flags only prints its status: link, expiry, caps and numbers."],
     learn: `${REF}#agentes`
@@ -1588,11 +1646,12 @@ var HELPS = {
     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)"]
@@ -1603,7 +1662,10 @@ 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."],
+    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: {
@@ -1636,15 +1698,16 @@ var HELPS = {
     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"],
+    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: {
@@ -1770,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]
 
@@ -1791,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] [--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]
@@ -1809,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
@@ -1835,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}`);
@@ -1922,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.1" }, () => "0.9.1");
+  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;
@@ -1965,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);
@@ -1976,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":
@@ -2011,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.1",
+  "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": {