@every-env/spiral-cli 0.2.0 → 1.0.0

package/src/cli.ts

@@ -1,1018 +1,334 @@
 #!/usr/bin/env bun
 
-import * as readline from "node:readline";
-import { parseArgs } from "node:util";
-import { password } from "@inquirer/prompts";
-import chalk from "chalk";
-import { marked } from "marked";
-import { markedTerminal } from "marked-terminal";
-import ora from "ora";
-import { fetchConversations, fetchMessages, getApiBaseUrl, streamChat } from "./api";
-import { formatAttachmentsSummary, processAttachments } from "./attachments";
+import { parseArgs } from "util";
+import { input } from "@inquirer/prompts";
+import { theme, EXIT_CODES } from "./theme.js";
+import { sanitizeError } from "./auth.js";
+import * as auth from "./auth.js";
+import * as api from "./api.js";
+import * as output from "./output.js";
 import {
-  clearStoredPAT,
-  clearTokenCache,
-  getAuthStatus,
-  getAuthToken,
-  sanitizeError,
-  storePAT,
-} from "./auth";
-import { config } from "./config";
-import {
-  editDraft,
-  listDrafts,
-  listVersions,
-  restoreVersion,
-  updateDraftContent,
-  viewDraft,
-} from "./drafts";
-import { addNote, clearNotes, listNotes, removeNote } from "./notes";
-import { listStyles } from "./styles";
-import {
-  applySuggestion,
-  dismissSuggestion,
-  listPendingSuggestions,
-  previewSuggestion,
-  registerSuggestions,
-} from "./suggestions";
-import { EXIT_CODES, theme } from "./theme";
-import { cleanupToolSpinners, handleToolCallUpdate } from "./tools/renderer";
-import { ApiError, type Attachment, AuthenticationError, SpiralCliError } from "./types";
-import { listWorkspaces } from "./workspaces";
-
-// Configure marked for terminal output
-marked.use(
-  markedTerminal({
-    heading: chalk.cyan.bold,
-    code: chalk.yellow,
-    codespan: chalk.bgBlack.yellow,
-  }),
-);
-
-const VERSION = "0.2.0";
-
-// Parse CLI arguments
-const { values, positionals } = parseArgs({
-  args: Bun.argv.slice(2),
-  options: {
-    help: { type: "boolean", short: "h" },
-    version: { type: "boolean", short: "v" },
-    session: { type: "string", short: "s" },
-    json: { type: "boolean" },
-    quiet: { type: "boolean", short: "q" },
-    new: { type: "boolean", short: "n" },
-    limit: { type: "string" },
-    debug: { type: "boolean", short: "d" },
-    // New options for extended features
-    attach: { type: "string", multiple: true, short: "a" },
-    style: { type: "string" },
-    workspace: { type: "string" },
-    force: { type: "boolean", short: "f" },
-    content: { type: "string" }, // For agent-native draft updates
-    title: { type: "string" }, // For draft title
-    versionId: { type: "string" }, // For version restore
-  },
-  allowPositionals: true,
-});
+  SpiralCliError,
+  AuthenticationError,
+  ApiError,
+  type GenerateRequest,
+  type GenerateResponse,
+} from "./types.js";
 
-// Enable debug mode via flag
-if (values.debug) {
-  process.env.DEBUG = "1";
-}
-
-// Store pending attachments for REPL mode
-let pendingAttachments: Attachment[] = [];
+const VERSION = "1.0.0";
 
-async function main(): Promise<void> {
-  const command = positionals[0];
+const HELP = `
+${theme.heading("spiral")} — write with Spiral from your terminal
 
-  if (values.version) {
-    console.log(`spiral-cli v${VERSION}`);
-    process.exit(EXIT_CODES.SUCCESS);
-  }
-
-  if (values.help || !command) {
-    showHelp();
-    process.exit(EXIT_CODES.SUCCESS);
-  }
-
-  switch (command) {
-    case "send":
-      await sendCommand(positionals.slice(1).join(" "));
-      break;
-    case "chat":
-      await chatCommand();
-      break;
-    case "sessions":
-      await sessionsCommand();
-      break;
-    case "history":
-      await historyCommand(positionals[1]);
-      break;
-    case "auth":
-      await authCommand(positionals[1]);
-      break;
-    // New commands
-    case "styles":
-      await listStyles({ json: values.json });
-      break;
-    case "workspaces":
-      await listWorkspaces({ json: values.json });
-      break;
-    case "drafts":
-      await draftsCommand();
-      break;
-    case "draft":
-      await draftCommand(positionals[1], positionals[2]);
-      break;
-    case "notes":
-      await notesCommand(positionals[1], positionals.slice(2).join(" "));
-      break;
-    case "suggestions":
-      await suggestionsCommand(positionals[1], positionals[2]);
-      break;
-    default:
-      console.error(theme.error(`Unknown command: ${command}`));
-      process.exit(EXIT_CODES.INVALID_ARGS);
-  }
+${theme.heading("Usage:")}
+  spiral write "a blog post about X"        Create content
+  spiral write "refine tone" --session <id>  Refine existing drafts
+  spiral styles                              List writing styles
+  spiral workspaces                          List workspaces
+  spiral sessions                            List conversations
+  spiral drafts --session <id>               List drafts in a session
+  spiral quota                               Session quota info
+  spiral prime                               Agent discovery document
+  spiral auth login|status|logout            Manage authentication
+
+${theme.heading("Flags:")}
+  --json              Machine-readable JSON output
+  --session <id>      Session ID for multi-turn / refinement
+  --style <id>        Writing style ID
+  --workspace <id>    Workspace ID
+  --instant           Skip clarifying questions
+  --num-drafts <n>    Number of drafts (1-5, default 1)
+  --token <key>       API key for auth login
+  --debug             Show debug info on errors
+  --help, -h          Show this help
+  --version, -v       Show version
+`;
+
+interface ParsedArgs {
+  command: string;
+  positional: string[];
+  flags: {
+    json: boolean;
+    session?: string;
+    style?: string;
+    workspace?: string;
+    instant: boolean;
+    numDrafts?: number;
+    token?: string;
+    debug: boolean;
+    help: boolean;
+    version: boolean;
+    limit?: number;
+  };
 }
 
-/**
- * Non-interactive send command (Agent-Native)
- * Usage: spiral send "Your message here" [--session id] [--json] [--attach file...]
- */
-async function sendCommand(initialMessage: string): Promise<void> {
-  let message = initialMessage;
-  if (!message) {
-    // Check for stdin piping
-    if (!process.stdin.isTTY) {
-      const chunks: string[] = [];
-      for await (const chunk of process.stdin) {
-        chunks.push(chunk.toString());
-      }
-      message = chunks.join("");
-    } else {
-      console.error(theme.error('Usage: spiral send "Your message"'));
-      process.exit(EXIT_CODES.INVALID_ARGS);
-    }
-  }
-
-  const sessionId = values.session || null;
-  const outputJson = values.json;
-  const quiet = values.quiet;
-  const spinner = quiet ? null : ora("Sending...").start();
-
-  // Process attachments if provided
-  let attachments: Attachment[] = [];
-  if (values.attach && values.attach.length > 0) {
-    try {
-      attachments = await processAttachments(values.attach, { quiet });
-      if (!quiet && !outputJson) {
-        console.log(theme.info(`Attached: ${formatAttachmentsSummary(attachments)}`));
-      }
-    } catch (error) {
-      console.error(theme.error((error as Error).message));
-      process.exit(EXIT_CODES.INVALID_ARGS);
-    }
-  }
-
-  // Performance: Use array accumulation (O(n) vs O(n²) string concat)
-  const chunks: string[] = [];
-  const thinkingChunks: string[] = [];
-  let finalSessionId = sessionId || "";
-
-  const controller = new AbortController();
-
-  // Handle Ctrl+C
-  process.on("SIGINT", () => {
-    controller.abort();
-    spinner?.stop();
-    cleanupToolSpinners();
-    if (outputJson) {
-      console.log(JSON.stringify({ status: "cancelled", partial: chunks.join("") }));
-    } else {
-      console.log(theme.warning("\n(Cancelled)"));
-    }
-    process.exit(EXIT_CODES.GENERAL_ERROR);
+function parse(argv: string[]): ParsedArgs {
+  const { values, positionals } = parseArgs({
+    args: argv.slice(2),
+    options: {
+      json: { type: "boolean", default: false },
+      session: { type: "string" },
+      style: { type: "string" },
+      workspace: { type: "string" },
+      instant: { type: "boolean", default: false },
+      "num-drafts": { type: "string" },
+      token: { type: "string" },
+      debug: { type: "boolean", default: false },
+      help: { type: "boolean", short: "h", default: false },
+      version: { type: "boolean", short: "v", default: false },
+      limit: { type: "string" },
+    },
+    allowPositionals: true,
+    strict: false,
   });
 
-  try {
-    await streamChat(
-      message,
-      sessionId,
-      {
-        onChunk: (chunk) => {
-          chunks.push(chunk);
-          if (!outputJson && !quiet) {
-            spinner?.stop();
-            process.stdout.write(chunk);
-          }
-        },
-        onThinking: (thought) => {
-          thinkingChunks.push(thought);
-          if (spinner) spinner.text = `Thinking: ${thought.slice(0, 40)}...`;
-        },
-        onToolCall: (tool) => {
-          if (spinner && tool.status === "started") {
-            spinner.text = `Using ${tool.tool_name}...`;
-          }
-          // Enhanced tool call visualization
-          handleToolCallUpdate({
-            callId: tool.tool_call_id || tool.call_id || `tool-${Date.now()}`,
-            toolName: tool.tool_name,
-            status: tool.status,
-            result: tool.result,
-            error: tool.error,
-          });
-        },
-        onSessionName: () => {},
-        onRetry: (info) => {
-          if (spinner) spinner.text = `Retrying (${info.attempt}/${info.max})...`;
-        },
-        onModelDowngrade: (from, to) => {
-          if (!quiet && !outputJson) {
-            console.log(theme.warning(`\nNote: Model downgraded from ${from} to ${to}`));
-          }
-        },
-        onComplete: (id) => {
-          finalSessionId = id;
-        },
-        onError: (error) => {
-          throw error;
-        },
-      },
-      controller.signal,
-      {
-        attachments: attachments.length > 0 ? attachments : undefined,
-      },
-    );
+  const command = positionals[0] ?? "";
+  const rest = positionals.slice(1);
+
+  return {
+    command,
+    positional: rest,
+    flags: {
+      json: values.json as boolean,
+      session: values.session as string | undefined,
+      style: values.style as string | undefined,
+      workspace: values.workspace as string | undefined,
+      instant: values.instant as boolean,
+      numDrafts: values["num-drafts"]
+        ? Number.parseInt(values["num-drafts"] as string, 10)
+        : undefined,
+      token: values.token as string | undefined,
+      debug: values.debug as boolean,
+      help: values.help as boolean,
+      version: values.version as boolean,
+      limit: values.limit
+        ? Number.parseInt(values.limit as string, 10)
+        : undefined,
+    },
+  };
+}
 
-    const content = chunks.join("");
+// ── Commands ──
 
-    // Register any suggestions from the response
-    const sugCount = registerSuggestions(content);
-    if (sugCount > 0 && !quiet && !outputJson) {
-      console.log(theme.info(`\n${sugCount} suggestion(s) parsed. Use /suggestions to view.`));
-    }
+async function cmdWrite(args: ParsedArgs): Promise<void> {
+  // Read prompt from positional args or stdin
+  let prompt = args.positional.join(" ").trim();
 
-    if (outputJson) {
-      console.log(
-        JSON.stringify({
-          status: "success",
-          session_id: finalSessionId,
-          content,
-          thinking: thinkingChunks.join(""),
-          suggestions_count: sugCount,
-        }),
-      );
-    } else {
-      console.log(); // Newline after streaming
+  if (!prompt && !process.stdin.isTTY) {
+    // Read from piped stdin
+    const chunks: Buffer[] = [];
+    for await (const chunk of process.stdin) {
+      chunks.push(chunk as Buffer);
     }
-
-    process.exit(EXIT_CODES.SUCCESS);
-  } catch (error) {
-    spinner?.stop();
-    cleanupToolSpinners();
-    handleError(error as Error);
+    prompt = Buffer.concat(chunks).toString("utf-8").trim();
   }
-}
-
-/**
- * Interactive REPL command
- */
-async function chatCommand(): Promise<void> {
-  console.log(`${theme.heading("Spiral Chat")} (type /help for commands)\n`);
 
-  if (process.env.DEBUG) {
-    console.log(theme.dim(`API: ${getApiBaseUrl()}\n`));
+  if (!prompt && !args.flags.session) {
+    throw new SpiralCliError(
+      'Usage: spiral write "your prompt here"',
+      EXIT_CODES.INVALID_ARGS,
+    );
   }
 
-  const rl = readline.createInterface({
-    input: process.stdin,
-    output: process.stdout,
-    prompt: theme.user("You: "),
-  });
-
-  let sessionId = values.session || null;
-  let currentController: AbortController | null = null;
+  const req: GenerateRequest = {
+    prompt: prompt || undefined,
+    session_id: args.flags.session,
+    style_id: args.flags.style,
+    workspace_id: args.flags.workspace,
+    mode: args.flags.instant ? "instant" : "interactive",
+    num_drafts: args.flags.numDrafts,
+  };
 
-  const handleInput = async (input: string): Promise<void> => {
-    const trimmed = input.trim();
+  let resp: GenerateResponse = await output.withSpinner("Writing...", () =>
+    api.generate(req),
+  );
 
-    // Handle REPL commands
-    if (trimmed.startsWith("/")) {
-      const newSession = await handleReplCommand(trimmed, rl, sessionId);
-      if (newSession !== undefined) {
-        sessionId = newSession;
-      }
-      rl.prompt();
+  // Multi-turn loop: handle needs_input
+  while (resp.status === "needs_input") {
+    if (args.flags.json || !process.stdin.isTTY) {
+      // Non-interactive: return the needs_input response for caller to handle
+      output.outputJson(resp);
       return;
     }
 
-    if (!trimmed) {
-      rl.prompt();
-      return;
-    }
+    // Show questions
+    output.formatGenerateResponse(resp);
 
-    const spinner = ora("Thinking...").start();
-    const chunks: string[] = [];
-    currentController = new AbortController();
-
-    try {
-      await streamChat(
-        trimmed,
-        sessionId,
-        {
-          onChunk: (chunk) => {
-            if (spinner.isSpinning) {
-              spinner.stop();
-              process.stdout.write(theme.assistant("Spiral: "));
-            }
-            chunks.push(chunk);
-            process.stdout.write(chunk);
-          },
-          onThinking: (thought) => {
-            spinner.text = theme.thinking(`Thinking: ${thought.slice(0, 40)}...`);
-          },
-          onToolCall: (tool) => {
-            if (tool.status === "started") {
-              spinner.text = `Using ${tool.tool_name}...`;
-            }
-          },
-          onSessionName: (name) => {
-            // Could update terminal title here
-            if (process.env.DEBUG) {
-              console.log(theme.dim(`\n[Session: ${name}]`));
-            }
-          },
-          onRetry: (info) => {
-            spinner.text = theme.warning(`Retrying (${info.attempt}/${info.max})...`);
-          },
-          onModelDowngrade: (from, to) => {
-            console.log(theme.warning(`\nNote: Model changed from ${from} to ${to}`));
-          },
-          onComplete: (id) => {
-            sessionId = id;
-          },
-          onError: (error) => {
-            throw error;
-          },
-        },
-        currentController.signal,
-      );
-
-      // Register suggestions from response
-      const content = chunks.join("");
-      const sugCount = registerSuggestions(content);
-      if (sugCount > 0) {
-        console.log(theme.info(`\n${sugCount} suggestion(s) parsed. Use /suggestions to view.`));
-      }
-
-      console.log("\n"); // Newline after response
-    } catch (error) {
-      if (!currentController.signal.aborted) {
-        spinner.fail(sanitizeError(error as Error));
-      }
-    }
-
-    currentController = null;
-    pendingAttachments = []; // Clear attachments after use
-    rl.prompt();
-  };
+    // Prompt for answers
+    const answer = await input({ message: "Your response:" });
 
-  rl.on("line", (input) => {
-    handleInput(input).catch((error) => {
-      console.error(theme.error("Error:"), sanitizeError(error));
-      rl.prompt();
-    });
-  });
+    resp = await output.withSpinner("Writing...", () =>
+      api.generate({
+        session_id: resp.session_id,
+        responses: answer,
+      }),
+    );
+  }
 
-  // Handle Ctrl+C: first cancels stream, second exits
-  rl.on("SIGINT", () => {
-    if (currentController) {
-      currentController.abort();
-      currentController = null;
-      console.log(theme.warning("\n(Stream cancelled)"));
-      rl.prompt();
-    } else {
-      console.log(theme.dim("\nGoodbye!"));
-      process.exit(EXIT_CODES.SUCCESS);
-    }
-  });
+  if (args.flags.json) {
+    output.outputJson(resp);
+  } else {
+    output.formatGenerateResponse(resp);
+  }
+}
 
-  rl.prompt();
+async function cmdStyles(args: ParsedArgs): Promise<void> {
+  const styles = await output.withSpinner("Loading styles...", () =>
+    api.getStyles(),
+  );
+  if (args.flags.json) {
+    output.outputJson(styles);
+  } else {
+    output.formatStyles(styles);
+  }
 }
 
-/**
- * Handle REPL slash commands
- * Returns new session ID if changed, undefined otherwise
- */
-async function handleReplCommand(
-  cmd: string,
-  _rl: readline.Interface,
-  sessionId: string | null,
-): Promise<string | null | undefined> {
-  const parts = cmd.slice(1).split(" ");
-  const command = parts[0];
-  const args = parts.slice(1);
-
-  switch (command) {
-    case "help":
-      console.log(`
-${theme.heading("Commands:")}
-  /help              Show this help
-  /exit              Exit the chat
-  /clear             Clear the screen
-  /history           Show current session history
-  /sessions          List all sessions
-  /new               Start a new session
-  /session <id>      Switch to different session
-  /debug             Toggle debug mode
-
-${theme.heading("Content Management:")}
-  /drafts            List drafts in current session
-  /draft view <id>   View a draft
-  /draft edit <id>   Edit a draft in $EDITOR
-  /draft versions <id>  Show version history
-  /styles            List writing styles
-  /style <id>        Set writing style for messages
-  /workspaces        List workspaces
-  /workspace <id>    Set workspace for new sessions
-
-${theme.heading("Notes & Suggestions:")}
-  /note <text>       Add a note to scratchpad
-  /notes             List all notes
-  /notes clear       Clear all notes
-  /suggestions       List pending suggestions
-  /apply <id>        Apply a suggestion
-  /dismiss <id>      Dismiss a suggestion
-
-${theme.heading("Attachments:")}
-  /attach <files...> Queue files for next message
-`);
-      break;
-    case "exit":
-    case "quit":
-      console.log(theme.dim("Goodbye!"));
-      return process.exit(EXIT_CODES.SUCCESS);
-    case "clear":
-      console.clear();
-      break;
-    case "history":
-      if (sessionId) {
-        await historyCommand(sessionId);
-      } else {
-        console.log(theme.warning("No active session. Start a conversation first."));
-      }
-      break;
-    case "sessions":
-      await sessionsCommand();
-      break;
-    case "new":
-      console.log(theme.info("Starting new session..."));
-      return null; // Clear session ID
-    case "session":
-      if (args[0]) {
-        console.log(theme.info(`Switching to session ${args[0]}...`));
-        return args[0];
-      }
-      console.log(theme.error("Usage: /session <id>"));
-      break;
-    case "debug":
-      process.env.DEBUG = process.env.DEBUG ? "" : "1";
-      console.log(theme.info(`Debug mode: ${process.env.DEBUG ? "ON" : "OFF"}`));
-      break;
-    // New commands
-    case "drafts":
-      if (sessionId) {
-        await listDrafts(sessionId, { json: false });
-      } else {
-        console.log(theme.warning("No active session."));
-      }
-      break;
-    case "draft": {
-      if (!sessionId) {
-        console.log(theme.warning("No active session."));
-        break;
-      }
-      const [draftAction, draftArg] = args;
-      switch (draftAction) {
-        case "view":
-          if (draftArg) await viewDraft(sessionId, draftArg, { json: false });
-          else console.log(theme.error("Usage: /draft view <id>"));
-          break;
-        case "edit":
-          if (draftArg) await editDraft(sessionId, draftArg, { json: false });
-          else console.log(theme.error("Usage: /draft edit <id>"));
-          break;
-        case "versions":
-          if (draftArg) await listVersions(sessionId, draftArg, { json: false });
-          else console.log(theme.error("Usage: /draft versions <id>"));
-          break;
-        default:
-          console.log(theme.error("Usage: /draft [view|edit|versions] <id>"));
-      }
-      break;
-    }
-    case "styles":
-      await listStyles({ json: false });
-      break;
-    case "style":
-      if (args[0]) {
-        config.set("currentStyleId", args[0]);
-        console.log(theme.info(`Style set to ${args[0]}`));
-      } else {
-        const current = config.get("currentStyleId");
-        if (current) {
-          console.log(theme.info(`Current style: ${current}`));
-        } else {
-          console.log(theme.error("Usage: /style <id>"));
-        }
-      }
-      break;
-    case "workspaces":
-      await listWorkspaces({ json: false });
-      break;
-    case "workspace":
-      if (args[0]) {
-        config.set("currentWorkspaceId", args[0]);
-        console.log(theme.info(`Workspace set to ${args[0]}`));
-        console.log(theme.warning("Note: Start a /new session to use this workspace."));
-      } else {
-        const current = config.get("currentWorkspaceId");
-        if (current) {
-          console.log(theme.info(`Current workspace: ${current}`));
-        } else {
-          console.log(theme.error("Usage: /workspace <id>"));
-        }
-      }
-      break;
-    case "note":
-      if (args.length > 0) {
-        addNote(args.join(" "));
-      } else {
-        console.log(theme.error("Usage: /note <text>"));
-      }
-      break;
-    case "notes":
-      if (args[0] === "clear") {
-        await clearNotes({ json: false });
-      } else {
-        listNotes({ json: false });
-      }
-      break;
-    case "suggestions":
-      listPendingSuggestions({ json: false });
-      break;
-    case "apply":
-      if (args[0] && sessionId) {
-        await applySuggestion(sessionId, args[0], { json: false });
-      } else if (!sessionId) {
-        console.log(theme.warning("No active session."));
-      } else {
-        console.log(theme.error("Usage: /apply <suggestion-id>"));
-      }
-      break;
-    case "dismiss":
-      if (args[0]) {
-        dismissSuggestion(args[0], { json: false });
-      } else {
-        console.log(theme.error("Usage: /dismiss <suggestion-id>"));
-      }
-      break;
-    case "attach":
-      if (args.length > 0) {
-        try {
-          pendingAttachments = await processAttachments(args);
-          console.log(
-            theme.success(`Queued ${pendingAttachments.length} file(s) for next message.`),
-          );
-        } catch (error) {
-          console.log(theme.error((error as Error).message));
-        }
-      } else {
-        console.log(theme.error("Usage: /attach <file1> [file2] ..."));
-      }
-      break;
-    default:
-      console.log(theme.error(`Unknown command: ${command}`));
+async function cmdWorkspaces(args: ParsedArgs): Promise<void> {
+  const workspaces = await output.withSpinner("Loading workspaces...", () =>
+    api.getWorkspaces(),
+  );
+  if (args.flags.json) {
+    output.outputJson(workspaces);
+  } else {
+    output.formatWorkspaces(workspaces);
   }
-  return undefined;
 }
 
-/**
- * Drafts command handler
- */
-async function draftsCommand(): Promise<void> {
-  const sessionId = values.session;
-  if (!sessionId) {
-    console.error(theme.error("Usage: spiral drafts --session <id>"));
-    process.exit(EXIT_CODES.INVALID_ARGS);
+async function cmdSessions(args: ParsedArgs): Promise<void> {
+  const data = await output.withSpinner("Loading sessions...", () =>
+    api.getConversations(),
+  );
+  if (args.flags.json) {
+    output.outputJson(data.sessions);
+  } else {
+    output.formatConversations(data.sessions);
   }
-  await listDrafts(sessionId, { json: values.json });
 }
 
-/**
- * Draft subcommand handler
- */
-async function draftCommand(action?: string, draftId?: string): Promise<void> {
-  const sessionId = values.session;
+async function cmdDrafts(args: ParsedArgs): Promise<void> {
+  const sessionId = args.flags.session;
   if (!sessionId) {
-    console.error(theme.error("--session required for draft commands"));
-    process.exit(EXIT_CODES.INVALID_ARGS);
+    throw new SpiralCliError(
+      "Usage: spiral drafts --session <id>",
+      EXIT_CODES.INVALID_ARGS,
+    );
   }
-
-  if (!action || !draftId) {
-    console.error(theme.error("Usage: spiral draft [view|edit|update|versions|restore] <id>"));
-    process.exit(EXIT_CODES.INVALID_ARGS);
+  const drafts = await output.withSpinner("Loading drafts...", () =>
+    api.getSessionDrafts(sessionId),
+  );
+  if (args.flags.json) {
+    output.outputJson(drafts);
+  } else {
+    output.formatSessionDrafts(drafts);
   }
+}
 
-  const limit = values.limit ? Number.parseInt(values.limit, 10) : undefined;
-
-  switch (action) {
-    case "view":
-      await viewDraft(sessionId, draftId, { json: values.json });
-      break;
-    case "edit":
-      await editDraft(sessionId, draftId, { json: values.json });
-      break;
-    case "update":
-      // Agent-native update with --content flag
-      if (!values.content) {
-        console.error(theme.error("--content required for update"));
-        process.exit(EXIT_CODES.INVALID_ARGS);
-      }
-      await updateDraftContent(sessionId, draftId, values.content, {
-        json: values.json,
-        title: values.title,
-      });
-      break;
-    case "versions":
-      await listVersions(sessionId, draftId, { json: values.json, limit });
-      break;
-    case "restore":
-      if (!values.versionId) {
-        console.error(theme.error("--versionId required for restore"));
-        process.exit(EXIT_CODES.INVALID_ARGS);
-      }
-      await restoreVersion(sessionId, draftId, values.versionId, { json: values.json });
-      break;
-    default:
-      console.error(theme.error(`Unknown draft action: ${action}`));
-      process.exit(EXIT_CODES.INVALID_ARGS);
+async function cmdQuota(args: ParsedArgs): Promise<void> {
+  const quota = await output.withSpinner("Loading quota...", () =>
+    api.getQuota(),
+  );
+  if (args.flags.json) {
+    output.outputJson(quota);
+  } else {
+    output.formatQuota(quota);
   }
 }
 
-/**
- * Notes command handler
- */
-async function notesCommand(action?: string, content?: string): Promise<void> {
-  const opts = { json: values.json, force: values.force };
-
-  switch (action) {
-    case "list":
-    case undefined:
-      listNotes(opts);
-      break;
-    case "add":
-      if (!content) {
-        console.error(theme.error("Usage: spiral notes add <content>"));
-        process.exit(EXIT_CODES.INVALID_ARGS);
-      }
-      addNote(content, undefined, opts);
-      break;
-    case "clear":
-      await clearNotes(opts);
-      break;
-    case "remove":
-      if (!content) {
-        console.error(theme.error("Usage: spiral notes remove <id>"));
-        process.exit(EXIT_CODES.INVALID_ARGS);
-      }
-      removeNote(content, opts);
-      break;
-    default:
-      // Treat as adding a note if no recognized action
-      addNote([action, content].filter(Boolean).join(" "), undefined, opts);
+async function cmdPrime(args: ParsedArgs): Promise<void> {
+  const doc = await output.withSpinner("Loading prime...", () =>
+    api.getPrime(),
+  );
+  if (args.flags.json) {
+    output.outputJson({ content: doc });
+  } else {
+    output.outputMarkdown(doc);
   }
 }
 
-/**
- * Suggestions command handler
- */
-async function suggestionsCommand(action?: string, suggestionId?: string): Promise<void> {
-  const opts = { json: values.json, force: values.force };
-  const sessionId = values.session;
-
-  switch (action) {
-    case "list":
-    case undefined:
-      listPendingSuggestions(opts);
+async function cmdAuth(args: ParsedArgs): Promise<void> {
+  const sub = args.positional[0];
+  switch (sub) {
+    case "login":
+      await auth.login(args.flags.token);
       break;
-    case "preview":
-      if (!suggestionId) {
-        console.error(theme.error("Usage: spiral suggestions preview <id>"));
-        process.exit(EXIT_CODES.INVALID_ARGS);
-      }
-      await previewSuggestion(suggestionId, opts);
+    case "status":
+      auth.showStatus();
       break;
-    case "apply":
-      if (!suggestionId) {
-        console.error(theme.error("Usage: spiral suggestions apply <id>"));
-        process.exit(EXIT_CODES.INVALID_ARGS);
-      }
-      if (!sessionId) {
-        console.error(theme.error("--session required for apply"));
-        process.exit(EXIT_CODES.INVALID_ARGS);
-      }
-      await applySuggestion(sessionId, suggestionId, opts);
-      break;
-    case "dismiss":
-      if (!suggestionId) {
-        console.error(theme.error("Usage: spiral suggestions dismiss <id>"));
-        process.exit(EXIT_CODES.INVALID_ARGS);
-      }
-      dismissSuggestion(suggestionId, opts);
+    case "logout":
+      auth.logout();
       break;
     default:
-      console.error(theme.error(`Unknown suggestions action: ${action}`));
-      process.exit(EXIT_CODES.INVALID_ARGS);
+      console.log("Usage: spiral auth login|status|logout");
+      break;
   }
 }
 
-/**
- * List sessions command (supports --json)
- */
-async function sessionsCommand(): Promise<void> {
-  const spinner = values.quiet ? null : ora("Fetching sessions...").start();
-
-  try {
-    const conversations = await fetchConversations();
-    spinner?.succeed("Sessions loaded");
-
-    if (values.json) {
-      console.log(JSON.stringify(conversations));
-      return;
-    }
-
-    console.log(theme.heading("\nYour Sessions:\n"));
-
-    const limit = Number.parseInt(values.limit || "20", 10);
-    for (const conv of conversations.slice(0, limit)) {
-      const date = new Date(conv.created_at).toLocaleDateString();
-      console.log(
-        `${theme.dim(conv.session_id.slice(0, 8))} ${chalk.white(conv.session_name || "Untitled")} ${theme.dim(`(${date})`)}`,
-      );
-    }
+// ── Main ──
 
-    if (conversations.length === 0) {
-      console.log(theme.dim("No sessions found."));
-    }
-  } catch (error) {
-    spinner?.stop();
-    handleError(error as Error);
-  }
-}
+async function main(): Promise<void> {
+  const args = parse(process.argv);
 
-/**
- * View history command (supports --json, --limit)
- */
-async function historyCommand(conversationId?: string): Promise<void> {
-  if (!conversationId) {
-    console.error(theme.error("Usage: spiral history <session-id>"));
-    process.exit(EXIT_CODES.INVALID_ARGS);
+  if (args.flags.version) {
+    console.log(VERSION);
+    return;
   }
 
-  const spinner = values.quiet ? null : ora("Fetching history...").start();
-
-  try {
-    const messages = await fetchMessages(conversationId);
-    spinner?.succeed("History loaded");
-
-    if (values.json) {
-      console.log(JSON.stringify(messages));
-      return;
-    }
-
-    const limit = Number.parseInt(values.limit || "50", 10);
-    console.log(theme.heading(`\nSession History (${messages.length} messages):\n`));
-
-    for (const msg of messages.slice(-limit)) {
-      const role = msg.role === "user" ? theme.user("You") : theme.assistant("Spiral");
-      const content = msg.content || "";
-      const preview = content.slice(0, 200);
-      console.log(`${role}: ${preview}${content.length > 200 ? "..." : ""}\n`);
-    }
-  } catch (error) {
-    spinner?.stop();
-    handleError(error as Error);
+  if (args.flags.help || !args.command) {
+    console.log(HELP);
+    return;
   }
-}
 
-/**
- * Auth command
- */
-async function authCommand(action?: string): Promise<void> {
-  switch (action) {
-    case "login": {
-      console.log(theme.heading("\nSpiral CLI Login\n"));
-      console.log(
-        theme.dim("Get your API key at: https://app.writewithspiral.com → Account → API Keys\n"),
-      );
-
-      try {
-        const apiKey = await password({
-          message: "Enter your API key:",
-          mask: "•",
-        });
-
-        if (!apiKey || !apiKey.trim()) {
-          console.log(theme.error("No API key provided"));
-          process.exit(EXIT_CODES.AUTH_ERROR);
-        }
-
-        storePAT(apiKey.trim());
-        console.log(theme.success("\n✓ Logged in successfully!"));
-        console.log(theme.dim("Your API key has been saved securely.\n"));
-      } catch (error) {
-        if ((error as Error).message?.includes("spiral_sk_")) {
-          console.log(theme.error((error as Error).message));
-        } else {
-          console.log(theme.error("Login cancelled"));
-        }
-        process.exit(EXIT_CODES.AUTH_ERROR);
-      }
+  switch (args.command) {
+    case "write":
+      await cmdWrite(args);
       break;
-    }
-
-    case "logout": {
-      const status = getAuthStatus();
-      if (status.method === "pat") {
-        clearStoredPAT();
-        console.log(theme.success("Logged out. API key removed."));
-      } else if (status.method === "env") {
-        console.log(
-          theme.warning("Using SPIRAL_TOKEN environment variable. Unset it to log out."),
-        );
-      } else {
-        console.log(theme.info("Not logged in with an API key."));
-      }
+    case "styles":
+      await cmdStyles(args);
       break;
-    }
-
-    case "status": {
-      const status = getAuthStatus();
-
-      if (values.json) {
-        console.log(JSON.stringify(status));
-        return;
-      }
-
-      switch (status.method) {
-        case "env":
-          console.log(theme.success("Authenticated via SPIRAL_TOKEN environment variable"));
-          console.log(theme.dim(`Token: ${status.tokenPrefix}`));
-          break;
-        case "pat":
-          console.log(theme.success("Authenticated with API key"));
-          console.log(theme.dim(`Key: ${status.tokenPrefix}`));
-          if (status.createdAt) {
-            console.log(theme.dim(`Saved: ${new Date(status.createdAt).toLocaleDateString()}`));
-          }
-          break;
-        case "none":
-          // Try browser fallback
-          try {
-            const token = await getAuthToken();
-            console.log(theme.success("Authenticated via browser session"));
-            console.log(theme.dim(`Token: ${token.slice(0, 20)}...`));
-          } catch {
-            console.log(theme.warning("Not authenticated"));
-            console.log(
-              theme.dim("\nRun `spiral auth login` to authenticate with an API key."),
-            );
-          }
-          break;
-      }
+    case "workspaces":
+      await cmdWorkspaces(args);
       break;
-    }
-
-    case "clear":
-      clearStoredPAT();
-      clearTokenCache();
-      console.log(theme.info("All credentials cleared."));
+    case "sessions":
+      await cmdSessions(args);
+      break;
+    case "drafts":
+      await cmdDrafts(args);
+      break;
+    case "quota":
+      await cmdQuota(args);
+      break;
+    case "prime":
+      await cmdPrime(args);
+      break;
+    case "auth":
+      await cmdAuth(args);
       break;
-
     default:
-      console.log(`
-${theme.heading("Auth Commands:")}
-  spiral auth login    Login with API key (recommended)
-  spiral auth logout   Remove stored API key
-  spiral auth status   Check authentication status
-  spiral auth clear    Clear all stored credentials
-
-${theme.dim("Get your API key at: https://app.writewithspiral.com → Account → API Keys")}
-`);
+      console.error(theme.error(`Unknown command: ${args.command}`));
+      console.log(HELP);
+      process.exit(EXIT_CODES.INVALID_ARGS);
   }
 }
 
-/**
- * Show help
- */
-function showHelp(): void {
-  console.log(`
-${theme.heading("spiral-cli")} - Interact with Spiral API from the terminal
-
-${theme.heading("Usage:")}
-  spiral send <message> [options]          Send single message (agent-native)
-  spiral chat [--session <id>] [--new]     Start interactive chat
-  spiral sessions [--json] [--limit N]     List sessions
-  spiral history <session-id> [--json]     View session history
-  spiral auth login                        Login with API key
-  spiral auth [status|logout|clear]        Manage authentication
-
-${theme.heading("Content Management:")}
-  spiral styles [--json]                   List writing styles
-  spiral workspaces [--json]               List workspaces
-  spiral drafts --session <id> [--json]    List drafts in a session
-  spiral draft <action> <id> --session <id> [--json]
-    view     View draft content
-    edit     Edit in $EDITOR
-    update   Update with --content (agent-native)
-    versions View version history
-    restore  Restore with --versionId
-
-${theme.heading("Notes & Suggestions:")}
-  spiral notes [list|add|clear|remove]     Manage local notes
-  spiral suggestions [list|preview|apply|dismiss] <id>
-
-${theme.heading("Send Options:")}
-  --attach, -a <files...>   Attach files to message
-  --style <id>              Use writing style
-  --workspace <id>          Use workspace context
-
-${theme.heading("General Options:")}
-  --help, -h        Show this help
-  --version, -v     Show version
-  --session, -s     Session ID to resume
-  --json            Output as JSON (for scripting/agents)
-  --quiet, -q       Suppress spinners and progress
-  --new, -n         Start new session
-  --limit           Limit results
-  --debug, -d       Enable debug output
-  --force, -f       Skip confirmations
-
-${theme.heading("Examples:")}
-  spiral send "Write a haiku" --json
-  spiral send "Analyze this" --attach data.csv
-  spiral chat --session abc123
-  spiral drafts --session abc123
-  spiral draft edit draft-id --session abc123
-  spiral draft update draft-id --session abc123 --content "New content"
-  spiral notes add "Remember to check X"
-  spiral suggestions apply sug-123 --session abc123
-
-${theme.heading("Exit Codes:")}
-  0  Success
-  1  General error
-  2  Authentication failed
-  3  API error
-  4  Network error
-  5  Invalid arguments
-
-${theme.heading("Environment Variables:")}
-  SPIRAL_API_URL    Override API endpoint
-  SPIRAL_TOKEN      Provide auth token directly
-  EDITOR            Editor for draft editing (default: vi)
-  DEBUG             Enable verbose debug logging
-
-${theme.heading("Authentication:")}
-  spiral-cli extracts your session from Safari automatically.
-  Make sure you're logged in at ${theme.info("https://app.writewithspiral.com")}
-`);
-}
-
-/**
- * Handle errors with proper exit codes
- */
-function handleError(error: Error): never {
-  const message = sanitizeError(error);
-
-  if (values.json) {
-    console.log(JSON.stringify({ status: "error", error: message }));
-  } else {
-    console.error(theme.error("Error:"), message);
+main().catch((err) => {
+  if (err instanceof SpiralCliError) {
+    if (!(err instanceof AuthenticationError) || !process.argv.includes("--json")) {
+      console.error(theme.error(err.message));
+    }
+    if (process.argv.includes("--json")) {
+      output.outputJson({
+        error: err.name,
+        message: err.message,
+        ...(err instanceof ApiError ? { statusCode: err.statusCode } : {}),
+      });
+    }
+    process.exit(err.exitCode);
   }
 
-  if (error instanceof AuthenticationError) {
-    process.exit(EXIT_CODES.AUTH_ERROR);
-  } else if (error instanceof ApiError) {
-    process.exit(EXIT_CODES.API_ERROR);
-  } else if (error instanceof SpiralCliError) {
-    process.exit(error.exitCode);
+  const msg = sanitizeError(err);
+  console.error(theme.error(`Unexpected error: ${msg}`));
+  if (process.argv.includes("--debug")) {
+    console.error(err);
   }
   process.exit(EXIT_CODES.GENERAL_ERROR);
-}
-
-// Run
-main().catch(handleError);
+});