sentisense 0.51.0 → 0.52.0

package/README.md

@@ -71,7 +71,8 @@ npx -y sentisense@latest health
 | `quote <ticker>...` | Price, day range, 52-week range, market cap, P/E. One request per ticker |
 | `sentiment <ticker>` | SentiSense Score, tone, attention, per-source breakdown, `--days N` history |
 | `mood` | Composite market sentiment, the signals behind it, and the sector map |
-| `analysts <ticker>` | Consensus, price target band, recent upgrades and downgrades |
+| `analysts <ticker>` | Consensus, price target band, recent upgrades and downgrades. `--coverage` for who covers it, by firm |
+| `analyst <slug>` | One analyst: their firms, their coverage book, and `--calls` for their price target notes |
 | `earnings [ticker]` | Forward calendar with no ticker, per-quarter analysis with one (`earnings AAPL`) |
 | `insiders <ticker>` | Filed Form 4 transactions, including whether they were pre-planned |
 | `insights <ticker>` | Generated signals, filterable by `--urgency` and `--type` |
@@ -80,9 +81,22 @@ npx -y sentisense@latest health
 | `flows [ticker]` | Institutional 13F flows, or one ticker's holders and notable changes |
 | `options <ticker>` | End-of-day options positioning, IV rank, walls, unusual contracts |
 | `screen --filter ...` | Screen the universe on Score, analyst, technical, and price fields |
+| `search <name>` | Resolve a name, alias, ticker or slug to a symbol and the entity handle |
 
 Run `sentisense help <command>` for its flags and examples.
 
+Three of these chain into each other. Start from a name, land on a person:
+
+```bash
+npx -y sentisense@latest search Tesla --type company   # "Tesla" -> TSLA, plus the entity slug
+npx -y sentisense@latest analysts NVDA --coverage      # who covers it, by firm, with analyst slugs
+npx -y sentisense@latest analyst quinn-bolton --calls  # that analyst's firms, book, and notes
+```
+
+`analyst` takes a slug, not a name: slugs are lowercase and hyphenated, and every named analyst in a `--coverage` row carries the one that addresses them. A name is rejected before a request is spent. What comes back is call history, not accuracy scoring: there is no hit rate, no ranking, and nothing in it rates the person.
+
+Ranking on `search` is the API's own, and a company can sort below its own products, so pass `--type company` when what you want is the issuer.
+
 ### Output modes
 
 Readable in a terminal, plain text when piped, and exact API JSON on request:
@@ -474,8 +488,18 @@ All five are optional: a response served before they shipped omits them. For the
 ```typescript
 client.marketMood.get()             // Composite market sentiment with sub-signals
 client.kb.getPopularEntities()      // Most-tracked entities
+client.kb.searchEntities("Tesla")   // Resolve a name, alias, ticker or slug to what we track
 ```
 
+Entity search is resolution, not enumeration: the query must be at least 2 characters, the match count is capped at 25, and it returns a bare `EntitySearchResult[]` rather than a `PreviewResponse` envelope. Each hit carries `name`, `type`, the `ticker` for a listed entity (`null` for everything else), and the `urlSlug` the metric endpoints address that entity by, which is the only way to get a handle for a person, product or topic with no ticker.
+
+```typescript
+const hits = await client.kb.searchEntities("Tesla", { type: "company", limit: 5 });
+const symbol = hits.find((hit) => hit.ticker)?.ticker;   // "TSLA"
+```
+
+An empty array is the normal answer for a query that matches nothing, so branch on `length` rather than catching.
+
 ### Screener
 
 Filter the tracked universe on the SentiSense Score, attention, analyst consensus, technicals and price in one query. Screening on analyst ratings alone is something a dozen free tools do; screening on analyst ratings *where the Score disagrees* is not.

package/dist/cli.cjs

@@ -77,6 +77,14 @@ var UnknownTickerError = class extends Error {
     this.ticker = ticker;
   }
 };
+var NoMatchError = class extends Error {
+  constructor(query2, hint) {
+    super(`nothing matches "${query2}".`);
+    this.name = "NoMatchError";
+    this.query = query2;
+    this.hint = hint;
+  }
+};
 var MissingKeyError = class extends Error {
   constructor() {
     super("no API key configured.");
@@ -109,6 +117,12 @@ function classify(error, command) {
       ]
     };
   }
+  if (error instanceof NoMatchError) {
+    return {
+      exitCode: EXIT.NOT_FOUND,
+      lines: [`error: ${error.message}`, `next: ${error.hint}`]
+    };
+  }
   if (error instanceof CliUsageError) {
     return {
       exitCode: EXIT.USAGE,
@@ -184,48 +198,6 @@ function classify(error, command) {
   };
 }
 
-// src/cli/ticker.ts
-function rejectSurplus(args, name, allowed) {
-  if (args.positionals.length <= allowed) return;
-  throw new CliUsageError(
-    `${name} takes one ticker, and got ${args.positionals.length}.`,
-    "run it once per ticker. Only quote accepts more than one."
-  );
-}
-function oneTicker(args, name) {
-  rejectSurplus(args, name, 1);
-  const ticker = args.positionals[0];
-  if (!ticker) {
-    throw new CliUsageError(
-      `${name} needs a ticker.`,
-      `for example: sentisense ${name} NVDA`
-    );
-  }
-  return ticker.toUpperCase();
-}
-function optionalTicker(args, name) {
-  rejectSurplus(args, name, 1);
-  return args.positionals[0]?.toUpperCase();
-}
-function rejectPositionals(args, name) {
-  if (args.positionals.length === 0) return;
-  throw new CliUsageError(
-    `${name} takes no ticker, and got ${args.positionals.length}.`,
-    `run "sentisense help ${name}" for what it accepts.`
-  );
-}
-async function verifyTickerOnEmpty(api, ticker) {
-  try {
-    await api.stocks.getQuote(ticker);
-    return void 0;
-  } catch (error) {
-    if (error instanceof NotFoundError) throw new UnknownTickerError(ticker);
-    return `could not verify ${ticker}, so the empty result is unconfirmed`;
-  }
-}
-var EMPTY_VERIFY_NOTE = "An empty result verifies the ticker before reporting no data, so a typo exits 4 rather";
-var EMPTY_VERIFY_NOTE_2 = "than looking like a company with nothing to report.";
-
 // src/cli/render/doc.ts
 function cell(text, tone) {
   return tone ? { text, tone } : { text };
@@ -322,34 +294,264 @@ function truncate(text, max) {
   return `${text.slice(0, Math.max(0, max - 3))}...`;
 }
 
+// src/cli/commands/analyst.ts
+var DEFAULT_CALLS = 25;
+var NOT_A_SCORECARD = "Call history, not accuracy scoring: no hit rate, no ranking, and nothing here rates the person.";
+function oneSlug(positionals) {
+  if (positionals.length > 1) {
+    throw new CliUsageError(
+      `analyst takes one slug, and got ${positionals.length}.`,
+      "run it once per analyst."
+    );
+  }
+  const raw = positionals[0];
+  if (!raw) {
+    throw new CliUsageError(
+      "analyst needs a slug.",
+      'for example: sentisense analyst dan-ives. Slugs come from "sentisense analysts <ticker> --coverage".'
+    );
+  }
+  if (/\s/.test(raw)) {
+    throw new CliUsageError(
+      `analyst takes a slug, not a name, and got "${raw}".`,
+      'slugs are lowercase and hyphenated, such as dan-ives. Every named analyst in "sentisense analysts <ticker> --coverage" carries one.'
+    );
+  }
+  return raw.toLowerCase();
+}
+var analystCommand = {
+  name: "analyst",
+  summary: "One analyst: the firms they publish under, what they cover, and their calls",
+  usage: "sentisense analyst <slug> [--calls] [--limit N]",
+  examples: [
+    "sentisense analyst dan-ives",
+    "sentisense analyst dan-ives --calls",
+    "sentisense analyst dan-ives --calls --limit 50 --full",
+    "sentisense analyst dan-ives --json"
+  ],
+  notes: [
+    "Takes a slug, not a name. Slugs are lowercase and hyphenated, and every named analyst",
+    'in "sentisense analysts <ticker> --coverage" carries the one that addresses them here.',
+    "--calls appends their price target notes, newest first.",
+    "firstSeen and lastSeen bound the notes on record, not employment: the most recent firm",
+    "is where they last published, not necessarily where they work today.",
+    NOT_A_SCORECARD,
+    "A slug that matches no analyst exits 4."
+  ],
+  flags: {
+    calls: { type: "boolean", describe: "Append their price target notes, newest first" },
+    limit: { type: "number", placeholder: "N", describe: `Calls to request, 1 to 200 (default ${DEFAULT_CALLS})` }
+  },
+  async run({ args, client, full }) {
+    const slug = oneSlug(args.positionals);
+    const wantCalls = args.flags.calls === true;
+    const limit = typeof args.flags.limit === "number" ? args.flags.limit : void 0;
+    const api = client();
+    const profileEnvelope = await api.analyst.profile(slug);
+    const callsEnvelope = wantCalls ? await api.analyst.calls(slug, limit === void 0 ? void 0 : { limit }) : null;
+    const data = profileEnvelope.data;
+    const blocks = [
+      {
+        kind: "head",
+        title: field("analyst", data?.name ?? slug),
+        subtitle: field("slug", data?.slug ?? slug),
+        right: fields(
+          field("notes", String(data?.noteCount ?? 0)),
+          field("tickers", String(data?.tickerCount ?? 0))
+        )
+      },
+      {
+        kind: "facts",
+        items: fields(
+          field("Most recent firm", data?.mostRecentFirm ?? "n/a"),
+          field("First seen", data?.firstSeen ?? "n/a"),
+          field("Last seen", data?.lastSeen ?? "n/a")
+        )
+      }
+    ];
+    const firms = data?.firms ?? [];
+    if (firms.length > 0) {
+      blocks.push({ kind: "blank" });
+      blocks.push({
+        kind: "table",
+        head: ["FIRM", "FIRST NOTE", "LAST NOTE", "CURRENT"],
+        rows: firms.map((firm) => [
+          cell(truncate(firm.firm, full ? 40 : 28)),
+          cell(firm.firstSeen),
+          cell(firm.lastSeen),
+          cell(firm.mostRecent ? "yes" : "")
+        ])
+      });
+    }
+    const book = data?.coverage ?? [];
+    if (book.length > 0) {
+      const shown = full ? book : book.slice(0, 10);
+      blocks.push({ kind: "blank" });
+      blocks.push({
+        kind: "table",
+        head: ["TICKER", "NOTES", "LAST NOTE", "TARGET", "FIRM"],
+        align: ["left", "right", "left", "right", "left"],
+        rows: shown.map((entry) => [
+          cell(entry.ticker),
+          cell(String(entry.noteCount)),
+          cell(entry.lastNote ?? ""),
+          cell(entry.latestPriceTarget === null ? "" : money(entry.latestPriceTarget)),
+          cell(truncate(entry.latestFirm ?? "", full ? 40 : 24))
+        ])
+      });
+      const total = profileEnvelope.totalCount ?? data?.tickerCount ?? book.length;
+      if (shown.length < total) {
+        blocks.push({
+          kind: "text",
+          text: `Showing ${shown.length} of ${total} covered tickers. Add --full for the rest.`,
+          tone: "dim"
+        });
+      }
+    }
+    if (callsEnvelope) {
+      const calls = callsEnvelope.data ?? [];
+      blocks.push({ kind: "blank" });
+      if (calls.length === 0) {
+        blocks.push({ kind: "text", text: "No price target notes on record for this analyst." });
+      } else {
+        const shown = full ? calls : calls.slice(0, 15);
+        blocks.push({
+          kind: "table",
+          head: ["DATE", "TICKER", "FIRM", "TARGET", "PRICE THEN", "PUBLISHER"],
+          align: ["left", "left", "left", "right", "right", "left"],
+          rows: shown.map((call) => [
+            cell(call.publishedDate),
+            cell(call.ticker),
+            cell(truncate(call.firm, full ? 40 : 22)),
+            cell(call.priceTarget === null ? "" : money(call.priceTarget)),
+            cell(call.priceWhenPosted === null ? "" : money(call.priceWhenPosted)),
+            cell(truncate(call.newsPublisher ?? "", full ? 40 : 20))
+          ])
+        });
+        const total = callsEnvelope.totalCount ?? calls.length;
+        if (shown.length < total) {
+          blocks.push({
+            kind: "text",
+            text: `Showing ${shown.length} of ${total} calls. Add --full, or --limit to ask for more.`,
+            tone: "dim"
+          });
+        }
+      }
+      if (callsEnvelope.isPreview) {
+        blocks.push({
+          kind: "text",
+          text: "Preview response: a free key reads the first 25 calls, a PRO key pages the whole history.",
+          tone: "dim"
+        });
+      }
+    }
+    if (profileEnvelope.isPreview) {
+      blocks.push({
+        kind: "text",
+        text: "Preview response: the coverage book is trimmed to the 5 most recent tickers on a free key.",
+        tone: "dim"
+      });
+    }
+    blocks.push({ kind: "text", text: NOT_A_SCORECARD, tone: "dim" });
+    return {
+      json: callsEnvelope ? { profile: profileEnvelope, calls: callsEnvelope } : profileEnvelope,
+      doc: doc(...blocks)
+    };
+  }
+};
+
+// src/cli/ticker.ts
+function rejectSurplus(args, name, allowed) {
+  if (args.positionals.length <= allowed) return;
+  throw new CliUsageError(
+    `${name} takes one ticker, and got ${args.positionals.length}.`,
+    "run it once per ticker. Only quote accepts more than one."
+  );
+}
+function oneTicker(args, name) {
+  rejectSurplus(args, name, 1);
+  const ticker = args.positionals[0];
+  if (!ticker) {
+    throw new CliUsageError(
+      `${name} needs a ticker.`,
+      `for example: sentisense ${name} NVDA`
+    );
+  }
+  return ticker.toUpperCase();
+}
+function optionalTicker(args, name) {
+  rejectSurplus(args, name, 1);
+  return args.positionals[0]?.toUpperCase();
+}
+function rejectPositionals(args, name) {
+  if (args.positionals.length === 0) return;
+  throw new CliUsageError(
+    `${name} takes no ticker, and got ${args.positionals.length}.`,
+    `run "sentisense help ${name}" for what it accepts.`
+  );
+}
+async function verifyTickerOnEmpty(api, ticker) {
+  try {
+    await api.stocks.getQuote(ticker);
+    return void 0;
+  } catch (error) {
+    if (error instanceof NotFoundError) throw new UnknownTickerError(ticker);
+    return `could not verify ${ticker}, so the empty result is unconfirmed`;
+  }
+}
+var EMPTY_VERIFY_NOTE = "An empty result verifies the ticker before reporting no data, so a typo exits 4 rather";
+var EMPTY_VERIFY_NOTE_2 = "than looking like a company with nothing to report.";
+
 // src/cli/commands/analysts.ts
 var DEFAULT_ACTIONS = 5;
+var DEFAULT_COVERAGE_ROWS = 15;
 function actionTone(actionType) {
   if (actionType === "UPGRADE") return "up";
   if (actionType === "DOWNGRADE") return "down";
   return void 0;
 }
+function primaryAnalyst(row) {
+  const named = row.latestNote?.analyst;
+  const match = (named ? row.analysts.find((analyst) => analyst.name === named) : void 0) ?? row.analysts[0];
+  const name = match?.name ?? named ?? "";
+  const extra = row.analysts.length > 1 ? ` +${row.analysts.length - 1}` : "";
+  return { name: name ? `${name}${extra}` : "", slug: match?.slug ?? "" };
+}
 var analystsCommand = {
   name: "analysts",
   summary: "Wall Street consensus, price target band, and recent rating changes",
-  usage: "sentisense analysts <ticker> [--days N]",
+  usage: "sentisense analysts <ticker> [--coverage] [--days N] [--limit N]",
   examples: [
     "sentisense analysts NVDA",
     "sentisense analysts NVDA --days 180 --full",
+    "sentisense analysts NVDA --coverage",
+    "sentisense analysts NVDA --coverage --days 180 --limit 30",
     "sentisense analysts NVDA --json"
   ],
   notes: [
     "The price target band and analyst count come back in full on every key.",
     "The buy / hold / sell distribution and the longer action history are PRO.",
-    "A ticker with no analyst coverage exits 4 rather than returning an empty band."
+    "A ticker with no analyst coverage exits 4 rather than returning an empty band.",
+    "--coverage answers who covers the ticker instead: one row per firm, the analyst that",
+    "firm last published under, their latest target, and the firm's current rating. The slug",
+    'on a row is what "sentisense analyst <slug>" takes.',
+    "A firm can cover a ticker on a rating action alone, so a blank target is a real reading",
+    "rather than missing data, and a blank analyst means the note named nobody.",
+    "--limit trims the rows printed under --coverage; the API returns the whole book either",
+    "way, and --full prints all of it."
   ],
   flags: {
-    days: { type: "number", placeholder: "N", describe: "Days of rating history (default 90)" }
+    coverage: { type: "boolean", describe: "Show who covers the ticker, one row per firm" },
+    days: { type: "number", placeholder: "N", describe: "Days of rating history (default 90)" },
+    limit: { type: "number", placeholder: "N", describe: `Firm rows to print with --coverage (default ${DEFAULT_COVERAGE_ROWS})` }
   },
   async run({ args, client, full }) {
     const ticker = oneTicker(args, "analysts");
     const lookbackDays = typeof args.flags.days === "number" ? args.flags.days : void 0;
     const api = client();
+    if (args.flags.coverage === true) {
+      return coverageRun({ api, ticker, lookbackDays, full, args });
+    }
     const notes = [];
     const [consensus, actions] = await Promise.all([
       api.analyst.consensus(ticker),
@@ -428,6 +630,91 @@ var analystsCommand = {
     return { json: { consensus, actions }, doc: doc(...blocks), notes };
   }
 };
+async function coverageRun({ api, ticker, lookbackDays, full, args }) {
+  const envelope = await api.analyst.coverage(
+    ticker,
+    lookbackDays === void 0 ? void 0 : { lookbackDays }
+  );
+  const data = envelope.data;
+  const rows = data?.coverage ?? [];
+  const limit = typeof args.flags.limit === "number" ? args.flags.limit : DEFAULT_COVERAGE_ROWS;
+  const shown = full ? rows : rows.slice(0, Math.max(1, limit));
+  const blocks = [
+    {
+      kind: "head",
+      title: field("ticker", ticker),
+      right: fields(
+        field("firms", String(data?.firmCount ?? rows.length)),
+        field("named analysts", String(data?.namedAnalystCount ?? 0)),
+        data?.windowDays === void 0 ? void 0 : field("window", `${data.windowDays}d`)
+      )
+    }
+  ];
+  const buckets = data?.ratingBuckets;
+  if (buckets) {
+    blocks.push({
+      kind: "facts",
+      items: fields(
+        field("Buy", String(buckets.buy), buckets.buy > 0 ? "up" : void 0),
+        field("Hold", String(buckets.hold)),
+        field("Sell", String(buckets.sell), buckets.sell > 0 ? "down" : void 0),
+        field("Unrated", String(buckets.unrated)),
+        field("Total", String(buckets.total))
+      )
+    });
+  }
+  blocks.push({
+    kind: "facts",
+    items: fields(
+      field("Notes", String(data?.noteCount ?? 0)),
+      field("Attributed", String(data?.attributedNoteCount ?? 0)),
+      field("Unattributed", String(data?.unattributedNoteCount ?? 0)),
+      field("Rating only", String(data?.ratingOnlyFirmCount ?? 0)),
+      data?.asOf === void 0 ? void 0 : field("As of", data.asOf)
+    )
+  });
+  if (shown.length === 0) {
+    blocks.push({ kind: "text", text: "No firm published a target or a rating in this window." });
+  } else {
+    blocks.push({ kind: "blank" });
+    blocks.push({
+      kind: "table",
+      head: ["FIRM", "ANALYST", "SLUG", "TARGET", "DATE", "RATING", "ACTION"],
+      align: ["left", "left", "left", "right", "left", "left", "left"],
+      rows: shown.map((row) => {
+        const analyst = primaryAnalyst(row);
+        return [
+          cell(truncate(row.firm, full ? 40 : 24)),
+          cell(truncate(analyst.name, full ? 32 : 20)),
+          cell(truncate(analyst.slug, full ? 32 : 20)),
+          cell(row.latestNote?.priceTarget === null || row.latestNote?.priceTarget === void 0 ? "" : money(row.latestNote.priceTarget)),
+          cell(row.latestNote?.publishedDate ?? row.firmRating?.date ?? ""),
+          cell(row.firmRating?.rating ?? ""),
+          cell(row.firmRating?.actionType ?? "", actionTone(row.firmRating?.actionType))
+        ];
+      })
+    });
+    const total = data?.firmCount ?? rows.length;
+    if (shown.length < total) {
+      blocks.push({
+        kind: "text",
+        text: `Showing ${shown.length} of ${total} firms. Add --full for the rest.`,
+        tone: "dim"
+      });
+    }
+  }
+  if (data?.attributionNote) {
+    blocks.push({ kind: "text", text: data.attributionNote, tone: "dim" });
+  }
+  if (envelope.isPreview) {
+    blocks.push({
+      kind: "text",
+      text: "Preview response: the counts describe the whole window, the rows are trimmed on a free key.",
+      tone: "dim"
+    });
+  }
+  return { json: envelope, doc: doc(...blocks) };
+}
 
 // src/cli/config.ts
 var import_node_fs = require("fs");
@@ -1037,7 +1324,7 @@ var flowsCommand = {
 };
 
 // src/version.ts
-var VERSION = "0.51.0";
+var VERSION = "0.52.0";
 
 // src/resources/analyst.ts
 var Analyst = class {
@@ -1206,8 +1493,8 @@ var Documents = class {
     );
   }
   /** Smart search with natural language query parsing. The rows are in `documents`. */
-  async search(query, options) {
-    return this.client.get("/api/v1/documents/search", { query, ...options });
+  async search(query2, options) {
+    return this.client.get("/api/v1/documents/search", { query: query2, ...options });
   }
   /** Get latest document metrics from a source type. The rows are in `documents`. */
   async getBySource(source, options) {
@@ -1675,6 +1962,22 @@ var KB = class {
   async getPopularEntities() {
     return this.client.get("/api/v1/kb/entities/popular");
   }
+  /**
+   * Resolve a name, alias, ticker or slug to the entities we track, best match first.
+   *
+   * This is resolution, not enumeration: the query must be at least 2 characters and the
+   * result count is capped, so it answers "which handle did the user mean" rather than
+   * dumping the graph. Use it when someone typed "Tesla" and the rest of your code needs
+   * `TSLA`, or when you need the `urlSlug` an entity's metric series is addressed by.
+   *
+   * Returns a bare array, not a `PreviewResponse` envelope, and an empty array is the
+   * normal answer for a query that matches nothing.
+   *
+   * @param q What the user typed. At least 2 characters, or the API answers 400.
+   */
+  async searchEntities(q, options) {
+    return this.client.get("/api/v1/kb/entities/search", { q, ...options });
+  }
 };
 
 // src/resources/marketMood.ts
@@ -3622,6 +3925,90 @@ var screenCommand = {
   }
 };
 
+// src/cli/commands/search.ts
+var TYPES = ["person", "company", "product", "organization", "etf", "topic", "country"];
+function query(positionals) {
+  const text = positionals.join(" ").trim();
+  if (!text) {
+    throw new CliUsageError("search needs something to look for.", "for example: sentisense search Tesla");
+  }
+  if (text.length < 2) {
+    throw new CliUsageError(
+      `search needs at least 2 characters, and got "${text}".`,
+      "for example: sentisense search Tesla"
+    );
+  }
+  return text;
+}
+var searchCommand = {
+  name: "search",
+  summary: "Resolve a name, alias, ticker or slug to the entities we track",
+  usage: "sentisense search <name> [--type <kind>] [--limit N]",
+  examples: [
+    "sentisense search Tesla",
+    "sentisense search 'Elon Musk' --type person",
+    "sentisense search nvidia --limit 5",
+    "sentisense search Tesla --json"
+  ],
+  notes: [
+    "For when you have a name and the rest of your pipeline needs a symbol: search Tesla,",
+    "get TSLA, then run quote or sentiment on it.",
+    "The slug column is the handle the metric endpoints address an entity by, which is the",
+    "only place to get it for a person, product or topic that has no ticker.",
+    `--type narrows to one kind: ${TYPES.join(", ")}.`,
+    "Ranking is the API's, and a company can sort below its own products, so reach for",
+    "--type company when what you want is the issuer. A query that matches nothing exits 4."
+  ],
+  flags: {
+    type: { type: "string", placeholder: "kind", describe: `Narrow to one kind: ${TYPES.join(", ")}` },
+    limit: { type: "number", placeholder: "N", describe: "Matches to return, 1 to 25 (default 10)" }
+  },
+  async run({ args, client, full }) {
+    const text = query(args.positionals);
+    const type = typeof args.flags.type === "string" ? args.flags.type.toLowerCase() : void 0;
+    if (type && !TYPES.includes(type)) {
+      throw new CliUsageError(
+        `--type takes one of ${TYPES.join(", ")}, got "${type}".`,
+        "for example: --type company"
+      );
+    }
+    const limit = typeof args.flags.limit === "number" ? args.flags.limit : void 0;
+    const api = client();
+    const results = await api.kb.searchEntities(text, {
+      ...type ? { type } : {},
+      ...limit === void 0 ? {} : { limit }
+    });
+    if (results.length === 0) {
+      throw new NoMatchError(
+        text,
+        type ? `nothing of type ${type} matched. Try dropping --type, or fewer characters.` : "try fewer characters, another spelling, or the ticker itself."
+      );
+    }
+    const blocks = [
+      {
+        kind: "head",
+        title: field("query", text),
+        right: fields(
+          field("matches", String(results.length)),
+          type === void 0 ? void 0 : field("type", type)
+        )
+      },
+      { kind: "blank" },
+      {
+        kind: "table",
+        head: ["SYMBOL", "NAME", "TYPE", "SLUG"],
+        rows: results.map((hit) => [
+          cell(hit.ticker ?? "", hit.ticker ? "accent" : void 0),
+          cell(truncate(hit.name, full ? 60 : 34)),
+          cell(hit.type ?? ""),
+          cell(truncate(hit.urlSlug ?? "", full ? 60 : 34))
+        ])
+      }
+    ];
+    return { json: results, doc: doc(...blocks) };
+  }
+};
+
 // src/cli/commands/sentiment.ts
 var DEFAULT_DAYS = 30;
 function toneForDirection(value) {
@@ -3784,6 +4171,7 @@ var COMMANDS = [
   sentimentCommand,
   moodCommand,
   analystsCommand,
+  analystCommand,
   earningsCommand,
   insidersCommand,
   insightsCommand,
@@ -3791,7 +4179,8 @@ var COMMANDS = [
   newsCommand,
   flowsCommand,
   optionsCommand,
-  screenCommand
+  screenCommand,
+  searchCommand
 ];
 var COMMAND_NAMES = COMMANDS.map((command) => command.name);
 function findCommand(name) {
@@ -3806,7 +4195,8 @@ var EXAMPLE = {
   quote: "sentisense quote NVDA AAPL",
   sentiment: "sentisense sentiment NVDA --days 30",
   mood: "sentisense mood",
-  analysts: "sentisense analysts NVDA",
+  analysts: "sentisense analysts NVDA --coverage",
+  analyst: "sentisense analyst dan-ives --calls",
   earnings: "sentisense earnings --week next",
   insiders: "sentisense insiders NVDA",
   insights: "sentisense insights NVDA",
@@ -3814,7 +4204,8 @@ var EXAMPLE = {
   news: "sentisense news NVDA",
   flows: "sentisense flows NVDA",
   options: "sentisense options NVDA",
-  screen: "sentisense screen --filter SENTI_SCORE_7D:GTE:13"
+  screen: "sentisense screen --filter SENTI_SCORE_7D:GTE:13",
+  search: "sentisense search Tesla"
 };
 function pad(text, width) {
   return text.length >= width ? text : text + " ".repeat(width - text.length);

package/dist/index.cjs

@@ -710,6 +710,22 @@ var KB = class {
   async getPopularEntities() {
     return this.client.get("/api/v1/kb/entities/popular");
   }
+  /**
+   * Resolve a name, alias, ticker or slug to the entities we track, best match first.
+   *
+   * This is resolution, not enumeration: the query must be at least 2 characters and the
+   * result count is capped, so it answers "which handle did the user mean" rather than
+   * dumping the graph. Use it when someone typed "Tesla" and the rest of your code needs
+   * `TSLA`, or when you need the `urlSlug` an entity's metric series is addressed by.
+   *
+   * Returns a bare array, not a `PreviewResponse` envelope, and an empty array is the
+   * normal answer for a query that matches nothing.
+   *
+   * @param q What the user typed. At least 2 characters, or the API answers 400.
+   */
+  async searchEntities(q, options) {
+    return this.client.get("/api/v1/kb/entities/search", { q, ...options });
+  }
 };
 
 // src/resources/marketMood.ts
@@ -1226,7 +1242,7 @@ var Trackers = class {
 };
 
 // src/version.ts
-var VERSION = "0.51.0";
+var VERSION = "0.52.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://app.sentisense.ai";