spook-cli 0.1.0

package/README.md

@@ -0,0 +1,81 @@
+# Spook CLI
+
+Agent-first CLI for the [Spook](https://www.tryspook.com) agent API. Spook is an
+SEO autopilot: it finds winnable Google & ChatGPT queries, writes SEO content,
+and publishes it automatically. This CLI is a thin, zero-dependency wrapper over
+Spook's REST agent API (`/api/agent`, described at `/openapi.json`), so terminal
+agents (Claude Code, Cursor, CI) and shell scripts can drive Spook. Everything
+prints JSON.
+
+## Install
+
+Requires Node.js 18+.
+
+```bash
+npm install -g spook-cli
+spook help
+```
+
+## Get an API key
+
+1. Sign in to Spook and open **Settings → Agent API**.
+2. Generate a key (`spook_agent_...`) and save it:
+
+```bash
+spook auth login --key spook_agent_xxxxxxxx
+spook auth whoami
+```
+
+The key is stored in `~/.spook/config.json` (chmod 600). You can instead set
+`SPOOK_API_KEY` in the environment. Point at a different host with `--base` or
+`SPOOK_BASE_URL` (default `https://www.tryspook.com`).
+
+## Try it free (no key)
+
+```bash
+spook analyze example.com          # quick-win queries any domain already ranks for
+```
+
+## Commands
+
+```
+Sites
+  spook sites                                     List your sites
+  spook site <siteId>                             Site details
+  spook sites:create --name <n> --domain <d> [--publish nextjs] [--webhook <url>]
+  spook publishing <siteId> --integration nextjs [--mode draft|live]
+  spook autopilot <siteId> on|off
+  spook metrics <siteId> [--days 28]
+  spook checkout                                  Stripe Checkout URL to add a paid site
+
+Content
+  spook opportunities <siteId> [--questions] [--limit 20]
+  spook articles <siteId> [--limit 20]
+  spook article <articleId>
+  spook generate <siteId> "<query>" [--callback <https-url>]
+  spook publish <articleId>
+
+Any tool (incl. the free AI writers)
+  spook tools                                     List every tool + input schema
+  spook run <tool> '<json>'                       e.g. spook run blog-outline-generator '{"topic":"cold brew"}'
+```
+
+## Examples
+
+```bash
+# Stand up a site, let Spook run it
+spook sites:create --name "Acme" --domain acme.com --publish nextjs
+spook opportunities <siteId> --limit 10
+spook generate <siteId> "how to brew cold brew coffee"
+spook article <articleId>          # review the draft
+spook publish <articleId>
+spook autopilot <siteId> on
+
+# Use a free AI tool
+spook run content-brief-generator '{"keyword":"cold brew ratios"}'
+```
+
+## MCP
+
+Prefer MCP? Spook is also an MCP server at `https://www.tryspook.com/api/mcp` —
+point any MCP client there. The CLI and MCP expose the same tools.

package/bin/spook.js

@@ -0,0 +1,358 @@
+#!/usr/bin/env node
+// Spook CLI — agent-first command line for the Spook agent API.
+// Zero dependencies; Node 18+ (uses global fetch). Thin wrapper over the REST
+// endpoints at <base>/api/agent (see <base>/openapi.json). Prints JSON so it
+// composes in shells and is trivial for terminal agents (Claude Code, Cursor,
+// CI) to parse.
+
+import { readFileSync, writeFileSync, mkdirSync, rmSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const DEFAULT_BASE = "https://www.tryspook.com";
+const CONFIG_DIR = join(homedir(), ".spook");
+const CONFIG_PATH = join(CONFIG_DIR, "config.json");
+const VERSION = "0.1.0";
+
+// ── config ────────────────────────────────────────────────────────────────
+function readConfig() {
+  try {
+    return JSON.parse(readFileSync(CONFIG_PATH, "utf8"));
+  } catch {
+    return {};
+  }
+}
+function writeConfig(cfg) {
+  mkdirSync(CONFIG_DIR, { recursive: true });
+  writeFileSync(CONFIG_PATH, JSON.stringify(cfg, null, 2) + "\n", { mode: 0o600 });
+}
+function config() {
+  const file = readConfig();
+  return {
+    apiKey: process.env.SPOOK_API_KEY || file.apiKey || "",
+    baseUrl: (process.env.SPOOK_BASE_URL || file.baseUrl || DEFAULT_BASE).replace(/\/$/, ""),
+  };
+}
+
+// ── output ────────────────────────────────────────────────────────────────
+function out(data) {
+  process.stdout.write(JSON.stringify(data, null, 2) + "\n");
+}
+function fail(message, extra) {
+  process.stderr.write(
+    JSON.stringify({ error: message, ...(extra || {}) }, null, 2) + "\n",
+  );
+  process.exit(1);
+}
+
+// ── arg parsing ─────────────────────────────────────────────────────────────
+// Splits argv into { _: positionals, flags: {name: value|true} }.
+function parseArgs(argv) {
+  const _ = [];
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith("--")) {
+        flags[key] = true;
+      } else {
+        flags[key] = next;
+        i++;
+      }
+    } else {
+      _.push(a);
+    }
+  }
+  return { _, flags };
+}
+
+// ── HTTP ────────────────────────────────────────────────────────────────────
+// Non-throwing: returns { status, json }. status 0 == network error.
+async function tryRequest(path, { method = "POST", body, auth = true } = {}) {
+  const { apiKey, baseUrl } = config();
+  const headers = { "Content-Type": "application/json" };
+  if (auth && apiKey) headers.Authorization = `Bearer ${apiKey}`;
+  let res;
+  try {
+    res = await fetch(`${baseUrl}${path}`, {
+      method,
+      headers,
+      body: body ? JSON.stringify(body) : undefined,
+    });
+  } catch (e) {
+    return { status: 0, json: { error: `Network error reaching ${baseUrl}${path}`, detail: String(e) } };
+  }
+  const text = await res.text();
+  let json;
+  try {
+    json = text ? JSON.parse(text) : {};
+  } catch {
+    json = { raw: text };
+  }
+  return { status: res.status, json };
+}
+
+// Throwing variant: exits non-zero on any error.
+async function request(path, opts = {}) {
+  const { status, json } = await tryRequest(path, opts);
+  if (status === 0 || status >= 400) {
+    fail(json.error || `Request failed (${status})`, { status, code: json.code });
+  }
+  return json;
+}
+
+// POST a tool at /api/agent/<tool>, returning its `result`.
+async function runTool(tool, args) {
+  const json = await request(`/api/agent/${tool}`, { body: args });
+  return json.result !== undefined ? json.result : json;
+}
+
+// Run any tool by name — tries the agent surface, then the free-tools surface
+// (/api/tools/<slug>), so deterministic tools work here too.
+async function runAnyTool(tool, args) {
+  let r = await tryRequest(`/api/agent/${tool}`, { body: args });
+  if (r.status === 404) r = await tryRequest(`/api/tools/${tool}`, { body: args });
+  if (r.status === 0 || r.status >= 400) {
+    fail(r.json.error || `Request failed (${r.status})`, { status: r.status, code: r.json.code });
+  }
+  return r.json.result !== undefined ? r.json.result : r.json;
+}
+
+function requireKey() {
+  if (!config().apiKey) {
+    fail(
+      "No API key. Run `spook auth login --key spook_agent_...` or set SPOOK_API_KEY. Generate a key in Spook → Settings → Agent API.",
+    );
+  }
+}
+
+// ── commands ──────────────────────────────────────────────────────────────
+const HELP = `Spook CLI ${VERSION} — agent-first CLI for the Spook agent API
+
+Usage: spook <command> [args] [--flags]
+
+Auth
+  auth login --key <spook_agent_...> [--base <url>]   Save your API key
+  auth whoami                                         Verify the key (lists sites)
+  auth logout                                         Remove saved config
+
+Free (no key)
+  analyze <domain>                                    Quick-win queries for any domain
+
+Sites
+  sites                                               List your sites
+  site <siteId>                                       Site details
+  sites:create --name <n> --domain <d> [--description <t>]
+               [--publish <nextjs|webhook|wordpress|ghost|shopify|rest>] [--webhook <url>]
+  publishing <siteId> --integration <type> [--mode <draft|live>] [--webhook <url>]
+  autopilot <siteId> <on|off>
+  metrics <siteId> [--days <n>]
+  checkout                                            Get a Stripe Checkout URL to add a paid site
+
+Content
+  opportunities <siteId> [--questions] [--limit <n>]  Winnable queries
+  articles <siteId> [--limit <n>]                     Recent articles
+  article <articleId>                                 One article (full body + SEO)
+  generate <siteId> <query...> [--callback <https-url>]
+  publish <articleId>
+
+Any tool (incl. the free AI tools)
+  tools                                               List every tool + schema
+  run <tool> [jsonBody]                               Run any tool by name
+     e.g. spook run blog-outline-generator '{"topic":"cold brew"}'
+
+Global: --base <url> and SPOOK_BASE_URL override the API host (default ${DEFAULT_BASE}).
+        SPOOK_API_KEY overrides the saved key. Output is JSON.`;
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const { _, flags } = parseArgs(argv);
+  const cmd = _[0];
+
+  if (!cmd || cmd === "help" || flags.help || cmd === "--help") return out({ help: HELP });
+  if (cmd === "version" || flags.version) return out({ version: VERSION });
+
+  // Allow --base to override for a single invocation.
+  if (typeof flags.base === "string") process.env.SPOOK_BASE_URL = flags.base;
+
+  switch (cmd) {
+    case "auth": {
+      const sub = _[1];
+      if (sub === "login") {
+        const key = typeof flags.key === "string" ? flags.key : "";
+        if (!key) fail("Pass --key spook_agent_...");
+        const cfg = readConfig();
+        cfg.apiKey = key;
+        if (typeof flags.base === "string") cfg.baseUrl = flags.base;
+        writeConfig(cfg);
+        return out({ ok: true, savedTo: CONFIG_PATH, baseUrl: config().baseUrl });
+      }
+      if (sub === "logout") {
+        if (existsSync(CONFIG_PATH)) rmSync(CONFIG_PATH);
+        return out({ ok: true });
+      }
+      if (sub === "whoami") {
+        requireKey();
+        const r = await request(`/api/agent/list_sites`, { body: {} });
+        const sites = r.result?.sites ?? [];
+        return out({ authenticated: true, sites: sites.length, baseUrl: config().baseUrl });
+      }
+      return fail("Usage: spook auth <login|whoami|logout>");
+    }
+
+    case "analyze": {
+      const domain = _[1];
+      if (!domain) fail("Usage: spook analyze <domain>");
+      return out(await runTool("analyze_domain", { domain }));
+    }
+
+    case "sites":
+      requireKey();
+      return out(await runTool("list_sites", {}));
+
+    case "sites:create": {
+      requireKey();
+      const { name, domain } = flags;
+      if (typeof name !== "string" || typeof domain !== "string") {
+        fail("Usage: spook sites:create --name <n> --domain <d>");
+      }
+      return out(
+        await runTool("create_site", {
+          name,
+          domain,
+          description: typeof flags.description === "string" ? flags.description : undefined,
+          brandVoice: typeof flags.voice === "string" ? flags.voice : undefined,
+          niche: typeof flags.niche === "string" ? flags.niche : undefined,
+          publishIntegration: typeof flags.publish === "string" ? flags.publish : undefined,
+          publishWebhookUrl: typeof flags.webhook === "string" ? flags.webhook : undefined,
+        }),
+      );
+    }
+
+    case "site": {
+      requireKey();
+      const siteId = _[1];
+      if (!siteId) fail("Usage: spook site <siteId>");
+      return out(await runTool("get_site", { siteId }));
+    }
+
+    case "publishing": {
+      requireKey();
+      const siteId = _[1];
+      if (!siteId) fail("Usage: spook publishing <siteId> --integration <type>");
+      return out(
+        await runTool("update_publishing", {
+          siteId,
+          publishIntegration: typeof flags.integration === "string" ? flags.integration : undefined,
+          publishMode: typeof flags.mode === "string" ? flags.mode : undefined,
+          publishWebhookUrl: typeof flags.webhook === "string" ? flags.webhook : undefined,
+          publishWebhookSecret: typeof flags.secret === "string" ? flags.secret : undefined,
+        }),
+      );
+    }
+
+    case "autopilot": {
+      requireKey();
+      const siteId = _[1];
+      const state = _[2];
+      if (!siteId || !["on", "off"].includes(state)) {
+        fail("Usage: spook autopilot <siteId> <on|off>");
+      }
+      return out(await runTool("set_autopilot", { siteId, enabled: state === "on" }));
+    }
+
+    case "metrics": {
+      requireKey();
+      const siteId = _[1];
+      if (!siteId) fail("Usage: spook metrics <siteId> [--days <n>]");
+      return out(
+        await runTool("get_site_metrics", {
+          siteId,
+          days: typeof flags.days === "string" ? Number(flags.days) : undefined,
+        }),
+      );
+    }
+
+    case "checkout":
+      requireKey();
+      return out(await runTool("create_checkout", {}));
+
+    case "opportunities": {
+      requireKey();
+      const siteId = _[1];
+      if (!siteId) fail("Usage: spook opportunities <siteId> [--questions] [--limit <n>]");
+      return out(
+        await runTool("list_opportunities", {
+          siteId,
+          questionsOnly: flags.questions === true,
+          limit: typeof flags.limit === "string" ? Number(flags.limit) : undefined,
+        }),
+      );
+    }
+
+    case "articles": {
+      requireKey();
+      const siteId = _[1];
+      if (!siteId) fail("Usage: spook articles <siteId> [--limit <n>]");
+      return out(
+        await runTool("list_articles", {
+          siteId,
+          limit: typeof flags.limit === "string" ? Number(flags.limit) : undefined,
+        }),
+      );
+    }
+
+    case "article": {
+      requireKey();
+      const articleId = _[1];
+      if (!articleId) fail("Usage: spook article <articleId>");
+      return out(await runTool("get_article", { articleId }));
+    }
+
+    case "generate": {
+      requireKey();
+      const siteId = _[1];
+      const query = _.slice(2).join(" ");
+      if (!siteId || !query) fail('Usage: spook generate <siteId> "<query>" [--callback <url>]');
+      return out(
+        await runTool("generate_article", {
+          siteId,
+          query,
+          callbackUrl: typeof flags.callback === "string" ? flags.callback : undefined,
+        }),
+      );
+    }
+
+    case "publish": {
+      requireKey();
+      const articleId = _[1];
+      if (!articleId) fail("Usage: spook publish <articleId>");
+      return out(await runTool("publish_article", { articleId }));
+    }
+
+    case "tools":
+      return out(await request(`/api/agent`, { method: "GET", auth: false }));
+
+    case "run": {
+      const tool = _[1];
+      if (!tool) fail('Usage: spook run <tool> [jsonBody]');
+      let body = {};
+      const raw = _[2];
+      if (raw) {
+        try {
+          body = JSON.parse(raw);
+        } catch {
+          fail("Invalid JSON body. Wrap it in single quotes, e.g. '{\"topic\":\"x\"}'");
+        }
+      }
+      return out(await runAnyTool(tool, body));
+    }
+
+    default:
+      return fail(`Unknown command: ${cmd}. Run \`spook help\`.`);
+  }
+}
+
+main().catch((e) => fail("Unexpected error", { detail: String(e?.stack || e) }));

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "spook-cli",
+  "version": "0.1.0",
+  "description": "Agent-first CLI for the Spook agent API (SEO autopilot: find winnable queries, generate & publish SEO content).",
+  "type": "module",
+  "bin": {
+    "spook": "bin/spook.js"
+  },
+  "files": [
+    "bin",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "spook",
+    "cli",
+    "agent",
+    "seo",
+    "content",
+    "ai",
+    "mcp"
+  ],
+  "author": "Spook (https://www.tryspook.com)",
+  "homepage": "https://www.tryspook.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/VictorKildahl/spook.git",
+    "directory": "cli"
+  },
+  "bugs": {
+    "url": "https://github.com/VictorKildahl/spook/issues"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}