@autumnai/cli 0.0.0-stage → 0.1.2

package/README.md

@@ -1,3 +1,28 @@
-# Temporary Holding Version
+# Autumn CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/@autumnai/cli)](https://www.npmjs.com/package/@autumnai/cli)
+
+Install the Autumn Skill and sign in:
+
+```sh
+npm install -g @autumnai/cli
+autumn setup
+autumn login
+```
+
+Start a research task and save its rows:
+
+```sh
+autumn run "Find recent funding rounds for climate software companies" --out rounds.csv
+```
+
+If the task asks for input, reply and resume it with the task id:
+
+```sh
+autumn reply <task-id> "Focus on North American companies"
+autumn wait <task-id>
+```
+
+The CLI stores its API key in `${XDG_CONFIG_HOME:-~/.config}/autumn/config.json` with mode `0600`; the config directory is mode `0700`. `AUTUMN_API_KEY` and `AUTUMN_API_URL` override saved configuration.
+
+Exit codes: `0` completed or successful, `1` error/failed/canceled, `2` input required, `3` still working or approval pending, and `4` authentication required.

package/bin/autumn.mjs

@@ -0,0 +1,997 @@
+#!/usr/bin/env node
+
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const VERSION = "0.1.2";
+const DEFAULT_API_URL = "https://api.autumn.ai";
+const USER_AGENT = `autumn-cli/${VERSION}`;
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const CONFIG_DIR = path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config"), "autumn");
+const CONFIG_PATH = path.join(CONFIG_DIR, "config.json");
+
+class CliError extends Error {
+  constructor(message, { exitCode = 1, status = 0, payload = null } = {}) {
+    super(message);
+    this.name = "CliError";
+    this.exitCode = exitCode;
+    this.status = status;
+    this.payload = payload;
+  }
+}
+
+let jsonMode = false;
+
+function writeOut(text) {
+  process.stdout.write(`${text}\n`);
+}
+
+function writeErr(text) {
+  process.stderr.write(`${text}\n`);
+}
+
+function emit(value) {
+  writeOut(jsonMode ? JSON.stringify(value) : typeof value === "string" ? value : JSON.stringify(value, null, 2));
+}
+
+function compactTaskStatus(status) {
+  const fields = [
+    "task_id",
+    "state",
+    "done",
+    "outcome",
+    "message",
+    "progress",
+    "credits_used",
+    "elapsed_s",
+    "queue_position",
+    "error",
+    "app_url",
+  ];
+  const compact = Object.fromEntries(fields.map((field) => [field, status[field] ?? null]));
+  for (const field of ["saved", "timed_out"]) {
+    if (Object.hasOwn(status, field)) compact[field] = status[field];
+  }
+  return compact;
+}
+
+function taskExitCode(state) {
+  if (state === "completed") return 0;
+  if (state === "failed" || state === "canceled") return 1;
+  if (state === "input-required") return 2;
+  return 3;
+}
+
+function creditsSummary(credits) {
+  if (credits.unlimited) return "Unlimited credits";
+  const remaining = Number(credits.credits_remaining || 0);
+  const used = Number(credits.credits_used || 0);
+  const total = credits.credits_total == null
+    ? remaining + used
+    : Number(credits.credits_total);
+  return `${remaining} credits left (${used} used of ${total})`;
+}
+
+function errorPayloadMessage(payload, fallback = "") {
+  if (payload && typeof payload === "object" && typeof payload.message === "string" && payload.message.trim()) {
+    return payload.message;
+  }
+  if (payload && typeof payload === "object" && typeof payload.error === "string" && payload.error.trim()) {
+    return payload.error;
+  }
+  return fallback;
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, Math.max(0, ms)));
+}
+
+function configApiKey(config) {
+  return process.env.AUTUMN_API_KEY || config.api_key || "";
+}
+
+function apiBase(config) {
+  return (process.env.AUTUMN_API_URL || config.api_url || DEFAULT_API_URL).replace(/\/+$/, "");
+}
+
+async function readConfig() {
+  try {
+    const parsed = JSON.parse(await readFile(CONFIG_PATH, "utf8"));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+  } catch (error) {
+    if (error && error.code === "ENOENT") return {};
+    throw new CliError(`Could not read ${CONFIG_PATH}: ${error.message}`);
+  }
+}
+
+async function saveConfig(config) {
+  await mkdir(CONFIG_DIR, { recursive: true, mode: 0o700 });
+  await chmod(CONFIG_DIR, 0o700);
+  await writeFile(CONFIG_PATH, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+  await chmod(CONFIG_PATH, 0o600);
+}
+
+function apiKeyOrThrow(config) {
+  const key = configApiKey(config);
+  if (!key) throw new CliError("Not logged in. Run: autumn login", { exitCode: 4, status: 401 });
+  return key;
+}
+
+function retryAfterMs(headers) {
+  const value = headers.get("retry-after");
+  if (value !== null) {
+    const seconds = Number(value);
+    if (Number.isFinite(seconds) && seconds >= 0) return seconds * 1000;
+    const dateMs = Date.parse(value) - Date.now();
+    if (Number.isFinite(dateMs) && dateMs >= 0) return dateMs;
+  }
+  return 5000;
+}
+
+async function parseResponse(response) {
+  const text = await response.text();
+  if (!text) return { text, data: null };
+  if ((response.headers.get("content-type") || "").includes("text/csv")) return { text, data: text };
+  try {
+    return { text, data: JSON.parse(text) };
+  } catch {
+    return { text, data: text };
+  }
+}
+
+async function requestRaw(config, route, {
+  method = "GET",
+  body,
+  headers = {},
+  authenticated = true,
+} = {}) {
+  const requestHeaders = { "User-Agent": USER_AGENT, ...headers };
+  if (authenticated) requestHeaders["X-API-Key"] = apiKeyOrThrow(config);
+  if (body !== undefined) requestHeaders["Content-Type"] = "application/json";
+  let statusRetries = 0;
+  let networkRetries = 0;
+
+  while (true) {
+    let response;
+    try {
+      response = await fetch(`${apiBase(config)}${route}`, {
+        method,
+        headers: requestHeaders,
+        body: body === undefined ? undefined : JSON.stringify(body),
+      });
+    } catch (error) {
+      if (method !== "GET") {
+        throw new CliError(`Network error: ${error.message || "request failed"}`);
+      }
+      networkRetries += 1;
+      if (networkRetries >= 3) {
+        throw new CliError(`Network error: ${error.message || "request failed"}`);
+      }
+      await sleep(250 * (2 ** (networkRetries - 1)));
+      continue;
+    }
+
+    const parsed = await parseResponse(response);
+    const createdTaskId = method !== "GET" && parsed.data && typeof parsed.data === "object" ? parsed.data.task_id : undefined;
+    if (response.status === 401) {
+      throw new CliError("Not logged in. Run: autumn login", {
+        exitCode: 4,
+        status: 401,
+        payload: parsed.data,
+      });
+    }
+    if ((response.status === 429 || response.status === 503) && !createdTaskId) {
+      statusRetries += 1;
+      if (statusRetries < 5) {
+        await sleep(retryAfterMs(response.headers));
+        continue;
+      }
+    }
+    if (!response.ok) {
+      const message = errorPayloadMessage(parsed.data, typeof parsed.data === "string" ? parsed.data : `HTTP ${response.status}`);
+      const taskNotice = createdTaskId
+        ? ` (task ${createdTaskId} was created; check it with: autumn status ${createdTaskId})`
+        : "";
+      throw new CliError(`${message}${taskNotice}`, { status: response.status, payload: parsed.data });
+    }
+    return {
+      data: parsed.data,
+      text: parsed.text,
+      headers: response.headers,
+      status: response.status,
+    };
+  }
+}
+
+async function request(config, route, options) {
+  return (await requestRaw(config, route, options)).data;
+}
+
+function parseArgs(tokens) {
+  const flags = {};
+  const positionals = [];
+  const booleanFlags = new Set(["detach", "force", "json", "no-browser", "wait", "help", "h", "yes"]);
+  const valueFlags = new Set(["out", "timeout", "limit", "format", "days", "name", "website", "share-by-default", "owners-can-demote"]);
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (token === "--") {
+      positionals.push(...tokens.slice(index + 1));
+      break;
+    }
+    if (token.startsWith("--")) {
+      const equals = token.indexOf("=");
+      const name = token.slice(2, equals === -1 ? undefined : equals);
+      if (booleanFlags.has(name)) {
+        flags[name] = equals === -1 ? true : token.slice(equals + 1) !== "false";
+      } else if (valueFlags.has(name)) {
+        if (equals !== -1) flags[name] = token.slice(equals + 1);
+        else if (index + 1 < tokens.length) flags[name] = tokens[++index];
+        else throw new CliError(`Missing value for --${name}`);
+      } else {
+        throw new CliError(`Unknown option: ${token}`);
+      }
+    } else if (token === "-h") {
+      flags.help = true;
+    } else {
+      positionals.push(token);
+    }
+  }
+  return { flags, positionals };
+}
+
+function globalHelp() {
+  return `Autumn CLI — research from an agent workflow
+
+autumn login
+autumn run "Research the latest funding rounds for..." --out rows.csv
+# Exit 2: Autumn needs input; use the task id from the JSON result:
+autumn reply <id> "..."
+# Exit 3: still working; resume the same task:
+autumn wait <id>
+
+Commands:
+  login [--force] [--no-browser] [--timeout S]  Connect this CLI to your Autumn account
+  logout                              Remove the saved API key
+  credits                             Show credit balance (alias: whoami)
+  buy <credits>                       Get a link to buy credits
+  run <prompt> [--out FILE] [--detach] [--timeout S] [--json]
+  wait <id> [--out FILE] [--timeout S] [--json]
+  reply <id> <message> [--out FILE] [--timeout S] [--wait] [--json]
+  status <id> [--json]                Show current task status once
+  rows <id> [--out FILE] [--format csv|json]
+  stop <id>                            Stop a running task
+  list [query] [--limit N] [--json]    List or search recent tasks (default limit: 20)
+  team [invite|revoke|role|remove|set] Manage your team (writes are owner-only)
+  usage [--days N] [--json]            Read usage for the last N days (1–90, default: 30)
+  setup [claude|codex|all]             Install the Autumn Skill
+  mcp-config [claude|codex|cursor]     Print MCP connection configuration
+
+Exit codes:
+  0  Success or completed
+  1  Error, failed task, or canceled task
+  2  Input required
+  3  Still working or login approval pending
+  4  Authentication needed`;
+}
+
+function commandHelp(command) {
+  const messages = {
+    login: "autumn login [--force] [--no-browser] [--timeout S] [--json]",
+    logout: "autumn logout",
+    credits: "autumn credits [--json]",
+    buy: "autumn buy <credits>",
+    whoami: "autumn whoami [--json]",
+    run: "autumn run <prompt> [--out FILE] [--detach] [--timeout S] [--json]",
+    wait: "autumn wait <id> [--out FILE] [--timeout S] [--json]",
+    reply: "autumn reply <id> <message> [--out FILE] [--timeout S] [--wait] [--json]",
+    status: "autumn status <id> [--json]",
+    rows: "autumn rows <id> [--out FILE] [--format csv|json]",
+    stop: "autumn stop <id>",
+    list: "autumn list [query] [--limit N] [--json] (default limit: 20)",
+    team: "autumn team [invite <email>|revoke <invitation_id>|role <user_id> owner|member|remove <user_id> --yes|set [--name N] [--website W] [--share-by-default true|false] [--owners-can-demote true|false]]",
+    usage: "autumn usage [--days N] [--json] (1–90, default: 30)",
+    setup: "autumn setup [claude|codex|all]",
+    "mcp-config": "autumn mcp-config [claude|codex|cursor]",
+  };
+  return messages[command] || globalHelp();
+}
+
+function requirePositionals(positionals, count, usage) {
+  if (positionals.length < count) throw new CliError(`Usage: ${usage}`);
+}
+
+function teamBoolean(value, option) {
+  if (value !== "true" && value !== "false") {
+    throw new CliError(`--${option} must be true or false.`);
+  }
+  return value === "true";
+}
+
+async function teamCommand(config, positionals, options) {
+  const action = positionals[0] || "";
+  if (!action) {
+    const result = await request(config, "/team");
+    if (jsonMode) emit(result);
+    else {
+      const account = result.account || {};
+      writeOut(`account\t${account.type || ""}\t${account.name || ""}\t${account.role || ""}`);
+      writeOut("user_id\tname\temail\trole");
+      for (const member of result.members || []) {
+        writeOut([member.user_id, member.name, member.email, member.role].map((value) => String(value || "").replace(/[\t\r\n]/g, " ")).join("\t"));
+      }
+      if (account.type === "team" && account.role === "owner") {
+        writeOut("\nPending invitations");
+        writeOut("id\temail\tcreated_at");
+        for (const invitation of result.invitations || []) {
+          writeOut([invitation.id, invitation.email, invitation.created_at].map((value) => String(value || "").replace(/[\t\r\n]/g, " ")).join("\t"));
+        }
+      }
+    }
+    return 0;
+  }
+
+  let result;
+  if (action === "invite") {
+    requirePositionals(positionals, 2, commandHelp("team"));
+    result = await request(config, "/team/invitations", { method: "POST", body: { email: positionals[1] } });
+  } else if (action === "revoke") {
+    requirePositionals(positionals, 2, commandHelp("team"));
+    result = await request(config, `/team/invitations/${encodeURIComponent(positionals[1])}`, { method: "DELETE" });
+  } else if (action === "role") {
+    requirePositionals(positionals, 3, commandHelp("team"));
+    if (!["owner", "member"].includes(positionals[2])) throw new CliError("Role must be owner or member.");
+    result = await request(config, `/team/members/${encodeURIComponent(positionals[1])}`, { method: "PATCH", body: { role: positionals[2] } });
+  } else if (action === "remove") {
+    requirePositionals(positionals, 2, commandHelp("team"));
+    if (!options.yes) throw new CliError(`Rerun with --yes to remove ${positionals[1]}`);
+    result = await request(config, `/team/members/${encodeURIComponent(positionals[1])}`, { method: "DELETE" });
+  } else if (action === "set") {
+    if (positionals.length !== 1) throw new CliError(`Usage: ${commandHelp("team")}`);
+    const body = {};
+    if (options.name !== undefined || options.website !== undefined) {
+      if (options.name !== undefined) body.name = options.name;
+      if (options.website !== undefined) body.website = options.website;
+    }
+    const settings = {};
+    if (options["share-by-default"] !== undefined) settings.share_chats_by_default = teamBoolean(options["share-by-default"], "share-by-default");
+    if (options["owners-can-demote"] !== undefined) settings.owners_can_demote_owners = teamBoolean(options["owners-can-demote"], "owners-can-demote");
+    if (Object.keys(settings).length) {
+      const current = await request(config, "/team");
+      body.settings = settings;
+      body.version = current.settings?.version;
+    }
+    if (!Object.keys(body).length) throw new CliError(`Usage: ${commandHelp("team")}`);
+    result = await request(config, "/team", { method: "PATCH", body });
+  } else {
+    throw new CliError(`Unknown team command: ${action}\n${commandHelp("team")}`);
+  }
+  if (jsonMode) emit(result);
+  else writeOut(action === "invite" ? `Invitation sent to ${positionals[1]}.` : action === "revoke" ? "Invitation revoked." : action === "remove" ? `Removed ${positionals[1]} from the team.` : action === "role" ? `Set ${positionals[1]} to ${positionals[2]}.` : "Team updated.");
+  return 0;
+}
+
+async function usageCommand(config, options) {
+  const days = Number(options.days || 30);
+  if (!Number.isInteger(days) || days < 1 || days > 90) throw new CliError("--days must be an integer from 1 to 90.");
+  const result = await request(config, `/team/usage?days=${days}`);
+  if (jsonMode) emit(result);
+  else {
+    writeOut(`${result.credits_used || 0} credits used across ${result.tasks || 0} tasks in the last ${result.days || days} days.`);
+    for (const member of result.members || []) writeOut(`${member.name || member.user_id}: ${member.credits_used || 0} credits, ${member.tasks || 0} tasks`);
+  }
+  return 0;
+}
+
+function taskRoute(taskId) {
+  return `/task/${encodeURIComponent(taskId)}`;
+}
+
+function formatElapsed(value) {
+  if (value === null || value === undefined || !Number.isFinite(Number(value))) return "?";
+  const seconds = Math.max(0, Math.floor(Number(value)));
+  if (seconds < 60) return `${seconds}s`;
+  return `${Math.floor(seconds / 60)}m${String(seconds % 60).padStart(2, "0")}s`;
+}
+
+function progressLine(status) {
+  const state = status.state || status.stage || "working";
+  const message = typeof status.message === "string" ? status.message.trim() : "";
+  const progress = status.progress && typeof status.progress === "object" ? status.progress : {};
+  const rows = progress.rows ?? 0;
+  const target = progress.target;
+  const rowsText = target == null ? `${rows} rows` : `${rows}/${target} rows`;
+  return [state, message, rowsText, formatElapsed(status.elapsed_s)].filter(Boolean).join(" · ");
+}
+
+function printProgress(status, lastVersion) {
+  if (jsonMode) return lastVersion;
+  const progress = status.progress && typeof status.progress === "object" ? status.progress : {};
+  const version = status.version ?? JSON.stringify([
+    status.state,
+    status.stage,
+    status.message,
+    progress.rows,
+    progress.target,
+    status.queue_position,
+  ]);
+  if (!process.stderr.isTTY && version === lastVersion) return lastVersion;
+  const line = progressLine(status);
+  if (process.stderr.isTTY) {
+    process.stderr.write(`\r\x1b[2K${line}`);
+  } else {
+    writeErr(line);
+  }
+  return version;
+}
+
+function clearProgressLine() {
+  if (process.stderr.isTTY && !jsonMode) process.stderr.write("\r\x1b[2K");
+}
+
+function errorFromStatus(status) {
+  const error = status.error;
+  if (status.state === "canceled" && !(error && typeof error === "object" && error.message)) {
+    return "Task canceled.";
+  }
+  if (error && typeof error === "object") return error.message || error.code || "Task failed.";
+  return "Task failed.";
+}
+
+function parseTimeout(value) {
+  if (value === undefined) return null;
+  const seconds = Number(value);
+  if (!Number.isFinite(seconds) || seconds < 0) throw new CliError("--timeout must be a non-negative number of seconds.");
+  return seconds;
+}
+
+async function fetchOutputPages(config, taskId, format) {
+  const rows = [];
+  const csvPages = [];
+  let cursor = "";
+  do {
+    const query = new URLSearchParams({ limit: "200", format });
+    if (cursor) query.set("cursor", cursor);
+    const response = await requestRaw(config, `${taskRoute(taskId)}/output?${query}`);
+    if (format === "csv") {
+      csvPages.push(response.text);
+      cursor = response.headers.get("x-next-cursor") || "";
+    } else {
+      const pageRows = Array.isArray(response.data?.rows) ? response.data.rows : [];
+      rows.push(...pageRows);
+      cursor = response.data?._next_cursor || response.data?.next_cursor || response.headers.get("x-next-cursor") || "";
+    }
+  } while (cursor);
+
+  if (format === "csv") {
+    const content = csvPages.length === 1 ? csvPages[0] : mergeCsvPages(csvPages);
+    return { content, rows: csvRecordCount(content), format };
+  }
+  return { content: rows, rows: rows.length, format };
+}
+
+function parseCsvRecords(csv) {
+  const records = [];
+  let record = [];
+  let field = "";
+  let quoted = false;
+
+  for (let index = 0; index < csv.length; index += 1) {
+    const char = csv[index];
+    if (quoted) {
+      if (char === '"') {
+        if (csv[index + 1] === '"') {
+          field += '"';
+          index += 1;
+        } else {
+          quoted = false;
+        }
+      } else {
+        field += char;
+      }
+    } else if (char === '"' && field === "") {
+      quoted = true;
+    } else if (char === ",") {
+      record.push(field);
+      field = "";
+    } else if (char === "\n" || char === "\r") {
+      if (char === "\r" && csv[index + 1] === "\n") index += 1;
+      record.push(field);
+      records.push(record);
+      record = [];
+      field = "";
+    } else {
+      field += char;
+    }
+  }
+
+  if (quoted) throw new CliError("Invalid CSV output: unterminated quoted field.");
+  if (field !== "" || record.length > 0) {
+    record.push(field);
+    records.push(record);
+  }
+  return records;
+}
+
+function serializeCsvRecord(fields) {
+  return fields.map((field) => {
+    const value = String(field ?? "");
+    const quote = (fields.length === 1 && value === "") || /[",\r\n]/.test(value);
+    return quote ? `"${value.replace(/"/g, '""')}"` : value;
+  }).join(",");
+}
+
+function mergeCsvPages(pages) {
+  const columns = [];
+  const seen = new Set();
+  const rows = [];
+
+  for (const page of pages) {
+    const [header, ...records] = parseCsvRecords(page);
+    if (!header) continue;
+    for (const column of header) {
+      if (!seen.has(column)) {
+        seen.add(column);
+        columns.push(column);
+      }
+    }
+    for (const record of records) {
+      rows.push(new Map(header.map((column, index) => [column, record[index] ?? ""])));
+    }
+  }
+
+  if (columns.length === 0) return "";
+  const output = [serializeCsvRecord(columns)];
+  for (const row of rows) {
+    output.push(serializeCsvRecord(columns.map((column) => row.get(column) ?? "")));
+  }
+  return `${output.join("\n")}\n`;
+}
+
+function csvRecordCount(csv) {
+  if (!csv) return 0;
+  let quoted = false;
+  let records = 0;
+  let hasValue = false;
+  for (let index = 0; index < csv.length; index += 1) {
+    const char = csv[index];
+    if (char === '"') {
+      hasValue = true;
+      if (quoted && csv[index + 1] === '"') {
+        index += 1;
+      } else {
+        quoted = !quoted;
+      }
+    } else if (char === "\n" && !quoted) {
+      records += 1;
+      hasValue = false;
+    } else {
+      hasValue ||= char !== "\r";
+    }
+  }
+  if (hasValue) records += 1;
+  return Math.max(0, records - 1);
+}
+
+async function saveOutputFile(filepath, result) {
+  const resolved = path.resolve(filepath);
+  await mkdir(path.dirname(resolved), { recursive: true });
+  const content = result.format === "csv"
+    ? result.content
+    : `${JSON.stringify(result.content, null, 2)}\n`;
+  await writeFile(resolved, content);
+  return { path: filepath, rows: result.rows };
+}
+
+function watchTimeout(options) {
+  const requested = parseTimeout(options.timeout);
+  if (requested !== null) return requested * 1000;
+  return process.stdout.isTTY ? Infinity : 100_000;
+}
+
+async function watchTask(config, taskId, options) {
+  const timeoutMs = watchTimeout(options);
+  const startedAt = Date.now();
+  const deadline = Number.isFinite(timeoutMs) ? startedAt + timeoutMs : Infinity;
+  let lastVersion = null;
+  let latest = null;
+
+  while (Date.now() <= deadline) {
+    const remainingSeconds = Number.isFinite(deadline) ? Math.max(1, Math.ceil((deadline - Date.now()) / 1000)) : 50;
+    const waitSeconds = Math.min(50, remainingSeconds);
+    latest = await request(config, `${taskRoute(taskId)}?wait=${waitSeconds}`);
+    lastVersion = printProgress(latest, lastVersion);
+    if (latest.done) {
+      clearProgressLine();
+      const status = latest;
+      if (status.state === "completed") {
+        let saved;
+        if (status.outcome === "blocked" || status.outcome === "partial") {
+          const label = status.outcome === "blocked" ? "Blocked" : "Partial";
+          writeErr(`${label}: ${status.message || ""}`);
+          writeErr(`Add detail: autumn reply ${taskId} "<more info>"`);
+        }
+        if (options.out) {
+          const format = path.extname(options.out).toLowerCase() === ".json" ? "json" : "csv";
+          saved = await saveOutputFile(options.out, await fetchOutputPages(config, taskId, format));
+          if (!jsonMode) writeErr(`Saved ${saved.rows} rows to ${saved.path}`);
+        } else if (!jsonMode) {
+          if (status.message) writeOut(status.message);
+          writeErr(`Rows: autumn rows ${taskId} --out rows.csv`);
+        }
+        if (jsonMode) {
+          emit(compactTaskStatus({
+            ...status,
+            task_id: status.task_id || taskId,
+            ...(saved ? { saved } : {}),
+          }));
+        }
+        return 0;
+      }
+      if (status.state === "input-required") {
+        if (!jsonMode) {
+          writeErr(`Autumn asks: ${status.message || "Send a message to continue."}`);
+          writeErr(`Reply: autumn reply ${taskId} "<answer>"`);
+        }
+        if (jsonMode) emit(compactTaskStatus({ ...status, task_id: status.task_id || taskId }));
+        return 2;
+      }
+      if (status.state === "failed" || status.state === "canceled") {
+        if (!jsonMode) writeErr(String(errorFromStatus(status)));
+        if (jsonMode) emit(compactTaskStatus({ ...status, task_id: status.task_id || taskId }));
+        return 1;
+      }
+    }
+    if (Date.now() >= deadline) break;
+    if (!latest.done) {
+      await sleep(Math.min(250, Math.max(0, deadline - Date.now())));
+    }
+  }
+
+  clearProgressLine();
+  const status = latest || { task_id: taskId, state: "working", done: false };
+  if (!jsonMode) {
+    writeErr(`Still working: ${status.message || status.state || "task in progress"}. Continue: autumn wait ${taskId}`);
+  }
+  if (jsonMode) {
+    emit(compactTaskStatus({ ...status, task_id: status.task_id || taskId, timed_out: true }));
+  }
+  return 3;
+}
+
+async function browserOpen(url) {
+  let command;
+  let args;
+  if (process.platform === "darwin") {
+    command = "open";
+    args = [url];
+  } else if (process.platform === "win32") {
+    command = "cmd";
+    args = ["/c", "start", "", url];
+  } else {
+    command = "xdg-open";
+    args = [url];
+  }
+  try {
+    const child = spawn(command, args, { detached: true, stdio: "ignore" });
+    child.on("error", () => {});
+    child.unref();
+  } catch {}
+}
+
+async function login(config, options) {
+  if (!options.force && configApiKey(config)) {
+    try {
+      await request(config, "/credits");
+      if (jsonMode) emit({ status: "already_logged_in" });
+      else writeErr("Already logged in. Use --force to log in again.");
+      return 0;
+    } catch (error) {
+      if (!(error instanceof CliError && error.status === 401)) throw error;
+    }
+  }
+
+  let pending = config.pending_login;
+  const nowSeconds = Date.now() / 1000;
+  if (!pending || !pending.device_code || Number(pending.expires_at) <= nowSeconds) {
+    const started = await requestRaw(config, "/auth/device", {
+      method: "POST",
+      body: { client: "Autumn CLI", host: os.hostname() },
+      authenticated: false,
+    });
+    pending = {
+      device_code: started.data.device_code,
+      user_code: started.data.user_code,
+      verification_uri_complete: started.data.verification_uri_complete,
+      interval: Number(started.data.interval) > 0 ? Number(started.data.interval) : 2,
+      expires_at: nowSeconds + Number(started.data.expires_in || 600),
+    };
+    config.pending_login = pending;
+    await saveConfig(config);
+  }
+
+  if (!jsonMode) {
+    writeErr(`Open this link to connect Autumn:\n  ${pending.verification_uri_complete}\nCode: ${pending.user_code}`);
+  }
+  if (process.stdout.isTTY && !options["no-browser"]) void browserOpen(pending.verification_uri_complete);
+
+  const requestedTimeout = parseTimeout(options.timeout);
+  const availableSeconds = Math.max(0, Number(pending.expires_at) - Date.now() / 1000);
+  const timeoutSeconds = requestedTimeout === null
+    ? (process.stdout.isTTY ? availableSeconds : 90)
+    : requestedTimeout;
+  const deadline = Date.now() + Math.min(timeoutSeconds, availableSeconds) * 1000;
+
+  while (Date.now() <= deadline) {
+    let polled;
+    try {
+      polled = await requestRaw(config, "/auth/device/token", {
+        method: "POST",
+        body: { device_code: pending.device_code },
+        authenticated: false,
+      });
+    } catch (error) {
+      if (error instanceof CliError && (error.status === 403 || error.status === 410)) {
+        delete config.pending_login;
+        await saveConfig(config);
+      }
+      throw error;
+    }
+    if (polled.data?.status === "approved") {
+      config.api_key = polled.data.api_key;
+      delete config.pending_login;
+      await saveConfig(config);
+      if (jsonMode) emit({ status: "logged_in" });
+      else writeErr(`Logged in. Key saved to ${CONFIG_PATH}.`);
+      return 0;
+    }
+    if (polled.data?.status !== "pending") {
+      throw new CliError(errorPayloadMessage(polled.data, "Unexpected device-login response."));
+    }
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) break;
+    await sleep(Math.min(Number(pending.interval || 2) * 1000, remaining));
+  }
+
+  if (jsonMode) {
+    emit({
+      status: "pending",
+      verification_uri_complete: pending.verification_uri_complete,
+      user_code: pending.user_code,
+    });
+  } else {
+    writeErr("Waiting for approval. After approving, run `autumn login` again.");
+  }
+  return 3;
+}
+
+async function logout(config) {
+  delete config.api_key;
+  await saveConfig(config);
+  writeOut(`Removed the saved API key. It remains valid until revoked in Settings > Developer.`);
+  return 0;
+}
+
+async function runTask(config, prompt, options) {
+  const started = await request(config, "/task", { method: "POST", body: { prompt } });
+  const taskId = started.task_id;
+  if (!taskId) throw new CliError("The API did not return a task_id.");
+  if (!jsonMode) writeErr(`Started ${taskId} · ${started.app_url || ""}`.trim());
+  if (options.detach) {
+    if (jsonMode) {
+      emit(compactTaskStatus({
+        ...started,
+        state: started.state || "submitted",
+        done: started.done ?? false,
+      }));
+    } else {
+      emit(taskId);
+    }
+    return 0;
+  }
+  return watchTask(config, taskId, options);
+}
+
+async function replyTask(config, taskId, message, options) {
+  const accepted = await request(config, `${taskRoute(taskId)}/continue`, {
+    method: "POST",
+    body: { message },
+    headers: { "Idempotency-Key": randomUUID() },
+  });
+  if (!jsonMode) {
+    if (accepted.queue_position != null) writeErr(`Queued (position ${accepted.queue_position})`);
+    else writeErr("Sent");
+  }
+  return watchTask(config, taskId, options);
+}
+
+function mcpConfig(kind, config) {
+  const key = configApiKey(config) || "$AUTUMN_API_KEY";
+  const endpoint = `${apiBase(config)}/mcp`;
+  if (kind === "claude") {
+    return `claude mcp add --transport http autumn ${endpoint} --header "Authorization: Bearer ${key}"`;
+  }
+  if (kind === "cursor") {
+    return JSON.stringify({
+      mcpServers: {
+        autumn: {
+          url: endpoint,
+          headers: { Authorization: `Bearer ${key}` },
+        },
+      },
+    }, null, 2);
+  }
+  if (kind === "codex") {
+    if (configApiKey(config)) {
+      return `[mcp_servers.autumn]\nurl = ${JSON.stringify(endpoint)}\n\n[mcp_servers.autumn.http_headers]\nAuthorization = ${JSON.stringify(`Bearer ${key}`)}`;
+    }
+    return `[mcp_servers.autumn]\nurl = ${JSON.stringify(endpoint)}\nbearer_token_env_var = "AUTUMN_API_KEY"`;
+  }
+  throw new CliError("Choose one of: claude, codex, cursor.");
+}
+
+async function readBundledSkill() {
+  return readFile(path.resolve(SCRIPT_DIR, "../skill.md"), "utf8");
+}
+
+async function installSkill(destination, content) {
+  await mkdir(path.dirname(destination), { recursive: true, mode: 0o700 });
+  await writeFile(destination, content, { mode: 0o600 });
+  return destination;
+}
+
+async function setup(kind, config) {
+  const selected = kind || "all";
+  if (!["claude", "codex", "all"].includes(selected)) {
+    throw new CliError("Choose one of: claude, codex, all.");
+  }
+  const content = await readBundledSkill();
+  const installed = [];
+  if (selected === "claude" || selected === "all") {
+    installed.push(await installSkill(
+      path.join(os.homedir(), ".claude", "skills", "autumn", "SKILL.md"),
+      content,
+    ));
+  }
+  if (selected === "codex" || selected === "all") {
+    installed.push(await installSkill(
+      path.join(os.homedir(), ".agents", "skills", "autumn", "SKILL.md"),
+      content,
+    ));
+  }
+  if (jsonMode) emit({ installed });
+  else {
+    for (const destination of installed) writeErr(`Installed Autumn Skill: ${destination}`);
+    if (!configApiKey(config)) writeErr("Next: autumn login");
+  }
+  return 0;
+}
+
+async function commandMain(command, options, positionals, config) {
+  if (command === "login") return login(config, options);
+  if (command === "logout") return logout(config);
+  if (command === "setup") return setup(positionals[0], config);
+  if (command === "mcp-config") {
+    const kind = positionals[0] || "claude";
+    emit(mcpConfig(kind, config));
+    return 0;
+  }
+  if (command === "credits" || command === "whoami") {
+    const result = await request(config, "/credits");
+    if (jsonMode) emit(result);
+    else writeOut(creditsSummary(result));
+    return 0;
+  }
+  if (command === "buy") {
+    const allowed = [5000, 10000, 20000, 50000];
+    const credits = Number(positionals[0]);
+    if (!positionals[0] || !Number.isInteger(credits) || !allowed.includes(credits)) {
+      throw new CliError(`Choose one of these credit amounts: ${allowed.join(", ")}.`);
+    }
+    const result = await request(config, "/credits/checkout", {
+      method: "POST",
+      body: { credits },
+    });
+    if (jsonMode) emit(result);
+    else {
+      writeOut(`Open this link to pay: ${result.url}`);
+      if (process.stdout.isTTY) void browserOpen(result.url);
+    }
+    return 0;
+  }
+  if (command === "run") {
+    requirePositionals(positionals, 1, commandHelp(command));
+    return runTask(config, positionals.join(" "), options);
+  }
+  if (command === "wait") {
+    requirePositionals(positionals, 1, commandHelp(command));
+    return watchTask(config, positionals[0], options);
+  }
+  if (command === "reply") {
+    requirePositionals(positionals, 2, commandHelp(command));
+    return replyTask(config, positionals[0], positionals.slice(1).join(" "), options);
+  }
+  if (command === "status") {
+    requirePositionals(positionals, 1, commandHelp(command));
+    const status = await request(config, taskRoute(positionals[0]));
+    if (jsonMode) emit(compactTaskStatus({ ...status, task_id: status.task_id || positionals[0] }));
+    else writeErr(progressLine(status));
+    return taskExitCode(status.state);
+  }
+  if (command === "rows") {
+    requirePositionals(positionals, 1, commandHelp(command));
+    const format = options.format || (path.extname(options.out || "").toLowerCase() === ".json" ? "json" : "csv");
+    if (format !== "csv" && format !== "json") throw new CliError("--format must be csv or json.");
+    const result = await fetchOutputPages(config, positionals[0], format);
+    if (options.out) {
+      const saved = await saveOutputFile(options.out, result);
+      if (jsonMode) emit(saved);
+      else writeErr(`Saved ${saved.rows} rows to ${saved.path}`);
+    } else if (format === "csv") {
+      process.stdout.write(result.content);
+    } else {
+      emit(result.content);
+    }
+    return 0;
+  }
+  if (command === "stop") {
+    requirePositionals(positionals, 1, commandHelp(command));
+    const result = await request(config, `${taskRoute(positionals[0])}/stop`, { method: "POST" });
+    if (jsonMode) emit(result);
+    else writeOut(`Stopping ${positionals[0]}.`);
+    return 0;
+  }
+  if (command === "list") {
+    const limit = Number(options.limit || 20);
+    if (!Number.isInteger(limit) || limit < 1 || limit > 200) {
+      throw new CliError("--limit must be an integer from 1 to 200.");
+    }
+    const query = positionals.join(" ").trim();
+    const params = new URLSearchParams({ limit: String(limit) });
+    if (query) params.set("q", query);
+    const result = await request(config, `/task?${params}`);
+    if (jsonMode) emit(result);
+    else {
+      const tasks = Array.isArray(result) ? result : result.tasks || [];
+      writeOut("task_id\tname\tupdated_at");
+      for (const task of tasks) writeOut(`${task.task_id || ""}\t${task.name || ""}\t${task.updated_at || ""}`);
+    }
+    return 0;
+  }
+  if (command === "team") return teamCommand(config, positionals, options);
+  if (command === "usage") return usageCommand(config, options);
+  throw new CliError(`Unknown command: ${command}\n\n${globalHelp()}`);
+}
+
+async function main() {
+  const tokens = process.argv.slice(2);
+  if (tokens.includes("--version")) {
+    writeOut(VERSION);
+    return 0;
+  }
+  if (!tokens.length || tokens[0] === "--help" || tokens[0] === "-h" || tokens[0] === "help") {
+    writeOut(globalHelp());
+    return 0;
+  }
+  const command = tokens.shift();
+  const { flags, positionals } = parseArgs(tokens);
+  jsonMode = Boolean(flags.json);
+  if (flags.help) {
+    writeOut(commandHelp(command));
+    return 0;
+  }
+  const config = await readConfig();
+  return commandMain(command, flags, positionals, config);
+}
+
+main().then((exitCode) => {
+  process.exitCode = exitCode;
+}).catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  if (jsonMode) writeOut(JSON.stringify({ error: message }));
+  else writeErr(message);
+  process.exitCode = error instanceof CliError ? error.exitCode : 1;
+});

package/package.json

@@ -1,6 +1,22 @@
 {
   "name": "@autumnai/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.2",
+  "description": "Autumn research agent from your terminal or coding agent",
+  "homepage": "https://www.autumn.ai/docs",
+  "type": "module",
+  "bin": {
+    "autumn": "bin/autumn.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin",
+    "skill.md"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "prepack": "cp ../landing/public/skill.md ./skill.md"
+  },
+  "license": "MIT"
+}

package/skill.md

@@ -0,0 +1,158 @@
+---
+name: autumn
+description: Use when a user wants web research done as rows - finding or enriching companies, people, jobs, products, filings or contacts; building or verifying a list; or scraping structured data from public sources. Also use to check, refine, stop or read an existing Autumn task, or to check Autumn credits.
+---
+
+# Autumn
+
+Autumn is a research agent that runs in the cloud. You give it a brief, it searches,
+verifies and saves rows with sources, and you read the rows. A task takes minutes, not
+seconds, and a task is a conversation: you can answer its questions and refine it on the
+same `task_id`.
+
+No task_id? Find it with `list_tasks` (MCP), `autumn list "<words>"` (CLI) or `GET /task?q=<words>`.
+
+Don't use Autumn for a quick fact you can answer yourself.
+
+## Fastest path: the CLI
+
+If `autumn` isn't installed, run:
+
+```bash
+npm install -g @autumnai/cli
+autumn setup
+autumn login
+```
+
+Start a task and save its rows:
+
+```bash
+autumn run "Find recent funding rounds for climate software companies" --out rounds.csv
+```
+
+If the task needs an answer, ask the user and reply on the same task. If it is still
+working, resume waiting:
+
+```bash
+autumn reply <task-id> "Focus on North American companies"
+autumn wait <task-id>
+```
+
+Exit codes: `0` completed, `1` failed or request error, `2` input required, `3` still
+working or approval pending, and `4` authentication required.
+
+## Setup (once)
+
+- Base URL `https://api.autumn.ai`. Send `X-API-Key: $AUTUMN_API_KEY` (keys start with `ak_`).
+- No key yet? Follow https://www.autumn.ai/agent-quickstart.md: `autumn login` or two curl calls get a key once the user approves in their browser. Never ask the user to paste a key into chat, and never print, log or commit it.
+- Check it works: `curl -sS https://api.autumn.ai/credits -H "X-API-Key: $AUTUMN_API_KEY"`.
+- To buy credits, use MCP `buy_credits` or `autumn buy 10000` to get a payment link for the user.
+
+## Team and usage
+
+- MCP: `get_team`, `get_usage`, `invite_member`, `revoke_invitation`,
+  `set_member_role`, `update_team`, `remove_member`.
+- CLI: `autumn team`, `autumn team invite|revoke|role|remove|set`, `autumn usage`.
+- REST: `GET /team`, `PATCH /team`, `POST /team/invitations`,
+  `DELETE /team/invitations/{invitation_id}`, `PATCH` / `DELETE /team/members/{user_id}`,
+  and `GET /team/usage?days=30`.
+- Team writes are owner-only. Creating or leaving a team is done in the app.
+
+## The loop
+
+```bash
+# 1. Start
+curl -sS -X POST https://api.autumn.ai/task -H "X-API-Key: $AUTUMN_API_KEY" \
+  -H "Content-Type: application/json" -d @brief.json        # -> {"task_id": ..., "state": "submitted", ...}
+
+# 2. Wait. Returns as soon as anything changes (max 50s). Repeat until "done": true.
+curl -sS "https://api.autumn.ai/task/$ID?wait=50" -H "X-API-Key: $AUTUMN_API_KEY"
+
+# 3. Answer or refine (queues if a turn is running, returns 202)
+curl -sS -X POST https://api.autumn.ai/task/$ID/continue -H "X-API-Key: $AUTUMN_API_KEY" \
+  -H "Content-Type: application/json" -d '{"message": "..."}'
+
+# 4. Read rows (paged; use cursor for more). CSV keeps big results out of your context.
+curl -sS "https://api.autumn.ai/task/$ID/output?format=csv" -H "X-API-Key: $AUTUMN_API_KEY" -o rows.csv
+```
+
+Every status response has: `state`, `done`, `message` (progress line, the agent's
+question, or its final reply), `progress` (`rows` / `target`), `credits_used`, `next.hint`
+and `app_url`.
+
+| `state` | `done` | What you do |
+|---|---|---|
+| `submitted` | no | Wait. `queue_position` says where it is. |
+| `working` | no | Wait. Relay `message` to the user as a one-line update. |
+| `input-required` | yes | Show `message` (a question) to the user, send their answer with `/continue`. |
+| `completed` | yes | Read `/output`. `outcome: partial` means it stopped short of the target. |
+| `failed` | yes | Report `error.message`. For `out_of_credits`, get a pay link with MCP `buy_credits`, `autumn buy 10000`, or `POST /credits/checkout {"credits":10000}` and give it to the user; https://platform.autumn.ai/?settings=usage is a fallback. |
+| `canceled` | yes | Stopped by `POST /task/$ID/stop`. Rows saved so far are still in `/output`. |
+
+Call the wait in a loop rather than sleeping. Each call is one update for the user.
+
+## How to research well with Autumn
+
+Autumn plans from your brief. A vague brief doesn't fail; it quietly answers a slightly
+different question. Write the brief like a contract:
+
+1. **Keep every specific the user gave you, verbatim.** Names, URLs, geography, time window,
+   exclusions, examples. Paraphrasing is where detail gets lost.
+2. **Say how many.** `"count": 25` (or a number in the prompt). Without one, "find companies"
+   has no natural end.
+3. **Name the columns.** If you know the shape, send a schema instead of describing it:
+   ```json
+   {"prompt": "Find 25 US fintechs that raised a Series A in 2025. Exclude crypto.",
+    "count": 25,
+    "output": {"kind": "research",
+               "schema": {"company": {"type": "name"}, "domain": {"type": "domain"},
+                          "round_date": {"type": "date"}, "lead_investor": {"type": "str"},
+                          "source_url": {"type": "url"}}}}
+   ```
+4. **State the per-row bar as rules.** Rules are checks each row must pass, not goals:
+   `{"rules": {"series_a_2025": "Raised a Series A in 2025, with a source", "us": "Headquartered in the US"}}`.
+   Without a bar the agent decides what counts.
+5. **Pick the output kind.** `research` for lists and tables. `person` or `company` for a
+   deep profile per known entity. Pass the known entities as `input_rows`
+   (e.g. `[{"name": "Ada Lovelace", "company": "Analytical Engines"}]`) or upload a file.
+6. **Pick the tier when it matters.** `"version": "ranger"` for open-ended research where the
+   agent must decide where to look or cross-check facts. `"version": "scout"` for bounded,
+   well-specified work where speed matters. The tier is fixed for the life of the task.
+7. **Questions.** `clarify` is `false` by default: the agent picks sensible defaults and runs.
+   Set `"clarify": true` only when the user is present and an answer would change the work.
+
+For complex or relayed requests, fetch `GET /task/metaprompt`. It returns the task spec
+schema and a metaprompt for turning a request into a spec for `POST /task/start`.
+
+## Iterate on the same task
+
+- More rows, a new column, a narrower list, fixing gaps: `/continue` the same task. Never start
+  a new task for a follow-up; that loses the rows and the context.
+- Restate the goal as one clear instruction, not the user's raw words.
+  "also linkedin" -> "Add each founder's LinkedIn URL to every existing row."
+- After `outcome: partial`, look at what's missing and ask for exactly that:
+  "Find 8 more that meet the same rules" or "Fill lead_investor where it's empty".
+
+## Judge the result before reporting it
+
+- Report from `/output` rows, never from status text.
+- When a completed task has outcome `blocked` or `partial`, read `message`; if it asks for information, get it from the user and reply on the same task.
+- A shorter verified list beats a padded one. Autumn leaves a cell empty or `unclear` rather
+  than guess. Say so, don't fill it in yourself.
+- Spot-check a few rows against their source links for anything the user will act on.
+- Show the most useful rows, the count vs target, and the `app_url` for the full table.
+
+## Style
+
+- Terse and status-first. One line per update, e.g. `working - 14/25 rows - verifying funding rounds`.
+- Keep the `task_id` and reuse it.
+- Don't show raw traces, internal errors or the API key.
+- Tasks spend credits. For a large or broad task, check `GET /credits` first and confirm
+  with the user if the cost looks high.
+
+## Reference
+
+- API contract: https://api.autumn.ai/openapi.json
+- Docs index: https://www.autumn.ai/docs/llms.txt
+- App and API keys: https://platform.autumn.ai/?settings=connect
+- Help: founders@autumnai.com