@dench.com/cli 2.8.2-staging.112 → 2.8.3

package/leads.ts

@@ -19,6 +19,7 @@ import {
   searchJobs,
   searchPeople,
 } from "./lib/enrichment-gateway";
+import { FIND_FILTER_OPTION_CATALOG } from "./lib/find-filter-options.generated";
 
 class FindCliError extends Error {
   constructor(message: string) {
@@ -39,13 +40,34 @@ const api = {
   saveFind: makeFunctionReference<"action">(
     "functions/workspaceArtifacts:saveFind",
   ),
+  updateFind: makeFunctionReference<"action">(
+    "functions/workspaceArtifacts:updateFind",
+  ),
+  rename: makeFunctionReference<"mutation">(
+    "functions/workspaceArtifacts:rename",
+  ),
+  remove: makeFunctionReference<"mutation">(
+    "functions/workspaceArtifacts:remove",
+  ),
   list: makeFunctionReference<"query">("functions/workspaceArtifacts:list"),
   get: makeFunctionReference<"query">("functions/workspaceArtifacts:get"),
   importArtifact: makeFunctionReference<"action">(
     "functions/workspaceArtifacts:importArtifact",
   ),
+  resolveCompanyList: makeFunctionReference<"action">(
+    "functions/companyLists:resolveCompanyList",
+  ),
 };
 
+/** createdFrom values that mark an artifact as a saved search / list. */
+const LIST_CREATED_FROM = new Set([
+  "find_people",
+  "find_companies",
+  "find_jobs",
+  "mixed",
+  "watch_fire",
+]);
+
 function shift(args: string[], expected: string): string {
   try {
     return shiftRaw(args, expected);
@@ -64,50 +86,103 @@ function assertNoUnknownFlags(args: readonly string[], command: string): void {
   }
 }
 
-function parseLeadsFindFlags(args: string[]): {
+type LeadsFindRange = { min?: number; max?: number };
+
+type LeadsFindFlags = {
   titles?: string[];
+  pastTitles?: string[];
+  personNames?: string[];
   locations?: string[];
   seniorities?: string[];
   industries?: string[];
   functions?: string[];
+  subFunctions?: string[];
   companyDomain?: string;
+  companyDomains?: string[];
+  companyNames?: string[];
+  pastCompanyNames?: string[];
+  companyHeadquarters?: string[];
+  companyTypes?: string[];
+  universities?: string[];
+  skills?: string[];
+  languages?: string[];
+  headcount?: string[];
+  yearsInRole?: LeadsFindRange;
+  yearsAtCompany?: LeadsFindRange;
+  daysSinceJobChange?: LeadsFindRange;
+  foundedYears?: LeadsFindRange;
   keywords?: string;
+  companyList?: string;
   limit?: number;
   pageToken?: string;
-} {
-  const titles = csvFlag(args, "--titles");
-  const locations = csvFlag(args, "--locations");
-  const seniorities = csvFlag(args, "--seniorities");
-  const industries = csvFlag(args, "--industries");
-  const functions = csvFlag(args, "--functions");
-  const companyDomain = getFlag(args, "--company-domain");
-  const keywords = getFlag(args, "--keywords");
-  const limit = parseLimit(args);
-  const pageToken = getFlag(args, "--page-token");
+  name?: string;
+};
+
+/** Parse `min:max` (either side optional; a bare number means min). */
+function rangeFlag(args: string[], name: string): LeadsFindRange | undefined {
+  const raw = getFlag(args, name);
+  if (!raw) return undefined;
+  const [minRaw, maxRaw] = raw.includes(":") ? raw.split(":", 2) : [raw, ""];
+  const parsePart = (part: string, label: string): number | undefined => {
+    const trimmed = part.trim();
+    if (!trimmed) return undefined;
+    const parsed = Number(trimmed);
+    if (!Number.isInteger(parsed) || parsed < 0) {
+      throw new FindCliError(
+        `${name} ${label} must be a non-negative integer (use min:max, e.g. 2:10)`,
+      );
+    }
+    return parsed;
+  };
+  const min = parsePart(minRaw ?? "", "min");
+  const max = parsePart(maxRaw ?? "", "max");
+  if (min === undefined && max === undefined) {
+    throw new FindCliError(`${name} must be min:max, e.g. 2:10, 2: or :10`);
+  }
+  return { min, max };
+}
+
+function parseLeadsFindFlags(args: string[]): LeadsFindFlags {
+  const flags: LeadsFindFlags = {
+    titles: csvFlag(args, "--titles"),
+    pastTitles: csvFlag(args, "--past-titles"),
+    personNames: csvFlag(args, "--person-names"),
+    locations: csvFlag(args, "--locations"),
+    seniorities: csvFlag(args, "--seniorities"),
+    industries: csvFlag(args, "--industries"),
+    functions: csvFlag(args, "--functions"),
+    subFunctions: csvFlag(args, "--sub-functions"),
+    companyDomain: getFlag(args, "--company-domain"),
+    companyDomains: csvFlag(args, "--company-domains"),
+    companyNames: csvFlag(args, "--company-names"),
+    pastCompanyNames: csvFlag(args, "--past-company-names"),
+    companyHeadquarters: csvFlag(args, "--company-hq"),
+    companyTypes: csvFlag(args, "--company-types"),
+    universities: csvFlag(args, "--universities"),
+    skills: csvFlag(args, "--skills"),
+    languages: csvFlag(args, "--languages"),
+    headcount: csvFlag(args, "--headcount"),
+    yearsInRole: rangeFlag(args, "--years-in-role"),
+    yearsAtCompany: rangeFlag(args, "--years-at-company"),
+    daysSinceJobChange: rangeFlag(args, "--days-since-job-change"),
+    foundedYears: rangeFlag(args, "--founded-years"),
+    keywords: getFlag(args, "--keywords"),
+    companyList: getFlag(args, "--company-list"),
+    limit: parseLimit(args),
+    pageToken: getFlag(args, "--page-token"),
+    name: getFlag(args, "--save-as"),
+  };
   assertNoUnknownFlags(args, "leads find");
-  if (
-    !titles &&
-    !locations &&
-    !companyDomain &&
-    !keywords &&
-    !industries &&
-    !seniorities
-  ) {
+  const hasFilter = Object.entries(flags).some(
+    ([key, value]) =>
+      !["limit", "pageToken", "name"].includes(key) && value !== undefined,
+  );
+  if (!hasFilter) {
     throw new FindCliError(
-      "dench leads find requires at least one of --titles, --locations, --company-domain, --keywords, --industries, --seniorities",
+      "dench leads find requires at least one of --titles, --locations, --company-domain, --keywords, --industries, --seniorities (or any other filter flag — run `dench leads help`)",
     );
   }
-  return {
-    titles,
-    locations,
-    seniorities,
-    industries,
-    functions,
-    companyDomain,
-    keywords,
-    limit,
-    pageToken,
-  };
+  return flags;
 }
 
 export function assertLeadsFindArgs(args: string[]): void {
@@ -167,6 +242,85 @@ function asArray(value: unknown): unknown[] {
   return Array.isArray(value) ? value : [];
 }
 
+/* ─── Company-list filter (--company-list) ─── */
+
+type ResolvedCompanyList = {
+  source: "artifact" | "view";
+  title: string;
+  domains: string[];
+  names: string[];
+  totalCompanies: number;
+  truncated: boolean;
+};
+
+/** Convex document ids are long lowercase alphanumeric strings. */
+const COMPANY_LIST_ID_RE = /^[a-z0-9]{25,40}$/;
+
+/**
+ * `--company-list` accepts a saved-search artifact id (from
+ * `dench companies find` / `dench lists`) or a Company saved-view name.
+ * Id-shaped values are tried as artifacts first; anything else (or an
+ * id that doesn't resolve) is looked up as a view name.
+ */
+async function resolveCompanyListFlag(
+  ctx: FindCliContext,
+  value: string,
+): Promise<ResolvedCompanyList> {
+  const trimmed = value.trim();
+  if (!trimmed) {
+    throw new FindCliError(
+      "--company-list requires a list artifact id or a Company view name",
+    );
+  }
+  if (COMPANY_LIST_ID_RE.test(trimmed)) {
+    try {
+      return (await callAction(ctx, api.resolveCompanyList, {
+        artifactId: trimmed,
+      })) as ResolvedCompanyList;
+    } catch {
+      // Not an artifact (or not ours) — fall through to view-name lookup.
+    }
+  }
+  try {
+    return (await callAction(ctx, api.resolveCompanyList, {
+      viewName: trimmed,
+    })) as ResolvedCompanyList;
+  } catch (error) {
+    throw new FindCliError(
+      error instanceof Error ? error.message : String(error),
+    );
+  }
+}
+
+/** Saved-filter entry: the reference (re-resolved on hydrate) + title. */
+function companyListFilterEntry(
+  ref: string,
+  resolved: ResolvedCompanyList,
+): Record<string, unknown> {
+  return resolved.source === "artifact"
+    ? { artifactId: ref.trim(), title: resolved.title }
+    : { viewName: ref.trim(), title: resolved.title };
+}
+
+/** Output block mirroring /api/workspace/find's `companyList` response. */
+function companyListInfo(resolved: ResolvedCompanyList) {
+  return {
+    source: resolved.source,
+    title: resolved.title,
+    companiesUsed: resolved.domains.length + resolved.names.length,
+    totalCompanies: resolved.totalCompanies,
+    truncated: resolved.truncated,
+  };
+}
+
+function mergeUnique(
+  base: string[] | undefined,
+  extra: string[] | undefined,
+): string[] | undefined {
+  const merged = [...new Set([...(base ?? []), ...(extra ?? [])])];
+  return merged.length > 0 ? merged : undefined;
+}
+
 function findTitle(
   kind: "people" | "companies" | "jobs",
   parts: string[],
@@ -197,22 +351,119 @@ export function leadsHelp(): void {
   console.log(`Dench leads
 
 Usage:
-  dench leads find --titles "VP Sales" --locations "San Francisco" [--company-domain acme.com] [--limit 500] [--page-token <token>] [--json]
+  dench leads find --titles "VP Sales" --locations "San Francisco" [--company-domain acme.com] [--save-as "Q3 targets"] [--limit 500] [--page-token <token>] [--json]
   dench leads find --keywords "fintech" [--industries SaaS] [--seniorities director,vp] [--json]
+  dench leads find --company-list <artifactId|"Company view name"> --titles "VP Sales" [--json]
+  dench leads filters [--filter titles|locations|company-hq|universities|skills|keywords|seniorities|functions|sub-functions|industries|headcount|company-types|languages] [--search "query"] [--json]
+
+Filter flags (all comma-separated lists unless noted):
+  People:   --titles --past-titles --person-names --seniorities --functions
+            --sub-functions --languages --universities --skills --locations
+  Company:  --company-names --past-company-names --company-domain (single)
+            --company-domains --company-hq --company-types --industries
+            --headcount (buckets like 11-50,51-200)
+  List:     --company-list <artifactId|view name> — filter by a saved
+            company list (a \`dench companies find\` artifact or a Company
+            saved view). Resolves to the list's CURRENT companies on each
+            run; lists up to ~1000 companies are searched in one go.
+  Ranges:   --years-in-role --years-at-company --days-since-job-change
+            --founded-years   (min:max, e.g. 2:10, 2: or :10)
+  Query:    --keywords "fintech, AI"
 
-Finds people through Dench search and writes a workspace artifact.
-Import with \`dench artifacts import <id> --to lead\`.
+\`dench leads filters\` prints the accepted values: enum filters (seniorities,
+functions, industries, headcount, company-types, languages) expect those
+exact values; the rest are free text with curated suggestions.
+
+Finds people through Dench search and writes a workspace list artifact.
+Pass --save-as to name the list (otherwise a title is generated).
+Manage lists with \`dench lists\`; import with \`dench artifacts import <id> --to lead\`.
+Typical chain: dench companies find … --json → grab artifactId →
+dench leads find --company-list <artifactId> --titles "VP Sales".
 `);
 }
 
+/* ─── dench leads filters ─── */
+
+/** kebab-case flag spellings accepted by `--filter` alongside catalog keys. */
+const FILTER_KEY_ALIASES: Record<string, string> = {
+  "past-titles": "pastTitles",
+  "company-hq": "companyHeadquarters",
+  "company-types": "companyTypes",
+  "sub-functions": "subFunctions",
+};
+
+/**
+ * Print the Lead Finder filter-option catalogs (offline; bundled data).
+ * Enum filters list exact gateway vocabularies; suggestion filters list
+ * curated starting points — custom free text always works for those.
+ */
+export function runFindFiltersCommand(opts: {
+  args: string[];
+  jsonOutput?: boolean;
+}): void {
+  const args = [...opts.args];
+  const jsonOutput = opts.jsonOutput === true || hasFlag(args, "--json");
+  const filterRaw = getFlag(args, "--filter");
+  const search = getFlag(args, "--search")?.trim().toLowerCase();
+  assertNoUnknownFlags(args, "leads filters");
+
+  const resolveKey = (raw: string): string => {
+    const aliased = FILTER_KEY_ALIASES[raw.toLowerCase()];
+    if (aliased) return aliased;
+    const match = Object.keys(FIND_FILTER_OPTION_CATALOG).find(
+      (key) => key.toLowerCase() === raw.toLowerCase(),
+    );
+    if (match) return match;
+    throw new FindCliError(
+      `Unknown filter: ${raw}. Valid filters: ${[
+        ...Object.keys(FIND_FILTER_OPTION_CATALOG),
+        ...Object.keys(FILTER_KEY_ALIASES),
+      ].join(", ")}`,
+    );
+  };
+
+  const keys = filterRaw
+    ? [resolveKey(filterRaw)]
+    : Object.keys(FIND_FILTER_OPTION_CATALOG);
+  const filters: Record<string, unknown> = {};
+  for (const key of keys) {
+    const entry = FIND_FILTER_OPTION_CATALOG[key];
+    const groups = search
+      ? entry.groups
+          .map((group) => ({
+            group: group.group,
+            values: group.values.filter((value) =>
+              value.toLowerCase().includes(search),
+            ),
+          }))
+          .filter((group) => group.values.length > 0)
+      : entry.groups;
+    filters[key] = { label: entry.label, kind: entry.kind, groups };
+  }
+  console.log(
+    JSON.stringify(
+      {
+        note: "kind=enum values are exact gateway vocabularies; kind=suggestion values are curated starting points and custom free text is accepted.",
+        filters,
+      },
+      null,
+      jsonOutput ? 2 : 0,
+    ),
+  );
+}
+
 export function companiesHelp(): void {
   console.log(`Dench companies
 
 Usage:
-  dench companies find --name "Acme" [--domain acme.com] [--keywords fintech] [--industries SaaS] [--locations "San Francisco"] [--linkedin https://linkedin.com/company/acme] [--limit 500] [--page-token <token>] [--json]
+  dench companies find --name "Acme" [--domain acme.com] [--keywords fintech] [--industries SaaS] [--locations "San Francisco"] [--linkedin https://linkedin.com/company/acme] [--save-as "Target accounts"] [--limit 500] [--page-token <token>] [--json]
 
-Finds companies through Dench search and writes a workspace artifact.
-Import with \`dench artifacts import <id> --to lead\`.
+Finds companies through Dench search and writes a workspace list artifact.
+Pass --save-as to name the list (otherwise a title is generated).
+Manage lists with \`dench lists\`; import with \`dench artifacts import <id> --to company\`.
+The artifact id doubles as a company list: pass it to
+\`dench leads find --company-list <id>\` or \`dench jobs find --company-list <id>\`
+to search people or job postings at exactly these companies.
 `);
 }
 
@@ -220,10 +471,17 @@ export function jobsHelp(): void {
   console.log(`Dench jobs
 
 Usage:
-  dench jobs find --titles "Account Executive" --locations "San Francisco" [--company-domain acme.com] [--keywords remote] [--limit 500] [--page-token <token>] [--json]
+  dench jobs find --titles "Account Executive" --locations "San Francisco" [--company-domain acme.com] [--keywords remote] [--save-as "AE openings"] [--limit 500] [--page-token <token>] [--json]
+  dench jobs find --company-list <artifactId|"Company view name"> [--titles "Account Executive"] [--posted-after 2026-08-01] [--json]
 
-Finds job postings through Dench search and writes a workspace artifact.
-Import with \`dench artifacts import <id> --to job_posting\`.
+Company filters: --company (name), --company-domain (single),
+--company-domains (comma-separated), or --company-list (a saved company
+list: a \`dench companies find\` artifact id or a Company saved-view name —
+resolved to its current companies on each run).
+
+Finds job postings through Dench search and writes a workspace list artifact.
+Pass --save-as to name the list (otherwise a title is generated).
+Manage lists with \`dench lists\`; import with \`dench artifacts import <id> --to job_posting\`.
 `);
 }
 
@@ -238,9 +496,138 @@ Usage:
 
 \`list\` / \`show\` / \`import\` operate on find results (lead lists and job
 searches). Bare \`dench artifacts\` still lists agent suggested-work artifacts.
+Rename/delete saved searches with \`dench lists rename|delete\`.
 `);
 }
 
+export function listsHelp(): void {
+  console.log(`Dench lists
+
+Usage:
+  dench lists [--limit 25] [--json]
+  dench lists show <id> [--json]
+  dench lists rename <id> "New name" [--json]
+  dench lists update <id> [--title "New name"] [--filters-json '{"titles":["CTO"]}'] [--json]
+  dench lists delete <id> [--json]
+
+Lists are saved searches from Find (people / companies / job postings).
+Create one with \`dench leads|companies|jobs find --save-as "Name"\`.
+Delete removes the list, its exported CSV/JSONL files, and any linked watch.
+CRM lists (saved views on Leads/Companies/Job Postings) are managed with
+\`dench crm views list|get|create|rename|delete\`.
+`);
+}
+
+/**
+ * `dench lists …` — full management of saved searches. Returns false
+ * only for `help` so the caller can print usage.
+ */
+export async function runListsCommand(opts: {
+  convex: ConvexHttpClient;
+  args: string[];
+  jsonOutput?: boolean;
+  sessionToken?: string;
+}): Promise<boolean> {
+  const args = [...opts.args];
+  const ctx: FindCliContext = {
+    convex: opts.convex,
+    args,
+    jsonOutput: opts.jsonOutput === true || hasFlag(args, "--json"),
+    sessionToken: opts.sessionToken,
+  };
+  const verb = args[0];
+  if (verb === "help" || verb === "--help") return false;
+  if (verb === undefined || verb === "list" || verb?.startsWith("--")) {
+    if (verb === "list") args.shift();
+    const limitRaw = getFlag(args, "--limit");
+    const limit = limitRaw ? Number(limitRaw) : 25;
+    assertNoUnknownFlags(args, "lists");
+    const rows = (await callQuery(ctx, api.list, {
+      kind: "table",
+      // Over-fetch: the query filters by kind only; saved searches are
+      // the table artifacts whose createdFrom is a find/watch source.
+      limit: Math.min(Math.max(limit * 2, limit), 200),
+    })) as Array<Record<string, unknown>>;
+    const lists = rows
+      .filter((row) => LIST_CREATED_FROM.has(String(row.createdFrom)))
+      .slice(0, limit)
+      .map((row) => ({
+        _id: row._id,
+        title: row.title,
+        createdFrom: row.createdFrom,
+        rowCount: row.rowCount,
+        createdAt: row.createdAt,
+        watchId: row.watchId,
+      }));
+    out(ctx, lists);
+    return true;
+  }
+  args.shift();
+  if (verb === "show") {
+    const artifactId = shift(args, "list id");
+    assertNoUnknownFlags(args, "lists show");
+    out(ctx, await callQuery(ctx, api.get, { artifactId }));
+    return true;
+  }
+  if (verb === "rename") {
+    const artifactId = shift(args, "list id");
+    const title = getFlag(args, "--title") ?? shift(args, "new name");
+    assertNoUnknownFlags(args, "lists rename");
+    out(
+      ctx,
+      await ctx.convex.mutation(api.rename, {
+        artifactId,
+        title,
+        ...(ctx.sessionToken ? { sessionToken: ctx.sessionToken } : {}),
+      } as never),
+    );
+    return true;
+  }
+  if (verb === "update") {
+    const artifactId = shift(args, "list id");
+    const title = getFlag(args, "--title");
+    const filtersJson = getFlag(args, "--filters-json");
+    assertNoUnknownFlags(args, "lists update");
+    let filters: unknown;
+    if (filtersJson !== undefined) {
+      try {
+        filters = JSON.parse(filtersJson);
+      } catch {
+        throw new FindCliError("--filters-json must be valid JSON");
+      }
+    }
+    if (title === undefined && filters === undefined) {
+      throw new FindCliError(
+        "dench lists update requires --title and/or --filters-json",
+      );
+    }
+    out(
+      ctx,
+      await callAction(ctx, api.updateFind, {
+        artifactId,
+        ...(title !== undefined ? { title } : {}),
+        ...(filters !== undefined ? { filters } : {}),
+      }),
+    );
+    return true;
+  }
+  if (verb === "delete") {
+    const artifactId = shift(args, "list id");
+    assertNoUnknownFlags(args, "lists delete");
+    out(
+      ctx,
+      await ctx.convex.mutation(api.remove, {
+        artifactId,
+        ...(ctx.sessionToken ? { sessionToken: ctx.sessionToken } : {}),
+      } as never),
+    );
+    return true;
+  }
+  throw new FindCliError(
+    `Unknown lists verb: ${verb}. Try list, show, rename, update, delete.`,
+  );
+}
+
 export function assertJobsFindArgs(args: string[]): void {
   const copy = [...args];
   hasFlag(copy, "--json");
@@ -249,11 +636,13 @@ export function assertJobsFindArgs(args: string[]): void {
     !copy.includes("--titles") &&
     !copy.includes("--locations") &&
     !copy.includes("--company-domain") &&
+    !copy.includes("--company-domains") &&
     !copy.includes("--company") &&
+    !copy.includes("--company-list") &&
     !copy.includes("--keywords")
   ) {
     throw new FindCliError(
-      "dench jobs find requires at least one of --titles, --locations, --company-domain, --company, --keywords",
+      "dench jobs find requires at least one of --titles, --locations, --company-domain, --company-domains, --company, --company-list, --keywords",
     );
   }
 }
@@ -298,52 +687,79 @@ export async function runLeadsCommand(opts: {
     leadsHelp();
     return;
   }
+  if (verb === "filters") {
+    runFindFiltersCommand({ args, jsonOutput: ctx.jsonOutput });
+    return;
+  }
   if (verb !== "find") {
     throw new FindCliError(`Unknown leads verb: ${verb}`);
   }
-  const {
-    titles,
-    locations,
-    seniorities,
-    industries,
-    functions,
-    companyDomain,
-    keywords,
-    limit,
-    pageToken,
-  } = parseLeadsFindFlags(args);
+  const { name: listName, ...flags } = parseLeadsFindFlags(args);
+  // Resolve --company-list fresh per search so the filter tracks the
+  // list's CURRENT companies (domains exact, name fallback for rows
+  // without a domain).
+  const companyList = flags.companyList
+    ? await resolveCompanyListFlag(ctx, flags.companyList)
+    : undefined;
   try {
     const result = await searchPeople(
       {
-        personTitles: titles,
-        personLocations: locations,
-        personSeniorities: seniorities,
-        personFunctions: functions,
-        organizationDomains: companyDomain ? [companyDomain] : undefined,
-        organizationIndustries: industries,
-        keywords,
-        limit,
-        pageToken,
+        titles: flags.titles,
+        pastTitles: flags.pastTitles,
+        personNames: flags.personNames,
+        locations: flags.locations,
+        seniorities: flags.seniorities,
+        jobFunctions: flags.functions,
+        subFunctions: flags.subFunctions,
+        industries: flags.industries,
+        organizationDomains: flags.companyDomain
+          ? [flags.companyDomain]
+          : undefined,
+        companyDomains: mergeUnique(flags.companyDomains, companyList?.domains),
+        companyNames: mergeUnique(flags.companyNames, companyList?.names),
+        pastCompanyNames: flags.pastCompanyNames,
+        companyHeadquarters: flags.companyHeadquarters,
+        companyTypes: flags.companyTypes,
+        universities: flags.universities,
+        skills: flags.skills,
+        languages: flags.languages,
+        headcountRanges: flags.headcount,
+        yearsInRole: flags.yearsInRole,
+        yearsAtCompany: flags.yearsAtCompany,
+        daysSinceJobChange: flags.daysSinceJobChange,
+        foundedYears: flags.foundedYears,
+        keywords: flags.keywords,
+        limit: flags.limit,
+        pageToken: flags.pageToken,
       },
       ctx.enrichmentGateway,
     );
     const people = asArray(result.people);
+    // Persist every set filter so the saved list hydrates the full rail.
+    const savedFilters: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(flags)) {
+      if (key === "pageToken" || value === undefined) continue;
+      savedFilters[key] = value;
+    }
+    if (flags.companyList && companyList) {
+      // Store the reference (not the resolved domains) so re-running the
+      // saved search picks up the list's contents at that time.
+      savedFilters.companyList = companyListFilterEntry(
+        flags.companyList,
+        companyList,
+      );
+    }
     const artifact = await persist(ctx, {
       createdFrom: "find_people",
-      title: findTitle("people", [
-        titles?.[0] ?? "",
-        keywords ?? "",
-        companyDomain ?? "",
-      ]),
-      filters: {
-        titles,
-        locations,
-        seniorities,
-        industries,
-        companyDomain,
-        keywords,
-        limit,
-      },
+      title:
+        listName ??
+        findTitle("people", [
+          flags.titles?.[0] ?? "",
+          flags.keywords ?? "",
+          flags.companyDomain ?? "",
+          companyList?.title ?? "",
+        ]),
+      filters: savedFilters,
       people,
     });
     // metadata carries total / nextPageToken — pass the token back via
@@ -351,6 +767,7 @@ export async function runLeadsCommand(opts: {
     out(ctx, {
       ...(artifact as Record<string, unknown>),
       metadata: result.metadata,
+      ...(companyList ? { companyList: companyListInfo(companyList) } : {}),
     });
   } catch (error) {
     throw new FindCliError(
@@ -388,24 +805,40 @@ export async function runJobsCommand(opts: {
   const titles = csvFlag(args, "--titles");
   const locations = csvFlag(args, "--locations");
   const companyDomain = getFlag(args, "--company-domain");
+  const companyDomains = csvFlag(args, "--company-domains");
   const companyName = getFlag(args, "--company");
   const keywords = getFlag(args, "--keywords");
   const postedAfter = getFlag(args, "--posted-after");
+  const companyListRef = getFlag(args, "--company-list");
   const limit = parseLimit(args);
   const pageToken = getFlag(args, "--page-token");
+  const listName = getFlag(args, "--save-as");
   assertNoUnknownFlags(args, "jobs find");
-  if (!titles && !locations && !companyDomain && !companyName && !keywords) {
+  if (
+    !titles &&
+    !locations &&
+    !companyDomain &&
+    !companyDomains &&
+    !companyName &&
+    !keywords &&
+    !companyListRef
+  ) {
     throw new FindCliError(
-      "dench jobs find requires at least one of --titles, --locations, --company-domain, --company, --keywords",
+      "dench jobs find requires at least one of --titles, --locations, --company-domain, --company-domains, --company, --company-list, --keywords",
     );
   }
+  const companyList = companyListRef
+    ? await resolveCompanyListFlag(ctx, companyListRef)
+    : undefined;
   try {
     const result = await searchJobs(
       {
         titles,
         locations,
         companyDomain,
+        companyDomains: mergeUnique(companyDomains, companyList?.domains),
         companyName,
+        companyNames: companyList?.names.length ? companyList.names : undefined,
         keywords,
         postedAfter,
         limit,
@@ -416,21 +849,35 @@ export async function runJobsCommand(opts: {
     const jobs = asArray(result.jobs);
     const artifact = await persist(ctx, {
       createdFrom: "find_jobs",
-      title: findTitle("jobs", [titles?.[0] ?? "", companyName ?? "", keywords ?? ""]),
+      title:
+        listName ??
+        findTitle("jobs", [
+          titles?.[0] ?? "",
+          companyName ?? "",
+          keywords ?? "",
+          companyList?.title ?? "",
+        ]),
       filters: {
         titles,
         locations,
         companyDomain,
+        companyDomains,
         companyName,
         keywords,
         postedAfter,
         limit,
+        ...(companyListRef && companyList
+          ? {
+              companyList: companyListFilterEntry(companyListRef, companyList),
+            }
+          : {}),
       },
       jobs,
     });
     out(ctx, {
       ...(artifact as Record<string, unknown>),
       metadata: result.metadata,
+      ...(companyList ? { companyList: companyListInfo(companyList) } : {}),
     });
   } catch (error) {
     throw new FindCliError(
@@ -474,6 +921,7 @@ export async function runCompaniesCommand(opts: {
   const headcountRanges = csvFlag(args, "--headcount");
   const limit = parseLimit(args);
   const pageToken = getFlag(args, "--page-token");
+  const listName = getFlag(args, "--save-as");
   assertNoUnknownFlags(args, "companies find");
   if (
     !domain &&
@@ -505,7 +953,9 @@ export async function runCompaniesCommand(opts: {
     );
     const artifact = await persist(ctx, {
       createdFrom: "find_companies",
-      title: findTitle("companies", [name ?? "", domain ?? "", keywords ?? ""]),
+      title:
+        listName ??
+        findTitle("companies", [name ?? "", domain ?? "", keywords ?? ""]),
       filters: {
         domain,
         name,