@ghostystudio/cli 0.1.0

package/README.md

@@ -0,0 +1,38 @@
+# @ghostystudio/cli
+
+The official [Ghosty Studio](https://www.ghosty.studio) CLI: configure, test and chat with your agents from the terminal. Built for humans **and** coding agents (Claude Code, Codex, Cursor).
+
+```bash
+npx -y @ghostystudio/cli login
+# or
+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.
+
+## Commands
+
+```bash
+ghosty whoami
+ghosty agents ls
+ghosty agents get <id> [--fields name,model,prompt]
+ghosty agents set <id> [--name] [--model] [--prompt | --prompt-file FILE]
+ghosty agents restart <id>
+
+ghosty files ls|get|put|rm <id> [path]   [--file LOCAL] [--out LOCAL]
+ghosty skills ls|add|rm <id> [slug]      [--file SKILL.md]
+ghosty mcp get|set <id>                  [--file servers.json]
+
+ghosty try <id> "message"                [--session] [--reset] [--whatsapp]
+ghosty chat <id> ["message"]             [--conversation ID]
+ghosty conversations ls <id>
+
+ghosty me files ls|upload|rm             [--kind image|video|audio|document|other]
+ghosty docs
+```
+
+Global: `--json` (stdout is JSON only), `--token <token>` / `GHOSTY_TOKEN` (a `gat_…` agent token reaches only that agent), `--help`, `--version`.
+
+Exit codes: `0` ok · `1` API error · `2` usage error · `3` not signed in.
+
+Requires Node 22+. Docs: https://www.ghosty.studio/docs/cli · Skill for coding agents: `npx skills add https://www.ghosty.studio`

package/dist/index.js

@@ -0,0 +1,736 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { parseArgs } from "node:util";
+
+// src/banner.ts
+var BANNER = "   \x1B[38;2;154;153;234m\u28C0\u2834\u2812\u281B\u2809\u2809\u2819\u2832\u2884\u2840\x1B[0m\n \x1B[38;2;212;212;215m\u28F4\u285A\u2809\x1B[38;2;154;153;234m\u28FD\x1B[38;2;212;212;215m\u28F7\u28C4\u28E4\u28C4\u28F4\x1B[38;2;154;153;234m\u28EF\x1B[38;2;212;212;215m\u2849\u2819\x1B[38;2;154;153;234m\u28F6\x1B[38;2;212;212;215m\u2844            \x1B[38;2;244;245;251m\u28A0\u2844\x1B[0m\n\x1B[38;2;212;212;215m\u28BA\x1B[38;2;154;153;234m\u285F \u28B8\u28FF\u28FF\u28FF \x1B[38;2;212;212;215m\u28B8\x1B[38;2;154;153;234m\u28FF\u28FF\u2847 \u2818\x1B[38;2;212;212;215m\u28FF\u2802   \x1B[38;2;244;245;251m\u2880\u28F4\u283F\u283F\u28B7\u28E6  \u28FF\u2807      \x1B[38;2;154;153;234m\u28C0\u2840   \x1B[38;2;244;245;251m\u2880\u28C0\u2840   \u28A0\u28FF\x1B[0m\n\x1B[38;2;154;153;234m\u2808\x1B[38;2;212;212;215m\u2867\u28C0 \x1B[38;2;154;153;234m\u289B\u28FB\x1B[38;2;212;212;215m\u281F \u2808\u28AE\x1B[38;2;154;153;234m\u28CB \x1B[38;2;212;212;215m\u2880\u2860\u284F   \x1B[38;2;244;245;251m\u2880\u28FF\u280F\u2880\u28C0\u28C0\u28C0\u2840\u28B8\u287F\u28E0\u28F6\u28BF\u28F7 \x1B[38;2;154;153;234m\u28E0\u28FE\u28FF\u28F7\u28C4 \x1B[38;2;244;245;251m\u2830\u28FF\u2849\u281B\u2802\u28E4\u28E4\u28FF\u28E7\u28E4\u2804 \u28FC\u2847 \u28A0\u28FF\u2807\x1B[0m\n \x1B[38;2;154;153;234m\u2847\x1B[38;2;212;212;215m\u2808\u2809\u2809     \u2808\u2809\u2809 \x1B[38;2;154;153;234m\u2847   \x1B[38;2;244;245;251m\u28B8\u28FF \u2808\u289B\u28FF\u280F\u2801\u28FF\u28FF\u281F\u2801\u28FC\u284F\x1B[38;2;154;153;234m\u28B4\u28FF\x1B[38;2;212;212;215m\u28B9\x1B[38;2;154;153;234m\u28DF\x1B[38;2;212;212;215m\u2889\x1B[38;2;154;153;234m\u28FF\x1B[38;2;244;245;251m\u2880\u2840\u2819\u283B\u28E6\u2840 \u28FF\u284F \u2880\u28C0\u28B0\u28FF \u28E0\u28FF\u285F\x1B[0m\n \x1B[38;2;154;153;234m\u2847            \u2847   \x1B[38;2;244;245;251m\u2818\u28BF\u28E6\u28F4\u287E\u280B \u28B8\u287F\u2803 \u2830\u28FF\u28F6\x1B[38;2;154;153;234m\u2818\u28BF\u28FF\u28FF\u287F\u280B\x1B[38;2;244;245;251m\u2808\u28BF\u28E6\u28E4\u28FF\u2807 \u28BF\u28F7\u28F6\u283F\u2803\u2838\u28F7\u287E\u28BF\u287F\u2801\x1B[0m\n \x1B[38;2;154;153;234m\u2847            \u2847                         \x1B[38;2;244;245;251m\u2808\u2809       \u28E0\u2844 \u28A0\u28FF\u2803\x1B[0m\n \x1B[38;2;154;153;234m\u28F7   \u28E0\u28C4   \u2880\u28C0\u2840\u28B8\u2847                                  \x1B[38;2;244;245;251m\u2838\u28FF\u28F6\u283F\u2801\x1B[0m\n \x1B[38;2;154;153;234m\u28BB\u28C0\u2864\u280A  \u2831\u2824\u2816\u2809 \u2819\u280B\x1B[0m";
+
+// src/auth.ts
+import { createHash, randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+// src/util.ts
+var EXIT = { OK: 0, API: 1, USAGE: 2, AUTH: 3 };
+var CliError = class extends Error {
+  constructor(message, code = EXIT.API, hint) {
+    super(message);
+    this.code = code;
+    this.hint = hint;
+  }
+  code;
+  hint;
+};
+var usage = (message, hint) => new CliError(message, EXIT.USAGE, hint);
+var globals = { json: false };
+var color = process.stderr.isTTY && !process.env.NO_COLOR;
+var paint = (code) => (s) => color ? `\x1B[${code}m${s}\x1B[0m` : s;
+var dim = paint("2");
+var bold = paint("1");
+var lavender = paint("38;2;154;153;234");
+var red = paint("31");
+var info = (s) => process.stderr.write(s + "\n");
+function out(data, human) {
+  if (globals.json || !human) process.stdout.write(JSON.stringify(data, null, globals.json ? 0 : 2) + "\n");
+  else process.stdout.write(human() + "\n");
+}
+function table(rows, cols) {
+  if (!rows.length) return dim("(empty)");
+  const cell = (v) => v === null || v === void 0 ? "\u2014" : String(v);
+  const w = cols.map((c) => Math.max(c.length, ...rows.map((r) => cell(r[c]).length)));
+  const line = (vals) => vals.map((v, i) => v.padEnd(w[i])).join("  ").trimEnd();
+  return [bold(line(cols.map((c) => c.toUpperCase()))), ...rows.map((r) => line(cols.map((c) => cell(r[c]))))].join("\n");
+}
+function fail(e) {
+  const err = e instanceof CliError ? e : new CliError(e instanceof Error ? e.message : String(e));
+  if (globals.json) {
+    process.stdout.write(JSON.stringify({ error: err.message, code: err.code, ...err.hint ? { hint: err.hint } : {} }) + "\n");
+  } else {
+    info(red("Error: ") + err.message);
+    if (err.hint) info(dim(err.hint));
+  }
+  process.exit(err.code);
+}
+async function openUrl(url) {
+  const { spawn } = await import("node:child_process");
+  const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+  const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+  try {
+    spawn(cmd, args, { stdio: "ignore", detached: true }).on("error", () => {
+    }).unref();
+  } catch {
+  }
+}
+
+// src/auth.ts
+var CLIENT_ID = "ghosty-cli";
+var SCOPES = "profile agents:read agents:write files";
+var LOGIN_TIMEOUT_MS = 5 * 6e4;
+var CONFIG_PATH = join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "ghosty", "config.json");
+async function readConfig() {
+  try {
+    return JSON.parse(await readFile(CONFIG_PATH, "utf8"));
+  } catch {
+    return {};
+  }
+}
+async function writeConfig(c) {
+  await mkdir(dirname(CONFIG_PATH), { recursive: true });
+  await writeFile(CONFIG_PATH, JSON.stringify(c, null, 2), { mode: 384 });
+  await chmod(CONFIG_PATH, 384);
+}
+var clearConfig = () => rm(CONFIG_PATH, { force: true });
+async function baseUrl() {
+  const url = process.env.GHOSTY_URL || (await readConfig()).baseUrl || "https://www.ghosty.studio";
+  return url.replace(/\/+$/, "");
+}
+var explicitToken = () => process.env.GHOSTY_TOKEN || globals.token;
+var b64url = (buf) => buf.toString("base64url");
+async function tokenRequest(base, form) {
+  const res = await fetch(`${base}/oauth2/token`, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({ client_id: CLIENT_ID, ...form })
+  });
+  const body = await res.json().catch(() => ({}));
+  if (!res.ok || !body.access_token) {
+    throw new CliError(`Login failed (${body.error ?? res.status}).`, EXIT.AUTH, "Run: ghosty login");
+  }
+  return body;
+}
+var CLOSE_PAGE = (ok, base) => `<!doctype html><html lang="es"><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1"><title>Ghosty CLI</title>
+<body style="font-family:system-ui,sans-serif;background:#F4F5FB;color:#191A20;display:grid;place-items:center;min-height:100vh;margin:0;padding:16px;box-sizing:border-box">
+<div style="text-align:center;max-width:420px">
+<img src="${base}/mascot.png" alt="Ghosty" width="112" height="133" style="display:block;margin:0 auto 20px">
+<h1 style="font-weight:700;font-size:28px;margin:0 0 8px">${ok ? "\xA1Listo, ya entraste!" : "No se pudo entrar"}</h1>
+<p style="margin:0;color:#4b4d57;line-height:1.5">${ok ? "Ya puedes cerrar esta pesta\xF1a y volver a la terminal." : "Vuelve a la terminal y corre <code>ghosty login</code> otra vez."}</p>
+</div>`;
+async function login() {
+  const base = await baseUrl();
+  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 server = createServer((req, res) => {
+      const u = new URL(req.url ?? "/", "http://127.0.0.1");
+      if (u.pathname !== "/cb") {
+        res.writeHead(404).end();
+        return;
+      }
+      const ok = u.searchParams.get("state") === state && !!u.searchParams.get("code");
+      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 });
+      else reject(new CliError(`Login was not completed (${u.searchParams.get("error") ?? "state mismatch"}).`, EXIT.AUTH, "Run: ghosty login"));
+    });
+    let redirectUri2 = "";
+    const timer = setTimeout(() => {
+      server.close();
+      reject(new CliError("Login timed out after 5 minutes.", EXIT.AUTH, "Run: ghosty login"));
+    }, LOGIN_TIMEOUT_MS);
+    server.listen(0, "127.0.0.1", () => {
+      const port = server.address().port;
+      redirectUri2 = `http://127.0.0.1:${port}/cb`;
+      const url = `${base}/oauth2/authorize?` + new URLSearchParams({
+        response_type: "code",
+        client_id: CLIENT_ID,
+        redirect_uri: redirectUri2,
+        scope: SCOPES,
+        state,
+        code_challenge: challenge,
+        code_challenge_method: "S256"
+      });
+      if (globals.json) process.stdout.write(JSON.stringify({ event: "login_url", url }) + "\n");
+      info(`${lavender("\u203A")} Opening your browser to sign in to Ghosty\u2026`);
+      info(dim(`  If it doesn't open, visit: ${url}`));
+      void openUrl(url);
+    });
+  });
+  const tok = await tokenRequest(base, {
+    grant_type: "authorization_code",
+    code,
+    redirect_uri: redirectUri,
+    code_verifier: verifier
+  });
+  const prev = await readConfig();
+  const cfg = {
+    ...prev.baseUrl ? { baseUrl: prev.baseUrl } : {},
+    accessToken: tok.access_token,
+    refreshToken: tok.refresh_token,
+    expiresAt: Date.now() + (tok.expires_in ?? 3600) * 1e3
+  };
+  await writeConfig(cfg);
+  return cfg;
+}
+function hasLocalBrowser() {
+  if (process.env.SSH_CONNECTION || process.env.SSH_TTY || process.env.CI) return false;
+  if (process.platform === "linux" && !process.env.DISPLAY && !process.env.WAYLAND_DISPLAY) return false;
+  return true;
+}
+async function loginDevice() {
+  const base = await baseUrl();
+  const res = await fetch(`${base}/oauth2/device`, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({ client_id: CLIENT_ID, scope: SCOPES })
+  });
+  const d = await res.json().catch(() => ({}));
+  if (!res.ok || !d.device_code) throw new CliError(`Could not start the login (${d.error ?? res.status}).`, EXIT.AUTH);
+  if (globals.json) process.stdout.write(JSON.stringify({ event: "login_url", url: d.verification_uri_complete, code: d.user_code, method: "device" }) + "\n");
+  info(`${lavender("\u203A")} Open this link on any device and confirm the code ${lavender(d.user_code)}:`);
+  info(`  ${d.verification_uri_complete}`);
+  let interval = (d.interval ?? 5) * 1e3;
+  const deadline = Date.now() + (d.expires_in ?? 600) * 1e3;
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, interval));
+    const t = await fetch(`${base}/oauth2/token`, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({ client_id: CLIENT_ID, grant_type: "urn:ietf:params:oauth:grant-type:device_code", device_code: d.device_code })
+    });
+    const body = await t.json().catch(() => ({}));
+    if (t.ok && body.access_token) {
+      const prev = await readConfig();
+      const cfg = {
+        ...prev.baseUrl ? { baseUrl: prev.baseUrl } : {},
+        accessToken: body.access_token,
+        refreshToken: body.refresh_token,
+        expiresAt: Date.now() + (body.expires_in ?? 3600) * 1e3
+      };
+      await writeConfig(cfg);
+      return cfg;
+    }
+    if (body.error === "authorization_pending") continue;
+    if (body.error === "slow_down") {
+      interval += 5e3;
+      continue;
+    }
+    if (body.error === "access_denied") throw new CliError("The login was rejected.", EXIT.AUTH, "Run: ghosty login");
+    throw new CliError(`Login failed (${body.error ?? t.status}).`, EXIT.AUTH, "Run: ghosty login");
+  }
+  throw new CliError("The code expired before it was confirmed.", EXIT.AUTH, "Run: ghosty login");
+}
+async function refresh(cfg) {
+  if (!cfg.refreshToken) return null;
+  try {
+    const tok = await tokenRequest(await baseUrl(), { grant_type: "refresh_token", refresh_token: cfg.refreshToken });
+    const next = {
+      ...cfg,
+      accessToken: tok.access_token,
+      refreshToken: tok.refresh_token ?? cfg.refreshToken,
+      expiresAt: Date.now() + (tok.expires_in ?? 3600) * 1e3
+    };
+    await writeConfig(next);
+    return next;
+  } catch {
+    return null;
+  }
+}
+async function logout() {
+  const cfg = await readConfig();
+  if (cfg.refreshToken) {
+    await fetch(`${await baseUrl()}/oauth2/revoke`, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({ client_id: CLIENT_ID, token: cfg.refreshToken })
+    }).catch(() => {
+    });
+  }
+  await clearConfig();
+}
+var interactive = () => Boolean(process.stdin.isTTY && process.stderr.isTTY) && !globals.json;
+
+// src/api.ts
+async function currentToken() {
+  const explicit = explicitToken();
+  if (explicit) return explicit;
+  let cfg = await readConfig();
+  if (!cfg.accessToken) {
+    if (!interactive()) throw new CliError("Not logged in.", EXIT.AUTH, "Run: ghosty login   (or set GHOSTY_TOKEN)");
+    info(dim("Not logged in yet \u2014 let's fix that."));
+    cfg = await (hasLocalBrowser() ? login() : loginDevice());
+  }
+  if (cfg.expiresAt !== void 0 && cfg.expiresAt - Date.now() < 6e4) cfg = await refresh(cfg) ?? cfg;
+  return cfg.accessToken;
+}
+async function api(path, opts = {}) {
+  const res = await request(path, opts);
+  const text = await res.text();
+  if (!text) return void 0;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+async function request(path, opts = {}, retried = false) {
+  const base = await baseUrl();
+  const token = await currentToken();
+  const res = await fetch(`${base}${path}`, {
+    method: opts.method ?? (opts.body !== void 0 || opts.raw !== void 0 ? "POST" : "GET"),
+    headers: {
+      authorization: `Bearer ${token}`,
+      "user-agent": `ghosty-cli/${"0.1.0"}`,
+      ...opts.body !== void 0 ? { "content-type": "application/json" } : {},
+      ...opts.headers
+    },
+    body: opts.raw ?? (opts.body !== void 0 ? JSON.stringify(opts.body) : void 0),
+    signal: opts.signal
+  });
+  if (res.status === 401 && !retried && !explicitToken()) {
+    const cfg = await refresh(await readConfig());
+    if (cfg) return request(path, opts, true);
+  }
+  if (!res.ok) throw await toError(res);
+  return res;
+}
+async function toError(res) {
+  const text = await res.text().catch(() => "");
+  let body = {};
+  try {
+    body = JSON.parse(text);
+  } catch {
+  }
+  const detail = body.message || body.error_description || body.error || text.slice(0, 300) || res.statusText;
+  if (res.status === 401) return new CliError("Your session is not valid anymore.", EXIT.AUTH, "Run: ghosty login");
+  if (res.status === 403) return new CliError(`Not allowed: ${detail}`, EXIT.API, "Run: ghosty login   (to refresh your permissions)");
+  if (res.status === 404) return new CliError("Not found.", EXIT.API, "Check the agent id (ghosty agents ls) or that your token belongs to that agent.");
+  if (body.error === "agente_sin_maquina") {
+    return new CliError("This agent's engine has no machine of its own: files, skills, MCP and restart are not available for it.", EXIT.API, "Name, model and prompt can still be changed: ghosty agents set <id> \u2026");
+  }
+  return new CliError(`${res.status} ${detail}`, EXIT.API);
+}
+
+// src/commands/agents.ts
+import { readFile as readFile2, writeFile as writeFile2 } from "node:fs/promises";
+var enc = encodeURIComponent;
+var agentPath = (id, rest = "") => `/api/v2/agents/${enc(id)}${rest}`;
+var need = (v, what, example) => {
+  if (!v) throw usage(`Missing ${what}.`, `Example: ${example}`);
+  return v;
+};
+async function agentsLs() {
+  const r = await api("/api/v2/me/agents?client=cli");
+  const rows = r.agentes.map((a) => ({
+    id: a.id,
+    name: a.nombre,
+    engine: a.motor ?? a.origen,
+    source: a.origen,
+    lastActivity: a.ultimaActividad ?? null,
+    ...a.compartidoPor ? { sharedBy: a.compartidoPor } : {}
+  }));
+  out(rows, () => table(rows, ["id", "name", "engine", "lastActivity"]));
+}
+async function agentsGet(id, fields) {
+  id = need(id, "agent id", "ghosty agents get <agent-id>");
+  const q = fields ? `?fields=${enc(fields)}` : "?full=1";
+  out(await api(agentPath(id, q)));
+}
+async function agentsSet(id, v) {
+  id = need(id, "agent id", "ghosty agents set <agent-id> --prompt-file PROMPT.md");
+  const body = {};
+  if (v.name) body.name = v.name;
+  if (v.model) body.model = v.model;
+  if (v.prompt) body.prompt = v.prompt;
+  if (v["prompt-file"]) body.prompt = await readFile2(v["prompt-file"], "utf8");
+  if (!Object.keys(body).length) throw usage("Nothing to change.", "Use --name, --model, --prompt or --prompt-file.");
+  const r = await api(agentPath(id), { method: "PATCH", body });
+  out(r, () => `${lavender("\u2713")} Updated ${Object.keys(body).join(", ")}.`);
+}
+async function agentsRestart(id) {
+  id = need(id, "agent id", "ghosty agents restart <agent-id>");
+  out(await api(agentPath(id, "/restart"), { method: "POST", body: {} }), () => `${lavender("\u2713")} Restarting \u2014 the next turn uses the new config.`);
+}
+async function tryTurn(id, text, v) {
+  id = need(id, "agent id", 'ghosty try <agent-id> "hello"');
+  if (!text && !v.reset) throw usage("Missing message.", 'Example: ghosty try <agent-id> "hello"');
+  if (!process.stdout.isTTY || !text) {
+  } else info(dim("Thinking\u2026 (a test turn can take up to 3 minutes)"));
+  const r = await api(agentPath(id, "/try"), {
+    body: { text, session: v.session, reset: v.reset, ...v.whatsapp ? { as: "whatsapp" } : {} }
+  });
+  out(r, () => (r.text ?? "") + (r.error ? `
+${dim(`(warning: ${r.error})`)}` : ""));
+}
+async function filesCmd(sub, id, path, v) {
+  const ex = "ghosty files ls <agent-id> | get <agent-id> <path> | put <agent-id> <path> --file <local> | rm <agent-id> <path>";
+  id = need(id, "agent id", ex);
+  const p = (path ?? "").replace(/^\/+/, "");
+  switch (sub) {
+    case "ls": {
+      const r = await api(agentPath(id, `/files/${p}`));
+      const cols = r.files?.length ? Object.keys(r.files[0]).slice(0, 4) : ["path"];
+      out(r, () => `${dim(r.dir)}
+${table(r.files ?? [], cols)}`);
+      return;
+    }
+    case "get": {
+      need(path, "path", ex);
+      const res = await request(agentPath(id, `/files/${p}`));
+      const bytes = Buffer.from(await res.arrayBuffer());
+      if (v.out) {
+        await writeFile2(v.out, bytes);
+        out({ path: p, saved: v.out, bytes: bytes.length }, () => `${lavender("\u2713")} Saved ${bytes.length} bytes to ${v.out}`);
+      } else process.stdout.write(bytes);
+      return;
+    }
+    case "put": {
+      need(path, "path", ex);
+      const data = v.file ? await readFile2(v.file) : await readStdin();
+      const r = await api(agentPath(id, `/files/${p}`), { method: "PUT", raw: new Uint8Array(data), headers: { "content-type": "application/octet-stream" } });
+      out(r ?? { path: p, bytes: data.length }, () => `${lavender("\u2713")} Wrote ${p} (${data.length} bytes). Run \`ghosty agents restart ${id}\` if the agent must reload it.`);
+      return;
+    }
+    case "rm": {
+      need(path, "path", ex);
+      out(await api(agentPath(id, `/files/${p}`), { method: "DELETE" }) ?? { deleted: p }, () => `${lavender("\u2713")} Deleted ${p}`);
+      return;
+    }
+    default:
+      throw usage(`Unknown files subcommand: ${sub ?? "(none)"}.`, ex);
+  }
+}
+async function readStdin() {
+  if (process.stdin.isTTY) throw usage("Nothing to upload.", "Use --file <local> or pipe the content through stdin.");
+  const parts = [];
+  for await (const c of process.stdin) parts.push(c);
+  return Buffer.concat(parts);
+}
+async function skillsCmd(sub, id, slug, v) {
+  const ex = "ghosty skills ls <agent-id> | add <agent-id> <slug> [--file SKILL.md] | rm <agent-id> <slug>";
+  id = need(id, "agent id", ex);
+  switch (sub) {
+    case "ls":
+      out(await api(agentPath(id, "/skills")));
+      return;
+    case "add": {
+      slug = need(slug, "skill slug", ex);
+      const body = v.file ? { markdown: await readFile2(v.file, "utf8") } : { fromCatalog: true };
+      out(await api(agentPath(id, `/skills/${enc(slug)}`), { method: "PUT", body }), () => `${lavender("\u2713")} Skill ${slug} installed. Run \`ghosty agents restart ${id}\` to load it.`);
+      return;
+    }
+    case "rm":
+      slug = need(slug, "skill slug", ex);
+      out(await api(agentPath(id, `/skills/${enc(slug)}`), { method: "DELETE" }) ?? { removed: slug }, () => `${lavender("\u2713")} Skill ${slug} removed.`);
+      return;
+    default:
+      throw usage(`Unknown skills subcommand: ${sub ?? "(none)"}.`, ex);
+  }
+}
+async function mcpCmd(sub, id, v) {
+  const ex = "ghosty mcp get <agent-id> | set <agent-id> --file servers.json";
+  id = need(id, "agent id", ex);
+  if (sub === "get") return out(await api(agentPath(id, "/mcp")));
+  if (sub === "set") {
+    const file = need(v.file, "--file", ex);
+    const parsed = JSON.parse(await readFile2(file, "utf8"));
+    const body = { servers: Array.isArray(parsed) ? parsed : parsed.servers ?? [] };
+    return out(await api(agentPath(id, "/mcp"), { method: "PUT", body }), () => `${lavender("\u2713")} MCP servers replaced. Run \`ghosty agents restart ${id}\` to load them.`);
+  }
+  throw usage(`Unknown mcp subcommand: ${sub ?? "(none)"}.`, ex);
+}
+
+// src/commands/chat.ts
+import { randomUUID } from "node:crypto";
+import { createInterface } from "node:readline/promises";
+import { readFile as readFile3 } from "node:fs/promises";
+import { basename } from "node:path";
+
+// src/sse.ts
+async function* readSse(body) {
+  const decoder = new TextDecoder();
+  let buf = "";
+  for await (const chunk of body) {
+    buf += decoder.decode(chunk, { stream: true });
+    let idx;
+    while ((idx = buf.search(/\r?\n\r?\n/)) !== -1) {
+      const raw = buf.slice(0, idx);
+      buf = buf.slice(idx + (buf[idx] === "\r" ? 4 : 2));
+      let event = "message";
+      const data = [];
+      for (const line of raw.split(/\r?\n/)) {
+        if (!line || line.startsWith(":")) continue;
+        const colon = line.indexOf(":");
+        const field = colon === -1 ? line : line.slice(0, colon);
+        const value = colon === -1 ? "" : line.slice(colon + 1).replace(/^ /, "");
+        if (field === "event") event = value;
+        else if (field === "data") data.push(value);
+      }
+      if (data.length || event !== "message") yield { event, data: data.join("\n") };
+    }
+  }
+}
+function parseData(e) {
+  try {
+    return JSON.parse(e.data || "{}");
+  } catch {
+    return {};
+  }
+}
+
+// src/commands/chat.ts
+var enc2 = encodeURIComponent;
+var convPath = (agent, rest = "") => `/api/v2/me/agents/${enc2(agent)}/conversations${rest}`;
+async function conversationsLs(agent) {
+  if (!agent) throw usage("Missing agent id.", "Example: ghosty conversations ls <agent-id>");
+  const r = await api(convPath(agent));
+  const rows = r.conversaciones.map((c) => ({ id: c.id, title: c.titulo, updated: c.actualizada }));
+  out(rows, () => table(rows, ["id", "title", "updated"]));
+}
+async function turn(agent, sid, text, first) {
+  const turnId = randomUUID();
+  const ctrl = new AbortController();
+  const res = await request(convPath(agent, `/${enc2(sid)}/events`), { signal: ctrl.signal, headers: { accept: "text/event-stream" } });
+  let cancelled = false;
+  const onSigint = () => {
+    if (cancelled) process.exit(130);
+    cancelled = true;
+    info(dim("\n(cancelling\u2026 press Ctrl-C again to quit)"));
+    void api(convPath(agent, `/${enc2(sid)}/cancel`), { method: "POST", body: {} }).catch(() => {
+    });
+  };
+  process.on("SIGINT", onSigint);
+  const sent = api(convPath(agent, `/${enc2(sid)}/messages`), { body: { content: text, turnId, primerTurno: first } });
+  let answer = "";
+  let usageData;
+  let ours = false;
+  try {
+    await sent;
+    for await (const ev of readSse(res.body)) {
+      const d = parseData(ev);
+      if (d.turnId) ours = d.turnId === turnId;
+      if (!ours) continue;
+      if (ev.event === "chunk" && d.text) {
+        answer += d.text;
+        if (globals.json) process.stdout.write(JSON.stringify({ event: "chunk", text: d.text }) + "\n");
+        else process.stdout.write(d.text);
+      } else if (ev.event === "tool" && d.title) {
+        if (globals.json) process.stdout.write(JSON.stringify({ event: "tool", ...d }) + "\n");
+        else if (!d.status || d.status === "pending" || d.status === "in_progress") info(dim(`  \u2699 ${d.title}`));
+      } else if (ev.event === "usage") {
+        usageData = d;
+      } else if (ev.event === "error") {
+        throw new CliError(d.message ?? "The turn failed.", EXIT.API);
+      } else if (ev.event === "done") {
+        break;
+      }
+    }
+  } finally {
+    process.off("SIGINT", onSigint);
+    ctrl.abort();
+  }
+  if (globals.json) process.stdout.write(JSON.stringify({ event: "done", conversation: sid, turnId, text: answer, usage: usageData }) + "\n");
+  else if (!answer.endsWith("\n")) process.stdout.write("\n");
+  return { text: answer, usage: usageData };
+}
+async function chat(agent, message, v) {
+  if (!agent) throw usage("Missing agent id.", 'Example: ghosty chat <agent-id> "hello"   (ghosty agents ls to find it)');
+  let sid = v.conversation;
+  let first = false;
+  if (!sid) {
+    sid = (await api(convPath(agent), { method: "POST", body: {} })).id;
+    first = true;
+    if (!globals.json) info(dim(`conversation ${sid}  (continue it with --conversation ${sid})`));
+  }
+  if (message) {
+    await turn(agent, sid, message, first);
+    return;
+  }
+  if (!process.stdin.isTTY) {
+    const piped = (await readAll()).trim();
+    if (!piped) throw usage("Nothing to send.", 'Example: ghosty chat <agent-id> "hello"');
+    await turn(agent, sid, piped, first);
+    return;
+  }
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  info(dim("Type your message. Ctrl-C cancels a turn, Ctrl-D exits."));
+  for (; ; ) {
+    let line;
+    try {
+      line = await rl.question(lavender("\u203A "));
+    } catch {
+      break;
+    }
+    if (!line.trim()) continue;
+    rl.pause();
+    await turn(agent, sid, line, first).catch((e) => info(e instanceof Error ? e.message : String(e)));
+    first = false;
+    rl.resume();
+  }
+  rl.close();
+}
+async function readAll() {
+  let s = "";
+  for await (const c of process.stdin) s += c;
+  return s;
+}
+async function meFiles(sub, arg, v) {
+  const ex = "ghosty me files ls [--kind image|video|audio|document|other] | upload <file> | rm <file-id>";
+  switch (sub) {
+    case "ls": {
+      const r = await api(
+        `/api/v2/me/files${v.kind ? `?kind=${enc2(v.kind)}` : ""}`
+      );
+      out(r, () => {
+        const rows = r.files.map((f) => ({ id: f.id, name: f.name, kind: f.kind, size: f.size, created: f.createdAt.slice(0, 10) }));
+        return `${table(rows, ["id", "name", "kind", "size", "created"])}
+${dim(`${(r.storage.usedBytes / 1e9).toFixed(2)} GB of ${r.storage.limitGb} GB used`)}`;
+      });
+      return;
+    }
+    case "upload": {
+      if (!arg) throw usage("Missing file.", ex);
+      const bytes = await readFile3(arg);
+      const r = await api(`/api/v2/me/files?nombre=${enc2(basename(arg))}`, {
+        method: "POST",
+        raw: new Uint8Array(bytes),
+        headers: { "content-type": "application/octet-stream" }
+      });
+      out(r, () => `${lavender("\u2713")} Uploaded ${r.name} (${r.id})`);
+      return;
+    }
+    case "rm": {
+      if (!arg) throw usage("Missing file id.", ex);
+      out(await api(`/api/v2/me/files/${enc2(arg)}`, { method: "DELETE" }) ?? { deleted: arg }, () => `${lavender("\u2713")} Deleted ${arg}`);
+      return;
+    }
+    default:
+      throw usage(`Unknown files subcommand: ${sub ?? "(none)"}.`, ex);
+  }
+}
+
+// src/index.ts
+var HELP = `${bold("Usage:")} ghosty <command> [options]
+
+${bold("Session")}
+  login                     Sign in with your browser (OAuth2). An agent can run it for you.
+    --device                Sign in from another device with a link + code (auto over SSH/CI)
+  logout                    Sign out and revoke this device's session
+  whoami                    Show who you are signed in as
+
+${bold("Agents")}
+  agents ls                 List your agents
+  agents get <id>           Show an agent's config            [--fields name,model,prompt]
+  agents set <id>           Change identity                   [--name] [--model] [--prompt | --prompt-file FILE]
+  agents restart <id>       Restart so the next turn loads new files/skills/MCP
+
+${bold("Configure an agent")}
+  files ls|get|put|rm <id> [path]    Files in the agent's machine   [--file LOCAL] [--out LOCAL]
+  skills ls|add|rm <id> [slug]       Skills (add from catalog, or --file SKILL.md)
+  mcp get|set <id>                   MCP servers                    [--file servers.json]
+
+${bold("Talk to an agent")}
+  try <id> "message"        One test turn, prints the full answer   [--session] [--reset] [--whatsapp]
+  chat <id> ["message"]     Stream a conversation (no message = interactive)   [--conversation ID]
+  conversations ls <id>     List conversations
+
+${bold("Your account")}
+  me files ls|upload|rm     Files in your account        [--kind image|video|audio|document|other]
+  docs [topic]              Open the docs
+
+${bold("Global options")}
+  --json                    Machine-readable output (stdout is JSON only)
+  --token <token>           Use this token (or env GHOSTY_TOKEN). A gat_\u2026 agent token reaches only that agent.
+  -h, --help                Show help
+  -v, --version             Show version
+
+${bold("Exit codes")}  0 ok \xB7 1 API error \xB7 2 usage error \xB7 3 not signed in
+${dim("Docs: https://www.ghosty.studio/docs/cli")}`;
+function showHelp() {
+  if (process.stdout.isTTY && !process.env.NO_COLOR && !globals.json) process.stdout.write(BANNER + "\n\n");
+  process.stdout.write(HELP + "\n");
+}
+async function main() {
+  const { values: v, positionals: pos } = parseArgs({
+    allowPositionals: true,
+    strict: true,
+    options: {
+      json: { type: "boolean" },
+      token: { type: "string" },
+      help: { type: "boolean", short: "h" },
+      version: { type: "boolean", short: "v" },
+      device: { type: "boolean" },
+      fields: { type: "string" },
+      name: { type: "string" },
+      model: { type: "string" },
+      prompt: { type: "string" },
+      "prompt-file": { type: "string" },
+      file: { type: "string" },
+      out: { type: "string" },
+      session: { type: "string" },
+      reset: { type: "boolean" },
+      whatsapp: { type: "boolean" },
+      conversation: { type: "string" },
+      kind: { type: "string" }
+    }
+  });
+  globals.json = Boolean(v.json);
+  globals.token = v.token;
+  if (v.version) return out({ version: "0.1.0" }, () => "0.1.0");
+  const [cmd, sub, a1, a2] = pos;
+  if (!cmd || v.help || cmd === "help") return showHelp();
+  switch (cmd) {
+    case "login": {
+      if (v.token) {
+        throw usage("--token is used per command, not saved.", "Set GHOSTY_TOKEN=<token> in your environment instead.");
+      }
+      await (v.device || !hasLocalBrowser() ? loginDevice() : login());
+      const me = await api("/api/v2/me");
+      const cfg = await readConfig();
+      await writeConfig({ ...cfg, email: me.email });
+      return out({ event: "logged_in", email: me.email }, () => `${lavender("\u2713")} Signed in as ${bold(me.email)}`);
+    }
+    case "logout":
+      await logout();
+      return out({ loggedOut: true }, () => `${lavender("\u2713")} Signed out.`);
+    case "whoami": {
+      if (explicitToken()?.startsWith("gat_")) return out({ tokenType: "agent" }, () => "Using an agent token (gat_\u2026): it reaches only its own agent.");
+      const me = await api("/api/v2/me");
+      return out(me, () => `${bold(me.email)}${dim(`  \xB7 ${new URL(process.env.GHOSTY_URL || "https://www.ghosty.studio").host}`)}`);
+    }
+    case "agents":
+      if (sub === "ls" || sub === "list" || !sub) return agentsLs();
+      if (sub === "get") return agentsGet(a1, v.fields);
+      if (sub === "set") return agentsSet(a1, v);
+      if (sub === "restart") return agentsRestart(a1);
+      throw usage(`Unknown agents subcommand: ${sub}.`, "Try: ghosty agents ls | get | set | restart");
+    case "files":
+      return filesCmd(sub, a1, a2, v);
+    case "skills":
+      return skillsCmd(sub, a1, a2, v);
+    case "mcp":
+      return mcpCmd(sub, a1, v);
+    case "try":
+      return tryTurn(sub, a1, v);
+    case "chat":
+      return chat(sub, a1, v);
+    case "conversations":
+      if (sub === "ls" || sub === "list") return conversationsLs(a1);
+      throw usage(`Unknown conversations subcommand: ${sub ?? "(none)"}.`, "Try: ghosty conversations ls <agent-id>");
+    case "me":
+      if (sub === "files") return meFiles(a1, a2, v);
+      throw usage(`Unknown me subcommand: ${sub ?? "(none)"}.`, "Try: ghosty me files ls");
+    case "docs": {
+      const url = `${await baseUrl()}/docs${sub ? `/${encodeURIComponent(sub)}` : "/cli"}`;
+      if (globals.json) return out({ url });
+      info(`${lavender("\u203A")} ${url}`);
+      return openUrl(url);
+    }
+    default:
+      throw usage(`Unknown command: ${cmd}.`, "Run: ghosty --help");
+  }
+}
+main().then(
+  () => process.exit(EXIT.OK),
+  (e) => {
+    if (e && typeof e === "object" && "code" in e && String(e.code).startsWith("ERR_PARSE_ARGS")) {
+      fail(usage(e.message, "Run: ghosty --help"));
+    }
+    fail(e);
+  }
+);

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@ghostystudio/cli",
+  "version": "0.1.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": {
+    "ghosty": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "esbuild src/index.ts --bundle --platform=node --format=esm --target=node22 --outfile=dist/index.js --banner:js='#!/usr/bin/env node' --define:__VERSION__=\\\"$npm_package_version\\\"",
+    "prepack": "npm run build"
+  },
+  "keywords": [
+    "ghosty",
+    "ghosty-studio",
+    "cli",
+    "agents",
+    "ai-agents",
+    "coding-agents",
+    "oauth2"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/blissito/ghosty-studio.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://www.ghosty.studio/docs/cli"
+}