attio-cli 0.1.0 → 0.2.1

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,10 @@
 
 // bin/attio.ts
 import { program } from "commander";
-import chalk6 from "chalk";
+import chalk7 from "chalk";
+import { readFileSync as readFileSync2 } from "fs";
+import { dirname, join as join2 } from "path";
+import { fileURLToPath } from "url";
 
 // src/errors.ts
 import chalk from "chalk";
@@ -57,7 +60,7 @@ var AttioRateLimitError = class extends Error {
 import chalk2 from "chalk";
 
 // src/config.ts
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync } from "fs";
 import { join } from "path";
 import { homedir } from "os";
 import * as dotenv from "dotenv";
@@ -73,8 +76,16 @@ function loadConfig() {
   }
 }
 function saveConfig(config2) {
-  mkdirSync(CONFIG_DIR, { recursive: true });
-  writeFileSync(CONFIG_FILE, JSON.stringify(config2, null, 2));
+  mkdirSync(CONFIG_DIR, { recursive: true, mode: 448 });
+  try {
+    chmodSync(CONFIG_DIR, 448);
+  } catch {
+  }
+  writeFileSync(CONFIG_FILE, JSON.stringify(config2, null, 2), { mode: 384 });
+  try {
+    chmodSync(CONFIG_FILE, 384);
+  } catch {
+  }
 }
 function resolveApiKey(flagValue) {
   return flagValue || process.env.ATTIO_API_KEY || loadConfig().apiKey || "";
@@ -87,11 +98,29 @@ 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;
+function getRetryDelayMs(response, attempt) {
+  const retryAfter = response.headers.get("retry-after");
+  if (retryAfter) {
+    const asSeconds = Number(retryAfter);
+    if (!Number.isNaN(asSeconds)) {
+      return Math.max(0, Math.ceil(asSeconds * 1e3));
+    }
+    const asDate = Date.parse(retryAfter);
+    if (!Number.isNaN(asDate)) {
+      return Math.max(0, asDate - Date.now());
+    }
+  }
+  return INITIAL_BACKOFF_MS * Math.pow(2, attempt);
+}
 var AttioClient = class {
   apiKey;
   debug;
@@ -103,6 +132,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,13 +148,28 @@ 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) {
-          const backoff = INITIAL_BACKOFF_MS * Math.pow(2, attempt);
+          const backoff = Math.max(100, getRetryDelayMs(response, attempt));
+          if (this.debug) {
+            console.error(chalk2.dim(`  retrying in ${backoff}ms`));
+          }
           await new Promise((resolve) => setTimeout(resolve, backoff));
           continue;
         }
@@ -135,6 +182,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;
@@ -171,6 +221,43 @@ var AttioClient = class {
 import chalk3 from "chalk";
 import Table from "cli-table3";
 import { createInterface } from "readline";
+var ID_KEY_PRIORITY = [
+  "record_id",
+  "entry_id",
+  "task_id",
+  "note_id",
+  "comment_id",
+  "thread_id",
+  "workspace_member_id",
+  "list_id",
+  "object_id",
+  "webhook_id",
+  "workspace_id"
+];
+function toIdString(value) {
+  if (typeof value === "string" || typeof value === "number" || typeof value === "bigint") {
+    const id = String(value);
+    return id.length > 0 ? id : "";
+  }
+  return "";
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function extractOutputId(raw) {
+  const direct = toIdString(raw);
+  if (direct) return direct;
+  if (!isRecord(raw)) return "";
+  for (const key of ID_KEY_PRIORITY) {
+    const id = toIdString(raw[key]);
+    if (id) return id;
+  }
+  for (const value of Object.values(raw)) {
+    const fallback = toIdString(value);
+    if (fallback) return fallback;
+  }
+  return "";
+}
 function detectFormat(opts) {
   if (opts.quiet) return "quiet";
   if (opts.json) return "json";
@@ -183,8 +270,8 @@ function outputList(items, opts) {
   const idField = opts.idField || "id";
   if (format === "quiet") {
     for (const item of items) {
-      const raw = typeof item === "string" ? item : item[idField] || "";
-      const id = typeof raw === "object" && raw !== null ? Object.values(raw)[0] : raw;
+      const raw = typeof item === "string" ? item : item[idField] ?? "";
+      const id = extractOutputId(raw);
       if (id) console.log(id);
     }
     return;
@@ -223,8 +310,8 @@ function outputList(items, opts) {
 }
 function outputSingle(item, opts) {
   if (opts.format === "quiet") {
-    const raw = item[opts.idField || "id"] || "";
-    const id = typeof raw === "object" && raw !== null ? Object.values(raw)[0] : raw;
+    const raw = item[opts.idField || "id"] ?? "";
+    const id = extractOutputId(raw);
     console.log(id || "");
     return;
   }
@@ -240,6 +327,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) => {
@@ -416,6 +508,20 @@ function flattenRecord(record) {
   }
   return flat;
 }
+function stripWrappingQuotes(raw) {
+  if (raw.startsWith('"') && raw.endsWith('"') || raw.startsWith("'") && raw.endsWith("'")) {
+    return raw.slice(1, -1);
+  }
+  return raw;
+}
+function parseScalar(raw) {
+  const normalized = stripWrappingQuotes(raw.trim());
+  if (normalized === "true") return true;
+  if (normalized === "false") return false;
+  if (normalized === "null") return null;
+  if (/^-?\d+(\.\d+)?$/.test(normalized)) return Number(normalized);
+  return normalized;
+}
 function parseSets(sets) {
   const values = {};
   for (const set of sets) {
@@ -423,23 +529,31 @@ function parseSets(sets) {
     if (eqIdx === -1) throw new Error(`Invalid --set format: "${set}". Expected: key=value`);
     const key = set.slice(0, eqIdx).trim();
     const raw = set.slice(eqIdx + 1).trim();
-    if (raw === "true") {
-      values[key] = true;
-      continue;
-    }
-    if (raw === "false") {
-      values[key] = false;
-      continue;
-    }
-    if (/^-?\d+(\.\d+)?$/.test(raw)) {
-      values[key] = Number(raw);
-      continue;
+    if (raw.startsWith("{") && raw.endsWith("}")) {
+      try {
+        values[key] = JSON.parse(raw);
+        continue;
+      } catch {
+      }
     }
     if (raw.startsWith("[") && raw.endsWith("]")) {
-      values[key] = raw.slice(1, -1).split(",").map((s) => s.trim());
+      try {
+        const parsed = JSON.parse(raw);
+        if (Array.isArray(parsed)) {
+          values[key] = parsed;
+          continue;
+        }
+      } catch {
+      }
+      const inner = raw.slice(1, -1).trim();
+      if (inner === "") {
+        values[key] = [];
+        continue;
+      }
+      values[key] = inner.split(",").map((s) => parseScalar(s));
       continue;
     }
-    values[key] = raw;
+    values[key] = parseScalar(raw);
   }
   return values;
 }
@@ -454,8 +568,8 @@ async function readStdin() {
 async function resolveValues(options) {
   if (options.values) {
     if (options.values.startsWith("@")) {
-      const { readFileSync: readFileSync2 } = await import("fs");
-      return JSON.parse(readFileSync2(options.values.slice(1), "utf-8"));
+      const { readFileSync: readFileSync3 } = await import("fs");
+      return JSON.parse(readFileSync3(options.values.slice(1), "utf-8"));
     }
     return JSON.parse(options.values);
   }
@@ -466,20 +580,31 @@ 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);
   }
   const allResults = [];
-  let offset = 0;
+  let offset = options.offset;
   const pageSize = 500;
   while (true) {
     const page = await fetchPage(pageSize, offset);
     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 +673,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 +692,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 +730,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 +777,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 +833,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 +856,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 +885,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 +944,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 +992,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 +1013,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 +1060,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 +1168,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 +1241,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,39 +1392,104 @@ 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)
+\`\`\`
+
+### Records (CRUD \u2014 works for any object)
+
+\`\`\`
+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>
+\`\`\`
+
+### 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)
+\`\`\`
+
+### Lists & entries
+
+\`\`\`
+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
+\`\`\`
+
+### 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
+\`\`\`
 
-### Common commands
+### Notes & comments
 
 \`\`\`
-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 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
+### Output modes
 
-Auto-detects TTY: table for terminal, JSON when piped. Force with \`--json\`, \`--csv\`, or \`--table\`. Use \`-q\` for IDs only.
+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:
 
-### Filters & sorting
+\`\`\`bash
+ID=$(attio records create companies --set name="Acme" -q)
+attio notes create --object companies --record $ID --title "Note" --content "..."
+\`\`\`
+
+### Filter syntax
 
-\`--filter 'name~Acme'\` \`--filter 'revenue>=1000000'\` \`--sort name:asc\`
-Multiple \`--filter\` flags are ANDed together.`;
+\`--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) {
   program2.command("open <object> [record-id]").description("Open an object or record in the Attio web app").action(async (object, recordId, options, command) => {
     const opts = command.optsWithGlobals();
+    const objectSlug = encodeURIComponent(object);
     let url;
     if (recordId) {
       const client = new AttioClient(opts.apiKey, opts.debug);
-      const res = await client.get(`/objects/${object}/records/${recordId}`);
+      const res = await client.get(`/objects/${objectSlug}/records/${encodeURIComponent(recordId)}`);
       const record = res.data;
       url = record.web_url;
       if (!url) {
@@ -1270,10 +1500,10 @@ function register14(program2) {
       const client = new AttioClient(opts.apiKey, opts.debug);
       const self = await client.get("/self");
       const slug = self.workspace_slug || "";
-      url = `https://app.attio.com/${slug}/${object}`;
+      url = `https://app.attio.com/${encodeURIComponent(slug)}/${objectSlug}`;
     }
-    const cmd = platform() === "darwin" ? "open" : platform() === "win32" ? "start" : "xdg-open";
-    exec(`${cmd} "${url}"`, (err) => {
+    const cmd = platform() === "darwin" ? "open" : platform() === "win32" ? "explorer" : "xdg-open";
+    execFile(cmd, [url], (err) => {
       if (err) {
         console.log(url);
       }
@@ -1281,31 +1511,158 @@ 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 loadCliVersion() {
+  try {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const packagePath = join2(here, "..", "package.json");
+    const packageJson = JSON.parse(readFileSync2(packagePath, "utf-8"));
+    if (typeof packageJson.version === "string" && packageJson.version.length > 0) {
+      return packageJson.version;
+    }
+  } catch {
+  }
+  return "0.2.0";
+}
 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");
+program.name("attio").version(loadCliVersion()).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 +1677,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.1",
   "description": "CLI for the Attio CRM API. Built for scripts, agents, and humans who prefer terminals.",
   "license": "MIT",
   "type": "module",
@@ -12,7 +12,8 @@
   ],
   "scripts": {
     "build": "tsup",
-    "dev": "tsx bin/attio.ts"
+    "dev": "tsx bin/attio.ts",
+    "test": "node --import tsx --test tests/**/*.test.ts"
   },
   "dependencies": {
     "commander": "^12.0.0",