@every-env/spiral-cli 0.1.0

package/src/cli.ts

@@ -0,0 +1,952 @@
+#!/usr/bin/env bun
+
+import * as readline from "node:readline";
+import { parseArgs } from "node:util";
+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 { clearTokenCache, getAuthToken, sanitizeError } 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,
+});
+
+// Enable debug mode via flag
+if (values.debug) {
+  process.env.DEBUG = "1";
+}
+
+// Store pending attachments for REPL mode
+let pendingAttachments: Attachment[] = [];
+
+async function main(): Promise<void> {
+  const command = positionals[0];
+
+  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);
+  }
+}
+
+/**
+ * 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);
+  });
+
+  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 content = chunks.join("");
+
+    // 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.`));
+    }
+
+    if (outputJson) {
+      console.log(
+        JSON.stringify({
+          status: "success",
+          session_id: finalSessionId,
+          content,
+          thinking: thinkingChunks.join(""),
+          suggestions_count: sugCount,
+        }),
+      );
+    } else {
+      console.log(); // Newline after streaming
+    }
+
+    process.exit(EXIT_CODES.SUCCESS);
+  } catch (error) {
+    spinner?.stop();
+    cleanupToolSpinners();
+    handleError(error as Error);
+  }
+}
+
+/**
+ * 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`));
+  }
+
+  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 handleInput = async (input: string): Promise<void> => {
+    const trimmed = input.trim();
+
+    // Handle REPL commands
+    if (trimmed.startsWith("/")) {
+      const newSession = await handleReplCommand(trimmed, rl, sessionId);
+      if (newSession !== undefined) {
+        sessionId = newSession;
+      }
+      rl.prompt();
+      return;
+    }
+
+    if (!trimmed) {
+      rl.prompt();
+      return;
+    }
+
+    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();
+  };
+
+  rl.on("line", (input) => {
+    handleInput(input).catch((error) => {
+      console.error(theme.error("Error:"), sanitizeError(error));
+      rl.prompt();
+    });
+  });
+
+  // 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);
+    }
+  });
+
+  rl.prompt();
+}
+
+/**
+ * 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}`));
+  }
+  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);
+  }
+  await listDrafts(sessionId, { json: values.json });
+}
+
+/**
+ * Draft subcommand handler
+ */
+async function draftCommand(action?: string, draftId?: string): Promise<void> {
+  const sessionId = values.session;
+  if (!sessionId) {
+    console.error(theme.error("--session required for draft commands"));
+    process.exit(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 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);
+  }
+}
+
+/**
+ * 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);
+  }
+}
+
+/**
+ * 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);
+      break;
+    case "preview":
+      if (!suggestionId) {
+        console.error(theme.error("Usage: spiral suggestions preview <id>"));
+        process.exit(EXIT_CODES.INVALID_ARGS);
+      }
+      await previewSuggestion(suggestionId, opts);
+      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);
+      break;
+    default:
+      console.error(theme.error(`Unknown suggestions action: ${action}`));
+      process.exit(EXIT_CODES.INVALID_ARGS);
+  }
+}
+
+/**
+ * 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})`)}`,
+      );
+    }
+
+    if (conversations.length === 0) {
+      console.log(theme.dim("No sessions found."));
+    }
+  } catch (error) {
+    spinner?.stop();
+    handleError(error as Error);
+  }
+}
+
+/**
+ * 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);
+  }
+
+  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);
+  }
+}
+
+/**
+ * Auth command
+ */
+async function authCommand(action?: string): Promise<void> {
+  switch (action) {
+    case "status":
+      try {
+        const token = await getAuthToken();
+        if (values.json) {
+          console.log(
+            JSON.stringify({
+              status: "authenticated",
+              token_preview: `${token.slice(0, 20)}...`,
+            }),
+          );
+        } else {
+          console.log(theme.success("Authenticated"));
+          if (process.env.DEBUG) {
+            console.log(theme.dim(`Token: ${token.slice(0, 20)}...`));
+          }
+        }
+      } catch (error) {
+        if (values.json) {
+          console.log(
+            JSON.stringify({
+              status: "unauthenticated",
+              error: (error as Error).message,
+            }),
+          );
+        } else {
+          console.log(theme.error(`Not authenticated: ${(error as Error).message}`));
+        }
+        process.exit(EXIT_CODES.AUTH_ERROR);
+      }
+      break;
+    case "clear":
+      clearTokenCache();
+      console.log(
+        theme.info("Token cache cleared. Re-login by visiting https://app.writewithspiral.com"),
+      );
+      break;
+    default:
+      console.log(`
+${theme.heading("Auth Commands:")}
+  spiral auth status   Check authentication status
+  spiral auth clear    Clear cached token
+`);
+  }
+}
+
+/**
+ * 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 [status|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);
+  }
+
+  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);
+  }
+  process.exit(EXIT_CODES.GENERAL_ERROR);
+}
+
+// Run
+main().catch(handleError);