specdown-cli 0.1.1

package/README.md

@@ -0,0 +1,167 @@
+# SpecDown CLI
+
+<p align="center">
+  <img src="https://img.shields.io/npm/v/specdown-cli?color=blue" alt="npm version" />
+  <img src="https://img.shields.io/node/v/specdown-cli" alt="node" />
+  <img src="https://img.shields.io/npm/dm/specdown-cli" alt="downloads" />
+</p>
+
+**CLI for [SpecDown](https://specdown.app)** — manage your Markdown spec docs from the terminal.
+Read, write, push, pull, and search spec documents. Works great in CI/CD pipelines and AI automation scripts.
+
+---
+
+## Install
+
+```bash
+# Run without installing (recommended):
+npx specdown-cli --help
+
+# Or install globally:
+npm install -g specdown-cli
+```
+
+**Requirements:** Node.js ≥ 18
+
+---
+
+## Quick Start
+
+```bash
+# 1. Login
+specdown login
+
+# 2. Switch to a project
+specdown use my-project-slug
+
+# 3. List documents
+specdown ls
+
+# 4. Read a document
+specdown read /README.md
+```
+
+---
+
+## Commands
+
+### Authentication
+
+```bash
+specdown login           # Sign in with email + password
+specdown logout          # Sign out and clear credentials
+specdown whoami          # Show current user and active project
+```
+
+### Projects
+
+```bash
+specdown projects        # List all projects you have access to
+specdown use <slug>      # Switch active project
+```
+
+### Documents
+
+```bash
+specdown ls                          # List documents in active project
+specdown read <path>                 # Print document content to stdout
+specdown read <path> --from 10 --to 50   # Print lines 10–50
+specdown read <path> -n              # Print with line numbers
+```
+
+### Search
+
+```bash
+specdown search "authentication flow"
+specdown search "api" --files "design,api-spec"   # Restrict to specific docs
+specdown search "TODO" -C 5                       # 5 lines of context
+```
+
+### Create & Edit
+
+```bash
+specdown new "API Design"            # Create a new document
+specdown new "Design" --folder       # Create a folder
+specdown new "Auth" -p /design       # Create inside a folder
+```
+
+### Sync
+
+```bash
+specdown push ./local-file.md /remote/path.md    # Upload local file to SpecDown
+specdown pull /remote/path.md                    # Print remote doc to stdout
+specdown pull /remote/path.md out.md             # Save to local file
+```
+
+### Delete
+
+```bash
+specdown rm /path/to/doc.md          # Delete a document (with confirmation)
+specdown rm /path/to/doc.md --force  # Skip confirmation
+```
+
+---
+
+## Configuration
+
+Credentials are stored in `~/.specdown/config.json` after login. No environment variables required for standard use.
+
+```json
+{
+  "access_token": "...",
+  "refresh_token": "...",
+  "user_email": "you@example.com",
+  "user_id": "...",
+  "current_project_slug": "my-project",
+  "current_project_name": "My Project"
+}
+```
+
+---
+
+## CI/CD Usage
+
+Use environment variables for non-interactive environments:
+
+```bash
+# In CI: set token directly, skip login prompt
+SPECDOWN_ACCESS_TOKEN=<token> specdown ls
+```
+
+Or use the CLI in automation scripts:
+
+```bash
+# Pull latest spec and pass to AI
+specdown pull /api-spec.md | claude "suggest improvements"
+
+# Auto-publish docs from CI
+specdown push ./docs/openapi.md /api/openapi.md
+```
+
+---
+
+## AI Usage (MCP)
+
+Pair the CLI with the [SpecDown MCP Server](https://github.com/specdown-app/mcp-server) to give Claude, Cursor, and other AI assistants direct access to your specs:
+
+```bash
+# Install MCP server
+npm install -g specdown-mcp
+
+# Your API key is in ~/.specdown/config.json after login
+cat ~/.specdown/config.json
+```
+
+---
+
+## Links
+
+- [SpecDown](https://specdown.app) — Spec-as-Code platform
+- [Docs](https://specdown.app/docs)
+- [MCP Server](https://github.com/specdown-app/mcp-server) — AI integration
+- [GitHub](https://github.com/specdown-app/cli)
+- [Report issue](https://github.com/specdown-app/cli/issues)
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,597 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command } from "commander";
+
+// src/commands/login.ts
+import chalk from "chalk";
+import ora from "ora";
+
+// src/lib/api.ts
+import { createClient } from "@supabase/supabase-js";
+var SUPABASE_URL = "https://zjvjdalqgrxdhefqqifd.supabase.co";
+var SUPABASE_ANON_KEY = "sb_publishable_y-O0ly4bNH0G4KJii3m25g_WXujFZDo";
+function getClient(cfg) {
+  const client = createClient(SUPABASE_URL, SUPABASE_ANON_KEY, {
+    auth: { persistSession: false }
+  });
+  client.auth.setSession({
+    access_token: cfg.access_token,
+    refresh_token: cfg.refresh_token
+  });
+  return client;
+}
+function anonClient() {
+  return createClient(SUPABASE_URL, SUPABASE_ANON_KEY, {
+    auth: { persistSession: false }
+  });
+}
+
+// src/lib/config.ts
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+var CONFIG_DIR = join(homedir(), ".specdown");
+var CONFIG_FILE = join(CONFIG_DIR, "config.json");
+function readConfig() {
+  if (!existsSync(CONFIG_FILE)) return null;
+  try {
+    return JSON.parse(readFileSync(CONFIG_FILE, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+function writeConfig(config) {
+  if (!existsSync(CONFIG_DIR)) mkdirSync(CONFIG_DIR, { recursive: true });
+  writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), "utf-8");
+}
+function clearConfig() {
+  if (existsSync(CONFIG_FILE)) writeFileSync(CONFIG_FILE, "{}", "utf-8");
+}
+function requireAuth() {
+  const cfg = readConfig();
+  if (!cfg?.access_token) {
+    console.error("Not logged in. Run: specdown login");
+    process.exit(1);
+  }
+  return cfg;
+}
+function requireProject(cfg) {
+  if (!cfg.current_project_id || !cfg.current_project_slug) {
+    console.error("No project selected. Run: specdown use <project-slug>");
+    process.exit(1);
+  }
+  return {
+    id: cfg.current_project_id,
+    slug: cfg.current_project_slug,
+    name: cfg.current_project_name ?? cfg.current_project_slug
+  };
+}
+
+// src/lib/prompt.ts
+import { createInterface } from "readline";
+function ask(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+function askPassword(question) {
+  return new Promise((resolve) => {
+    process.stdout.write(question);
+    const stdin = process.stdin;
+    const chunks = [];
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.on("data", function handler(chunk) {
+      const char = chunk.toString();
+      if (char === "\r" || char === "\n") {
+        stdin.setRawMode(false);
+        stdin.pause();
+        stdin.removeListener("data", handler);
+        process.stdout.write("\n");
+        resolve(Buffer.concat(chunks).toString());
+      } else if (char === "") {
+        process.exit();
+      } else if (char === "\x7F") {
+        if (chunks.length) chunks.pop();
+      } else {
+        chunks.push(chunk);
+      }
+    });
+  });
+}
+
+// src/commands/login.ts
+async function login() {
+  console.log(chalk.bold("\nSpecDown Login\n"));
+  const email = await ask("Email: ");
+  const password = await askPassword("Password: ");
+  const spinner = ora("Signing in\u2026").start();
+  try {
+    const supabase = anonClient();
+    const { data, error } = await supabase.auth.signInWithPassword({ email, password });
+    if (error || !data.session) {
+      spinner.fail(chalk.red("Login failed: " + (error?.message ?? "No session")));
+      process.exit(1);
+    }
+    const { session, user } = data;
+    writeConfig({
+      access_token: session.access_token,
+      refresh_token: session.refresh_token,
+      user_email: user.email ?? email,
+      user_id: user.id
+    });
+    spinner.succeed(chalk.green(`Logged in as ${chalk.bold(user.email)}`));
+  } catch (err) {
+    spinner.fail(chalk.red("Login failed"));
+    console.error(err);
+    process.exit(1);
+  }
+}
+
+// src/commands/logout.ts
+import chalk2 from "chalk";
+function logout() {
+  const cfg = readConfig();
+  if (!cfg?.access_token) {
+    console.log(chalk2.yellow("Not logged in."));
+    return;
+  }
+  clearConfig();
+  console.log(chalk2.green("Logged out."));
+}
+
+// src/commands/whoami.ts
+import chalk3 from "chalk";
+function whoami() {
+  const cfg = requireAuth();
+  console.log(chalk3.bold(cfg.user_email));
+  console.log(chalk3.gray("ID: ") + cfg.user_id);
+  if (cfg.current_project_name) {
+    console.log(chalk3.gray("Project: ") + cfg.current_project_name + chalk3.gray(` (${cfg.current_project_slug})`));
+  }
+}
+
+// src/commands/projects.ts
+import chalk4 from "chalk";
+import ora2 from "ora";
+async function listProjects() {
+  const cfg = requireAuth();
+  const supabase = getClient(cfg);
+  const spinner = ora2("Fetching projects\u2026").start();
+  try {
+    const { data, error } = await supabase.from("projects").select("id, name, slug, updated_at").order("updated_at", { ascending: false });
+    if (error) throw error;
+    spinner.stop();
+    if (!data?.length) {
+      console.log(chalk4.gray("No projects found."));
+      return;
+    }
+    for (const p of data) {
+      const isCurrent = p.slug === cfg.current_project_slug;
+      const marker = isCurrent ? chalk4.green("* ") : "  ";
+      const name = isCurrent ? chalk4.bold.green(p.name) : chalk4.bold(p.name);
+      console.log(`${marker}${name} ${chalk4.gray(p.slug)}`);
+    }
+  } catch (err) {
+    spinner.fail(chalk4.red("Failed to fetch projects"));
+    console.error(err);
+    process.exit(1);
+  }
+}
+
+// src/commands/use.ts
+import chalk5 from "chalk";
+import ora3 from "ora";
+async function useProject(slug) {
+  const cfg = requireAuth();
+  const supabase = getClient(cfg);
+  const spinner = ora3(`Switching to project "${slug}"\u2026`).start();
+  try {
+    const { data, error } = await supabase.from("projects").select("id, name, slug").eq("slug", slug).single();
+    if (error || !data) {
+      spinner.fail(chalk5.red(`Project "${slug}" not found.`));
+      process.exit(1);
+    }
+    const current = readConfig() ?? cfg;
+    writeConfig({
+      ...current,
+      current_project_id: data.id,
+      current_project_slug: data.slug,
+      current_project_name: data.name
+    });
+    spinner.succeed(chalk5.green(`Now using project ${chalk5.bold(data.name)}`));
+  } catch (err) {
+    spinner.fail(chalk5.red("Failed to switch project"));
+    console.error(err);
+    process.exit(1);
+  }
+}
+
+// src/commands/ls.ts
+import chalk6 from "chalk";
+import ora4 from "ora";
+function buildTree(docs) {
+  const map = /* @__PURE__ */ new Map();
+  for (const d of docs) map.set(d.id, { ...d, children: [] });
+  const roots = [];
+  for (const node of map.values()) {
+    if (node.parent_id && map.has(node.parent_id)) {
+      map.get(node.parent_id).children.push(node);
+    } else {
+      roots.push(node);
+    }
+  }
+  const sort = (nodes) => {
+    nodes.sort((a, b) => {
+      if (a.is_folder !== b.is_folder) return a.is_folder ? -1 : 1;
+      if (a.sort_order !== b.sort_order) return a.sort_order - b.sort_order;
+      return a.title.localeCompare(b.title);
+    });
+    for (const n of nodes) sort(n.children);
+  };
+  sort(roots);
+  return roots;
+}
+function printTree(nodes, prefix = "") {
+  for (let i = 0; i < nodes.length; i++) {
+    const node = nodes[i];
+    const isLast = i === nodes.length - 1;
+    const connector = isLast ? "\u2514\u2500\u2500 " : "\u251C\u2500\u2500 ";
+    const childPrefix = prefix + (isLast ? "    " : "\u2502   ");
+    if (node.is_folder) {
+      console.log(prefix + connector + chalk6.bold.blue("\u{1F4C1} " + node.title));
+    } else {
+      console.log(prefix + connector + chalk6.white("\u{1F4C4} " + node.title) + chalk6.gray("  " + node.path));
+    }
+    if (node.children.length) printTree(node.children, childPrefix);
+  }
+}
+async function ls() {
+  const cfg = requireAuth();
+  const project = requireProject(cfg);
+  const supabase = getClient(cfg);
+  const spinner = ora4("Loading documents\u2026").start();
+  try {
+    const { data, error } = await supabase.from("documents").select("id, title, slug, path, full_path, is_folder, parent_id, sort_order, updated_at").eq("project_id", project.id).is("deleted_at", null).order("is_folder", { ascending: false }).order("sort_order").order("title");
+    if (error) throw error;
+    spinner.stop();
+    console.log(chalk6.bold(`
+${project.name}
+`));
+    if (!data?.length) {
+      console.log(chalk6.gray("  (empty)"));
+      return;
+    }
+    const tree = buildTree(data);
+    printTree(tree);
+    console.log();
+  } catch (err) {
+    spinner.fail(chalk6.red("Failed to list documents"));
+    console.error(err);
+    process.exit(1);
+  }
+}
+
+// src/commands/read.ts
+import chalk7 from "chalk";
+import ora5 from "ora";
+function normalizePath(p) {
+  return p.startsWith("/") ? p : `/${p}`;
+}
+async function readDoc(pathArg, opts) {
+  const cfg = requireAuth();
+  const project = requireProject(cfg);
+  const supabase = getClient(cfg);
+  const spinner = ora5("Fetching document\u2026").start();
+  try {
+    const { data, error } = await supabase.from("documents").select("title, full_path, content, updated_at").eq("project_id", project.id).eq("is_folder", false).is("deleted_at", null).eq("full_path", normalizePath(pathArg)).single();
+    if (error || !data) {
+      spinner.fail(chalk7.red(`Document not found: ${pathArg}`));
+      process.exit(1);
+    }
+    spinner.stop();
+    const rawLines = (data.content ?? "").split("\n");
+    const totalLines = rawLines.length;
+    const fromLine = opts.from ? Math.max(1, parseInt(opts.from, 10)) : 1;
+    const toLine = opts.to ? Math.min(totalLines, parseInt(opts.to, 10)) : totalLines;
+    if (fromLine > toLine) {
+      console.error(chalk7.red(`Invalid range: --from ${fromLine} is after --to ${toLine}`));
+      process.exit(1);
+    }
+    const selectedLines = rawLines.slice(fromLine - 1, toLine);
+    const rangeLabel = fromLine === 1 && toLine === totalLines ? `${totalLines} lines` : `lines ${fromLine}\u2013${toLine} of ${totalLines}`;
+    console.log(chalk7.gray(`# ${data.full_path}  (${rangeLabel}, updated ${new Date(data.updated_at).toLocaleString()})
+`));
+    if (opts.lineNumbers) {
+      const padWidth = String(toLine).length;
+      selectedLines.forEach((line, i) => {
+        console.log(chalk7.gray(String(fromLine + i).padStart(padWidth) + "  ") + line);
+      });
+    } else {
+      console.log(selectedLines.join("\n"));
+    }
+  } catch {
+    spinner.fail(chalk7.red("Failed to read document"));
+    process.exit(1);
+  }
+}
+
+// src/commands/new.ts
+import chalk8 from "chalk";
+import ora6 from "ora";
+function normalizePath2(p) {
+  return p.startsWith("/") ? p : `/${p}`;
+}
+async function newDoc(title, opts) {
+  const cfg = requireAuth();
+  const project = requireProject(cfg);
+  const supabase = getClient(cfg);
+  const spinner = ora6("Creating\u2026").start();
+  try {
+    const slug = title.toLowerCase().replace(/\s+/g, "-").replace(/[^a-z0-9-]/g, "");
+    const docSlug = opts.folder ? slug : `${slug}.md`;
+    let parentId = null;
+    let dirPath = "/";
+    if (opts.parent) {
+      const parentPath = normalizePath2(opts.parent);
+      const { data: parentDoc } = await supabase.from("documents").select("id, full_path").eq("project_id", project.id).eq("is_folder", true).eq("full_path", parentPath).single();
+      if (!parentDoc) {
+        spinner.fail(chalk8.red(`Parent folder not found: ${opts.parent}`));
+        process.exit(1);
+      }
+      parentId = parentDoc.id;
+      dirPath = (parentDoc.full_path ?? "") + "/";
+    }
+    const fullPath = `${dirPath}${docSlug}`;
+    const { data, error } = await supabase.from("documents").insert({
+      project_id: project.id,
+      created_by: cfg.user_id,
+      title,
+      slug: docSlug,
+      path: dirPath,
+      full_path: fullPath,
+      is_folder: opts.folder ?? false,
+      parent_id: parentId,
+      sort_order: 9999,
+      content: opts.folder ? null : `# ${title}
+`
+    }).select("id, full_path").single();
+    if (error) throw error;
+    spinner.succeed(chalk8.green(`Created: ${data.full_path}`));
+  } catch {
+    spinner.fail(chalk8.red("Failed to create document"));
+    process.exit(1);
+  }
+}
+
+// src/commands/push.ts
+import { readFileSync as readFileSync2, existsSync as existsSync2, statSync } from "fs";
+import chalk9 from "chalk";
+import ora7 from "ora";
+var MAX_FILE_BYTES = 10 * 1024 * 1024;
+function normalizePath3(p) {
+  return p.startsWith("/") ? p : `/${p}`;
+}
+async function push(filePath, docPath) {
+  if (!existsSync2(filePath)) {
+    console.error(chalk9.red(`File not found: ${filePath}`));
+    process.exit(1);
+  }
+  const stat = statSync(filePath);
+  if (stat.size > MAX_FILE_BYTES) {
+    console.error(chalk9.red(`File too large (${(stat.size / 1024 / 1024).toFixed(1)} MB). Max 10 MB.`));
+    process.exit(1);
+  }
+  const content = readFileSync2(filePath, "utf-8");
+  const cfg = requireAuth();
+  const project = requireProject(cfg);
+  const supabase = getClient(cfg);
+  const fullPath = normalizePath3(docPath);
+  const spinner = ora7(`Pushing ${filePath} \u2192 ${fullPath}\u2026`).start();
+  try {
+    const { data: existing } = await supabase.from("documents").select("id").eq("project_id", project.id).eq("is_folder", false).is("deleted_at", null).eq("full_path", fullPath).single();
+    if (existing) {
+      const { error } = await supabase.from("documents").update({ content, updated_at: (/* @__PURE__ */ new Date()).toISOString() }).eq("id", existing.id);
+      if (error) throw error;
+      spinner.succeed(chalk9.green(`Updated: ${fullPath}`));
+    } else {
+      const parts = fullPath.split("/");
+      const filename = parts.pop() ?? "doc.md";
+      const dirPath = parts.length > 1 ? parts.join("/") + "/" : "/";
+      const slug = filename.toLowerCase().replace(/\s+/g, "-").replace(/[^a-z0-9.-]/g, "");
+      const { error } = await supabase.from("documents").insert({
+        project_id: project.id,
+        created_by: cfg.user_id,
+        title: slug.replace(/\.md$/, ""),
+        slug,
+        path: dirPath,
+        full_path: fullPath,
+        is_folder: false,
+        parent_id: null,
+        sort_order: 9999,
+        content
+      });
+      if (error) throw error;
+      spinner.succeed(chalk9.green(`Created: ${fullPath}`));
+    }
+  } catch {
+    spinner.fail(chalk9.red("Push failed"));
+    process.exit(1);
+  }
+}
+
+// src/commands/pull.ts
+import { writeFileSync as writeFileSync2, mkdirSync as mkdirSync2 } from "fs";
+import { dirname } from "path";
+import chalk10 from "chalk";
+import ora8 from "ora";
+function normalizePath4(p) {
+  return p.startsWith("/") ? p : `/${p}`;
+}
+async function pull(docPath, outFile) {
+  const cfg = requireAuth();
+  const project = requireProject(cfg);
+  const supabase = getClient(cfg);
+  const spinner = ora8(`Pulling ${docPath}\u2026`).start();
+  try {
+    const { data, error } = await supabase.from("documents").select("title, full_path, content").eq("project_id", project.id).eq("is_folder", false).is("deleted_at", null).eq("full_path", normalizePath4(docPath)).single();
+    if (error || !data) {
+      spinner.fail(chalk10.red(`Document not found: ${docPath}`));
+      process.exit(1);
+    }
+    const content = data.content ?? "";
+    if (outFile) {
+      const dir = dirname(outFile);
+      if (dir !== ".") mkdirSync2(dir, { recursive: true });
+      writeFileSync2(outFile, content, "utf-8");
+      spinner.succeed(chalk10.green(`Saved to ${outFile}`));
+    } else {
+      spinner.stop();
+      process.stdout.write(content);
+    }
+  } catch {
+    spinner.fail(chalk10.red("Pull failed"));
+    process.exit(1);
+  }
+}
+
+// src/commands/rm.ts
+import chalk11 from "chalk";
+import ora9 from "ora";
+function normalizePath5(p) {
+  return p.startsWith("/") ? p : `/${p}`;
+}
+async function rm(docPath, opts) {
+  const cfg = requireAuth();
+  const project = requireProject(cfg);
+  const supabase = getClient(cfg);
+  const fullPath = normalizePath5(docPath);
+  const spinner = ora9(`Looking up ${fullPath}\u2026`).start();
+  try {
+    const { data, error } = await supabase.from("documents").select("id, title, is_folder").eq("project_id", project.id).is("deleted_at", null).eq("full_path", fullPath).single();
+    if (error || !data) {
+      spinner.fail(chalk11.red(`Document not found: ${fullPath}`));
+      process.exit(1);
+    }
+    spinner.stop();
+    if (!opts.force) {
+      const answer = await ask(
+        chalk11.yellow(`Delete "${data.title}"${data.is_folder ? " (folder + all children)" : ""}? [y/N] `)
+      );
+      if (answer.toLowerCase() !== "y") {
+        console.log("Aborted.");
+        return;
+      }
+    }
+    const deleteSpinner = ora9("Deleting\u2026").start();
+    const { error: delErr } = await supabase.from("documents").update({ deleted_at: (/* @__PURE__ */ new Date()).toISOString() }).eq("id", data.id);
+    if (delErr) throw delErr;
+    deleteSpinner.succeed(chalk11.green(`Deleted: ${fullPath}`));
+  } catch {
+    spinner.fail(chalk11.red("Delete failed"));
+    process.exit(1);
+  }
+}
+
+// src/commands/search.ts
+import chalk12 from "chalk";
+import ora10 from "ora";
+function searchInContent(content, query, contextLines) {
+  const lines = content.split("\n");
+  const lower = query.toLowerCase();
+  const results = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].toLowerCase().includes(lower)) {
+      results.push({
+        lineNo: i + 1,
+        line: lines[i],
+        before: lines.slice(Math.max(0, i - contextLines), i),
+        after: lines.slice(i + 1, Math.min(lines.length, i + 1 + contextLines))
+      });
+    }
+  }
+  return results;
+}
+function highlight(line, query) {
+  const idx = line.toLowerCase().indexOf(query.toLowerCase());
+  if (idx === -1) return line;
+  return line.slice(0, idx) + chalk12.bgYellow.black(line.slice(idx, idx + query.length)) + line.slice(idx + query.length);
+}
+function printContextLine(lineNo, line) {
+  console.log(chalk12.gray(String(lineNo).padStart(4) + " \u2502 ") + chalk12.dim(line));
+}
+async function search(query, opts) {
+  const cfg = requireAuth();
+  const project = requireProject(cfg);
+  const supabase = getClient(cfg);
+  const contextLines = Math.min(parseInt(opts.context ?? "2", 10), 10);
+  const spinner = ora10("Searching\u2026").start();
+  try {
+    let q = supabase.from("documents").select("full_path, slug, content").eq("project_id", project.id).eq("is_folder", false).is("deleted_at", null).ilike("content", `%${query}%`).order("full_path").limit(100);
+    if (opts.files) {
+      const paths = opts.files.split(",").map((s) => s.trim()).filter(Boolean);
+      if (paths.length > 0) {
+        q = q.in("full_path", paths.map((p) => p.startsWith("/") ? p : `/${p}`));
+      }
+    }
+    const { data, error } = await q;
+    if (error) throw error;
+    spinner.stop();
+    const allMatches = [];
+    for (const doc of data ?? []) {
+      if (!doc.content) continue;
+      const hits = searchInContent(doc.content, query, contextLines);
+      for (const h of hits) {
+        allMatches.push({ docPath: doc.full_path ?? doc.slug, ...h });
+      }
+    }
+    if (!allMatches.length) {
+      console.log(chalk12.yellow(`No results for "${query}" in ${project.name}`));
+      return;
+    }
+    let currentFile = "";
+    for (const m of allMatches) {
+      if (m.docPath !== currentFile) {
+        if (currentFile) console.log();
+        currentFile = m.docPath;
+        console.log(chalk12.bold.cyan(`
+\u{1F4C4} ${m.docPath}`));
+        console.log(chalk12.gray("\u2500".repeat(50)));
+      }
+      m.before.forEach((l, i) => printContextLine(m.lineNo - m.before.length + i, l));
+      console.log(chalk12.green(String(m.lineNo).padStart(4) + " \u2502 ") + highlight(m.line, query));
+      m.after.forEach((l, i) => printContextLine(m.lineNo + 1 + i, l));
+      if (m.after.length || m.before.length) console.log(chalk12.gray("     \xB7"));
+    }
+    const fileCount = new Set(allMatches.map((m) => m.docPath)).size;
+    console.log();
+    console.log(
+      chalk12.bold(`${allMatches.length} match${allMatches.length === 1 ? "" : "es"}`) + chalk12.gray(` across ${fileCount} file${fileCount === 1 ? "" : "s"} in `) + chalk12.bold(project.name)
+    );
+  } catch {
+    spinner.fail(chalk12.red("Search failed"));
+    process.exit(1);
+  }
+}
+
+// src/index.ts
+var program = new Command();
+program.name("specdown").description("Manage SpecDown docs from your terminal").version("0.1.0");
+program.command("login").description("Log in to SpecDown").action(login);
+program.command("logout").description("Log out").action(logout);
+program.command("whoami").description("Show current user and active project").action(whoami);
+program.command("projects").description("List all projects you have access to").action(listProjects);
+program.command("use <slug>").description("Switch active project by slug").action(useProject);
+program.command("ls").description("List documents in the active project").action(ls);
+program.command("read <path>").description("Print a document to stdout").option("--from <line>", "Start line (1-based, inclusive)").option("--to <line>", "End line (1-based, inclusive)").option("-n, --line-numbers", "Show line numbers").action(readDoc);
+program.command("search <query>").description("Search text across the whole project or specific files").option("--files <paths>", 'Comma-separated doc paths to restrict search (e.g. "api,docs/guide")').option("-C, --context <n>", "Lines of context around each match", "2").action(search);
+program.command("new <title>").description("Create a new document (or folder with --folder)").option("-f, --folder", "Create a folder instead of a document").option("-p, --parent <path>", "Parent folder path").action(newDoc);
+program.command("push <file> <doc-path>").description("Upload a local file to a document path in SpecDown").action(push);
+program.command("pull <doc-path> [out-file]").description("Download a document from SpecDown (or print to stdout)").action(pull);
+program.command("rm <path>").description("Delete a document or folder (soft delete)").option("-f, --force", "Skip confirmation prompt").action(rm);
+program.parseAsync(process.argv);

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "specdown-cli",
+  "version": "0.1.1",
+  "description": "CLI for SpecDown — manage spec docs from your terminal",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "specdown": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "specdown",
+    "cli",
+    "docs",
+    "markdown",
+    "spec"
+  ],
+  "author": "SpecDown",
+  "license": "MIT",
+  "homepage": "https://specdown.app",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/specdown-app/cli"
+  },
+  "dependencies": {
+    "@supabase/supabase-js": "^2.97.0",
+    "chalk": "^5.4.1",
+    "commander": "^12.1.0",
+    "ora": "^8.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "tsup": "^8.3.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.0"
+  }
+}