attio-cli 0.1.0 → 0.2.0

package/README.md

@@ -11,19 +11,34 @@ npm install -g attio-cli
 ## Quick Start
 
 ```bash
-export ATTIO_API_KEY=your_key
-# or
-attio config set api-key your_key
-
-attio whoami
-attio objects list
+attio init          # guided setup — paste your API key, done
+attio whoami        # verify connection
 attio people list --limit 5
 ```
 
+You'll need an API key from [Attio Developer Settings](https://app.attio.com/settings/developers). `attio init` walks you through the rest.
+
+For non-interactive environments (CI, scripts), use any of:
+
+```bash
+attio init --api-key <key>           # validates and saves
+export ATTIO_API_KEY=<key>           # env var (takes precedence)
+attio config set api-key <key>       # direct config write
+```
+
+## Agent Setup
+
+To let AI agents (Claude, etc.) discover this CLI, append the auto-generated snippet to your project's `CLAUDE.md`:
+
+```bash
+attio config claude-md >> CLAUDE.md
+```
+
 ## Command Reference
 
 | Command | Description |
 |---------|-------------|
+| `attio init` | Interactive setup wizard — connect to your Attio workspace |
 | `attio whoami` | Show current workspace and user info |
 | **Objects** | |
 | `attio objects list` | List all objects in the workspace |

package/dist/attio.js

@@ -2,7 +2,7 @@
 
 // bin/attio.ts
 import { program } from "commander";
-import chalk6 from "chalk";
+import chalk7 from "chalk";
 
 // src/errors.ts
 import chalk from "chalk";
@@ -87,11 +87,15 @@ function setApiKey(key) {
 function getConfigPath() {
   return CONFIG_FILE;
 }
+function isConfigured() {
+  return resolveApiKey() !== "";
+}
 
 // src/client.ts
 var BASE_URL = "https://api.attio.com/v2";
 var MAX_RETRIES = 3;
 var INITIAL_BACKOFF_MS = 1e3;
+var DEFAULT_TIMEOUT_MS = 3e4;
 var AttioClient = class {
   apiKey;
   debug;
@@ -103,6 +107,9 @@ var AttioClient = class {
     const url = `${BASE_URL}${path}`;
     if (this.debug) {
       console.error(chalk2.dim(`\u2192 ${method} ${url}`));
+      if (body !== void 0) {
+        console.error(chalk2.dim(`  body: ${JSON.stringify(body)}`));
+      }
     }
     if (!this.apiKey) {
       throw new AttioAuthError("No API key configured");
@@ -116,9 +123,21 @@ var AttioClient = class {
       init.body = JSON.stringify(body);
     }
     for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
-      const response = await fetch(url, init);
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS);
+      let response;
+      try {
+        response = await fetch(url, { ...init, signal: controller.signal });
+      } catch (err) {
+        clearTimeout(timer);
+        if (err?.name === "AbortError") {
+          throw new Error(`Request timed out after ${DEFAULT_TIMEOUT_MS / 1e3}s: ${method} ${path}`);
+        }
+        throw err;
+      }
+      clearTimeout(timer);
       if (this.debug) {
-        console.error(chalk2.dim(`\u2190 ${response.status}`));
+        console.error(chalk2.dim(`\u2190 ${response.status} ${response.statusText}`));
       }
       if (response.status === 429) {
         if (attempt < MAX_RETRIES) {
@@ -135,6 +154,9 @@ var AttioClient = class {
         return void 0;
       }
       const json = await response.json();
+      if (this.debug && !response.ok) {
+        console.error(chalk2.dim(`  error: ${JSON.stringify(json)}`));
+      }
       if (!response.ok) {
         const errorType = json?.type ?? "unknown_error";
         let errorDetail = json?.message ?? json?.detail ?? response.statusText;
@@ -240,6 +262,11 @@ function outputSingle(item, opts) {
   console.log(table.toString());
 }
 async function confirm(message) {
+  if (!process.stdin.isTTY) {
+    console.error(`${message} [y/N]`);
+    console.error("Error: Confirmation required but stdin is not a TTY. Use --yes to skip.");
+    return false;
+  }
   const rl = createInterface({ input: process.stdin, output: process.stderr });
   return new Promise((resolve) => {
     rl.question(`${message} [y/N] `, (answer) => {
@@ -466,8 +493,15 @@ async function resolveValues(options) {
   if (stdin.trim()) return JSON.parse(stdin);
   return {};
 }
+function requireValues(values) {
+  if (Object.keys(values).length === 0) {
+    throw new Error(`No values provided. Use --set key=value, --values '{"key":"value"}', or pipe JSON to stdin.`);
+  }
+  return values;
+}
 
 // src/pagination.ts
+var MAX_ALL_RECORDS = 1e4;
 async function paginate(fetchPage, options) {
   if (!options.all) {
     return fetchPage(options.limit, options.offset);
@@ -480,6 +514,10 @@ async function paginate(fetchPage, options) {
     allResults.push(...page);
     if (page.length < pageSize) break;
     offset += pageSize;
+    if (allResults.length >= MAX_ALL_RECORDS) {
+      console.error(`Warning: --all stopped after ${MAX_ALL_RECORDS} records. Use --limit and --offset for manual pagination.`);
+      break;
+    }
   }
   return allResults;
 }
@@ -548,7 +586,7 @@ async function getRecord(object, recordId, cmdOpts) {
 async function createRecord(object, cmdOpts) {
   const client = new AttioClient(cmdOpts.apiKey, cmdOpts.debug);
   const format = detectFormat(cmdOpts);
-  const values = await resolveValues(cmdOpts);
+  const values = requireValues(await resolveValues(cmdOpts));
   const res = await client.post(
     `/objects/${encodeURIComponent(object)}/records`,
     { data: { values } }
@@ -567,7 +605,7 @@ async function createRecord(object, cmdOpts) {
 async function updateRecord(object, recordId, cmdOpts) {
   const client = new AttioClient(cmdOpts.apiKey, cmdOpts.debug);
   const format = detectFormat(cmdOpts);
-  const values = await resolveValues(cmdOpts);
+  const values = requireValues(await resolveValues(cmdOpts));
   const res = await client.patch(
     `/objects/${encodeURIComponent(object)}/records/${encodeURIComponent(recordId)}`,
     { data: { values } }
@@ -605,7 +643,7 @@ async function upsertRecord(object, cmdOpts) {
   if (!matchAttr) {
     throw new Error("--match <attribute-slug> is required for upsert");
   }
-  const values = await resolveValues(cmdOpts);
+  const values = requireValues(await resolveValues(cmdOpts));
   const res = await client.put(
     `/objects/${encodeURIComponent(object)}/records?matching_attribute=${encodeURIComponent(matchAttr)}`,
     { data: { values } }
@@ -652,7 +690,7 @@ function register4(program2) {
   const records = program2.command("records").description("Manage records in any Attio object");
   records.command("list").description("List or query records for an object").argument("<object>", "Object slug or ID (e.g. companies, people)").option(
     "--filter <expr>",
-    'Filter expression, e.g. "name~Acme" (repeatable)',
+    'Filter: = != ~ !~ ^ > >= < <= ? (e.g. "name~Acme", "revenue>=1000", "email?"). Repeatable',
     (val, prev) => [...prev, val],
     []
   ).option("--filter-json <json>", "Raw JSON filter (overrides --filter)").option(
@@ -708,7 +746,7 @@ function register4(program2) {
 // src/commands/people.ts
 function register5(program2) {
   const cmd = program2.command("people").description("Manage people records (shortcut for: records <cmd> people)");
-  cmd.command("list").description("List people").option("--filter <expr>", "Filter expression (repeatable)", (v, p) => [...p, v], []).option("--filter-json <json>", "Raw JSON filter").option("--sort <expr>", "Sort expression (repeatable)", (v, p) => [...p, v], []).option("--limit <n>", "Max results per page", "25").option("--offset <n>", "Starting offset", "0").option("--all", "Fetch all pages").action(async (options, command) => {
+  cmd.command("list").description("List people").option("--filter <expr>", 'Filter: = != ~ !~ ^ > >= < <= ? (e.g. "name~Acme"). Repeatable', (v, p) => [...p, v], []).option("--filter-json <json>", "Raw JSON filter").option("--sort <expr>", "Sort expression (repeatable)", (v, p) => [...p, v], []).option("--limit <n>", "Max results per page", "25").option("--offset <n>", "Starting offset", "0").option("--all", "Fetch all pages").action(async (options, command) => {
     await listRecords("people", command.optsWithGlobals());
   });
   cmd.command("get <record-id>").description("Get a person by record ID").action(async (recordId, options, command) => {
@@ -731,7 +769,7 @@ function register5(program2) {
 // src/commands/companies.ts
 function register6(program2) {
   const cmd = program2.command("companies").description("Manage company records (shortcut for: records <cmd> companies)");
-  cmd.command("list").description("List companies").option("--filter <expr>", "Filter expression (repeatable)", (v, p) => [...p, v], []).option("--filter-json <json>", "Raw JSON filter").option("--sort <expr>", "Sort expression (repeatable)", (v, p) => [...p, v], []).option("--limit <n>", "Max results per page", "25").option("--offset <n>", "Starting offset", "0").option("--all", "Fetch all pages").action(async (options, command) => {
+  cmd.command("list").description("List companies").option("--filter <expr>", 'Filter: = != ~ !~ ^ > >= < <= ? (e.g. "name~Acme"). Repeatable', (v, p) => [...p, v], []).option("--filter-json <json>", "Raw JSON filter").option("--sort <expr>", "Sort expression (repeatable)", (v, p) => [...p, v], []).option("--limit <n>", "Max results per page", "25").option("--offset <n>", "Starting offset", "0").option("--all", "Fetch all pages").action(async (options, command) => {
     await listRecords("companies", command.optsWithGlobals());
   });
   cmd.command("get <record-id>").description("Get a company by record ID").action(async (recordId, options, command) => {
@@ -760,6 +798,16 @@ function register7(program2) {
     const format = detectFormat(opts);
     const res = await client.get("/lists");
     const lists = res.data;
+    if (format === "quiet") {
+      for (const l of lists) {
+        console.log(l.id?.list_id ?? "");
+      }
+      return;
+    }
+    if (format === "json") {
+      outputList(lists, { format });
+      return;
+    }
     const flat = lists.map((l) => ({
       id: l.id?.list_id || "",
       api_slug: l.api_slug || "",
@@ -809,7 +857,7 @@ function flattenEntry(entry) {
 }
 function register8(program2) {
   const cmd = program2.command("entries").description("Manage list entries");
-  cmd.command("list <list>").description("List entries in a list").option("--filter <expr>", "Filter expression (repeatable)", (v, p) => [...p, v], []).option("--filter-json <json>", "Raw JSON filter").option("--sort <expr>", "Sort expression (repeatable)", (v, p) => [...p, v], []).option("--limit <n>", "Max results per page", "25").option("--offset <n>", "Starting offset", "0").option("--all", "Fetch all pages").action(async (list, _options, command) => {
+  cmd.command("list <list>").description("List entries in a list").option("--filter <expr>", 'Filter: = != ~ !~ ^ > >= < <= ? (e.g. "name~Acme"). Repeatable', (v, p) => [...p, v], []).option("--filter-json <json>", "Raw JSON filter").option("--sort <expr>", "Sort expression (repeatable)", (v, p) => [...p, v], []).option("--limit <n>", "Max results per page", "25").option("--offset <n>", "Starting offset", "0").option("--all", "Fetch all pages").action(async (list, _options, command) => {
     const opts = command.optsWithGlobals();
     const client = new AttioClient(opts.apiKey, opts.debug);
     const format = detectFormat(opts);
@@ -857,7 +905,7 @@ function register8(program2) {
     const opts = command.optsWithGlobals();
     const client = new AttioClient(opts.apiKey, opts.debug);
     const format = detectFormat(opts);
-    const resolvedValues = await resolveValues({ values: opts.values, set: opts.set });
+    const resolvedValues = requireValues(await resolveValues({ values: opts.values, set: opts.set }));
     const body = {
       data: {
         parent_record_id: opts.record,
@@ -878,7 +926,7 @@ function register8(program2) {
     const opts = command.optsWithGlobals();
     const client = new AttioClient(opts.apiKey, opts.debug);
     const format = detectFormat(opts);
-    const resolvedValues = await resolveValues({ values: opts.values, set: opts.set });
+    const resolvedValues = requireValues(await resolveValues({ values: opts.values, set: opts.set }));
     const body = {
       data: {
         entry_values: resolvedValues
@@ -925,6 +973,16 @@ function register9(program2) {
     if (opts.sort) params.set("sort", opts.sort);
     const res = await client.get(`/tasks?${params.toString()}`);
     const tasksList = res.data;
+    if (format === "quiet") {
+      for (const t of tasksList) {
+        console.log(t.id?.task_id ?? "");
+      }
+      return;
+    }
+    if (format === "json") {
+      outputList(tasksList, { format });
+      return;
+    }
     const flat = tasksList.map((t) => ({
       id: t.id?.task_id || "",
       content: truncate(t.content_plaintext || "", 60),
@@ -1023,6 +1081,16 @@ function register10(program2) {
     if (opts.record) params.set("parent_record_id", opts.record);
     const res = await client.get(`/notes?${params.toString()}`);
     const notesList = res.data;
+    if (format === "quiet") {
+      for (const n of notesList) {
+        console.log(n.id?.note_id ?? "");
+      }
+      return;
+    }
+    if (format === "json") {
+      outputList(notesList, { format });
+      return;
+    }
     const flat = notesList.map((n) => ({
       id: n.id?.note_id || "",
       title: n.title || "",
@@ -1086,6 +1154,16 @@ function register11(program2) {
     if (opts.offset) params.set("offset", String(opts.offset));
     const res = await client.get(`/threads?${params.toString()}`);
     const threads = res.data;
+    if (format === "quiet") {
+      for (const thread of threads) {
+        console.log(thread.id?.thread_id || thread.thread_id || "");
+      }
+      return;
+    }
+    if (format === "json") {
+      outputList(threads, { format });
+      return;
+    }
     const flat = [];
     for (const thread of threads) {
       const threadId = thread.id?.thread_id || thread.thread_id || "";
@@ -1227,30 +1305,94 @@ function register13(program2) {
 }
 var CLAUDE_MD_SNIPPET = `## Attio CLI (\`attio\`)
 
-Use the \`attio\` CLI for all Attio CRM operations. Run \`attio <command> --help\` for full usage.
+Use the \`attio\` CLI for all Attio CRM operations. Always pass \`--yes\` on delete commands to avoid interactive prompts.
+
+### Discovery & setup
+
+\`\`\`
+attio whoami                                   Show workspace info
+attio objects list                             List all objects (people, companies, custom...)
+attio attributes list <object>                 List attributes for an object (shows slugs, types)
+attio lists list                               List all lists
+attio members list                             List workspace members (get member IDs for tasks)
+\`\`\`
 
-### Common commands
+### Records (CRUD \u2014 works for any object)
 
 \`\`\`
-attio companies search <query>              Search companies by name/domain
-attio people search <query>                 Search people by name/email
-attio records list <object> --filter <expr> List/filter records (companies, people, or custom objects)
-attio tasks create --content <text> --deadline <ISO-date> --record <object:record-id>
-attio notes create --object <obj> --record <id> --title <t> --content <text>
-attio open <object> [record-id]             Open in browser
+attio records list <object> [--filter <expr>] [--sort <expr>] [--limit N] [--all]
+attio records get <object> <record-id>
+attio records create <object> --set key=value [--set key2=value2]
+attio records update <object> <record-id> --set key=value
+attio records delete <object> <record-id> --yes
+attio records upsert <object> --match <attr-slug> --set key=value
+attio records search <object> <query>
 \`\`\`
 
-### Output
+### Shortcuts
+
+\`\`\`
+attio people list|get|create|update|delete|search    (same as: records ... people)
+attio companies list|get|create|update|delete|search (same as: records ... companies)
+\`\`\`
 
-Auto-detects TTY: table for terminal, JSON when piped. Force with \`--json\`, \`--csv\`, or \`--table\`. Use \`-q\` for IDs only.
+### Lists & entries
 
-### Filters & sorting
+\`\`\`
+attio entries list <list> [--filter <expr>] [--sort <expr>] [--limit N] [--all]
+attio entries get <list> <entry-id>
+attio entries create <list> --record <record-id> --object <obj> [--set key=value]
+attio entries update <list> <entry-id> --set key=value
+attio entries delete <list> <entry-id> --yes
+\`\`\`
 
-\`--filter 'name~Acme'\` \`--filter 'revenue>=1000000'\` \`--sort name:asc\`
-Multiple \`--filter\` flags are ANDed together.`;
+### Tasks
+
+\`\`\`
+attio tasks list [--assignee <member-id>] [--is-completed] [--limit N]
+attio tasks get <task-id>
+attio tasks create --content "..." [--assignee <member-id>] [--deadline <ISO-date>] [--record <object:record-id>]
+attio tasks update <task-id> [--complete] [--incomplete] [--deadline <ISO-date>] [--content "..."]
+attio tasks delete <task-id> --yes
+\`\`\`
+
+### Notes & comments
+
+\`\`\`
+attio notes list [--object <obj> --record <id>]
+attio notes get <note-id>
+attio notes create --object <obj> --record <id> --title "..." --content "..."
+attio notes delete <note-id> --yes
+attio comments list --object <obj> --record <id>
+attio comments create --object <obj> --record <id> --content "..."
+attio comments delete <comment-id> --yes
+\`\`\`
+
+### Output modes
+
+Auto-detects: table for TTY, JSON when piped. Force with \`--json\`, \`--csv\`, or \`--table\`.
+Use \`-q\` for IDs only (one per line) \u2014 ideal for chaining:
+
+\`\`\`bash
+ID=$(attio records create companies --set name="Acme" -q)
+attio notes create --object companies --record $ID --title "Note" --content "..."
+\`\`\`
+
+### Filter syntax
+
+\`--filter\` supports: \`=\` (equals), \`!=\` (not equals), \`~\` (contains), \`!~\` (not contains), \`^\` (starts with), \`>\`, \`>=\`, \`<\`, \`<=\`, \`?\` (is set/not empty).
+Multiple \`--filter\` flags are ANDed. Use \`--filter-json '{...}'\` for raw Attio filter JSON.
+
+\`\`\`
+--filter 'name~Acme' --filter 'revenue>=1000000' --sort name:asc
+\`\`\`
+
+### Values for create/update
+
+\`--set key=value\` (repeatable), \`--values '{"key":"value"}'\`, \`--values @file.json\`, or pipe JSON to stdin.`;
 
 // src/commands/open.ts
-import { exec } from "child_process";
+import { execFile } from "child_process";
 import { platform } from "os";
 import chalk5 from "chalk";
 function register14(program2) {
@@ -1273,7 +1415,7 @@ function register14(program2) {
       url = `https://app.attio.com/${slug}/${object}`;
     }
     const cmd = platform() === "darwin" ? "open" : platform() === "win32" ? "start" : "xdg-open";
-    exec(`${cmd} "${url}"`, (err) => {
+    execFile(cmd, [url], (err) => {
       if (err) {
         console.log(url);
       }
@@ -1281,31 +1423,146 @@ function register14(program2) {
   });
 }
 
+// src/commands/init.ts
+import { createInterface as createInterface2 } from "readline";
+import chalk6 from "chalk";
+function register15(program2) {
+  program2.command("init").description("Interactive setup wizard \u2014 connect to your Attio workspace").action(async function() {
+    const opts = this.optsWithGlobals();
+    let apiKey = opts.apiKey;
+    if (!apiKey) {
+      if (!process.stdin.isTTY) {
+        console.log("Non-interactive environment detected. To configure manually:\n");
+        console.log("  export ATTIO_API_KEY=your_key");
+        console.log("  # or");
+        console.log(`  attio config set api-key your_key`);
+        console.log(`  # or`);
+        console.log(`  attio init --api-key your_key
+`);
+        console.log(`Get your API key at: https://app.attio.com/settings/developers`);
+        return;
+      }
+      if (isConfigured()) {
+        const rl2 = createInterface2({ input: process.stdin, output: process.stderr });
+        const overwrite = await new Promise((resolve) => {
+          rl2.question(chalk6.yellow("An API key is already configured. Overwrite? [y/N] "), (answer) => {
+            rl2.close();
+            resolve(answer.trim().toLowerCase() === "y");
+          });
+        });
+        if (!overwrite) {
+          console.error(chalk6.dim("Setup cancelled."));
+          return;
+        }
+      }
+      console.error("");
+      console.error(chalk6.bold("  Attio CLI Setup"));
+      console.error(chalk6.dim("  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500"));
+      console.error("");
+      console.error(`  You'll need an API key from ${chalk6.cyan("https://app.attio.com/settings/developers")}`);
+      console.error("");
+      const rl = createInterface2({ input: process.stdin, output: process.stderr });
+      apiKey = await new Promise((resolve, reject) => {
+        rl.question("  Paste your API key: ", (answer) => {
+          rl.close();
+          resolve(answer);
+        });
+        rl.on("close", () => reject(new Error("cancelled")));
+      }).catch(() => {
+        console.error("");
+        process.exit(0);
+      });
+    }
+    apiKey = apiKey.trim().replace(/^['"]|['"]$/g, "");
+    if (!apiKey) {
+      console.error(chalk6.red("\n  No API key provided."));
+      console.error(`  Get one at: ${chalk6.cyan("https://app.attio.com/settings/developers")}`);
+      process.exit(1);
+    }
+    process.stderr.write(chalk6.dim("  Verifying..."));
+    try {
+      const client = new AttioClient(apiKey);
+      const self = await client.get("/self");
+      console.error(chalk6.green(" \u2713"));
+      console.error("");
+      const name = self.workspace_name || "your workspace";
+      const slug = self.workspace_slug;
+      console.error(`  Connected to ${chalk6.bold(`"${name}"`)}${slug ? ` (${slug})` : ""}`);
+      setApiKey(apiKey);
+      console.error(`  API key saved to ${chalk6.dim(getConfigPath())}`);
+      console.error("");
+      console.error(chalk6.dim("  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500"));
+      console.error(chalk6.bold("  Agent Setup") + chalk6.dim(" (optional)"));
+      console.error("");
+      console.error("  To let AI agents discover this CLI, run:");
+      console.error("");
+      console.error(`    ${chalk6.cyan("attio config claude-md >> CLAUDE.md")}`);
+      console.error("");
+      console.error(`  Done! Try ${chalk6.cyan("attio whoami")} or ${chalk6.cyan("attio companies list")} to get started.`);
+      console.error("");
+    } catch (err) {
+      console.error(chalk6.red(" \u2717"));
+      console.error("");
+      if (err?.message?.includes("Invalid or expired") || err?.message?.includes("401") || err?.message?.includes("not recognised")) {
+        console.error(chalk6.red("  Invalid API key."));
+        console.error(`  Double-check at: ${chalk6.cyan("https://app.attio.com/settings/developers")}`);
+      } else {
+        console.error(chalk6.red(`  Could not connect: ${err?.message || err}`));
+      }
+      process.exit(1);
+    }
+  });
+}
+
 // bin/attio.ts
 function handleError(err) {
+  const jsonMode = program.opts().json || !process.stdout.isTTY;
   if (err instanceof AttioApiError) {
-    console.error(err.display());
+    if (jsonMode) {
+      console.error(JSON.stringify({ error: true, status: err.statusCode, type: err.type, message: err.detail }));
+    } else {
+      console.error(err.display());
+    }
     process.exit(err.exitCode);
   }
   if (err instanceof AttioAuthError) {
-    console.error(err.display());
+    if (jsonMode) {
+      console.error(JSON.stringify({ error: true, status: 401, type: "auth_error", message: err.message }));
+    } else {
+      console.error(err.display());
+    }
     process.exit(err.exitCode);
   }
   if (err instanceof AttioRateLimitError) {
-    console.error(err.display());
+    if (jsonMode) {
+      console.error(JSON.stringify({ error: true, status: 429, type: "rate_limit", message: err.message }));
+    } else {
+      console.error(err.display());
+    }
     process.exit(err.exitCode);
   }
   if (err instanceof Error) {
-    console.error(chalk6.red(`Error: ${err.message}`));
-    if (process.env.ATTIO_DEBUG || program.opts().debug) {
-      console.error(err.stack);
+    if (jsonMode) {
+      console.error(JSON.stringify({ error: true, type: "unknown_error", message: err.message }));
+    } else {
+      console.error(chalk7.red(`Error: ${err.message}`));
+      if (process.env.ATTIO_DEBUG || program.opts().debug) {
+        console.error(err.stack);
+      }
     }
   } else {
-    console.error(chalk6.red("An unexpected error occurred"));
+    if (jsonMode) {
+      console.error(JSON.stringify({ error: true, type: "unknown_error", message: "An unexpected error occurred" }));
+    } else {
+      console.error(chalk7.red("An unexpected error occurred"));
+    }
   }
   process.exit(1);
 }
 program.name("attio").version("0.1.0").description("CLI for the Attio CRM API. Built for scripts, agents, and humans who prefer terminals.").option("--api-key <key>", "Override API key").option("--json", "Force JSON output").option("--table", "Force table output").option("--csv", "Force CSV output").option("-q, --quiet", "Only output IDs").option("--no-color", "Disable colors").option("--debug", "Print request/response details to stderr");
+if (process.argv.includes("--no-color")) {
+  process.env.NO_COLOR = "1";
+}
 register(program);
 register2(program);
 register3(program);
@@ -1320,6 +1577,22 @@ register11(program);
 register12(program);
 register13(program);
 register14(program);
+register15(program);
+program.action(() => {
+  if (!isConfigured()) {
+    console.error("");
+    console.error(chalk7.bold("  Welcome to attio-cli!"));
+    console.error("");
+    console.error(`  You haven't configured an API key yet. Run:`);
+    console.error("");
+    console.error(`    ${chalk7.cyan("attio init")}`);
+    console.error("");
+    console.error("  to connect to your Attio workspace.");
+    console.error("");
+  } else {
+    program.outputHelp();
+  }
+});
 program.parseAsync(process.argv).catch(handleError);
 process.on("uncaughtException", handleError);
 process.on("unhandledRejection", (reason) => handleError(reason));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "attio-cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "CLI for the Attio CRM API. Built for scripts, agents, and humans who prefer terminals.",
   "license": "MIT",
   "type": "module",