github-search-cli 9.10.0 → 9.10.1

package/CHANGELOG.md

@@ -6,6 +6,49 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). Publish
 
 ---
 
+## [9.10.1] — 2026-10-08 (released)
+
+### Fixed
+
+- **`--interval` is parsed again.** The flag was documented in `--help`, the
+  README, the shell completions and `docs/HOW-TO.md`, but `parseArgs` had no
+  case for it — so `ghfind --watch --interval 60` silently searched for
+  `"--interval 60"` and polled at the default 300s. It now parses a positive
+  whole number of seconds and rejects anything else.
+- **`--format` and `--pipe` validate up front.** A typo like `--format jsonn`
+  used to throw `Unknown format` mid-run and route into the crash-report flow
+  (which prints "ghfind encountered an unexpected error" and opens a GitHub
+  issue tab); `--pipe clonee` silently did nothing and exited 0. Both now fail
+  fast with the list of valid values and exit 1.
+- **An empty query no longer reaches GitHub.** `ghfind --count` sent `q=" "`,
+  got a 422 back, and surfaced it as "⚠ Network error — check your connection.
+  Retrying in 5s…". The search/format/pipe/watch handlers now fail fast with a
+  usage hint instead.
+- **Bare `ghfind --trending` launches the trending view** (as TRACKER.md
+  documents) instead of falling through to the landing menu.
+- **`--since` validates its value** (`daily|weekly|monthly`) instead of
+  silently falling back to daily for anything it did not recognize — matching
+  the existing `--sort` validation.
+- **Watch mode honors `--since`.** The trending period was derived from the
+  query string (`ghfind --watch --trending weekly`), so `--since weekly` was
+  ignored in watch-trending. An explicit `--since` now wins; the query-string
+  convention still applies when the flag is absent.
+- **The MCP `ghfind_user_profile` tool returns formatted text** like
+  `ghfind_org_profile` (and like the CLI's default `ghfind user`), instead of
+  raw JSON; the structured profile still rides along in `data`.
+- **Trending TUI footer matches the `/` key** (scroll-to-top: `/ top`, not
+  `/ search`), and the quit paths of the main TUI, trending and package browser
+  call `renderer.destroy()` before `process.exit(0)` so the terminal is
+  released (raw mode, alternate screen).
+
+### Removed
+
+- Dead modules with no importers: `src/search-state.ts` (stale
+  `config.githubTokens` reference from before token unification),
+  `src/export.ts` and `src/pipe.ts` (byte-for-byte duplicates of the formats
+  in `src/output.ts`, which is what everything imports), and the unused
+  `historyCount()` export.
+
 ## [9.10.0] — 2026-10-03 (released)
 
 ### Added

package/README.md

@@ -347,14 +347,14 @@ cd ghfind
 # With Bun (recommended for TUI)
 bun install
 bun start        # TUI
-bun test         # 657 tests
+bun test         # 682 tests
 bun run check    # format check + tests — the green gate
 bun run build    # build dist/
 
 # Or with npm
 npm install
 npm start        # TUI (requires Node 20+)
-npm test         # 657 tests
+npm test         # 682 tests
 npm run build    # build dist/
 
 > Want to contribute? See [CONTRIBUTING.md](CONTRIBUTING.md) for commands,
@@ -388,6 +388,17 @@ for the architecture, measurements, and remaining work.
 
 Recent releases (full history in [CHANGELOG.md](CHANGELOG.md)):
 
+### v9.10.1
+
+- **`--interval` is parsed again** — it was documented in `--help`, the README, the how-to guide and all three shell completions, but `parseArgs` had no case for it, so `ghfind --watch --interval 60` searched for the literal string `--interval 60` and polled at the default 300s anyway
+- **A flag typo no longer opens a GitHub issue tab** — `--format jsonn` threw mid-run and routed into the crash-report flow (printing "ghfind encountered an unexpected error" and opening a prefilled issue page); `--pipe clonee` silently did nothing and exited 0; both now validate up front, list the valid values, and exit 1
+- **An empty query fails fast instead of faking a network error** — `ghfind --count` with no query sent `q=" "`, got a 422 back, and looped on `⚠ Network error — check your connection. Retrying in 5s...`; the search/format/pipe/watch handlers now print a usage hint instead
+- **Bare `ghfind --trending` opens the trending view** instead of falling through to the landing menu, as documented
+- **`--since` validates `daily|weekly|monthly`** instead of silently accepting anything and falling back to daily — the same treatment `--sort` already had
+- **`--watch --trending --since weekly` polls weekly** — the trending period used to be derived from the query string, so `--since` was ignored in watch mode
+- **The MCP `ghfind_user_profile` tool returns formatted text**, matching `ghfind_org_profile` and the CLI's default `ghfind user` output; the raw JSON still rides along in `data`
+- **Quit paths release the terminal** — the main TUI, the trending view and the package browser call `renderer.destroy()` before exiting, and the trending footer's `/` hint now matches the scroll-to-top key it actually binds
+
 ### v9.10.0
 
 - **The TUI is now fully clickable** — the mouse was already enabled (OpenTUI emitted and hit-tested every event) but nothing consumed them, so they were silently discarded; click selects, double-click opens, the wheel scrolls, and clicking outside an overlay closes it
@@ -412,25 +423,6 @@ Recent releases (full history in [CHANGELOG.md](CHANGELOG.md)):
 - **A prerelease is no longer offered as an upgrade** — the version comparison used by Node and the compiled binaries reported `9.9.0-beta.1` as newer than `9.9.0`, i.e. a downgrade; it now follows npm ordering and ignores build metadata
 - **A new [how-to guide](docs/HOW-TO.md)** — token setup, writing queries, reading results, recovering from errors, and copy-paste recipes
 
-### v9.8.3
-
-- **401/403 say what actually happened** — a rejected token and an authenticated-but-forbidden request (e.g. SAML/SSO enforcement) both used to report "Network error", naming a connectivity problem you didn't have; only genuine connectivity and server failures keep that message now
-- **A rate-limited search no longer looks like an empty one** — the adapter used to swallow the error and render a silent, successful "no repositories found"; the real message reaches the status bar, and the `ghfind_search_repos` MCP tool returns `rateLimited: true` with backoff advice instead of a tool failure
-- **Recover from errors without leaving the TUI** — while the matching error is in the status bar, `t` opens an inline token prompt (saves it and re-runs the failed query), `u` clears the token and retries unauthenticated, `c` swaps in a different token, `r` retries
-- **A corrupted session no longer hijacks startup** — a `session.json` holding an MCP handshake blob used to skip the landing menu and auto-run that garbage as a search on every launch; the menu always comes first now, and both save and restore sanitize the session
-- **Images wrapped in a link render now** — the badge-and-screenshot shape `[![alt](shot.png)](url)` rendered nothing at all, which cost `sst/opencode` its only image and `withastro/astro` 23 of its 25; the image cells carry an OSC 8 hyperlink, so clicking it opens the target
-- **A README full of small images no longer floods the screen** — images the README declares under 100px on any edge are skipped before a request is made, and undeclared `![]()` images are measured from the image header before any pixel decode; on `openclaw/openclaw` (648 sponsor avatars) that is 649 fetches / 28.3s → 1 fetch / ~0.5s
-
-### v9.8.2
-
-- **Security: tokens no longer leak into crash reports** — an uncaught error auto-built a GitHub issue URL from raw `process.argv`, so a `--token` value ended up in a public URL; every field is redacted now, and ghfind prints the URL to copy instead of opening a browser when it finds a credential
-- **Security: your token is never sent to `raw.githubusercontent.com`** when fetching a README, only to `api.github.com` and only for a private repo
-- **Security: untrusted skill sources are validated** before reaching a shell command or URL, so a hostile skills.sh entry cannot inject into `npx skills add`
-- **Recoverable errors no longer open a bug-report tab** — rate limits, network blips and layout changes print a short message and exit
-- **`--compare` resolves repositories exactly** in both the CLI and the `ghfind_compare_repos` MCP tool; it used a free-text search that could silently compare the wrong repo
-- **State files are written atomically** — a crash mid-write used to leave truncated JSON that was silently replaced with defaults, losing bookmarks and history
-- Fixed notification IDs restarting after "dismiss all", `history --delete` removing every duplicate, an invalid `--sort` degrading silently, a failed "load more" clearing the TUI's results, `--markdown` not escaping `|`, and a not-quite-LRU memory cache
-
 ## License
 
 MIT

package/dist/cli.js

@@ -1569,6 +1569,7 @@ async function launchPackageBrowser() {
   renderer.keyInput.on("keypress", (key) => {
     const name = key.name || "";
     if (name === "q" || name === "escape") {
+      renderer.destroy();
       process.exit(0);
       return;
     }
@@ -2153,7 +2154,7 @@ var cached = null;
 function getVersion() {
   if (cached) return cached;
   if (true) {
-    cached = "9.10.0";
+    cached = "9.10.1";
     return cached;
   }
   try {
@@ -2322,6 +2323,7 @@ function reportError(err, context = {
 
 // src/output.ts
 import { writeFileSync as writeFileSync2 } from "fs";
+var PIPE_TARGETS = ["open", "clone"];
 var FORMATS = /* @__PURE__ */ new Map([
   // Export formats
   ["json", formatJson],
@@ -2335,6 +2337,7 @@ var FORMATS = /* @__PURE__ */ new Map([
   ["clone-commands", formatCloneCommands],
   ["ids", formatIds]
 ]);
+var FORMAT_VALUES = [...FORMATS.keys()];
 function formatJson(repos) {
   return JSON.stringify(repos, null, 2);
 }
@@ -2407,6 +2410,13 @@ async function pipeExec(repos, target) {
 }
 
 // src/watch.ts
+function resolveTrendingSince(opts) {
+  if (opts.since === "weekly" || opts.since === "monthly") return opts.since;
+  if (opts.since === "daily") return "daily";
+  if (opts.query === "weekly") return "weekly";
+  if (opts.query === "monthly") return "monthly";
+  return "daily";
+}
 var MAX_FAILS = 5;
 async function runWatch(opts, onChange, onError) {
   let previous = [];
@@ -2419,7 +2429,7 @@ async function runWatch(opts, onChange, onError) {
     try {
       let repos;
       if (opts.trending) {
-        const since = opts.query === "weekly" ? "weekly" : opts.query === "monthly" ? "monthly" : "daily";
+        const since = resolveTrendingSince(opts);
         const trendingSearch = createTrendingSearch();
         const response = await trendingSearch.search(trendingQuery(), {
           limit: opts.limit,
@@ -4870,10 +4880,12 @@ var StatusManager = class {
   type = "idle";
   message = "";
   onUpdate;
+  disposed = false;
   constructor(onUpdate) {
     this.onUpdate = onUpdate;
   }
   set(type, message) {
+    if (this.disposed) return;
     this.stopSpinner();
     this.type = type;
     this.message = message;
@@ -4886,6 +4898,7 @@ var StatusManager = class {
     }
   }
   startSpinner(frames) {
+    if (this.disposed) return;
     this.spinnerIndex = 0;
     this.emit(frames[0]);
     this.spinnerInterval = setInterval(() => {
@@ -4900,14 +4913,23 @@ var StatusManager = class {
     }
   }
   emit(spinner) {
+    if (this.disposed) return;
     const icon = this.type === "searching" ? "\u{1F50D}" : this.type === "loading" ? "\u{1F4E6}" : this.type === "success" ? "\u2713" : this.type === "error" ? "\u26A0" : " ";
     const prefix = spinner ?? "";
     this.onUpdate(`${icon} ${this.message}  ${prefix}`.trim());
   }
   dispose() {
+    this.disposed = true;
     this.stopSpinner();
   }
 };
+function createStatusManager(bar, onFrame) {
+  return new StatusManager((text) => {
+    if (bar.isDestroyed) return;
+    bar.content = ` ${text}`;
+    onFrame();
+  });
+}
 
 // src/share.ts
 import { spawn as spawn3 } from "child_process";
@@ -5270,13 +5292,15 @@ function createTuiLogger() {
   };
 }
 var logger = createTuiLogger();
+var activeStatusMgr = null;
+var activeRenderer = null;
 var SORT_MODES = [
   { key: "best-match", label: "best-match" },
   { key: "stars", label: "stars" },
   { key: "updated", label: "updated" },
   { key: "forks", label: "forks" }
 ];
-async function launchBrowser(theme_override) {
+async function launchBrowser(theme_override, startMode) {
   const terminalBg = await detectTerminalBackground();
   let renderer;
   try {
@@ -5312,6 +5336,7 @@ async function launchBrowser(theme_override) {
     return;
   }
   const root = renderer.root;
+  activeRenderer = renderer;
   root.flexDirection = "column";
   const config = loadConfig();
   let githubToken = config.githubToken || process.env.GITHUB_TOKEN;
@@ -5677,6 +5702,7 @@ async function launchBrowser(theme_override) {
     leaderBox.visible = false;
     leaderDim.visible = false;
     readmeBox.visible = false;
+    orgBox.visible = false;
     updateBox.visible = false;
     updateDim.visible = false;
     if (type === "none") {
@@ -6761,6 +6787,7 @@ async function launchBrowser(theme_override) {
     }
   });
   const orgText = new TextRenderable5(renderer, {
+    ...NON_INTERACTIVE_TEXT,
     content: "",
     fg: colors.text,
     bg: colors.bg
@@ -6768,6 +6795,7 @@ async function launchBrowser(theme_override) {
   orgScroll.add(orgText);
   orgBox.add(orgScroll);
   const orgFooter = new TextRenderable5(renderer, {
+    ...NON_INTERACTIVE_TEXT,
     content: "  \u2191\u2193/jk scroll  Esc/q close",
     fg: colors.muted,
     bg: colors.bg,
@@ -6941,10 +6969,12 @@ async function launchBrowser(theme_override) {
     menuButtonLabel.fg = colors.muted;
     renderer.requestRender();
   };
-  const statusMgr = new StatusManager((text) => {
-    statusBar.content = ` ${text}`;
-    renderer.requestRender();
-  });
+  activeStatusMgr = createStatusManager(
+    statusBar,
+    () => renderer.requestRender()
+  );
+  const statusMgr = activeStatusMgr;
+  renderer.on("destroy", () => statusMgr.dispose());
   setTimeout(() => {
     if (currentOverlay === "none") {
       setStatus(nextTip());
@@ -8037,7 +8067,12 @@ ${pack.description ?? ""}`;
     }
   });
   const _currentVersion = getVersion();
-  showLanding(true);
+  if (startMode === "trending") {
+    showLanding(false);
+    loadTrending();
+  } else {
+    showLanding(true);
+  }
   checkForUpdateAndShow();
   checkPostUpgradePanel();
   renderer.start();
@@ -8054,10 +8089,17 @@ function formatToolbar(sort, limit, totalCount) {
   return ` sort: ${sortLabel}   limit: ${limit}   results: ${totalCount.toLocaleString()}`;
 }
 function cleanup() {
+  activeStatusMgr?.dispose();
+  activeStatusMgr = null;
   try {
     rotateHistory();
   } catch {
   }
+  try {
+    activeRenderer?.destroy();
+  } catch {
+  }
+  activeRenderer = null;
   process.exit(0);
 }
 if (import.meta.main && false) {
@@ -8729,7 +8771,7 @@ var TOOLS = [
         token: resolveToken(state, args.token),
         limit
       });
-      return { text: formatUserJson(profile), data: { ...profile } };
+      return { text: formatUserText(profile), data: { ...profile } };
     }
   },
   {
@@ -9076,6 +9118,7 @@ var SORT_VALUES = [
   "downloads",
   "name"
 ];
+var SINCE_VALUES = ["daily", "weekly", "monthly"];
 function parseArgs(args) {
   const flags = {
     query: "",
@@ -9088,6 +9131,7 @@ function parseArgs(args) {
     token: process.env.GITHUB_TOKEN,
     trending: false,
     since: "daily",
+    sinceExplicit: false,
     watch: false,
     releases: false,
     interval: 300,
@@ -9188,15 +9232,51 @@ function parseArgs(args) {
       case "--token":
         flags.token = args[++i];
         break;
-      case "--since":
-        flags.since = args[++i];
+      case "--interval": {
+        const parsed = parseInt(args[++i], 10);
+        if (Number.isNaN(parsed) || parsed < 1) {
+          console.error(
+            `Invalid interval: ${args[i] ?? "(missing)"} (must be a whole number of seconds, e.g. 300).`
+          );
+          process.exit(1);
+        }
+        flags.interval = parsed;
+        break;
+      }
+      case "--since": {
+        const since = args[++i];
+        if (!since || !SINCE_VALUES.includes(since)) {
+          console.error(
+            `Invalid since: ${since ?? "(missing)"} (use daily|weekly|monthly).`
+          );
+          process.exit(1);
+        }
+        flags.since = since;
+        flags.sinceExplicit = true;
         break;
-      case "--pipe":
-        flags.pipe = args[++i];
+      }
+      case "--pipe": {
+        const target = args[++i];
+        if (!target || !PIPE_TARGETS.includes(target)) {
+          console.error(
+            `Invalid pipe target: ${target ?? "(missing)"} (use open|clone).`
+          );
+          process.exit(1);
+        }
+        flags.pipe = target;
         break;
-      case "--format":
-        flags.format = args[++i];
+      }
+      case "--format": {
+        const fmt = args[++i];
+        if (!fmt || !FORMAT_VALUES.includes(fmt)) {
+          console.error(
+            `Invalid format: ${fmt ?? "(missing)"} (use ${FORMAT_VALUES.join("|")}).`
+          );
+          process.exit(1);
+        }
+        flags.format = fmt;
         break;
+      }
       case "--registry":
         flags.registry = args[++i] ?? "npm";
         break;
@@ -9485,7 +9565,13 @@ Options:
     await runNonInteractive(flags, outputFormat);
     return;
   }
-  await launchBrowser(flags.theme);
+  await launchBrowser(
+    flags.theme,
+    // `ghfind --trending` with no query/format promises the trending view
+    // (TRACKER.md), but the bare flag used to fall through to the landing
+    // menu. An explicit flag is explicit intent — skip the menu.
+    flags.trending ? "trending" : void 0
+  );
 }
 function buildSearchContext(flags) {
   const parsed = applyFlagFilters(parseQuery(flags.query), {});
@@ -9950,7 +10036,8 @@ async function runNonInteractive(flags, outputFormat) {
           limit: flags.limit,
           token: flags.token,
           intervalMs: flags.interval * 1e3,
-          trending: flags.trending
+          trending: flags.trending,
+          since: flags.sinceExplicit ? flags.since : void 0
         },
         (repos, delta) => {
           tick++;
@@ -10038,6 +10125,16 @@ Not found: ${missing.join(", ")}` : "";
     }
   };
   const key = flags.compare.length > 0 ? "compare" : flags.trending && !flags.watch ? "trending" : flags.watch ? "watch" : flags.pipe ? "pipe" : flags.format ? "format" : "search";
+  const needsQuery = key === "search" || key === "format" || key === "pipe" || key === "watch" && !flags.trending;
+  if (needsQuery && flags.query.trim() === "") {
+    console.error("\u26A0 No search query given.");
+    console.error(
+      '  Usage: ghfind "<query>" [--count|--format <fmt>|--pipe <tgt>|--watch]'
+    );
+    console.error('  Example: ghfind "language:Rust stars:>500" --count');
+    console.error("  Run `ghfind --help` for all options.");
+    process.exit(1);
+  }
   const ctx = buildSearchContext(flags);
   await handlers[key](ctx);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "github-search-cli",
-  "version": "9.10.0",
+  "version": "9.10.1",
   "description": "Search GitHub from your terminal — repo search, trending repos, npm package search, bookmarks, deep-dive, compare, export. Keyboard + mouse TUI + pipeable CLI.",
   "type": "module",
   "packageManager": "bun@1",

package/release-notes/9.10.1.md

@@ -0,0 +1,59 @@
+# v9.10.1
+
+A bug-fix release, found by crawling the whole source against its own docs.
+Three of the eight issues were the kind that quietly cost you time: a flag
+that was documented everywhere but never parsed, a typo that opened a GitHub
+issue tab instead of printing an error, and an empty query that came back as
+a network problem you didn't have.
+
+## `--interval` was never parsed
+
+`--interval` appeared in `--help`, the README, the how-to guide and all
+three shell completions. `parseArgs` had no case for it. So
+`ghfind --watch --interval 60` searched for the literal string
+`"--interval 60"` and polled at the default 300s anyway. It now parses a
+positive whole number of seconds — and rejects anything else with a message
+instead of a mangled query.
+
+## A typo used to open a GitHub issue tab
+
+`--format jsonn` threw `Unknown format` from inside the run, which the top
+level error handler classified as unexpected: it printed "ghfind encountered
+an unexpected error" and opened a prefilled GitHub issue page in your
+browser. `--pipe clonee` was the opposite failure — it did nothing at all
+and exited 0.
+
+Both flags now validate up front, print the list of valid values, and exit 1
+before any search happens.
+
+## An empty query was a network error
+
+`ghfind --count` with no query sent `q=" "` to GitHub, got a 422 back, and
+surfaced it as `⚠ Network error — check your connection. Retrying in 5s...`
+— a connectivity problem you didn't have, on a loop. The search, format,
+pipe and watch handlers now fail fast with a usage hint instead.
+
+## The rest
+
+- **Bare `ghfind --trending` opens the trending view.** It used to fall
+  through to the landing menu, contradicting TRACKER.md.
+- **`--since` validates its value** (`daily|weekly|monthly`) instead of
+  silently falling back to daily — the same treatment `--sort` already had.
+- **Watch mode honors `--since`.** The trending period was derived from the
+  query string, so `--watch --trending --since weekly` polled daily. An
+  explicit `--since` wins; the query-string convention still works when the
+  flag is absent.
+- **The MCP `ghfind_user_profile` tool returns formatted text**, matching
+  `ghfind_org_profile` and the CLI's default `ghfind user` output — the raw
+  JSON still rides along in `data`.
+- **The trending footer matches its `/` key** (`/ top` — it scrolls to the
+  top, it never opened search), and the quit paths of the main TUI, trending
+  and package browser now call `renderer.destroy()` before exiting, so the
+  terminal is released properly.
+
+## Removed
+
+Dead code with no importers: `src/search-state.ts` (still referenced the
+pre-unification `config.githubTokens`), `src/export.ts` and `src/pipe.ts`
+(byte-for-byte duplicates of `src/output.ts`, which is what everything
+imports), and the unused `historyCount()` export.

package/src/cli.ts

@@ -25,6 +25,8 @@ import { reportError } from "./error-report";
 import {
   format as formatOutput,
   pipeExec,
+  FORMAT_VALUES,
+  PIPE_TARGETS,
   type Format,
   type ExportFormat,
 } from "./output";
@@ -104,6 +106,8 @@ interface CLIFlags {
   token?: string;
   trending: boolean;
   since: string;
+  /** True when --since was passed (watch falls back to the query-string convention otherwise). */
+  sinceExplicit: boolean;
   pipe?: string;
   format?: string;
   watch: boolean;
@@ -156,6 +160,9 @@ const SORT_VALUES = [
   "name",
 ];
 
+/** Valid `--since` values — the periods github.com/trending accepts. */
+const SINCE_VALUES: readonly string[] = ["daily", "weekly", "monthly"];
+
 function parseArgs(args: string[]): CLIFlags {
   const flags: CLIFlags = {
     query: "",
@@ -168,6 +175,7 @@ function parseArgs(args: string[]): CLIFlags {
     token: process.env.GITHUB_TOKEN,
     trending: false,
     since: "daily",
+    sinceExplicit: false,
     watch: false,
     releases: false,
     interval: 300,
@@ -276,15 +284,51 @@ function parseArgs(args: string[]): CLIFlags {
       case "--token":
         flags.token = args[++i];
         break;
-      case "--since":
-        flags.since = args[++i];
+      case "--interval": {
+        const parsed = parseInt(args[++i], 10);
+        if (Number.isNaN(parsed) || parsed < 1) {
+          console.error(
+            `Invalid interval: ${args[i] ?? "(missing)"} (must be a whole number of seconds, e.g. 300).`,
+          );
+          process.exit(1);
+        }
+        flags.interval = parsed;
         break;
-      case "--pipe":
-        flags.pipe = args[++i];
+      }
+      case "--since": {
+        const since = args[++i];
+        if (!since || !SINCE_VALUES.includes(since)) {
+          console.error(
+            `Invalid since: ${since ?? "(missing)"} (use daily|weekly|monthly).`,
+          );
+          process.exit(1);
+        }
+        flags.since = since;
+        flags.sinceExplicit = true;
         break;
-      case "--format":
-        flags.format = args[++i];
+      }
+      case "--pipe": {
+        const target = args[++i];
+        if (!target || !PIPE_TARGETS.includes(target)) {
+          console.error(
+            `Invalid pipe target: ${target ?? "(missing)"} (use open|clone).`,
+          );
+          process.exit(1);
+        }
+        flags.pipe = target;
+        break;
+      }
+      case "--format": {
+        const fmt = args[++i];
+        if (!fmt || !FORMAT_VALUES.includes(fmt)) {
+          console.error(
+            `Invalid format: ${fmt ?? "(missing)"} (use ${FORMAT_VALUES.join("|")}).`,
+          );
+          process.exit(1);
+        }
+        flags.format = fmt;
         break;
+      }
       case "--registry":
         flags.registry = args[++i] ?? "npm";
         break;
@@ -636,7 +680,13 @@ Options:
     return;
   }
 
-  await launchBrowser(flags.theme);
+  await launchBrowser(
+    flags.theme,
+    // `ghfind --trending` with no query/format promises the trending view
+    // (TRACKER.md), but the bare flag used to fall through to the landing
+    // menu. An explicit flag is explicit intent — skip the menu.
+    flags.trending ? "trending" : undefined,
+  );
 }
 
 interface SearchContext {
@@ -1197,6 +1247,7 @@ async function runNonInteractive(flags: CLIFlags, outputFormat?: ExportFormat) {
           token: flags.token,
           intervalMs: flags.interval * 1000,
           trending: flags.trending,
+          since: flags.sinceExplicit ? flags.since : undefined,
         },
         (repos, delta) => {
           tick++;
@@ -1298,6 +1349,25 @@ async function runNonInteractive(flags: CLIFlags, outputFormat?: ExportFormat) {
               ? "format"
               : "search";
 
+  // The search/format/pipe/watch handlers all need a query. Without this
+  // gate an empty query was sent to GitHub as `q=" "`, which returns 422 and
+  // surfaced to the user as a misleading "Network error — check your
+  // connection" retry loop.
+  const needsQuery =
+    key === "search" ||
+    key === "format" ||
+    key === "pipe" ||
+    (key === "watch" && !flags.trending);
+  if (needsQuery && flags.query.trim() === "") {
+    console.error("⚠ No search query given.");
+    console.error(
+      '  Usage: ghfind "<query>" [--count|--format <fmt>|--pipe <tgt>|--watch]',
+    );
+    console.error('  Example: ghfind "language:Rust stars:>500" --count');
+    console.error("  Run `ghfind --help` for all options.");
+    process.exit(1);
+  }
+
   const ctx = buildSearchContext(flags);
   await handlers[key](ctx);
 }

package/src/history.ts

@@ -29,6 +29,10 @@ export function readHistory(): HistoryEntry[] {
 
 /** Delete a single history entry by index (0 = newest). */
 export function deleteHistoryEntry(index: number): void {
+  // The index comes from the overlay, which lists readHistory()'s deduplicated
+  // newest-first view — so delete against that same view. Raw lines can't be
+  // addressed by this index: consecutive duplicate queries are collapsed in
+  // the view, which shifts every raw-line position after them.
   const entries = readHistory();
   if (index < 0 || index >= entries.length) return;
   entries.splice(index, 1);
@@ -59,8 +63,3 @@ export function rotateHistory(): void {
       .join("\n")}\n`,
   );
 }
-
-/** Count entries in history file. */
-export function historyCount(): number {
-  return readJSONL<HistoryEntry>(HISTORY_FILE).length;
-}

package/src/mcp-server.ts

@@ -38,7 +38,7 @@ import {
   type PackageSortMode,
 } from "./package";
 import { fetchOrgProfile, formatOrgText } from "./org";
-import { fetchUserProfile, formatUserJson } from "./user";
+import { fetchUserProfile, formatUserText } from "./user";
 import {
   fetchDeepDive,
   buildDeepDiveText,
@@ -511,7 +511,9 @@ const TOOLS: ToolDefinition[] = [
         token: resolveToken(state, args.token),
         limit,
       });
-      return { text: formatUserJson(profile), data: { ...profile } };
+      // Human-readable text like ghfind_org_profile (the structured data
+      // still rides along in `data` for callers that want the raw numbers).
+      return { text: formatUserText(profile), data: { ...profile } };
     },
   },
   {