github-search-cli 9.8.0 → 9.8.1

package/dist/cli.js

@@ -1538,7 +1538,7 @@ var cached = null;
 function getVersion() {
   if (cached) return cached;
   if (true) {
-    cached = "9.8.0";
+    cached = "9.8.1";
     return cached;
   }
   try {
@@ -2309,6 +2309,12 @@ function removeBookmark(fullName) {
   const bookmarks = loadRaw().filter((b) => b.repo.fullName !== fullName);
   saveRaw(bookmarks);
 }
+function searchBookmarks(query) {
+  const q = query.toLowerCase();
+  return getBookmarks().filter(
+    (b) => b.repo.fullName.toLowerCase().includes(q) || (b.repo.description ?? "").toLowerCase().includes(q) || b.tags.some((t3) => t3.toLowerCase().includes(q))
+  );
+}
 function getLastSeen(fullName) {
   return loadRaw().find((b) => b.repo.fullName === fullName)?.lastSeenAt ?? 0;
 }
@@ -2946,8 +2952,8 @@ function buildDeepDiveText(data) {
 }
 
 // src/cli.ts
-import { readFileSync as readFileSync6 } from "fs";
-import { join as join6, dirname as dirname4 } from "path";
+import { readFileSync as readFileSync7 } from "fs";
+import { join as join7, dirname as dirname4 } from "path";
 import { fileURLToPath as fileURLToPath4 } from "url";
 
 // src/tui.ts
@@ -3577,7 +3583,25 @@ var RAW_HOSTS = /* @__PURE__ */ new Set([
 ]);
 var RASTER_EXT = /\.(png|jpe?g|webp|gif|bmp|avif|heic|tiff?)(?:[?#]|$)/i;
 var CACHE_LIMIT = 24;
+var MAX_CONCURRENT_IMAGE_FETCHES = 4;
 var cache = /* @__PURE__ */ new Map();
+var activeFetches = 0;
+var waiting = [];
+function releaseSlot() {
+  activeFetches--;
+  waiting.shift()?.();
+}
+async function withSlot(job) {
+  if (activeFetches >= MAX_CONCURRENT_IMAGE_FETCHES) {
+    await new Promise((resolve) => waiting.push(resolve));
+  }
+  activeFetches++;
+  try {
+    return await job();
+  } finally {
+    releaseSlot();
+  }
+}
 function decodeDataUri(uri) {
   const match = /^data:([^;,]+)?(;base64)?,(.*)$/is.exec(uri);
   if (!match) return null;
@@ -3660,7 +3684,7 @@ function isGitHubHost(hostname) {
 async function fetchImageBytes(url, opts = {}) {
   const cached2 = cache.get(url);
   if (cached2) return cached2;
-  const pending = loadImageBytes(url, opts);
+  const pending = withSlot(() => loadImageBytes(url, opts));
   cache.set(url, pending);
   while (cache.size > CACHE_LIMIT) {
     const oldest = cache.keys().next().value;
@@ -3793,6 +3817,7 @@ function extractImageRefs(token) {
 
 // src/markdown-view.ts
 var MAX_IMAGE_ROWS = 24;
+var RASTER_CACHE_LIMIT = 32;
 function createMarkdownStyle(colors2) {
   const surface = colors2.surface ?? colors2.bg;
   return SyntaxStyle.fromStyles({
@@ -3887,6 +3912,11 @@ function createMarkdownView(opts) {
       });
     })();
     rasterCache.set(key, pending);
+    while (rasterCache.size > RASTER_CACHE_LIMIT) {
+      const oldest = rasterCache.keys().next().value;
+      if (oldest === void 0) break;
+      rasterCache.delete(oldest);
+    }
     return pending;
   };
   const imageNode = (image) => {
@@ -3902,9 +3932,6 @@ function createMarkdownView(opts) {
     container.add(placeholder);
     void rasterize(url).then(
       (cells) => {
-        console.error(
-          `[dbg] image resolved: cells=${cells ? `${cells.cols}x${cells.rows}` : "null"} destroyed=${container.isDestroyed} parent=${!!container.parent} enabled=${imagesEnabled}`
-        );
         if (container.isDestroyed || !container.parent) return;
         container.remove(placeholder);
         placeholder.destroy();
@@ -3923,7 +3950,7 @@ function createMarkdownView(opts) {
         renderable.requestRender();
       },
       (err) => {
-        console.error("[dbg] image promise rejected:", err);
+        void err;
       }
     );
     return container;
@@ -3978,6 +4005,8 @@ function createMarkdownView(opts) {
       renderable.fg = text();
       renderable.bg = bg();
       renderable.content = markdown;
+      renderable.streaming = false;
+      renderable.requestRender();
     },
     setImagesEnabled(enabled) {
       if (imagesEnabled === enabled) return;
@@ -3988,6 +4017,29 @@ function createMarkdownView(opts) {
   };
 }
 
+// src/readme.ts
+var CANDIDATES = [
+  ["main", "README.md"],
+  ["master", "README.md"],
+  ["main", "README.rst"]
+];
+async function fetchReadme(owner, repo, opts = {}) {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const headers = { "User-Agent": "ghfind/1.0" };
+  if (opts.token) headers.Authorization = `Bearer ${opts.token}`;
+  const attempts = CANDIDATES.map(async ([branch, file]) => {
+    const url = readmeBaseUrl(owner, repo, branch, file);
+    const res = await fetchImpl(url, { headers });
+    if (!res.ok) throw new Error(`no readme at ${url}`);
+    return { text: await res.text(), sourceUrl: url };
+  });
+  try {
+    return await Promise.any(attempts);
+  } catch {
+    return null;
+  }
+}
+
 // src/explore.ts
 async function fetchTopics() {
   const res = await fetch(
@@ -5889,27 +5941,13 @@ async function launchBrowser(theme_override) {
     readmeScroll.scrollTop = 0;
     showOverlay("readme");
     try {
-      const headers = { "User-Agent": "ghfind/1.0" };
-      if (githubToken) headers.Authorization = `Bearer ${githubToken}`;
-      let text = "";
-      let sourceUrl = "";
-      for (const [branch, file] of [
-        ["main", "README.md"],
-        ["master", "README.md"],
-        ["main", "README.rst"]
-      ]) {
-        const url = readmeBaseUrl(repo.owner, repo.name, branch, file);
-        const r = await fetch(url, { headers });
-        if (r.ok) {
-          text = await r.text();
-          sourceUrl = url;
-          break;
-        }
-      }
-      if (!text) {
-        readmeView.setContent(`_(no README found for ${repo.fullName})_`);
+      const readme = await fetchReadme(repo.owner, repo.name, {
+        token: githubToken
+      });
+      if (readme) {
+        readmeView.setContent(readme.text, readme.sourceUrl);
       } else {
-        readmeView.setContent(text, sourceUrl);
+        readmeView.setContent(`_(no README found for ${repo.fullName})_`);
       }
     } catch {
       readmeView.setContent("_Failed to load README._");
@@ -6931,6 +6969,12 @@ reported in text output and via the error message.
     ghfind deep-dive owner/repo --json
 Text output (no flag) prints the same sections formatted for the terminal.
 
+## Finding skills
+    ghfind skill search QUERY            # skills installed on this machine
+    ghfind skill search QUERY --remote   # the public skills.sh ecosystem
+Results carry path+description (local) or install command (registry, read-only --
+nothing is installed). The MCP server exposes the same search as
+ghfind_skill_search.
 ## Rate limits
 
 60 req/hr unauthenticated, 5,000 with GITHUB_TOKEN (env var or \`ghfind login\`).
@@ -6942,6 +6986,14 @@ Bookmarks live in ghfind's local state, not GitHub. An agent can read the
 release feed with:
     ghfind --releases --json
 Marking releases seen and editing bookmarks is a TUI action; skip it.
+## Local state (read-only)
+    ghfind bookmarks [QUERY] --json    # saved repos, newest first
+    ghfind history [QUERY] --json      # past searches
+    ghfind saved --json                # named searches
+    ghfind topics --json               # popular GitHub topics
+    ghfind readme owner/repo           # print a repo README
+    ghfind share owner/repo --as gh-cli|markdown|plain|short
+These never write local state; skip them when nothing needs reading.
 
 ## Token efficiency
 
@@ -6981,6 +7033,233 @@ function formatSkillCatalog() {
   ].join("\n");
 }
 
+// src/skill-finder.ts
+import { readdirSync, readFileSync as readFileSync6 } from "fs";
+import { homedir as homedir3 } from "os";
+import { delimiter, join as join6 } from "path";
+var REGISTRY_SEARCH_ENDPOINT = "https://skills.sh/api/search";
+var MIN_QUERY_LENGTH = 2;
+var MAX_SKILL_RESULTS = 100;
+function displayPath(path) {
+  const home = homedir3();
+  const normalized = path.replace(/\\/g, "/");
+  const homeNorm = home.replace(/\\/g, "/").replace(/\/$/, "");
+  if (normalized === homeNorm) return "~";
+  if (normalized.startsWith(`${homeNorm}/`)) {
+    return `~${normalized.slice(homeNorm.length)}`;
+  }
+  return normalized;
+}
+function defaultSkillRoots(cwd = process.cwd()) {
+  const home = homedir3();
+  return [
+    join6(home, ".codex", "skills"),
+    join6(home, ".agents", "skills"),
+    join6(cwd, ".codex", "skills"),
+    join6(cwd, ".github", "skills")
+  ];
+}
+function resolveSkillRoots(cwd = process.cwd()) {
+  const override = process.env.GHFIND_SKILL_ROOTS;
+  const paths = override?.trim() ? override.split(delimiter).filter((p) => p.trim()).map((p) => p.trim()) : defaultSkillRoots(cwd);
+  return paths.map((path) => ({ path, label: displayPath(path) }));
+}
+var SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", ".git"]);
+var MAX_DEPTH = 4;
+function unquote(value) {
+  const trimmed = value.trim();
+  if (trimmed.length >= 2 && (trimmed.startsWith('"') && trimmed.endsWith('"') || trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+    return trimmed.slice(1, -1).trim();
+  }
+  return trimmed;
+}
+function parseSkillFrontmatter(text) {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+  if (!match) return null;
+  const lines = match[1].split(/\r?\n/);
+  const fields = {};
+  for (let i = 0; i < lines.length; i++) {
+    const field = /^([A-Za-z_][\w-]*):[ \t]*(.*)$/.exec(lines[i]);
+    if (!field) continue;
+    const key = field[1].toLowerCase();
+    const inline = field[2].trim();
+    if (inline === ">" || inline === "|" || /^[>|][-+]?$/.test(inline)) {
+      const literal = inline.startsWith("|");
+      const parts = [];
+      while (i + 1 < lines.length && /^[ \t]+\S/.test(lines[i + 1])) {
+        parts.push(lines[++i].trim());
+      }
+      fields[key] = literal ? parts.join("\n") : parts.join(" ");
+    } else {
+      fields[key] = unquote(inline);
+    }
+  }
+  const name = fields.name ?? "";
+  if (!name) return null;
+  return { name, description: fields.description ?? "" };
+}
+function scanLocalSkills(roots = resolveSkillRoots()) {
+  const byName = /* @__PURE__ */ new Map();
+  for (const root of roots) {
+    for (const dir of walkDirs(root.path)) {
+      const entries = listDir(dir);
+      if (!entries) continue;
+      if (!entries.some((e) => e.isFile() && e.name === "SKILL.md")) continue;
+      const file = join6(dir, "SKILL.md");
+      try {
+        const parsed = parseSkillFrontmatter(readFileSync6(file, "utf-8"));
+        if (!parsed || byName.has(parsed.name)) continue;
+        byName.set(parsed.name, {
+          name: parsed.name,
+          description: parsed.description.replace(/\s+/g, " ").trim(),
+          path: file,
+          origin: root.label
+        });
+      } catch {
+      }
+    }
+  }
+  return [...byName.values()];
+}
+function listDir(dir) {
+  try {
+    return readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+}
+function* walkDirs(root) {
+  const queue = [[root, 0]];
+  while (queue.length > 0) {
+    const [dir, depth] = queue.shift();
+    const entries = listDir(dir);
+    if (!entries) continue;
+    yield dir;
+    if (depth >= MAX_DEPTH) continue;
+    for (const entry of entries) {
+      if (!entry.isDirectory() || SKIP_DIRS.has(entry.name)) continue;
+      queue.push([join6(dir, entry.name), depth + 1]);
+    }
+  }
+}
+function localMatchTier(hit, needle) {
+  const name = hit.name.toLowerCase();
+  if (name === needle) return 0;
+  if (name.startsWith(needle)) return 1;
+  if (name.includes(needle)) return 2;
+  if (hit.description.toLowerCase().includes(needle)) return 3;
+  return null;
+}
+function rankLocalSkills(hits, query, limit = MAX_SKILL_RESULTS) {
+  const needle = query.trim().toLowerCase();
+  return hits.map((hit) => ({ hit, tier: localMatchTier(hit, needle) })).filter(
+    (entry) => entry.tier !== null
+  ).sort((a, b) => a.tier - b.tier || a.hit.name.localeCompare(b.hit.name)).slice(0, clampLimit(limit)).map((entry) => entry.hit);
+}
+function clampLimit(limit) {
+  const n = Math.trunc(Number(limit));
+  if (!Number.isFinite(n)) return MAX_SKILL_RESULTS;
+  return Math.min(Math.max(n, 1), MAX_SKILL_RESULTS);
+}
+function assertSearchableQuery(query) {
+  const trimmed = query.trim();
+  if (trimmed.length < MIN_QUERY_LENGTH) {
+    throw new Error(
+      `Query must be at least ${MIN_QUERY_LENGTH} characters (got "${trimmed}").`
+    );
+  }
+  return trimmed;
+}
+function searchLocalSkills(query, opts = {}) {
+  const trimmed = assertSearchableQuery(query);
+  const skills = rankLocalSkills(
+    scanLocalSkills(opts.roots ?? resolveSkillRoots()),
+    trimmed,
+    opts.limit ?? MAX_SKILL_RESULTS
+  );
+  return { query: trimmed, source: "local", count: skills.length, skills };
+}
+function normalizeRegistrySkill(raw) {
+  if (typeof raw !== "object" || raw === null) return null;
+  const obj = raw;
+  const source = typeof obj.source === "string" ? obj.source : "";
+  const skillId = typeof obj.skillId === "string" ? obj.skillId : "";
+  if (!source || !skillId) return null;
+  const name = typeof obj.name === "string" && obj.name.trim() ? obj.name : skillId;
+  const installs = typeof obj.installs === "number" ? obj.installs : 0;
+  const id = typeof obj.id === "string" && obj.id ? obj.id : `${source}/${skillId}`;
+  return {
+    id,
+    source,
+    skillId,
+    name,
+    installs,
+    installCommand: `npx skills add ${source}@${skillId}`,
+    url: `https://skills.sh/${source}/${skillId}`
+  };
+}
+async function searchRegistrySkills(query, opts = {}) {
+  const trimmed = assertSearchableQuery(query);
+  const limit = clampLimit(opts.limit ?? MAX_SKILL_RESULTS);
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const url = `${REGISTRY_SEARCH_ENDPOINT}?q=${encodeURIComponent(trimmed)}&limit=${limit}`;
+  let res;
+  try {
+    res = await fetchImpl(url, {
+      headers: { Accept: "application/json", "User-Agent": "ghfind/1.0" }
+    });
+  } catch (err) {
+    throw new Error(
+      `Could not reach skills.sh: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  if (!res.ok) {
+    throw new Error(
+      `skills.sh returned HTTP ${res.status} for "${trimmed}". Retry, or search locally with --local.`
+    );
+  }
+  let payload;
+  try {
+    payload = await res.json();
+  } catch {
+    throw new Error("skills.sh returned a response that was not JSON.");
+  }
+  const items = payload?.skills ?? [];
+  const skills = items.map(normalizeRegistrySkill).filter((s) => s !== null).slice(0, limit);
+  return { query: trimmed, source: "registry", count: skills.length, skills };
+}
+async function searchSkills(query, opts = {}) {
+  if ((opts.source ?? "local") === "registry") {
+    return searchRegistrySkills(query, opts);
+  }
+  return searchLocalSkills(query, opts);
+}
+function formatSkillSearchJson(result) {
+  return JSON.stringify(result, null, 2);
+}
+function shortDescription(description, width = 100) {
+  if (description.length <= width) return description;
+  return `${description.slice(0, width - 1).trimEnd()}\u2026`;
+}
+function formatSkillSearchText(result) {
+  if (result.count === 0) {
+    return result.source === "local" ? `No installed skills match "${result.query}". Try --remote to search the skills.sh ecosystem.` : `No skills.sh entries match "${result.query}".`;
+  }
+  if (result.source === "local") {
+    return result.skills.map(
+      (s) => `${s.name}  (${s.origin})
+  ${shortDescription(s.description)}`
+    ).join("\n");
+  }
+  return result.skills.map(
+    (s) => `${s.name}  ${s.installs.toLocaleString()} installs  [${s.source}]
+  ${s.installCommand}`
+  ).join("\n");
+}
+function formatSkillSearchNames(result) {
+  return result.skills.map((s) => s.name).join("\n");
+}
+
 // src/mcp-server.ts
 var SUPPORTED_PROTOCOL_VERSIONS = ["2025-06-18", "2025-03-26", "2024-11-05"];
 var LATEST_PROTOCOL_VERSION = SUPPORTED_PROTOCOL_VERSIONS[0];
@@ -7043,6 +7322,7 @@ function asMcpToolError(err) {
 }
 var TRENDING_QUERY = { keywords: [], qualifiers: [], raw: "trending" };
 var REPO_SORTS = ["best-match", "stars", "updated", "forks"];
+var SKILL_SOURCES = ["local", "registry"];
 var TRENDING_SINCE = ["daily", "weekly", "monthly"];
 var PKG_SORTS = ["best-match", "score", "downloads", "name"];
 var TOOLS = [
@@ -7387,6 +7667,52 @@ Not found: ${missing.join(", ")}` : "");
         data: { name: "ghfind-cli" }
       };
     }
+  },
+  {
+    name: "ghfind_skill_search",
+    title: "Search agent skills",
+    description: "Search installed agent skills (SKILL.md files under the user's skill directories) or the public skills.sh ecosystem by keyword, and return matching skills with their descriptions. Read-only: it never installs anything - registry hits include the `npx skills add` command for the user to run deliberately. Use when the user asks to find a skill for a task, or asks what skills are available.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description: 'Keyword to match against skill names and descriptions, e.g. "changelog" or "testing" (2+ characters).'
+        },
+        source: {
+          type: "string",
+          description: "Where to search: 'local' for skills installed on this machine (default), 'registry' for the public skills.sh ecosystem.",
+          enum: [...SKILL_SOURCES]
+        },
+        limit: {
+          type: "number",
+          description: "Max results, 1-100 (default 20).",
+          minimum: 1,
+          maximum: 100
+        }
+      },
+      required: ["query"]
+    },
+    async run(args) {
+      const source = coerceEnum(
+        args.source,
+        SKILL_SOURCES,
+        "local"
+      );
+      const limit = coerceInt(args.limit, 20, 1, 100);
+      const result = await searchSkills(
+        String(args.query ?? ""),
+        { source, limit }
+      );
+      const where = result.source === "local" ? "installed skills on this machine" : "the public skills.sh ecosystem";
+      const header = `${result.count} match(es) for "${result.query}" in ${where}:`;
+      return {
+        text: `${header}
+
+${formatSkillSearchText(result)}`,
+        data: { ...result }
+      };
+    }
   }
 ];
 function toolSummaries() {
@@ -7465,7 +7791,7 @@ async function processServerLine(line, state, config) {
             title: "ghfind \u2014 GitHub search for agents",
             version: getVersion()
           },
-          instructions: "ghfind gives agents GitHub search: repositories, trending, npm packages, org/user profiles, repo comparison and deep-dives. Call ghfind_skill for the full CLI guide. Unauthenticated requests are rate-limited to 60/hr; pass a token or set GITHUB_TOKEN for 5,000/hr."
+          instructions: "ghfind gives agents GitHub search: repositories, trending, npm packages, org/user profiles, repo comparison and deep-dives. ghfind_skill_search finds agent skills, either installed on this machine or in the public skills.sh ecosystem. Call ghfind_skill for the full CLI guide. Unauthenticated requests are rate-limited to 60/hr; pass a token or set GITHUB_TOKEN for 5,000/hr."
         })
       );
       return;
@@ -7569,7 +7895,7 @@ async function runMcpServer(options = {}) {
 // src/cli.ts
 process.env.GHFIND_CLI_RUN = "1";
 var __dirname3 = dirname4(fileURLToPath4(import.meta.url));
-var PKG_DIR3 = join6(__dirname3, "..");
+var PKG_DIR3 = join7(__dirname3, "..");
 function parseArgs(args) {
   const flags = {
     query: "",
@@ -7593,7 +7919,16 @@ function parseArgs(args) {
     registry: "npm",
     compare: [],
     doctor: false,
-    mcp: false
+    mcp: false,
+    bookmarks: false,
+    history: false,
+    topics: false,
+    saved: false,
+    remote: false,
+    local: false,
+    copy: false,
+    raw: false,
+    limitExplicit: false
   };
   const queryParts = [];
   for (let i = 0; i < args.length; i++) {
@@ -7650,6 +7985,7 @@ function parseArgs(args) {
         break;
       case "--limit": {
         const parsed = parseInt(args[++i], 10);
+        flags.limitExplicit = true;
         if (Number.isNaN(parsed) || parsed < 1 || parsed > 100) {
           console.error(`Invalid limit: must be 1-100. Using default 50.`);
           flags.limit = 50;
@@ -7682,9 +8018,56 @@ function parseArgs(args) {
       case "--completion":
         flags.completion = args[++i];
         break;
+      case "--remote":
+        flags.remote = true;
+        break;
+      case "--local":
+        flags.local = true;
+        break;
+      case "--copy":
+        flags.copy = true;
+        break;
+      case "--raw":
+        flags.raw = true;
+        break;
+      case "--as":
+        flags.sharedAs = args[++i];
+        break;
       case "mcp":
         flags.mcp = true;
         break;
+      case "bookmarks":
+        flags.bookmarks = true;
+        break;
+      case "history":
+        flags.history = true;
+        break;
+      case "topics":
+        flags.topics = true;
+        break;
+      case "saved":
+        flags.saved = true;
+        break;
+      case "readme": {
+        const next = args[i + 1];
+        if (next && !next.startsWith("-")) {
+          flags.readme = next;
+          i++;
+        } else {
+          flags.readme = "";
+        }
+        break;
+      }
+      case "share": {
+        const next = args[i + 1];
+        if (next && !next.startsWith("-")) {
+          flags.share = next;
+          i++;
+        } else {
+          flags.share = "";
+        }
+        break;
+      }
       case "deep-dive": {
         const next = args[i + 1];
         if (next && !next.startsWith("-")) {
@@ -7695,6 +8078,17 @@ function parseArgs(args) {
       }
       case "skill": {
         const next = args[i + 1];
+        if (next === "search") {
+          i++;
+          const query = args[i + 1];
+          if (query && !query.startsWith("-")) {
+            flags.skillSearch = query;
+            i++;
+          } else {
+            flags.skillSearch = "";
+          }
+          break;
+        }
         if (next && !next.startsWith("-")) {
           flags.skill = next;
           i++;
@@ -7773,6 +8167,13 @@ Usage:
   ghfind pkg <query>               Search npm packages, text list
   ghfind mcp                       Run the MCP server for AI agents (stdio)
   ghfind skill [name]              Print the agent skill guide (or catalog)
+  ghfind bookmarks [query]         Saved repos, newest first
+  ghfind history [query]           Past searches, newest first
+  ghfind topics                    Browse popular GitHub topics
+  ghfind saved                     Named searches saved in the TUI
+  ghfind readme <owner/repo>       Print a repository README
+  ghfind share a/b --as gh-cli     Share snippet (--copy to clipboard)
+  ghfind skill search <query>      Find skills locally, or --remote
   ghfind --watch <query>           Watch mode (poll every Ns)
   ghfind init                      Run setup wizard
   ghfind login                     Import the gh CLI token or paste one
@@ -7797,14 +8198,19 @@ Options:
   --releases                           New-release feed for bookmarks
   --interval <s>                       Watch interval in seconds (default: 300)
   --completion <shell>                 Generate completions
+  --remote                             skill search: query skills.sh instead of this machine
+  --local                              skill search: force the local scan (default)
+  --as <fmt>                           share format: markdown|plain|gh-cli|short
+  --copy                               share: also copy the snippet to the clipboard
+  --raw                                readme: print the raw markdown with no header
 `);
     return;
   }
   if (flags.completion) {
     const shell = flags.completion;
     try {
-      const content = readFileSync6(
-        join6(PKG_DIR3, "completions", `ghfind.${shell}`),
+      const content = readFileSync7(
+        join7(PKG_DIR3, "completions", `ghfind.${shell}`),
         "utf-8"
       );
       console.log(content);
@@ -7826,10 +8232,38 @@ Options:
     await runMcpServer({ token: flags.token });
     return;
   }
+  if (flags.skillSearch !== void 0) {
+    await runSkillSearch(flags);
+    return;
+  }
   if (flags.skill !== void 0) {
     printAgentSkill(flags.skill);
     return;
   }
+  if (flags.bookmarks) {
+    runBookmarks(flags);
+    return;
+  }
+  if (flags.history) {
+    runHistory(flags);
+    return;
+  }
+  if (flags.saved) {
+    runSavedSearches(flags);
+    return;
+  }
+  if (flags.topics) {
+    await runTopics(flags);
+    return;
+  }
+  if (flags.readme !== void 0) {
+    await runReadme(flags);
+    return;
+  }
+  if (flags.share !== void 0) {
+    await runShare(flags);
+    return;
+  }
   if (flags.pkg) {
     const interactive = !flags.query && !flags.json && !flags.csv && !flags.markdown && !flags.count && !flags.format;
     if (interactive) {
@@ -7963,6 +8397,233 @@ async function runDeepDive(flags, outputFormat) {
     process.exit(1);
   }
 }
+async function runSkillSearch(flags) {
+  const query = flags.skillSearch ?? "";
+  if (!query.trim()) {
+    console.error(
+      "Usage: ghfind skill search <query> [--remote] [--limit <n>] [--json]"
+    );
+    process.exit(1);
+  }
+  if (flags.remote && flags.local) {
+    console.error(
+      "Contradictory flags: pass either --remote or --local, not both."
+    );
+    process.exit(1);
+  }
+  const source = flags.remote ? "registry" : "local";
+  try {
+    const result = await searchSkills(query, {
+      source,
+      limit: flags.limit
+    });
+    if (flags.json) {
+      console.log(formatSkillSearchJson(result));
+    } else if (flags.format === "names") {
+      console.log(formatSkillSearchNames(result));
+    } else {
+      console.log(formatSkillSearchText(result));
+    }
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+}
+function runBookmarks(flags) {
+  const query = flags.query.trim();
+  const bookmarks = query ? searchBookmarks(query) : getBookmarks();
+  if (flags.json) {
+    console.log(JSON.stringify(bookmarks, null, 2));
+    return;
+  }
+  if (bookmarks.length === 0) {
+    console.log(
+      query ? `No bookmarks match "${query}".` : "No bookmarks yet. Press Space \u2192 Bookmark in the TUI to save one."
+    );
+    return;
+  }
+  if (flags.csv || flags.markdown) {
+    const header = ["full_name", "stars", "language", "tags", "saved_at"];
+    const rows = bookmarks.map((b) => [
+      b.repo.fullName,
+      String(b.repo.stars),
+      b.repo.language ?? "",
+      b.tags.join(" "),
+      new Date(b.savedAt).toISOString().slice(0, 10)
+    ]);
+    console.log(
+      flags.csv ? rowsToCsv(header, rows) : rowsToMarkdown(header, rows)
+    );
+    return;
+  }
+  for (const b of bookmarks) {
+    const tags = b.tags.length > 0 ? `  [${b.tags.join(", ")}]` : "";
+    console.log(
+      `${b.repo.fullName}  \u2014 ${b.repo.stars.toLocaleString()}  ${b.repo.language ?? "n/a"}${tags}`
+    );
+  }
+}
+function runHistory(flags) {
+  const limit = flags.limitExplicit ? flags.limit : 20;
+  const query = flags.query.trim().toLowerCase();
+  const entries = readHistory().filter((e) => !query || e.query.toLowerCase().includes(query)).slice(0, limit);
+  if (flags.json) {
+    console.log(JSON.stringify(entries, null, 2));
+    return;
+  }
+  if (entries.length === 0) {
+    console.log(
+      query ? `No history matches "${query}".` : "No search history yet."
+    );
+    return;
+  }
+  if (flags.csv || flags.markdown) {
+    const header = ["query", "mode", "results", "when"];
+    const rows = entries.map((e) => [
+      e.query,
+      e.mode,
+      String(e.resultCount),
+      new Date(e.timestamp).toISOString()
+    ]);
+    console.log(
+      flags.csv ? rowsToCsv(header, rows) : rowsToMarkdown(header, rows)
+    );
+    return;
+  }
+  for (const e of entries) {
+    const when = new Date(e.timestamp).toISOString().slice(0, 10);
+    console.log(
+      `${e.query}  \u2014 ${e.mode}  \u2014 ${e.resultCount} results  \u2014 ${when}`
+    );
+  }
+}
+function runSavedSearches(flags) {
+  const saved = getSavedSearches();
+  if (flags.json) {
+    console.log(JSON.stringify(saved, null, 2));
+    return;
+  }
+  if (saved.length === 0) {
+    console.log("No saved searches yet. Save one from the TUI command menu.");
+    return;
+  }
+  if (flags.csv || flags.markdown) {
+    const header = ["name", "query", "mode", "limit"];
+    const rows = saved.map((s) => [s.name, s.query, s.mode, String(s.limit)]);
+    console.log(
+      flags.csv ? rowsToCsv(header, rows) : rowsToMarkdown(header, rows)
+    );
+    return;
+  }
+  for (const s of saved) {
+    console.log(`${s.name}  \u2014 ${s.query}  \u2014 ${s.mode}  \u2014 limit ${s.limit}`);
+  }
+}
+function rowsToCsv(header, rows) {
+  const quote = (value) => /[",\n]/.test(value) ? `"${value.replace(/"/g, '""')}"` : value;
+  return [header, ...rows].map((row) => row.map(quote).join(",")).join("\n");
+}
+function rowsToMarkdown(header, rows) {
+  return [
+    `| ${header.join(" | ")} |`,
+    `|${header.map(() => "---").join("|")}|`,
+    ...rows.map((row) => `| ${row.join(" | ")} |`)
+  ].join("\n");
+}
+function truncate2(text, width) {
+  if (text.length <= width) return text;
+  return `${text.slice(0, width - 1).trimEnd()}\u2026`;
+}
+function plainText(html) {
+  return html.replace(/<\/p>|<br\s*\/?>/gi, " ").replace(/<[^>]*>/g, "").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&nbsp;/g, " ").replace(/\s+/g, " ").trim();
+}
+async function runTopics(flags) {
+  try {
+    const topics = (await fetchTopics()).slice(0, flags.limit);
+    if (flags.json) {
+      console.log(JSON.stringify(topics, null, 2));
+      return;
+    }
+    if (topics.length === 0) {
+      console.log("No topics returned.");
+      return;
+    }
+    for (const t3 of topics) {
+      const description = truncate2(plainText(t3.description), 140);
+      console.log(description ? `${t3.name}  ${description}` : t3.name);
+    }
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+}
+async function runReadme(flags) {
+  const ref = flags.readme ?? "";
+  if (!ref) {
+    console.error(
+      "Usage: ghfind readme <owner/repo> [--json] [--raw] [--token <t>]"
+    );
+    process.exit(1);
+  }
+  try {
+    const { owner, name } = repoFromRef(ref);
+    const readme = await fetchReadme(owner, name, { token: flags.token });
+    if (!readme) {
+      console.error(`No README found for ${owner}/${name}.`);
+      process.exit(1);
+    }
+    if (flags.json) {
+      console.log(
+        JSON.stringify(
+          { owner, name, sourceUrl: readme.sourceUrl, text: readme.text },
+          null,
+          2
+        )
+      );
+      return;
+    }
+    if (!flags.raw) {
+      console.log(`# ${owner}/${name} README (${readme.sourceUrl})`);
+      console.log("");
+    }
+    console.log(readme.text);
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+}
+async function runShare(flags) {
+  const ref = flags.share ?? "";
+  if (!ref) {
+    console.error(
+      "Usage: ghfind share <owner/repo> [--as markdown|plain|gh-cli|short] [--copy]"
+    );
+    process.exit(1);
+  }
+  const SHARE_FORMATS = ["markdown", "plain", "gh-cli", "short"];
+  const as = flags.sharedAs ?? "markdown";
+  if (!SHARE_FORMATS.includes(as)) {
+    console.error(
+      `Invalid --as value: "${flags.sharedAs}" (use markdown|plain|gh-cli|short).`
+    );
+    process.exit(1);
+  }
+  try {
+    repoFromRef(ref);
+    const repo = await resolveRepoFromRef(ref, flags.token);
+    const text = formatShare(repo, as);
+    console.log(text);
+    if (flags.copy) {
+      const copied = await copyToClipboard(text);
+      console.error(
+        copied ? "Copied to clipboard." : "Could not copy to the clipboard on this platform."
+      );
+    }
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+}
 async function runPackageSearch(flags) {
   if (flags.registry !== "npm") {
     console.error(`Registry "${flags.registry}" not yet supported (only npm).`);