higherdata 0.2.2 → 0.3.1

package/README.md

@@ -213,12 +213,41 @@ Formats follow the current [Claude Code MCP](https://code.claude.com/docs/en/mcp
 ## Compatibility
 
 The CLI reads public `/api/v1/meta` once per day per API origin and caches the
-policy beside its config file. Updates are announced on stderr so JSON output
-stays machine-readable. Versions below the server's minimum refuse commands
-with `npm install --global higherdata@latest` as the upgrade command. `login`,
+policy beside its config file. Update notices are written to stderr only during interactive invocations.
+Versions below the server's minimum refuse commands and suggest `higherdata update`. `update`, `login`,
 `--help` and `--version` remain available without a compatibility check.
 
 The metadata request times out after three seconds. On network failure the CLI
 uses its last known policy; with no cached policy it allows the command. Failed
 checks are cached for a day too. A read-only cache directory allows commands but
 cannot persist the daily check, so subsequent invocations may check again.
+
+Download the loaded search page to a new file with `higherdata search companies --country-code CA --out results.csv`. Add `--all` to download up to 5,000 rows, or use a `.jsonl` destination for JSON Lines. The interactive results screen offers "This page" and "All results" when you press `d`. For larger sets, save the search to a list and export the list. Existing files are never overwritten.
+
+## Updates
+
+Run `higherdata update` (alias `higherdata upgrade`) to check npm and install the
+latest stable release. The CLI installs the exact version it checked and prints
+the old and new versions. A permission failure prints npm's error summary and
+the manual command. It never retries with sudo.
+
+Interactive npm global installs check npm on every run with a 1.5-second timeout, then
+automatically install a newer release and restart the same command with the
+same arguments. Failed installs print a manual command and continue on the
+current version. Timeouts and network failures continue silently. There is no
+cache for this npm release check.
+
+Automatic updates are skipped when either stdin or stdout is not a TTY, `CI`
+is set, `--json` or `--jsonl` is used, for MCP or stdio protocols, and for `npx`
+or non-global installs. To opt out for an invocation, set
+`HIGHERDATA_NO_AUTO_UPDATE=1`. To persist the preference, run:
+
+```sh
+higherdata config set auto-update false
+# Re-enable automatic updates
+higherdata config set auto-update true
+```
+
+Explicit `higherdata update` remains available with an opt-out or a server
+minimum-version refusal. Users on 0.3.0 must reinstall once to obtain the update
+command: `npm install --global higherdata@latest`.

package/dist/index.js

@@ -20573,6 +20573,7 @@ var init_config = __esm({
       space: external_exports.string().min(1).optional()
     });
     configSchema = external_exports.strictObject({
+      autoUpdate: external_exports.boolean().optional(),
       activeProfile: external_exports.string().min(1),
       profiles: external_exports.record(external_exports.string().min(1), profileSchema)
     }).refine((config2) => Object.hasOwn(config2.profiles, config2.activeProfile), {
@@ -20587,6 +20588,16 @@ var init_config = __esm({
   }
 });
 
+// ../../src/lib/ai/messages.ts
+var OWN_KEY_REQUIRED, OWN_KEY_REJECTED;
+var init_messages = __esm({
+  "../../src/lib/ai/messages.ts"() {
+    "use strict";
+    OWN_KEY_REQUIRED = "Add your OpenRouter key in Settings to use AI features.";
+    OWN_KEY_REJECTED = "Your OpenRouter key was rejected. Update it in Settings.";
+  }
+});
+
 // ../sdk/src/generated.ts
 var TOOL_CATALOG;
 var init_generated = __esm({
@@ -28133,6 +28144,10 @@ function retryAfter(response, data, now) {
     const date5 = Date.parse(value);
     if (Number.isFinite(date5)) return Math.max(0, (date5 - now) / 1e3);
   }
+  if (response.status === 429) {
+    const reset = response.headers.get("ratelimit-reset");
+    if (reset !== null && /^\d+(?:\.\d+)?$/.test(reset.trim())) return Number(reset);
+  }
   const parsed = failure2.safeParse(data);
   return parsed.success && typeof parsed.data.error !== "string" ? parsed.data.error.retry_after : void 0;
 }
@@ -28308,6 +28323,7 @@ function apiFailure(status, data) {
   if (code === "limit_exceeded" && message && /^This month's email verification allowance is reached\. Resets \d{4}-\d{2}-\d{2}\. Upgrade: (https:\/\/[^\s]+|\/docs\/plans-and-limits)$/.test(message)) return new CliError(message, EXIT_CODES.LIMIT);
   if (status === 429 || code === "limit_exceeded") return new CliError("A HigherData limit was reached. Wait until the limit resets.", EXIT_CODES.LIMIT);
   if (code === "suppressed" || code === "suppressed_only") return new CliError("All requested records are suppressed.", EXIT_CODES.SUPPRESSED_ONLY);
+  if (code === "ai_key_required" || code === "ai_key_rejected") return new CliError(code === "ai_key_required" ? OWN_KEY_REQUIRED : OWN_KEY_REJECTED);
   if (code === "needs_approval") return new CliError("This operation needs approval.", EXIT_CODES.NEEDS_APPROVAL);
   if (code === "jobs_unavailable") return new CliError("Background jobs are not configured for this deployment.");
   if (code === "invalid_input") return new CliError("The API rejected the input. Check the command's filters and identifiers.");
@@ -28318,6 +28334,7 @@ var CliError, object2, ApiClient;
 var init_api2 = __esm({
   "src/api.ts"() {
     "use strict";
+    init_messages();
     init_src();
     init_zod();
     init_exit_codes();
@@ -28340,8 +28357,16 @@ var init_api2 = __esm({
       async request(path2, input2, options = {}) {
         if (options.authenticated && !this.settings.apiKey) throw new CliError("Run higherdata login or set HIGHERDATA_API_KEY.", EXIT_CODES.AUTH);
         try {
-          const response = await this.transport.request(path2, input2, { ...options, idempotencyKey: this.settings.idempotencyKey });
-          return { status: response.status, data: response.data };
+          for (let attempt = 0; ; attempt++) {
+            try {
+              return await this.transport.request(path2, input2, { ...options, idempotencyKey: this.settings.idempotencyKey });
+            } catch (error63) {
+              if (!(error63 instanceof HigherDataError) || error63.status !== 429 || !options.rateLimitRecovery || attempt >= 5) throw error63;
+              const wait = (error63.retryAfter ?? 1) * 1e3;
+              if (!Number.isFinite(wait) || wait > 3e5) throw error63;
+              await options.rateLimitRecovery.sleep(Math.max(100, wait));
+            }
+          }
         } catch (error63) {
           if (error63 instanceof HigherDataError) {
             if (error63.status) throw apiFailure(error63.status, { error: { code: error63.code, message: error63.message } });
@@ -28469,7 +28494,7 @@ async function checkCliVersion(input2) {
     }
   }
   if (!policy) return;
-  const upgrade = "npm install --global higherdata@latest";
+  const upgrade = "higherdata update";
   if (compareVersions(input2.version, policy.minCliVersion) < 0) throw new CliError(`HigherData CLI ${input2.version} is no longer supported; minimum is ${policy.minCliVersion}. Upgrade: ${upgrade}`);
   if (compareVersions(input2.version, policy.latestCliVersion) < 0) input2.warn(`HigherData CLI ${policy.latestCliVersion} is available. Upgrade: ${upgrade}
 `);
@@ -31914,7 +31939,7 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "higherdata",
-      version: "0.2.2",
+      version: "0.3.1",
       type: "module",
       bin: {
         higherdata: "dist/index.js"
@@ -34894,6 +34919,9 @@ function cell(value) {
   const text2 = value == null ? "" : typeof value === "object" ? JSON.stringify(value) : String(value);
   return text2.replace(/[\u0000-\u001f\u007f-\u009f]/gu, " ");
 }
+function lookupMatchColumns(row) {
+  return { kind: cell(row.kind), name: cell(row.label), details: cell(row.detail) };
+}
 function customerOutput(value) {
   if (Array.isArray(value)) return value.map(customerOutput);
   if (!value || typeof value !== "object") return value;
@@ -34903,10 +34931,10 @@ function renderOutput(value, mode) {
   value = customerOutput(value);
   if (mode === "json") return `${JSON.stringify(value)}
 `;
-  const records = Array.isArray(value.items) ? value.items : Array.isArray(value.candidates) ? value.candidates : [value];
+  const records = Array.isArray(value.items) ? value.items : Array.isArray(value.candidates) ? value.candidates : Array.isArray(value.matches) ? value.matches : [value];
   if (mode === "jsonl") return records.map((record2) => JSON.stringify(record2)).join("\n") + (records.length ? "\n" : "");
   if (!records.length) return "No results.\n";
-  const rows = records.map((record2) => record2);
+  const rows = records.map((record2) => Array.isArray(value.matches) ? lookupMatchColumns(record2) : record2);
   const columns = rows.some((row) => "companyName" in row) ? rows.some((row) => "fullName" in row) ? ["id", "fullName", "jobTitle", "companyName", "emailAddress"] : ["id", "companyName", "normalizedDomain", "headquartersCountryCode"] : Object.keys(rows[0]);
   const headings = columns.map((column) => column.replace(/([a-z])([A-Z])/gu, "$1 $2").toUpperCase());
   const widths = columns.map((column, index) => rows.reduce((width, row) => Math.min(64, Math.max(width, cell(row[column]).length)), headings[index].length));
@@ -34922,6 +34950,105 @@ var init_output = __esm({
   }
 });
 
+// ../../src/lib/csv/search-download.ts
+function csvCell(value) {
+  let text2 = value === null || value === void 0 ? "" : String(value);
+  if (/^[\s\u0000-\u001f]*[=+\-@]/.test(text2)) text2 = `'${text2}`;
+  return `"${text2.replaceAll('"', '""')}"`;
+}
+function pageCsv(headers, rows) {
+  const lines = [headers.map(csvCell).join(","), ...rows.map((row) => row.map(csvCell).join(","))];
+  return `${lines.join("\r\n")}\r
+`;
+}
+function companyPageCsv(items) {
+  return pageCsv(
+    [...COMPANY_DOWNLOAD_FIELDS],
+    items.map((item) => COMPANY_DOWNLOAD_FIELDS.map((field) => item[field]))
+  );
+}
+function peoplePageCsv(items) {
+  return pageCsv(
+    [...PEOPLE_DOWNLOAD_FIELDS],
+    items.map((item) => PEOPLE_DOWNLOAD_FIELDS.map((field) => item[field]))
+  );
+}
+function searchPageJsonl(kind, items) {
+  const fields = kind === "companies" ? COMPANY_DOWNLOAD_FIELDS : PEOPLE_DOWNLOAD_FIELDS;
+  return items.map((item) => JSON.stringify(Object.fromEntries(fields.map((field) => [field, item[field] ?? null]))) + "\n").join("");
+}
+var COMPANY_DOWNLOAD_FIELDS, PEOPLE_DOWNLOAD_FIELDS;
+var init_search_download = __esm({
+  "../../src/lib/csv/search-download.ts"() {
+    "use strict";
+    COMPANY_DOWNLOAD_FIELDS = ["id", "companyName", "normalizedDomain", "headquartersCountryCode", "industryLinkedin", "employeeCountEstimate"];
+    PEOPLE_DOWNLOAD_FIELDS = ["id", "fullName", "jobTitle", "companyName", "emailAddress", "countryCode"];
+  }
+});
+
+// src/search-download.ts
+import { open as open5 } from "fs/promises";
+function searchDownloadFormat(path2) {
+  if (!/\.(csv|jsonl)$/.test(path2)) throw new CliError("Choose a new .csv or .jsonl destination.");
+  return path2.endsWith(".jsonl") ? "jsonl" : "csv";
+}
+async function downloadSearch(api, name, input2, path2, options) {
+  const format2 = searchDownloadFormat(path2);
+  if (options.all && api.settings.idempotencyKey) throw new CliError("An idempotency key applies to one page. Omit --all.");
+  const file2 = await open5(path2, "wx", 384);
+  let count = 0, first = true, cursor = input2.cursor, loaded = options.loadedPage;
+  const seen = /* @__PURE__ */ new Set();
+  if (typeof cursor === "string") seen.add(cursor);
+  try {
+    while (true) {
+      let raw, headers;
+      if (loaded) {
+        raw = loaded;
+        loaded = void 0;
+      } else {
+        const response = await api.request(`/api/v1/tools/${name}`, { ...input2, ...cursor === void 0 ? {} : { cursor } }, { authenticated: true, rateLimitRecovery: options });
+        raw = response.data;
+        headers = response.headers;
+      }
+      const page = pageSchema2.safeParse(raw);
+      if (!page.success || page.data.items.some((item) => typeof item.id !== "string" || !(name === "search.companies" ? /^hdo_[a-f0-9]{32}$/ : /^hdp_[a-f0-9]{32}$/).test(item.id))) throw new CliError("The API returned an invalid search page.");
+      const items = page.data.items.slice(0, SEARCH_DOWNLOAD_CAP - count);
+      if (format2 === "jsonl") await file2.writeFile(searchPageJsonl(name === "search.companies" ? "companies" : "people", items));
+      else {
+        const csv = (name === "search.companies" ? companyPageCsv : peoplePageCsv)(items);
+        await file2.writeFile(first ? csv : csv.slice(csv.indexOf("\r\n") + 2));
+      }
+      first = false;
+      count += items.length;
+      options.progress?.(`Downloaded ${count.toLocaleString("en-US")} of 5,000`);
+      const next = page.data.nextCursor;
+      if (!options.all || !next || count === SEARCH_DOWNLOAD_CAP) return { rows: count, capped: !!options.all && count === SEARCH_DOWNLOAD_CAP && (!!next || items.length < page.data.items.length) };
+      if (seen.has(next)) throw new CliError("The API repeated a cursor. Pagination stopped.");
+      seen.add(next);
+      cursor = next;
+      if (headers?.get("ratelimit-remaining") === "0") {
+        const reset = headers.get("ratelimit-reset");
+        if (reset !== null && /^\d+(?:\.\d+)?$/.test(reset.trim())) await options.sleep(Number(reset) * 1e3);
+      }
+    }
+  } finally {
+    await file2.close();
+  }
+}
+var SEARCH_DOWNLOAD_CAP, SEARCH_DOWNLOAD_CAP_NOTICE, isSearchResults, pageSchema2;
+var init_search_download2 = __esm({
+  "src/search-download.ts"() {
+    "use strict";
+    init_zod();
+    init_search_download();
+    init_api2();
+    SEARCH_DOWNLOAD_CAP = 5e3;
+    SEARCH_DOWNLOAD_CAP_NOTICE = "Download stopped at 5,000 rows. Save the search to a list and export the list for larger sets.";
+    isSearchResults = (name) => name === "search.companies" || name === "search.people";
+    pageSchema2 = external_exports.object({ items: external_exports.array(external_exports.record(external_exports.string(), external_exports.unknown())).max(50), nextCursor: external_exports.string().min(1).max(2048).nullable() });
+  }
+});
+
 // ../../node_modules/smol-toml/dist/error.js
 function getLineColFromPtr(string4, ptr) {
   let lines = string4.slice(0, ptr).split(/\r?\n/);
@@ -36718,11 +36845,11 @@ function parseTree(text2, errors2 = [], options = ParseOptions.DEFAULT) {
       onValue({ type: getNodeType(value), offset, length, parent: currentParent, value });
       ensurePropertyComplete(offset + length);
     },
-    onSeparator: (sep, offset, length) => {
+    onSeparator: (sep2, offset, length) => {
       if (currentParent.type === "property") {
-        if (sep === ":") {
+        if (sep2 === ":") {
           currentParent.colonOffset = offset;
-        } else if (sep === ",") {
+        } else if (sep2 === ",") {
           ensurePropertyComplete(offset);
         }
       }
@@ -37342,7 +37469,7 @@ var init_main = __esm({
 
 // src/install.ts
 import { constants } from "fs";
-import { access, chmod as chmod2, lstat, mkdir as mkdir3, open as open5, readFile as readFile3, readdir, rename as rename3, unlink as unlink3 } from "fs/promises";
+import { access, chmod as chmod2, lstat, mkdir as mkdir3, open as open6, readFile as readFile3, readdir, rename as rename3, unlink as unlink3 } from "fs/promises";
 import { execFile as execFile2 } from "child_process";
 import { promisify, isDeepStrictEqual } from "util";
 import { homedir as homedir2 } from "os";
@@ -37416,7 +37543,7 @@ async function safeParents(path2) {
   await mkdir3(dirname3(path2), { recursive: true, mode: 448 });
 }
 async function privateFile(path2, text2) {
-  const file2 = await open5(path2, "wx", 384);
+  const file2 = await open6(path2, "wx", 384);
   try {
     await file2.writeFile(text2, "utf8");
   } finally {
@@ -37965,6 +38092,7 @@ function recordFields(value, prefix = "") {
   if (!value || typeof value !== "object") return [[prefix || "Value", shownValue(value)]];
   return Object.entries(value).flatMap(([key, child]) => {
     if (internalCostKey(key) || child === void 0 || child === null && !["before", "after"].includes(key) || ["nextCursor", "requestId", "releaseId", "rawId", "warehouseId"].includes(key)) return [];
+    if (key === "aiMode") return [["AI key", { byok: "Own key", platform: "Platform", none: "Not configured" }[String(child)] ?? "Unavailable"]];
     const name = prefix ? `${prefix} / ${title(key)}` : title(key);
     if (Array.isArray(child) && child.some((item) => item && typeof item === "object")) return child.flatMap((item, i) => recordFields(item, `${name} ${i + 1}`));
     if (child && typeof child === "object" && !Array.isArray(child)) return recordFields(child, name);
@@ -38049,7 +38177,7 @@ var init_model = __esm({
       ["account", "Account", "Usage, limits and API keys"],
       ["icp", "ICP", "Build your ideal customer profile"]
     ];
-    groupTools = (group) => TOOL_CATALOG.filter((tool) => tool.name.startsWith(`${group}.`));
+    groupTools = (group) => TOOL_CATALOG.filter((tool) => tool.name.startsWith(`${group}.`) && tool.name !== "lookup.find");
     toolByName = (name) => TOOL_CATALOG.find((tool) => tool.name === name);
     clean = (value) => String(value ?? "").replace(/[\u0000-\u001f\u007f-\u009f]/gu, " ");
     title = (value) => value.replaceAll("_", " ").replace(/([a-z])([A-Z])/gu, "$1 $2").replace(/\b\w/gu, (c) => c.toUpperCase());
@@ -38137,19 +38265,43 @@ var init_install_menu = __esm({
 });
 
 // src/terminal/banner.ts
-function bannerFrame(frame, columns) {
-  const full = Array.from({ length: 6 }, (_, row) => [..."HIGHERDATA"].map((letter) => GLYPHS[letter][row]).join(" "));
-  const visible = frame < 5 ? Math.ceil((frame + 1) / 5 * full[0].length) : full[0].length;
-  const indent = Math.max(0, Math.floor((columns - full[0].length) / 2));
-  const widths = [24, 12, 18], offsets = [0, 6, 3];
-  const logo = widths.flatMap((width, index) => {
-    const progress = Math.max(0, Math.min(1, (frame - 5 - index) / 2));
-    const line = " ".repeat(Math.max(0, Math.floor((columns - 24) / 2)) + offsets[index]) + "\u2588".repeat(Math.ceil(width * progress));
-    return [line, line, ""];
+function markFrame(size, progress = [1, 1, 1]) {
+  const scale = size === "large" ? 3 : 1;
+  return [8, 4, 6].flatMap((units, index) => {
+    const width = Math.round(units * scale * Math.max(0, Math.min(1, progress[index])));
+    const indent = " ".repeat([0, 2, 1][index] * scale);
+    const cap = width > 2 ? indent + " " + "\u2584".repeat(width - 2) : "";
+    const base2 = width ? indent + "\u2580".repeat(width) : "";
+    return size === "large" ? [cap, width ? indent + "\u2588".repeat(width) : "", cap.replaceAll("\u2584", "\u2580")] : [cap, base2];
+  });
+}
+function wordmarkFrame(frame = BANNER_FRAMES - 1) {
+  const visible = frame < 5 ? Math.ceil((frame + 1) / 5 * WORDMARK_WIDTH) : WORDMARK_WIDTH;
+  return Array.from({ length: 6 }, (_, row) => {
+    const higher = [..."HIGHER"].map((letter) => GLYPHS[letter][row]).join(" ") + " ";
+    const data = [..."DATA"].map((letter) => GLYPHS[letter][row]).join(" ");
+    return { higher: higher.slice(0, visible), data: data.slice(0, Math.max(0, visible - higher.length)) };
   });
-  return [...full.map((line) => " ".repeat(indent) + line.slice(0, visible)), "", ...logo, frame >= 10 ? " ".repeat(Math.max(0, Math.floor((columns - 23) / 2))) + "HIGHERDATA by HigherOps" : ""].map((line) => line.trimEnd());
 }
-var GLYPHS, BANNER_FRAMES, BANNER_DURATION_MS, SMALL_MARK, shouldAnimate;
+function homeBrandLayout(columns, rows, extraRows = 0) {
+  const sideBySide = columns - 4 >= WORDMARK_WIDTH + 3 + MARK_WIDTH;
+  const headerRows = sideBySide ? 10 : 17;
+  return { large: columns - 4 >= WORDMARK_WIDTH && rows >= headerRows + 14 + extraRows, sideBySide, headerRows };
+}
+function busyFrame(frame, size = "large") {
+  return markFrame(size, [0, 1, 2].map((index) => 0.65 + 0.35 * (1 + Math.sin(frame * Math.PI / 4 - index * Math.PI / 2)) / 2));
+}
+function bannerFrame(frame, columns) {
+  const wordmark = wordmarkFrame(frame).map((line) => line.higher + line.data);
+  const indent = " ".repeat(Math.max(0, Math.floor((columns - WORDMARK_WIDTH) / 2)));
+  const logo = markFrame("large", [0, 1, 2].map((index) => Math.max(0, Math.min(1, (frame - 5 - index) / 2))));
+  const markIndent = " ".repeat(Math.max(0, Math.floor((columns - MARK_WIDTH) / 2)));
+  return [...wordmark.map((line) => indent + line), "", ...logo.map((line) => markIndent + line), frame >= 10 ? " ".repeat(Math.max(0, Math.floor((columns - 23) / 2))) + "HIGHERDATA by HigherOps" : ""].map((line) => line.trimEnd());
+}
+function animationOptions(args = process.argv.slice(2)) {
+  return { banner: !args.includes("--no-banner"), json: args.includes("--json"), jsonl: args.includes("--jsonl") };
+}
+var GLYPHS, BANNER_FRAMES, BANNER_DURATION_MS, MARK_WIDTH, WORDMARK_WIDTH, shouldAnimate;
 var init_banner = __esm({
   "src/terminal/banner.ts"() {
     "use strict";
@@ -38165,13 +38317,15 @@ var init_banner = __esm({
     };
     BANNER_FRAMES = 11;
     BANNER_DURATION_MS = 1210;
-    SMALL_MARK = ["\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588", "  \u2588\u2588\u2588\u2588  ", " \u2588\u2588\u2588\u2588\u2588\u2588 "];
+    MARK_WIDTH = 24;
+    WORDMARK_WIDTH = [..."HIGHERDATA"].reduce((width, letter) => width + GLYPHS[letter][0].length, "HIGHERDATA".length - 1);
     shouldAnimate = (tty, options, env) => tty && options.banner !== false && !options.json && !options.jsonl && !Object.hasOwn(env, "CI");
   }
 });
 
 // src/terminal/screens.tsx
-import { Box, Text } from "ink";
+import { useEffect, useState } from "react";
+import { Box, Text, useStdout } from "ink";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 function Menu({ items, selected, limit, color, width }) {
   const start = Math.max(0, Math.min(selected - Math.floor(limit / 2), items.length - limit));
@@ -38194,17 +38348,54 @@ function Menu({ items, selected, limit, color, width }) {
     ] })
   ] });
 }
+function Mark({ lines, color }) {
+  return /* @__PURE__ */ jsx(Box, { flexDirection: "column", children: lines.map((line, i) => /* @__PURE__ */ jsx(Text, { color, children: line || " " }, i)) });
+}
+function Wordmark({ color, frame }) {
+  return /* @__PURE__ */ jsx(Box, { flexDirection: "column", width: WORDMARK_WIDTH, children: wordmarkFrame(frame).map((line, i) => /* @__PURE__ */ jsxs(Text, { children: [
+    line.higher,
+    /* @__PURE__ */ jsx(Text, { color, children: line.data })
+  ] }, i)) });
+}
+function BusyMark({ color, size = "large", options = animationOptions(), env = process.env }) {
+  const { stdout } = useStdout(), [frame, setFrame] = useState(0);
+  const animate = shouldAnimate(Boolean(stdout.isTTY), options, env);
+  useEffect(() => {
+    if (!animate) return;
+    const timer = setInterval(() => setFrame((value) => (value + 1) % 8), 120);
+    return () => clearInterval(timer);
+  }, [animate]);
+  return /* @__PURE__ */ jsx(Mark, { lines: animate ? busyFrame(frame, size) : markFrame(size), color });
+}
 function TerminalScreen({ state, columns, rows = 28, colors = true, profile = "default", space = "Default", workspace = "HigherOps", remaining = "--" }) {
   const width = Math.max(40, columns), color = colors ? "#f2b705" : void 0;
-  const limit = Math.max(4, rows - 12);
+  const limit = Math.max(4, rows - 15);
+  const extraRows = [state.error, state.notice].reduce((count, text2) => count + Math.ceil(clean(text2).length / (width - 4)), 0);
+  const brand = homeBrandLayout(width, rows, extraRows), largeHome = state.screen === "home" && brand.large;
   if (state.screen === "banner") return /* @__PURE__ */ jsxs(Box, { flexDirection: "column", width, children: [
-    bannerFrame(state.frame, width).map((line, i) => /* @__PURE__ */ jsx(Text, { color, children: line }, i)),
+    /* @__PURE__ */ jsx(Box, { paddingLeft: Math.max(0, Math.floor((width - WORDMARK_WIDTH) / 2)), children: /* @__PURE__ */ jsx(Wordmark, { color, frame: state.frame }) }),
+    /* @__PURE__ */ jsx(Text, { children: " " }),
+    /* @__PURE__ */ jsx(Mark, { lines: bannerFrame(state.frame, width).slice(7, 16), color }),
+    /* @__PURE__ */ jsx(Text, { dimColor: true, children: bannerFrame(state.frame, width)[16] || " " }),
     /* @__PURE__ */ jsx(Text, { dimColor: true, children: "Press any key to start" })
   ] });
   const fields = state.tool ? fieldsFor(state.tool.input, state.input, state.variant) : [];
   let help = "Up/Down choose. Enter opens. Esc back. Ctrl+C quit.";
   let content;
-  if (state.screen === "home") content = /* @__PURE__ */ jsx(Menu, { items: homeItems, selected: state.selected, limit: Math.max(4, rows - 14), color, width: width - 4 });
+  if (state.screen === "home") help = "Up/Down choose. Enter opens. / Look up. Ctrl+C quit.";
+  if (state.screen === "home") content = /* @__PURE__ */ jsx(Menu, { items: homeItems, selected: state.selected, limit: Math.max(4, rows - (largeHome ? brand.headerRows : 6) - 8 - extraRows), color, width: width - 4 });
+  if (state.screen === "lookup") {
+    content = /* @__PURE__ */ jsxs(Fragment, { children: [
+      /* @__PURE__ */ jsx(Text, { bold: true, children: "Look up" }),
+      /* @__PURE__ */ jsx(Text, { dimColor: true, children: "Name, work email, international phone, domain, LinkedIn or record id" }),
+      /* @__PURE__ */ jsxs(Text, { color, wrap: "wrap", children: [
+        "> ",
+        clean(state.text),
+        "_"
+      ] })
+    ] });
+    help = "Type or paste. Enter looks up. Esc home.";
+  }
   if (state.screen === "install") {
     content = /* @__PURE__ */ jsxs(Fragment, { children: [
       /* @__PURE__ */ jsxs(Text, { bold: true, children: [
@@ -38275,6 +38466,12 @@ function TerminalScreen({ state, columns, rows = 28, colors = true, profile = "d
     ] });
     help = "Enter edit/run. Arrays: comma separated. Blank clears. Esc back.";
   }
+  if (state.screen === "download-choice") {
+    content = /* @__PURE__ */ jsxs(Fragment, { children: [
+      /* @__PURE__ */ jsx(Text, { bold: true, children: "Download search results" }),
+      /* @__PURE__ */ jsx(Menu, { items: [{ label: "This page", hint: "Loaded rows, no new request" }, { label: "All results", hint: "Same search, up to 5,000 rows" }], selected: state.selected, limit: 2, color, width: width - 4 })
+    ] });
+  }
   if (["edit", "upload", "download", "space"].includes(state.screen)) {
     const field = fields.find((field2) => field2.path === state.field);
     content = /* @__PURE__ */ jsxs(Fragment, { children: [
@@ -38296,7 +38493,7 @@ function TerminalScreen({ state, columns, rows = 28, colors = true, profile = "d
   }
   if (state.screen === "busy") {
     content = /* @__PURE__ */ jsxs(Fragment, { children: [
-      SMALL_MARK.map((line, i) => /* @__PURE__ */ jsx(Text, { color, children: line }, i)),
+      /* @__PURE__ */ jsx(BusyMark, { color, size: rows >= 28 ? "large" : "compact" }),
       /* @__PURE__ */ jsx(Text, { children: state.notice || "Working..." })
     ] });
     help = "The current operation is running. It is never retried automatically.";
@@ -38315,35 +38512,58 @@ function TerminalScreen({ state, columns, rows = 28, colors = true, profile = "d
   }
   if (state.screen === "results") {
     const items = rowsOf(state.result);
-    const list = state.tool?.name === "lists.get" && state.input.id && Array.isArray(state.result.lists) ? state.result.lists[0] : void 0;
-    content = /* @__PURE__ */ jsxs(Fragment, { children: [
-      /* @__PURE__ */ jsx(Text, { bold: true, children: state.tool?.name ?? "Enrichment job" }),
-      list && /* @__PURE__ */ jsxs(Text, { dimColor: true, wrap: "truncate-end", children: [
-        clean(list.name),
-        " / ",
-        clean(list.type),
-        " / ",
-        list.recurringEnabled ? "Each release" : "On demand",
-        " / ",
-        clean(list.maxRecords),
-        " records / ",
-        clean(list.maxNewRecordsPerRefresh),
-        " new records per refresh"
-      ] }),
-      items.length ? /* @__PURE__ */ jsx(Menu, { items: items.map((row) => ({ label: rowLabel(row), hint: row.matchesCriteria === false ? "No longer matches" : clean(row.status ?? row.jobTitle ?? row.normalizedDomain ?? row.domain ?? row.headquartersCountryCode) })), selected: state.selected, limit: limit - (list ? 3 : 2), color, width: width - 4 }) : recordFields(state.result).slice(state.selected, state.selected + limit).map(([key, value]) => /* @__PURE__ */ jsxs(Text, { wrap: "truncate-end", children: [
-        key,
-        ": ",
-        value
-      ] }, key)),
-      /* @__PURE__ */ jsxs(Text, { dimColor: true, children: [
-        items.length ? `${items.length} on this page. ` : "",
-        state.result.nextCursor ? "More records available." : "End of page."
-      ] })
-    ] });
-    help = "Enter detail. N next page. R refresh. D download. E edit inputs. Esc back.";
-    if (!state.tool) help = "E installation options. Esc home. ";
-    if (state.tool?.name === "searches.list") help = "Enter reopen search. A create audience. N next page. E edit. Esc back.";
-    if (state.tool?.name === "lists.get" && state.input.id) help += " P preview refresh.";
+    if (state.tool?.name === "lookup.find") {
+      content = /* @__PURE__ */ jsxs(Fragment, { children: [
+        /* @__PURE__ */ jsxs(Text, { bold: true, children: [
+          "Look up: ",
+          clean(state.input.query)
+        ] }),
+        items.length ? /* @__PURE__ */ jsxs(Fragment, { children: [
+          /* @__PURE__ */ jsx(Text, { dimColor: true, children: "KIND / NAME / DETAILS" }),
+          /* @__PURE__ */ jsx(Menu, { items: items.map((row) => {
+            const match = lookupMatchColumns(row);
+            return { label: `${match.kind}: ${match.name}`, hint: match.details };
+          }), selected: state.selected, limit: limit - 2, color, width: width - 4 })
+        ] }) : /* @__PURE__ */ jsxs(Fragment, { children: [
+          /* @__PURE__ */ jsxs(Text, { children: [
+            "No match for ",
+            clean(state.input.query)
+          ] }),
+          /* @__PURE__ */ jsx(Text, { dimColor: true, children: "Try Search to find companies or people with filters." })
+        ] })
+      ] });
+      help = "Enter detail. E edit lookup. Esc home.";
+    } else {
+      const list = state.tool?.name === "lists.get" && state.input.id && Array.isArray(state.result.lists) ? state.result.lists[0] : void 0;
+      content = /* @__PURE__ */ jsxs(Fragment, { children: [
+        /* @__PURE__ */ jsx(Text, { bold: true, children: state.tool?.name ?? "Enrichment job" }),
+        list && /* @__PURE__ */ jsxs(Text, { dimColor: true, wrap: "truncate-end", children: [
+          clean(list.name),
+          " / ",
+          clean(list.type),
+          " / ",
+          list.recurringEnabled ? "Each release" : "On demand",
+          " / ",
+          clean(list.maxRecords),
+          " records / ",
+          clean(list.maxNewRecordsPerRefresh),
+          " new records per refresh"
+        ] }),
+        items.length ? /* @__PURE__ */ jsx(Menu, { items: items.map((row) => ({ label: rowLabel(row), hint: row.matchesCriteria === false ? "No longer matches" : clean(row.status ?? row.jobTitle ?? row.normalizedDomain ?? row.domain ?? row.headquartersCountryCode) })), selected: state.selected, limit: limit - (list ? 3 : 2), color, width: width - 4 }) : recordFields(state.result).slice(state.selected, state.selected + limit).map(([key, value]) => /* @__PURE__ */ jsxs(Text, { wrap: "truncate-end", children: [
+          key,
+          ": ",
+          value
+        ] }, key)),
+        /* @__PURE__ */ jsxs(Text, { dimColor: true, children: [
+          items.length ? `${items.length} on this page. ` : "",
+          state.result.nextCursor ? "More records available." : "End of page."
+        ] })
+      ] });
+      help = "Enter detail. N next page. R refresh. D download. E edit inputs. Esc back.";
+      if (!state.tool) help = "E installation options. Esc home. ";
+      if (state.tool?.name === "searches.list") help = "Enter reopen search. A create audience. N next page. E edit. Esc back.";
+      if (state.tool?.name === "lists.get" && state.input.id) help += " P preview refresh.";
+    }
   }
   if (state.screen === "detail") {
     const row = detailRecord(state.row), isCore = coreRecord(state.row);
@@ -38390,26 +38610,45 @@ function TerminalScreen({ state, columns, rows = 28, colors = true, profile = "d
     help = "Enter sends. Ctrl+B step limit. Ctrl+N new conversation. Esc home.";
   }
   return /* @__PURE__ */ jsxs(Box, { flexDirection: "column", width, borderStyle: "double", paddingX: 1, children: [
-    /* @__PURE__ */ jsxs(Box, { justifyContent: "space-between", children: [
+    largeHome ? /* @__PURE__ */ jsxs(Fragment, { children: [
+      /* @__PURE__ */ jsxs(Box, { flexDirection: brand.sideBySide ? "row" : "column", gap: brand.sideBySide ? 3 : 1, children: [
+        /* @__PURE__ */ jsx(Wordmark, { color }),
+        /* @__PURE__ */ jsx(Mark, { lines: markFrame("large"), color })
+      ] }),
+      /* @__PURE__ */ jsxs(Text, { dimColor: true, wrap: "truncate-end", children: [
+        "by HigherOps / ",
+        clean(profile),
+        " / ",
+        clean(workspace),
+        " / ",
+        clean(space),
+        " / ",
+        clean(remaining),
+        " email verifications remaining"
+      ] })
+    ] }) : /* @__PURE__ */ jsxs(Box, { justifyContent: "space-between", children: [
       /* @__PURE__ */ jsxs(Box, { gap: 1, children: [
-        /* @__PURE__ */ jsx(Box, { flexDirection: "column", children: SMALL_MARK.map((line, i) => /* @__PURE__ */ jsx(Text, { color, children: line }, i)) }),
+        /* @__PURE__ */ jsx(Mark, { lines: markFrame("compact"), color }),
         /* @__PURE__ */ jsxs(Box, { flexDirection: "column", children: [
-          /* @__PURE__ */ jsx(Text, { bold: true, color, children: "HIGHERDATA" }),
+          /* @__PURE__ */ jsxs(Text, { bold: true, children: [
+            "Higher",
+            /* @__PURE__ */ jsx(Text, { color, children: "Data" })
+          ] }),
           /* @__PURE__ */ jsx(Text, { dimColor: true, children: "by HigherOps" }),
           /* @__PURE__ */ jsx(Text, { dimColor: true, children: clean(profile) })
         ] })
       ] }),
-      /* @__PURE__ */ jsxs(Box, { flexDirection: "column", alignItems: "flex-end", children: [
+      /* @__PURE__ */ jsxs(Box, { flexDirection: "column", alignItems: "flex-end", flexShrink: 1, children: [
         /* @__PURE__ */ jsx(Text, { wrap: "truncate-end", children: clean(workspace) }),
         /* @__PURE__ */ jsx(Text, { dimColor: true, wrap: "truncate-end", children: clean(space) }),
-        /* @__PURE__ */ jsxs(Text, { dimColor: true, children: [
+        /* @__PURE__ */ jsxs(Text, { dimColor: true, wrap: "truncate-end", children: [
           clean(remaining),
           " email verifications remaining"
         ] })
       ] })
     ] }),
     /* @__PURE__ */ jsx(Text, { dimColor: true, children: "\u2550".repeat(Math.max(1, width - 4)) }),
-    /* @__PURE__ */ jsx(Box, { flexDirection: "column", width: width - 4, minHeight: Math.min(rows - 7, 16), children: content }),
+    /* @__PURE__ */ jsx(Box, { flexDirection: "column", width: width - 4, minHeight: largeHome ? 0 : Math.max(0, Math.min(rows - 16, 13)), children: content }),
     state.error && /* @__PURE__ */ jsx(Text, { color: colors ? "red" : void 0, children: clean(state.error) }),
     state.notice && state.screen !== "busy" && /* @__PURE__ */ jsx(Text, { dimColor: true, children: clean(state.notice) }),
     /* @__PURE__ */ jsx(Text, { dimColor: true, wrap: "wrap", children: help })
@@ -38419,6 +38658,7 @@ var initialState, accountItems, homeItems;
 var init_screens = __esm({
   "src/terminal/screens.tsx"() {
     "use strict";
+    init_output();
     init_tool_commands();
     init_banner();
     init_install_menu();
@@ -38432,8 +38672,8 @@ var init_screens = __esm({
       { id: "skills-install", label: "Install skills", hint: "Five task guides for Claude Code or Codex" },
       { id: "quit", label: "Quit", hint: "" }
     ];
-    homeItems = [["Find", ["search", "searches", "lookup", "icp", "ask"]], ["Work", ["lists", "enrich", "email", "jobs"]], ["Govern", ["suppress", "crm", "changes", "hygiene"]], ["Account", ["account"]]].flatMap(([section, ids]) => ids.map((id, index) => {
-      const group = GROUPS.find(([name]) => name === id);
+    homeItems = [["Find", ["find", "search", "searches", "lookup", "icp", "ask"]], ["Work", ["lists", "enrich", "email", "jobs"]], ["Govern", ["suppress", "crm", "changes", "hygiene"]], ["Account", ["account"]]].flatMap(([section, ids]) => ids.map((id, index) => {
+      const group = id === "find" ? ["find", "Look up", "Name, email, phone, domain, LinkedIn or record id"] : GROUPS.find(([name]) => name === id);
       return { id, label: group?.[1] ?? "Ask HigherData", hint: group?.[2] ?? "Plan a request, limit its steps", section: index === 0 ? section : "" };
     }));
   }
@@ -38448,25 +38688,25 @@ __export(app_exports, {
 });
 import { randomUUID as randomUUID6 } from "crypto";
 import { createReadStream as createReadStream2 } from "fs";
-import { open as open6 } from "fs/promises";
-import { useEffect, useRef, useState } from "react";
+import { open as open7 } from "fs/promises";
+import { useEffect as useEffect2, useRef, useState as useState2 } from "react";
 import { render, useApp, useInput, useWindowSize } from "ink";
 import { jsx as jsx2 } from "react/jsx-runtime";
 function InteractiveApp({ session }) {
   const { exit } = useApp(), { columns, rows } = useWindowSize();
   const settings = session.settings();
-  const [chrome, setChrome] = useState({ workspace: "Workspace", remaining: "--" });
-  const [state, setState] = useState(() => ({ ...initialState(), screen: shouldAnimate(true, session.options, session.runtime.env) ? "banner" : "home" }));
+  const [chrome, setChrome] = useState2({ workspace: "Workspace", remaining: "--" });
+  const [state, setState] = useState2(() => ({ ...initialState(), screen: shouldAnimate(true, session.options, session.runtime.env) ? "banner" : "home" }));
   const current = useRef(state);
   current.current = state;
   const mounted = useRef(true), request = useRef(false), back = useRef(initialState());
-  useEffect(() => {
+  useEffect2(() => {
     mounted.current = true;
     return () => {
       mounted.current = false;
     };
   }, []);
-  useEffect(() => {
+  useEffect2(() => {
     let active = true;
     if (!settings.apiKey || !settings.space) return;
     void Promise.all([session.call("account.whoami", {}), session.call("account.usage", {})]).then(([identity, usage]) => {
@@ -38479,12 +38719,12 @@ function InteractiveApp({ session }) {
       active = false;
     };
   }, [session, settings.apiKey, settings.space]);
-  useEffect(() => {
+  useEffect2(() => {
     if (state.screen !== "banner") return;
     const timer = setInterval(() => setState((s) => s.frame >= BANNER_FRAMES - 1 ? { ...s, screen: "home" } : { ...s, frame: s.frame + 1 }), BANNER_DURATION_MS / BANNER_FRAMES);
     return () => clearInterval(timer);
   }, [state.screen]);
-  useEffect(() => {
+  useEffect2(() => {
     const job = state.result.job;
     const id = job?.id ?? (state.tool?.name === "jobs.get" ? state.result.id : void 0);
     const status = job?.status ?? state.result.status;
@@ -38542,6 +38782,7 @@ function InteractiveApp({ session }) {
   function activate(item) {
     const s = current.current;
     if (item.id === "quit") exit();
+    else if (item.id === "find") patch({ screen: "lookup", tool: toolByName("lookup.find"), input: {}, text: "", selected: 0 });
     else if (item.id === "mcp-install" || item.id === "skills-install") patch({ screen: "install", group: item.id === "mcp-install" ? "mcp" : "skills", tool: null, input: { agent: "claude", scope: "user", profile: "default" }, selected: 0 });
     else if (item.id === "space") {
       back.current = s;
@@ -38568,12 +38809,27 @@ function InteractiveApp({ session }) {
       return;
     }
     if (s.screen === "busy") return;
+    if (s.screen === "home" && input2 === "/") {
+      activate({ id: "find" });
+      return;
+    }
     if (key.escape && s.screen === "filter-group") {
       patch({ screen: "form", selected: searchGroups(s.tool.input, s.input).findIndex((group) => group.group === s.filterGroup) });
       return;
     }
     if (key.escape) {
-      patch(s.screen === "home" ? { screen: "home" } : ["edit", "download", "space", "upload"].includes(s.screen) ? { ...back.current } : { screen: s.screen === "detail" ? "results" : s.screen === "form" ? "tools" : "home", selected: 0 });
+      patch(s.screen === "home" ? { screen: "home" } : ["edit", "download", "download-choice", "space", "upload"].includes(s.screen) ? { ...back.current } : { screen: s.screen === "detail" ? "results" : s.screen === "form" ? "tools" : "home", selected: 0 });
+      return;
+    }
+    if (s.screen === "lookup") {
+      if (key.return && s.text.trim()) void work("Looking up your record...", () => session.lookup(s.text));
+      else if (key.backspace || key.delete) patch({ text: s.text.slice(0, -1) });
+      else if (!key.return && !key.ctrl && !key.meta && !key.upArrow && !key.downArrow) patch({ text: s.text + input2 });
+      return;
+    }
+    if (s.screen === "download-choice") {
+      if (key.upArrow || key.downArrow) patch({ selected: s.selected === 0 ? 1 : 0 });
+      else if (key.return) patch({ screen: "download", field: "New destination .csv or .jsonl file", text: "" });
       return;
     }
     if (["edit", "download", "space", "upload"].includes(s.screen)) {
@@ -38587,8 +38843,10 @@ function InteractiveApp({ session }) {
         }
         if (s.screen === "download") {
           void work("Downloading into a new file...", async () => {
-            await session.download(back.current, s.text);
-            return { ...back.current, notice: `Saved ${s.text}` };
+            const notice = await session.download(back.current, s.text, { all: isSearchResults(back.current.tool?.name) && s.selected === 1, progress: (text2) => {
+              if (mounted.current) patch({ notice: text2 });
+            } });
+            return { ...back.current, notice: `Saved ${s.text}${notice ? `. ${notice}` : ""}` };
           });
           return;
         }
@@ -38697,15 +38955,15 @@ function InteractiveApp({ session }) {
         patch({ input: { ...s.input, cursor: s.result.nextCursor } });
         void work("Loading the next page...", async () => ({ screen: "results", selected: 0, input: { ...s.input, cursor: s.result.nextCursor }, result: await session.call(s.tool.name, { ...s.input, cursor: s.result.nextCursor }) }));
       } else if (input2 === "r" && s.tool) runTool(!needsConfirmation(s.tool));
-      else if (input2 === "e") patch({ screen: s.tool ? "form" : "install", selected: 0 });
+      else if (input2 === "e") patch({ screen: s.tool?.name === "lookup.find" ? "lookup" : s.tool ? "form" : "install", text: s.tool?.name === "lookup.find" ? String(s.input.query ?? "") : s.text, selected: 0 });
       else if (input2 === "d") {
         back.current = s;
-        patch({ screen: "download", field: "New destination .csv or .jsonl file", text: "" });
+        patch({ screen: isSearchResults(s.tool?.name) ? "download-choice" : "download", selected: 0, field: "New destination .csv or .jsonl file", text: "" });
       } else if (input2 === "a" && s.tool?.name === "searches.list") {
         const row = rowsOf(s.result)[s.selected];
         if (row) form("lists.create", { type: "audience", savedSearchId: row.id, recurringEnabled: true, maxRecords: 1e3, maxNewRecordsPerRefresh: 1e3, removeNonmatches: false });
       } else if (input2 === "p" && s.tool?.name === "lists.get" && typeof s.input.id === "string") form("lists.refresh", { id: s.input.id, maxNewRecords: 1e3 });
-      else if (key.return) {
+      else if (key.return && (rowsOf(s.result).length || s.tool?.name !== "lookup.find")) {
         void work("Opening the record...", () => session.openRow(s));
       }
     } else if (s.screen === "detail") {
@@ -38735,6 +38993,7 @@ var TerminalSession;
 var init_app = __esm({
   "src/terminal/app.tsx"() {
     "use strict";
+    init_search_download2();
     init_tool_commands();
     init_api2();
     init_config();
@@ -38758,6 +39017,12 @@ var init_app = __esm({
       async load() {
         this.config = await this.runtime.readConfig();
       }
+      async lookup(query) {
+        const result = await this.call("lookup.find", { query });
+        const state = { ...initialState(), screen: "results", tool: toolByName("lookup.find"), input: { query }, result };
+        if (result.exactMatch === true && rowsOf(result).length === 1) return { ...state, ...await this.openRow(state) };
+        return state;
+      }
       settings() {
         return resolveSettings(this.config, this.options, this.runtime.env);
       }
@@ -38787,15 +39052,22 @@ var init_app = __esm({
         this.config.profiles[this.config.activeProfile] = { apiUrl: settings.apiUrl, apiKey: key };
         await this.runtime.writeConfig(this.config);
       }
-      async download(state, path2) {
+      async download(state, path2, options = {}) {
         if (!path2.trim()) throw new CliError("Enter a new destination file.");
         path2 = path2.trim();
         if (!/\.(csv|jsonl)$/.test(path2)) throw new CliError("Choose a new .csv or .jsonl destination.");
+        if (isSearchResults(state.tool?.name)) {
+          const input2 = { ...state.input };
+          const loadedPage = !options.all || !input2.cursor ? state.result : void 0;
+          if (options.all) delete input2.cursor;
+          const result = await downloadSearch(this.api(), state.tool.name, input2, path2, { ...options, loadedPage, sleep: this.runtime.sleep });
+          return result.capped ? SEARCH_DOWNLOAD_CAP_NOTICE : "";
+        }
         const job = state.result.job;
         const jobId = state.result.jobId ?? job?.id ?? (state.tool?.name.startsWith("jobs.") ? state.result.id ?? state.input.jobId : void 0);
         const exportTool = state.tool?.name === "lists.get" && state.input.id ? "lists.export" : state.tool?.name;
         if (typeof jobId !== "string" && !["lists.export", "suppress.export"].includes(exportTool ?? "")) throw new CliError("Open a completed job or a list export to download a file.");
-        const file2 = await open6(path2.trim(), "wx", 384);
+        const file2 = await open7(path2.trim(), "wx", 384);
         try {
           const format2 = path2.endsWith(".jsonl") ? "jsonl" : "csv";
           if (typeof jobId === "string") await downloadBulkJob(this.api(), jobId, format2, async (text2) => {
@@ -38935,11 +39207,12 @@ async function buildFilters(api, options, kind) {
 
 // src/commands.ts
 init_output();
+init_search_download2();
 
 // src/pagination.ts
 init_zod();
 init_api2();
-var pageSchema2 = external_exports.object({ items: external_exports.array(external_exports.record(external_exports.string(), external_exports.unknown())).max(50), nextCursor: external_exports.string().min(1).max(2048).nullable(), zeroResults: external_exports.boolean() });
+var pageSchema3 = external_exports.object({ items: external_exports.array(external_exports.record(external_exports.string(), external_exports.unknown())).max(50), nextCursor: external_exports.string().min(1).max(2048).nullable(), zeroResults: external_exports.boolean() });
 var exportSchema = external_exports.object({ content: external_exports.string(), mimeType: external_exports.enum(["text/csv", "application/x-ndjson"]), nextCursor: external_exports.string().min(1).max(2048).nullable(), zeroResults: external_exports.boolean() });
 async function pagedTool(api, name, input2, all, exporting = false) {
   if (all && api.settings.idempotencyKey) throw new CliError("An idempotency key applies to one page. Omit --all.");
@@ -38952,7 +39225,7 @@ async function pagedTool(api, name, input2, all, exporting = false) {
   let empty = true;
   while (true) {
     const raw = await api.tool(name, { ...input2, ...cursor === void 0 ? {} : { cursor } });
-    const page = (exporting ? exportSchema : pageSchema2).safeParse(raw);
+    const page = (exporting ? exportSchema : pageSchema3).safeParse(raw);
     if (!page.success) throw new CliError("The API returned an invalid cursor page.");
     if ("items" in page.data) records.push(...page.data.items);
     else {
@@ -39182,8 +39455,158 @@ function registerSuppressCommands(program2, helpers) {
 
 // src/commands.ts
 init_install();
+
+// src/update.ts
+init_zod();
+init_api2();
+init_version_policy();
+import { execFile as execFile3, spawn } from "child_process";
+import { realpath } from "fs/promises";
+import { isAbsolute, join as join4, sep } from "path";
+import { promisify as promisify2 } from "util";
+var NpmUpdateError = class extends Error {
+};
+function npmSummary(error63) {
+  const value = error63;
+  const lines = typeof value?.stderr === "string" ? value.stderr.split(/\r?\n/u) : [];
+  const line = lines.find((line2) => /^npm (?:error|ERR!) code [A-Z0-9_]+$/u.test(line2.trim())) ?? lines.find((line2) => /^npm (?:error|ERR!) (?:EACCES|EPERM|ENOENT|ETIMEDOUT)\b/u.test(line2.trim()));
+  return line?.trim().slice(0, 200) ?? (typeof value?.code === "string" && /^[A-Z0-9_]+$/u.test(value.code) ? value.code : "npm install failed");
+}
+function updateRuntime() {
+  return {
+    stdinTTY: Boolean(process.stdin.isTTY),
+    stdoutTTY: Boolean(process.stdout.isTTY),
+    script: process.argv[1] ?? "",
+    realpath,
+    async npm(args, env) {
+      try {
+        return (await promisify2(execFile3)("npm", args, { env, timeout: args[0] === "install" ? 12e4 : 1500, maxBuffer: 64 * 1024 })).stdout;
+      } catch (error63) {
+        throw new NpmUpdateError(npmSummary(error63));
+      }
+    },
+    rerun(script, args, env) {
+      return new Promise((resolve2, reject) => {
+        const child = spawn(process.execPath, [script, ...args], { env, stdio: "inherit" });
+        child.once("error", reject);
+        child.once("exit", (code, signal) => resolve2(code ?? (signal === "SIGINT" ? 130 : signal === "SIGTERM" ? 143 : 1)));
+      });
+    }
+  };
+}
+async function npmLatest(fetchImpl, timeoutMs = 3e3) {
+  try {
+    const response = await fetchImpl("https://registry.npmjs.org/higherdata/latest", { headers: { accept: "application/json" }, redirect: "error", signal: AbortSignal.timeout(timeoutMs) });
+    if (!response.ok || !response.body) {
+      await response.body?.cancel();
+      throw new Error();
+    }
+    const reader = response.body.getReader(), chunks = [];
+    let size = 0;
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        size += value.length;
+        if (size > 16384) {
+          await reader.cancel();
+          throw new Error();
+        }
+        chunks.push(value);
+      }
+    } finally {
+      reader.releaseLock();
+    }
+    return external_exports.object({ version: releaseVersion }).parse(JSON.parse(Buffer.concat(chunks).toString("utf8"))).version;
+  } catch {
+    throw new CliError("Could not check the npm release. Try higherdata update again.");
+  }
+}
+var installArgs = (version2) => ["install", "--global", `higherdata@${releaseVersion.parse(version2)}`];
+var manual = (version2) => `npm install --global higherdata@${releaseVersion.parse(version2)}`;
+async function updateCli(input2) {
+  const latest = await npmLatest(input2.fetchImpl);
+  if (compareVersions(input2.version, latest) >= 0) {
+    input2.out(`HigherData CLI ${input2.version} is up to date.
+`);
+    return;
+  }
+  try {
+    await input2.runtime.npm(installArgs(latest), input2.env);
+  } catch (error63) {
+    throw new CliError(`${error63 instanceof NpmUpdateError ? error63.message : "npm install failed"}. Run: ${manual(latest)}`);
+  }
+  input2.out(`Updated HigherData CLI ${input2.version} to ${latest}
+`);
+}
+function primaryCommand(args) {
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index];
+    if (["--api-url", "--idempotency-key"].includes(arg)) {
+      index++;
+      continue;
+    }
+    if (arg === "--") return args[index + 1];
+    if (!arg.startsWith("-")) return arg;
+  }
+}
+function interactiveUpdateAllowed(args, env, runtime) {
+  return runtime.stdinTTY && runtime.stdoutTTY && !Object.hasOwn(env, "CI") && !["mcp", "stdio"].includes(primaryCommand(args) ?? "") && !args.some((arg) => ["--json", "--jsonl", "--stdio", "--help", "-h", "--version", "-V"].includes(arg) || /^(--jsonl?|--stdio)=/u.test(arg));
+}
+async function possibleGlobalScript(runtime, env) {
+  try {
+    const script = await runtime.realpath(runtime.script);
+    if (script.split(sep).includes("_npx") || env.npm_command === "exec" || env.npm_lifecycle_event === "npx") return null;
+    return script.endsWith(`${sep}${join4("node_modules", "higherdata", "dist", "index.js")}`) ? script : null;
+  } catch {
+    return null;
+  }
+}
+async function globalScript(runtime, env, script) {
+  try {
+    const prefix = (await runtime.npm(["prefix", "-g"], env)).trim();
+    if (!isAbsolute(prefix)) return null;
+    const root = await runtime.realpath(prefix);
+    const expected = join4(root, process.platform === "win32" ? "node_modules" : "lib/node_modules", "higherdata", "dist/index.js");
+    return script === expected ? script : null;
+  } catch {
+    return null;
+  }
+}
+async function autoUpdate(input2) {
+  if (!interactiveUpdateAllowed(input2.args, input2.env, input2.runtime) || input2.env.HIGHERDATA_NO_AUTO_UPDATE === "1" || input2.env.HIGHERDATA_UPDATE_RERUN === "1" || ["update", "upgrade", "config"].includes(primaryCommand(input2.args) ?? "")) return null;
+  if ((await input2.readConfig()).autoUpdate === false) return null;
+  const candidate = await possibleGlobalScript(input2.runtime, input2.env);
+  if (!candidate) return null;
+  let latest = null;
+  try {
+    latest = await npmLatest(input2.fetchImpl, 1500);
+  } catch {
+    return null;
+  }
+  if (!latest || compareVersions(input2.version, latest) >= 0) return null;
+  const script = await globalScript(input2.runtime, input2.env, candidate);
+  if (!script) return null;
+  input2.warn(`Updating HigherData CLI to ${latest}...
+`);
+  try {
+    await input2.runtime.npm(installArgs(latest), input2.env);
+  } catch {
+    input2.warn(`Automatic update failed. Run: ${manual(latest)}
+`);
+    return null;
+  }
+  try {
+    return await input2.runtime.rerun(script, input2.args, { ...input2.env, HIGHERDATA_UPDATE_RERUN: "1" });
+  } catch {
+    input2.warn("Could not restart HigherData CLI. Run your command again.\n");
+    return 2;
+  }
+}
+
+// src/commands.ts
 function cliRuntime(overrides = {}) {
-  return { installation: installRuntime(), versionCache: fileVersionCache(), write: overrides.write ?? (overrides.out ? async (text2) => {
+  return { updater: updateRuntime(), installation: installRuntime(), versionCache: fileVersionCache(), write: overrides.write ?? (overrides.out ? async (text2) => {
     overrides.out(text2);
   } : (text2) => new Promise((resolve2, reject) => {
     process.stdout.write(text2, (error63) => error63 ? reject(error63) : resolve2());
@@ -39246,10 +39669,18 @@ function registerCommands(program2, runtime) {
     emit(identity, mode);
   });
   const search = program2.command("search").description("Search HigherData Core");
-  for (const kind of ["companies", "people"]) pageOptions(excludeList(addFilterOptions(search.command(kind).description(`Find ${kind}`), kind === "people"))).action(async (options, command) => {
+  for (const kind of ["companies", "people"]) pageOptions(excludeList(addFilterOptions(search.command(kind).description(`Find ${kind}`), kind === "people"))).option("--out <path>", "Download to a new .csv or .jsonl file (up to 5,000 rows with --all)").action(async (options, command) => {
     const { api, mode } = await session(command);
+    if (options.out) searchDownloadFormat(options.out);
     const filters = await buildFilters(api, options, kind);
-    emit(await pagedTool(api, `search.${kind}`, { ...filters, limit: options.limit, ...options.cursor ? { cursor: options.cursor } : {}, ...excluded(options) }, Boolean(options.all)), mode);
+    const input2 = { ...filters, limit: options.limit, ...options.cursor ? { cursor: options.cursor } : {}, ...excluded(options) };
+    if (options.out) {
+      const result = await downloadSearch(api, `search.${kind}`, input2, options.out, { all: Boolean(options.all), sleep: runtime.sleep, progress: (text2) => runtime.err(`${text2}
+`) });
+      if (result.capped) runtime.err(`${SEARCH_DOWNLOAD_CAP_NOTICE}
+`);
+      emit({ path: options.out, ...result }, mode);
+    } else emit(await pagedTool(api, `search.${kind}`, input2, Boolean(options.all)), mode);
   });
   addFilterOptions(program2.command("count").description("Estimate companies and their contacts")).action(async (options, command) => {
     const { api, mode } = await session(command);
@@ -39339,9 +39770,21 @@ function createProgram(overrides = {}) {
     } else program2.outputHelp();
   });
   program2.hook("preAction", async (_program, command) => {
-    if (command === program2 || command.name() === "login" || ["mcp", "skills"].includes(command.parent?.name() ?? "")) return;
+    if (["login", "update", "upgrade"].includes(command.name()) || ["mcp", "skills", "config"].includes(command.parent?.name() ?? "")) return;
+    if (command === program2 && (!runtime.updater.stdinTTY || !runtime.updater.stdoutTTY || Object.hasOwn(runtime.env, "CI") || program2.opts().json || program2.opts().jsonl)) return;
     const settings = resolveSettings(await runtime.readConfig(), command.optsWithGlobals(), runtime.env);
-    await checkCliVersion({ apiUrl: settings.apiUrl, version: package_default.version, cache: runtime.versionCache, fetchImpl: runtime.fetchImpl, now: runtime.now, warn: runtime.err });
+    const interactive = runtime.updater.stdinTTY && runtime.updater.stdoutTTY && !Object.hasOwn(runtime.env, "CI") && !command.optsWithGlobals().json && !command.optsWithGlobals().jsonl;
+    await checkCliVersion({ apiUrl: settings.apiUrl, version: package_default.version, cache: runtime.versionCache, fetchImpl: runtime.fetchImpl, now: runtime.now, warn: interactive ? runtime.err : () => {
+    } });
+  });
+  program2.command("update").alias("upgrade").description("Install the latest HigherData CLI release").action(() => updateCli({ version: package_default.version, fetchImpl: runtime.fetchImpl, runtime: runtime.updater, env: runtime.env, out: runtime.out }));
+  program2.command("config").description("Configure the CLI").command("set <key> <value>").action(async (key, value) => {
+    if (key !== "auto-update" || !["true", "false"].includes(value)) throw new CliError("Use higherdata config set auto-update true or false.");
+    const config2 = await runtime.readConfig();
+    config2.autoUpdate = value === "true";
+    await runtime.writeConfig(config2);
+    runtime.out(`Automatic updates ${config2.autoUpdate ? "enabled" : "disabled"}.
+`);
   });
   registerCommands(program2, runtime);
   registerToolCommands(program2, runtime);
@@ -39352,6 +39795,18 @@ async function runCli(args = process.argv.slice(2), overrides = {}) {
   const runtime = cliRuntime(overrides);
   const program2 = createProgram(runtime);
   try {
+    if (interactiveUpdateAllowed(args, runtime.env, runtime.updater)) {
+      const restarted = await autoUpdate({
+        args,
+        version: package_default.version,
+        env: runtime.env,
+        runtime: runtime.updater,
+        readConfig: runtime.readConfig,
+        fetchImpl: runtime.fetchImpl,
+        warn: runtime.err
+      });
+      if (restarted !== null) return restarted;
+    }
     await program2.parseAsync(args, { from: "user" });
     return EXIT_CODES.OK;
   } catch (error63) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "higherdata",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "type": "module",
   "bin": {
     "higherdata": "dist/index.js"