ethos-cli 0.7.6 → 0.7.7

package/dist/bin/ethos.js

@@ -7,6 +7,7 @@ import { registerAgents } from "../commands/agents.js";
 import { registerAuth } from "../commands/auth.js";
 import { registerCampaigns } from "../commands/campaigns.js";
 import { registerFlows } from "../commands/flows.js";
+import { registerFindPeople } from "../commands/find-people.js";
 import { registerGifting } from "../commands/gifting.js";
 import { registerHooks } from "../commands/hooks.js";
 import { registerLists } from "../commands/lists.js";
@@ -24,6 +25,7 @@ export function createEthosProgram() {
     registerAuth(program);
     registerAgents(program);
     registerCampaigns(program);
+    registerFindPeople(program);
     registerFlows(program);
     registerGifting(program);
     registerHooks(program);

package/dist/bin/ethos.js.map

@@ -1 +1 @@
-{"version":3,"file":"ethos.js","sourceRoot":"","sources":["../../src/bin/ethos.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,MAAM,GAAG,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,oBAAoB,CAAwB,CAAC;AAExF,MAAM,UAAU,kBAAkB;IAChC,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;IAE9B,gBAAgB,CACd,OAAO;SACJ,IAAI,CAAC,OAAO,CAAC;SACb,WAAW,CAAC,8CAA8C,CAAC;SAC3D,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CACxB,CAAC;IAEF,YAAY,CAAC,OAAO,CAAC,CAAC;IACtB,cAAc,CAAC,OAAO,CAAC,CAAC;IACxB,iBAAiB,CAAC,OAAO,CAAC,CAAC;IAC3B,aAAa,CAAC,OAAO,CAAC,CAAC;IACvB,eAAe,CAAC,OAAO,CAAC,CAAC;IACzB,aAAa,CAAC,OAAO,CAAC,CAAC;IACvB,aAAa,CAAC,OAAO,CAAC,CAAC;IACvB,cAAc,CAAC,OAAO,CAAC,CAAC;IACxB,cAAc,CAAC,OAAO,CAAC,CAAC;IACxB,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,IAAI,CAAC,OAAiB,OAAO,CAAC,IAAI;IACtD,MAAM,kBAAkB,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;AAC9C,CAAC;AAED,SAAS,kBAAkB;IACzB,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC9B,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IACzB,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,YAAY,CAAC,KAAK,CAAC,CAAC;IAC9E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,IAAI,kBAAkB,EAAE,EAAE,CAAC;IACzB,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;QACrB,UAAU,CAAC,KAAK,CAAC,CAAC;QAClB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"ethos.js","sourceRoot":"","sources":["../../src/bin/ethos.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,MAAM,GAAG,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,oBAAoB,CAAwB,CAAC;AAExF,MAAM,UAAU,kBAAkB;IAChC,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;IAE9B,gBAAgB,CACd,OAAO;SACJ,IAAI,CAAC,OAAO,CAAC;SACb,WAAW,CAAC,8CAA8C,CAAC;SAC3D,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CACxB,CAAC;IAEF,YAAY,CAAC,OAAO,CAAC,CAAC;IACtB,cAAc,CAAC,OAAO,CAAC,CAAC;IACxB,iBAAiB,CAAC,OAAO,CAAC,CAAC;IAC3B,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAC5B,aAAa,CAAC,OAAO,CAAC,CAAC;IACvB,eAAe,CAAC,OAAO,CAAC,CAAC;IACzB,aAAa,CAAC,OAAO,CAAC,CAAC;IACvB,aAAa,CAAC,OAAO,CAAC,CAAC;IACvB,cAAc,CAAC,OAAO,CAAC,CAAC;IACxB,cAAc,CAAC,OAAO,CAAC,CAAC;IACxB,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,IAAI,CAAC,OAAiB,OAAO,CAAC,IAAI;IACtD,MAAM,kBAAkB,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;AAC9C,CAAC;AAED,SAAS,kBAAkB;IACzB,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC9B,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IACzB,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,YAAY,CAAC,KAAK,CAAC,CAAC;IAC9E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,IAAI,kBAAkB,EAAE,EAAE,CAAC;IACzB,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;QACrB,UAAU,CAAC,KAAK,CAAC,CAAC;QAClB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/commands/find-people.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerFindPeople(program: Command): void;

package/dist/commands/find-people.js

@@ -0,0 +1,200 @@
+import { inferAppUrl } from "../lib/agent-clients.js";
+import { EthosApiError } from "../lib/client.js";
+import { compactObject, jsonRequest, parsePositiveInteger, pathId, withClient } from "../lib/command-helpers.js";
+import { openInBrowser } from "../lib/open-browser.js";
+import { printResult } from "../lib/output.js";
+const terminalStatuses = new Set([
+    "needs_refinement",
+    "succeeded",
+    "failed",
+    "canceled",
+]);
+const STATUS_REQUEST_TIMEOUT_MS = 15_000;
+export function registerFindPeople(program) {
+    const findPeople = program
+        .command("find-people")
+        .description("Find prospects from a natural-language company and person ICP search");
+    const startCommand = findPeople
+        .command("start")
+        .description("Parse a prospect search and start linked table creation in the background")
+        .requiredOption("--query <text>", "natural-language query with both company ICP and person criteria")
+        .option("--name <name>", "base name for the generated company and people tables")
+        .option("--max-profiles <count>", "maximum profiles allowed before refinement is required", "10000")
+        .option("--wait", "wait until the background search reaches a terminal state")
+        .option("--timeout <seconds>", "seconds to wait when --wait is set", "1800")
+        .option("--poll-interval <seconds>", "seconds between status checks when --wait is set", "3")
+        .option("--app-url <url>", "Ethos web app URL for table links")
+        .option("--open", "open the people table when the job succeeds");
+    startCommand.action(async () => {
+        await withClient(startCommand, async (client, config) => {
+            const options = startCommand.opts();
+            const maxProfiles = parsePositiveInteger(options.maxProfiles, "--max-profiles", 10_000);
+            let search;
+            try {
+                search = await client.request("/v1/prospect-searches", jsonRequest("POST", compactObject({
+                    query: options.query,
+                    name: options.name,
+                    max_profiles: maxProfiles,
+                })));
+            }
+            catch (error) {
+                if (emitRichProspectSearchError(config.json, error))
+                    return;
+                throw error;
+            }
+            if (options.wait) {
+                search = await waitForProspectSearch(client, search.id, options);
+            }
+            const data = prospectSearchCliResponse(search, config.apiUrl, options.appUrl);
+            printResult(config, {
+                label: prospectSearchLabel(data),
+                data,
+            });
+            if (options.open && data.status === "succeeded" && data.people_table_url) {
+                openInBrowser(data.people_table_url);
+            }
+        });
+    });
+    const getCommand = findPeople.command("get <search-id>").description("Fetch a prospect search job");
+    getCommand.option("--app-url <url>", "Ethos web app URL for table links");
+    getCommand.action(async (searchId) => {
+        await withClient(getCommand, async (client, config) => {
+            const options = getCommand.opts();
+            const search = await client.request(`/v1/prospect-searches/${pathId(searchId)}`);
+            const data = prospectSearchCliResponse(search, config.apiUrl, options.appUrl);
+            printResult(config, {
+                label: prospectSearchLabel(data),
+                data,
+            });
+        });
+    });
+    const waitCommand = findPeople
+        .command("wait <search-id>")
+        .description("Poll a prospect search until it succeeds, needs refinement, fails, or is canceled")
+        .option("--timeout <seconds>", "seconds to wait for completion", "1800")
+        .option("--poll-interval <seconds>", "seconds between status checks", "3")
+        .option("--app-url <url>", "Ethos web app URL for table links")
+        .option("--open", "open the people table when the job succeeds");
+    waitCommand.action(async (searchId) => {
+        await withClient(waitCommand, async (client, config) => {
+            const options = waitCommand.opts();
+            const search = await waitForProspectSearch(client, searchId, options);
+            const data = prospectSearchCliResponse(search, config.apiUrl, options.appUrl);
+            printResult(config, {
+                label: prospectSearchLabel(data),
+                data,
+            });
+            if (options.open && data.status === "succeeded" && data.people_table_url) {
+                openInBrowser(data.people_table_url);
+            }
+        });
+    });
+    const interruptCommand = findPeople
+        .command("interrupt <search-id>")
+        .description("Cancel a queued or running prospect search job");
+    interruptCommand.option("--app-url <url>", "Ethos web app URL for table links");
+    interruptCommand.action(async (searchId) => {
+        await withClient(interruptCommand, async (client, config) => {
+            const options = interruptCommand.opts();
+            const search = await client.request(`/v1/prospect-searches/${pathId(searchId)}/interrupt`, {
+                method: "POST",
+            });
+            const data = prospectSearchCliResponse(search, config.apiUrl, options.appUrl);
+            printResult(config, {
+                label: prospectSearchLabel(data),
+                data,
+            });
+        });
+    });
+}
+async function waitForProspectSearch(client, searchId, options) {
+    const timeoutSeconds = parseWaitSeconds(options.timeout, "--timeout", 7200);
+    const pollIntervalMs = parseWaitSeconds(options.pollInterval, "--poll-interval", 300) * 1000;
+    const deadline = Date.now() + timeoutSeconds * 1000;
+    let lastSearch;
+    for (;;) {
+        let search;
+        try {
+            const requestTimeoutMs = Math.min(STATUS_REQUEST_TIMEOUT_MS, Math.max(1000, deadline - Date.now()));
+            search = await fetchProspectSearchStatus(client, searchId, requestTimeoutMs);
+            lastSearch = search;
+        }
+        catch (error) {
+            if (!isAbortError(error))
+                throw error;
+        }
+        if (search && terminalStatuses.has(search.status))
+            return search;
+        if (Date.now() >= deadline) {
+            const lastStatus = lastSearch
+                ? ` Last status: ${lastSearch.status}${lastSearch.progressMessage ? ` (${lastSearch.progressMessage})` : ""}.`
+                : "";
+            throw new Error(`Timed out after ${timeoutSeconds}s waiting for prospect search ${searchId}.${lastStatus} ` +
+                `Run \`ethos find-people get ${searchId}\` for current status, ` +
+                `\`ethos find-people wait ${searchId}\` to keep polling, or ` +
+                `\`ethos find-people interrupt ${searchId}\` to cancel.`);
+        }
+        await new Promise((resolve) => {
+            setTimeout(resolve, pollIntervalMs);
+        });
+    }
+}
+async function fetchProspectSearchStatus(client, searchId, requestTimeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), requestTimeoutMs);
+    try {
+        return await client.request(`/v1/prospect-searches/${pathId(searchId)}`, {
+            signal: controller.signal,
+        });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function prospectSearchCliResponse(search, apiUrl, appUrlOverride) {
+    const appUrl = (appUrlOverride || inferAppUrl(apiUrl)).replace(/\/+$/, "");
+    return {
+        ...search,
+        search_id: search.id,
+        people_table_id: search.peopleTableId,
+        company_table_id: search.companyTableId,
+        people_table_url: search.peopleTableId ? `${appUrl}/tables/${search.peopleTableId}` : null,
+        company_table_url: search.companyTableId ? `${appUrl}/tables/${search.companyTableId}` : null,
+    };
+}
+function prospectSearchLabel(search) {
+    if (search.status === "succeeded") {
+        return `Prospect search ${search.id} succeeded; people table ${search.people_table_id}`;
+    }
+    if (search.status === "needs_refinement") {
+        return `Prospect search ${search.id} needs refinement (${search.profileCount ?? "unknown"} profiles)`;
+    }
+    return `Prospect search ${search.id} is ${search.status}`;
+}
+function emitRichProspectSearchError(json, error) {
+    if (!(error instanceof EthosApiError) || error.status !== 400 || !isRecord(error.body))
+        return false;
+    if (!("parsedParams" in error.body) && !("suggestedAction" in error.body))
+        return false;
+    if (json) {
+        process.stdout.write(`${JSON.stringify({ success: false, error: error.body }, null, 2)}\n`);
+        return true;
+    }
+    const message = typeof error.body.message === "string" ? error.body.message : error.message;
+    process.stderr.write(`${message}\n${JSON.stringify(error.body, null, 2)}\n`);
+    return true;
+}
+function isRecord(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function isAbortError(error) {
+    return Boolean(error && typeof error === "object" && "name" in error && error.name === "AbortError");
+}
+function parseWaitSeconds(value, name, max) {
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed < 1) {
+        throw new Error(`${name} must be a positive number of seconds.`);
+    }
+    return Math.min(parsed, max);
+}
+//# sourceMappingURL=find-people.js.map

package/dist/commands/find-people.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-people.js","sourceRoot":"","sources":["../../src/commands/find-people.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ethos-cli",
-  "version": "0.7.6",
+  "version": "0.7.7",
   "description": "Commander-based CLI for Ethos table operations",
   "homepage": "https://github.com/cluster-software/ethos#readme",
   "repository": {

package/skills/find-people.md

@@ -0,0 +1,176 @@
+---
+name: find-people
+description: Find relevant prospects in one shot from a natural-language ICP by using Ethos prospect search to parse company and person criteria, create linked company and people tables in the background, poll for completion, open the resulting people table, and refine or interrupt searches. Use when the user wants to find prospects, buyers, founders, leaders, contacts, or people matching an ICP without starting from an existing company CSV.
+---
+
+# find-people
+
+Use this when the user wants Ethos to find prospects from scratch. This skill
+does not require a CSV upload. The production CLI default is
+`https://api.ethos.hello-cluster.com`, so only pass `--api-url` for local
+development or an explicitly requested environment.
+
+## Required CLI
+
+The Ethos CLI (`ethos`) is required. If `ethos` is not installed or not on
+`PATH`, install the latest CLI and retry:
+
+```sh
+npm install -g ethos-cli@latest --prefer-online
+```
+
+If a CLI command fails because the CLI is not authenticated, run:
+
+```sh
+ethos auth login --agent-client auto
+```
+
+then retry the failed command. Do not ask for API tokens unless the user
+explicitly wants a non-browser setup.
+
+## Query Shape
+
+Create one natural-language query that clearly includes both:
+
+- Target companies: industry, geography, size, business model, technology,
+  funding/stage, or other ICP constraints.
+- Target people: titles, functions, seniority, job status, and exclusions.
+
+Good query:
+
+```text
+Find VP Sales, Head of Revenue, and RevOps leaders at US B2B SaaS companies with 50-500 employees that sell to enterprise finance teams. Exclude agencies and consultants.
+```
+
+Weak query:
+
+```text
+Find sales people.
+```
+
+If the user's request is underspecified, ask up to 3 concise followups before
+starting the search. Prioritize missing dimensions in this order:
+
+1. Who the target people are: titles, functions, seniority.
+2. Which companies qualify: industry, product category, size, stage, business
+   model, or technologies.
+3. Geography or other hard exclusions.
+
+Use an AskUserQuestion tool when available. If not, ask directly in chat. If the
+user wants speed, make reasonable assumptions and include them in the query.
+
+## Start Search
+
+Run:
+
+```sh
+ethos find-people start --query "$QUERY" --json
+```
+
+Save `response.search_id`, `response.parsedParams`, `response.status`, and
+`response.progressMessage`.
+
+If the command returns `success: false`, inspect `error.suggestedAction` and
+`error.parsedParams`. When `suggestedAction` is not `combinedSearch`, tell the
+user the parser understood only company criteria or only person criteria, then
+rewrite the query so it includes both target companies and target individuals.
+
+After a successful start, summarize the parsed params in plain language. Do not
+paste the full JSON unless the user asks for it.
+
+## How To Communicate With The User
+
+When a search starts successfully, do not talk about the parser or implementation
+details. Say the search was queued, then describe the criteria in a short,
+easy-to-scan list:
+
+```text
+Ok, I queued up a search with these criteria:
+- People: CFOs, VP Finance, Heads of Finance, Treasurers, and senior project finance leaders.
+- Companies: infrastructure developers and operators in data centers, energy, toll roads, and bridges.
+- Signals: project finance, capital raises, debt/equity funding, and active development projects.
+- Exclusions: banks, funds, consultants, law firms, and EPC-only contractors.
+```
+
+If the CLI response includes `unsupportedFilters`, mention them after the
+criteria as caveats. Explain whether the search used proxy keywords/signals
+instead of a native filter, but keep it short.
+
+Always invite adjustment before or while polling:
+
+```text
+If any of that looks off, tell me what to change and I can interrupt or refine
+the search. I’ll poll this one now and send the table link when it’s ready.
+```
+
+When the search succeeds, lead with the result count and table link. If
+`progressMessage` says the table contains only part of the matching set, tell
+the user directly, e.g. "I created a table with the first 1,000 of 5,000
+matching profiles." Include the company table link only if useful or if the user
+asks. Keep parsed params at the plain-English level unless the user asks for raw
+JSON.
+
+## Poll
+
+Poll the background table-creation job with status checks that return
+immediately:
+
+```sh
+ethos find-people get "$SEARCH_ID" --json
+```
+
+Use `response.status`, `response.progressMessage`, `response.companyCount`,
+`response.profileCount`, `response.people_table_url`, and
+`response.company_table_url` to understand and explain what is happening. For
+interactive agent work, prefer repeated `get` calls every 10-20 seconds over a
+long-running `wait` command: `wait --json` is silent until the job reaches a
+terminal state, which makes the agent blind while the job is running.
+
+The job reaches one of these terminal statuses:
+
+- `succeeded`: linked company and people tables were created. Open
+  `response.people_table_url` for the user. For valid searches with more than
+  1,000 and up to 10,000 matching profiles, Ethos materializes the first 1,000
+  profiles instead of paginating the full result set.
+- `needs_refinement`: more than 10,000 matching profiles were found. Use
+  `response.refinementSuggestions` and the parsed params to suggest narrower
+  criteria, then ask the user how to refine.
+- `failed`: explain `response.error.message` and retry only after changing the
+  query or environment issue.
+- `canceled`: the search was interrupted.
+
+While the job is `queued` or `running`, report the latest `progressMessage` when
+it adds useful information. Do not infer or guess phases from a silent command;
+if you need status, run `get` again. Do not start a duplicate search unless the
+user changed the criteria.
+
+For non-interactive shell usage, `ethos find-people wait "$SEARCH_ID" --json`
+is still available, but it should not be the default for agent polling.
+
+## Interrupt And Refine
+
+If the user changes the search while a job is queued or running, interrupt the
+old job before starting the new one:
+
+```sh
+ethos find-people interrupt "$SEARCH_ID" --json
+```
+
+Then build a revised query and run `ethos find-people start --query "$QUERY"
+--json` again.
+
+Fast refinements that can be handled in the table UI include person title,
+seniority, job function, country, company, and company domain. Refinements that
+depend on provider-side filters, such as company size, funding stage,
+technologies, or broad industry expansion, should start a new search.
+
+## Open Result
+
+When the search succeeds, open the people table URL from the CLI response:
+
+- In Codex, use the in-app Browser when available.
+- In shell clients, `ethos find-people wait "$SEARCH_ID" --open --json` can open
+  the table in the default browser.
+
+The company table is linked to the people table and available at
+`response.company_table_url`.