github-search-cli 9.10.3 → 9.11.0

package/CHANGELOG.md

@@ -6,6 +6,24 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). Publish
 
 ---
 
+## [9.11.0] — 2026-10-14 (released)
+
+### Added
+
+- **`ghfind clone <owner/repo>` — clone a repository to disk.** Cloning was
+  previously only reachable as a command you copy: `--pipe clone` and
+  `--format clone-commands` print `git clone …` lines. This runs it. The ref is
+  validated with the same `parseRepoRef` the other repo subcommands use, the
+  repo lands in `<dir>/<name>` (default: the cwd), and HTTPS is the default
+  transport — `--ssh` switches to `git@github.com`, `--dir <path>` moves the
+  destination root. No GitHub API call is made, so a clone is never blocked by
+  the 60/hr unauthenticated budget, and git's own output and exit code are
+  passed through untouched. The TUI gets the same action under
+  `Esc` → Repo → Clone: git runs in the background with its output captured for
+  `GHFIND_LOG`, and the status bar carries git's own diagnosis, because the TUI
+  owns the screen and cannot render a progress bar or a credential prompt.
+  `ghfind --doctor` now reports whether git is on PATH.
+
 ## [9.10.3] — 2026-10-14 (released)
 
 ### Fixed

package/README.md

@@ -87,6 +87,7 @@ ghfind "query" --count       # count only
 ghfind "query" --format urls # one URL per line
 ghfind "query" --pipe open   # open in browser
 ghfind "query" --pipe clone  # clone commands
+ghfind clone facebook/react # clone the repo into ./react (--dir, --ssh)
 ghfind --trending --json     # trending as JSON
 ghfind trending rust --json  # trending, filtered by language
 ghfind --watch "query"       # poll every 300s
@@ -192,6 +193,7 @@ ghfind --completion fish | source
 <tr><td><b>Skill search</b></td><td><code>ghfind skill search &lt;query&gt;</code> — find installed skills, or <code>--remote</code> for the skills.sh ecosystem (also <code>ghfind_skill_search</code> over MCP)</td></tr>
 <tr><td><b>Read-only state</b></td><td><code>ghfind bookmarks|history|saved|topics</code> — print local state and popular topics without modifying anything</td></tr>
 <tr><td><b>README &amp; share</b></td><td><code>ghfind readme a/b</code> and <code>ghfind share a/b --as gh-cli</code> — the TUI's <code>r</code> / <code>y</code> actions from the shell</td></tr>
+<tr><td><b>Clone</b></td><td>Menu → Clone, or <code>ghfind clone a/b</code> — clone the repo to disk (HTTPS, or <code>--ssh</code>; <code>--dir</code> picks the destination)</td></tr>
 </table>
 
 <details>
@@ -261,6 +263,7 @@ Actions shown depend on current mode (search vs trending) and selection:
 | Compare         | Add/remove repo to comparison set                       |
 | Compare view    | Show side-by-side comparison table                      |
 | Open in browser | Open selected repo URL                                  |
+| Clone           | Clone the repo to disk (into the cwd)                   |
 | History         | Recall past searches                                    |
 | Saved searches  | Load a saved search                                     |
 | Save search     | Save current query                                      |
@@ -348,14 +351,14 @@ cd ghfind
 # With Bun (recommended for TUI)
 bun install
 bun start        # TUI
-bun test         # 682 tests
+bun test         # 705 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         # 682 tests
+npm test         # 705 tests
 npm run build    # build dist/
 
 > Want to contribute? See [CONTRIBUTING.md](CONTRIBUTING.md) for commands,
@@ -389,6 +392,12 @@ for the architecture, measurements, and remaining work.
 
 Recent releases (full history in [CHANGELOG.md](CHANGELOG.md)):
 
+### v9.11.0
+
+- **`ghfind clone <owner/repo>` clones to disk** — until now cloning was only a command you copy (`--pipe clone` printed `git clone …` lines); the new subcommand runs it, into `<dir>/<name>` (default: the cwd), over HTTPS or `--ssh` for the `git@github.com` form, and with no GitHub API call, so a spent unauthenticated budget can never block a clone
+- **`Esc` → Repo → Clone in the TUI** — git runs in the background because the TUI owns the screen: full output goes to `GHFIND_LOG` and the status bar carries git's own diagnosis; `--pipe clone` keeps printing commands for scripts, and git's exit codes are passed through (128 stays 128)
+- **`ghfind --doctor` reports whether git is on PATH** — a warning rather than a failure, since only `clone` needs it
+
 ### v9.10.3
 
 - **The help overlay lists `Ctrl+E`** — the utility-keys section documented `t`, `Ctrl+X` and `Ctrl+C` but not the export shortcut the startup tip and the README already advertised
@@ -397,17 +406,6 @@ Recent releases (full history in [CHANGELOG.md](CHANGELOG.md)):
 
 - **`Ctrl+E` opens the export chooser** — the startup tip advertised "Press Ctrl+E to export results as CSV or Markdown", but nothing bound the chord: it was ignored on the results screen and, while the query input had focus, its emacs binding read it as "move to line end"; it now opens the export overlay (JSON / CSV / Markdown / plain text), or reports that there is nothing to export yet
 
-### 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
-
 ## License
 
 MIT

package/completions/ghfind.bash

@@ -7,7 +7,7 @@ _ghfind() {
   cur="${COMP_WORDS[COMP_CWORD]}"
   prev="${COMP_WORDS[COMP_CWORD-1]}"
 
-  opts="--json --csv --markdown --count --limit --sort --token --trending --language --since --pipe --format --registry --watch --interval --version --help --completion --remote --local --copy --raw --as pkg login init doctor org user mcp skill bookmarks history topics saved readme share trending deep-dive compare"
+  opts="--json --csv --markdown --count --limit --sort --token --trending --language --since --pipe --format --registry --watch --interval --version --help --completion --remote --local --copy --raw --as --dir --ssh pkg login init doctor org user mcp skill bookmarks history topics saved readme share clone trending deep-dive compare"
 
   case "${prev}" in
     --sort)
@@ -42,7 +42,7 @@ _ghfind() {
       COMPREPLY=( $(compgen -W "rust python typescript javascript go c c++ c# java ruby php swift kotlin zig" -- "${cur}") )
       return 0
       ;;
-    --limit|--interval)
+    --limit|--interval|--dir)
       return 0
       ;;
     *)

package/completions/ghfind.fish

@@ -25,5 +25,7 @@ complete -c ghfind -l remote -d "Skill search: query skills.sh instead of this m
 complete -c ghfind -l local -d "Skill search: force the local scan (default)"
 complete -c ghfind -l copy -d "Share: also copy the snippet to the clipboard"
 complete -c ghfind -l raw -d "Readme: print the raw markdown with no header"
+complete -c ghfind -l dir -d "Clone: directory to clone into (default: cwd)" -r
+complete -c ghfind -l ssh -d "Clone: clone over SSH (git@github.com)"
 
-complete -c ghfind -f -a "login init doctor org user bookmarks history topics saved readme share pkg mcp skill trending deep-dive compare"
+complete -c ghfind -f -a "login init doctor org user bookmarks history topics saved readme share clone pkg mcp skill trending deep-dive compare"

package/completions/ghfind.zsh

@@ -28,6 +28,8 @@ _ghfind() {
     '--local[Skill search: force the local scan (default)]'
     '--copy[Share: also copy the snippet to the clipboard]'
     '--raw[Readme: print the raw markdown with no header]'
+    '--dir[Clone: directory to clone into (default: cwd)]:path:'
+    '--ssh[Clone: clone over SSH (git@github.com)]'
 
     'login[Import a GitHub token from the gh CLI or paste one]'
     'init[Run the setup wizard]'
@@ -40,6 +42,7 @@ _ghfind() {
     'saved[List saved searches]'
     'readme[Print a repository README]:owner/repo:'
     'share[Print a share snippet]:owner/repo:'
+    'clone[Clone a repo to disk]:owner/repo:'
     'pkg[Search packages]:query:'
     'trending[Trending repos, optionally by language]'
     'deep-dive[Repo deep-dive: languages, contributors, README]:owner/repo:'

package/dist/cli.js

@@ -1304,7 +1304,7 @@ async function detectTerminalBackground(timeoutMs = 400) {
   const setRawMode = stdin.setRawMode;
   if (!stdout.isTTY || !stdin.isTTY || typeof setRawMode !== "function")
     return null;
-  return new Promise((resolve) => {
+  return new Promise((resolve2) => {
     const wasRaw = stdin.isRaw === true;
     let settled = false;
     let buffer = "";
@@ -1318,7 +1318,7 @@ async function detectTerminalBackground(timeoutMs = 400) {
       } catch {
       }
       stdin.pause();
-      resolve(result);
+      resolve2(result);
     };
     const onData = (d) => {
       buffer += d.toString("latin1");
@@ -1732,10 +1732,10 @@ function persistToken(token, deps) {
 }
 function createAsk() {
   const rl = createInterface({ input: process.stdin, output: process.stdout });
-  return (query) => new Promise((resolve) => {
+  return (query) => new Promise((resolve2) => {
     rl.question(query, (answer) => {
       rl.close();
-      resolve(answer.trim());
+      resolve2(answer.trim());
     });
   });
 }
@@ -1905,6 +1905,19 @@ function checkSystemBun(bundledOk) {
     );
   }
 }
+function checkGit() {
+  const res = run("git", ["--version"]);
+  const version = res.stdout.trim();
+  if (res.status === 0 && version) {
+    add("PASS", "git", `${version} \u2014 used by \`ghfind clone\`.`);
+    return;
+  }
+  add(
+    "WARN",
+    "git",
+    "not found on PATH \u2014 `ghfind clone` will fail; every other command works. Install: https://git-scm.com/downloads"
+  );
+}
 function checkNodeVersion() {
   const major = parseInt(process.version.replace(/^v/, "").split(".")[0], 10);
   if (Number.isNaN(major) || major >= 20) {
@@ -2125,6 +2138,7 @@ async function runDoctor() {
   const bundled = checkBundledBun();
   checkSystemBun(bundled.ok);
   checkNodeVersion();
+  checkGit();
   checkBuildOutput();
   checkSource();
   checkTuiBackend();
@@ -2154,7 +2168,7 @@ var cached = null;
 function getVersion() {
   if (cached) return cached;
   if (true) {
-    cached = "9.10.3";
+    cached = "9.11.0";
     return cached;
   }
   try {
@@ -3176,10 +3190,10 @@ function allCachedReleases() {
 import { createInterface as createInterface2 } from "readline";
 function ask(query) {
   const rl = createInterface2({ input: process.stdin, output: process.stdout });
-  return new Promise((resolve) => {
+  return new Promise((resolve2) => {
     rl.question(query, (answer) => {
       rl.close();
-      resolve(answer.trim());
+      resolve2(answer.trim());
     });
   });
 }
@@ -3452,7 +3466,7 @@ function releaseSlot() {
 }
 async function withSlot(job) {
   if (activeFetches >= MAX_CONCURRENT_IMAGE_FETCHES) {
-    await new Promise((resolve) => waiting.push(resolve));
+    await new Promise((resolve2) => waiting.push(resolve2));
   }
   activeFetches++;
   try {
@@ -3836,7 +3850,7 @@ function buildDeepDiveText(data) {
 
 // src/cli.ts
 import { readFileSync as readFileSync8 } from "fs";
-import { join as join8, dirname as dirname4 } from "path";
+import { join as join9, dirname as dirname4 } from "path";
 import { fileURLToPath as fileURLToPath4 } from "url";
 
 // src/tui.ts
@@ -4090,6 +4104,7 @@ function buildHelpSections() {
         { keys: "Limit", action: "Cycle limit: 10 \u2192 25 \u2192 50 \u2192 100" },
         { keys: "Refresh", action: "Re-run current search" },
         { keys: "Graph", action: "Toggle commit activity chart" },
+        { keys: "Clone", action: "Clone the repo to disk" },
         { keys: "Readme", action: "Full markdown README viewer" },
         { keys: "Deep-dive", action: "Languages + contributors + excerpt" },
         { keys: "Bookmark", action: "Save / unsave selected repo" },
@@ -4959,9 +4974,9 @@ async function copyToClipboard(text) {
     });
     proc.stdin.write(text);
     proc.stdin.end();
-    return new Promise((resolve) => {
-      proc.on("close", (code) => resolve(code === 0));
-      proc.on("error", () => resolve(false));
+    return new Promise((resolve2) => {
+      proc.on("close", (code) => resolve2(code === 0));
+      proc.on("error", () => resolve2(false));
     });
   } catch {
     return false;
@@ -5154,9 +5169,9 @@ async function performUpdate(location = detectInstallLocation(PKG_DIR2)) {
   }
   const argv = buildUpdateCommand(location);
   try {
-    const { spawn: spawn4 } = await import("child_process");
+    const { spawn: spawn5 } = await import("child_process");
     const useShell = process.platform === "win32";
-    const proc = spawn4(
+    const proc = spawn5(
       argv[0],
       useShell ? argv.slice(1).map(quoteWin32) : argv.slice(1),
       { stdio: ["ignore", "ignore", "pipe"], shell: useShell }
@@ -5165,9 +5180,9 @@ async function performUpdate(location = detectInstallLocation(PKG_DIR2)) {
     proc.stderr?.on("data", (chunk) => {
       stderr += String(chunk);
     });
-    const code = await new Promise((resolve) => {
-      proc.on("close", (c) => resolve(c));
-      proc.on("error", () => resolve(-1));
+    const code = await new Promise((resolve2) => {
+      proc.on("close", (c) => resolve2(c));
+      proc.on("error", () => resolve2(-1));
     });
     if (code !== 0) {
       debugLog(`Install failed (code ${code}): ${stderr.trim()}`);
@@ -5218,6 +5233,57 @@ function fetchReleaseNotes(version) {
   return null;
 }
 
+// src/clone.ts
+import { spawn as spawn4 } from "child_process";
+import { mkdirSync as mkdirSync4 } from "fs";
+import { join as join7, resolve } from "path";
+async function cloneRepo(ref, opts = {}) {
+  const { owner, name } = parseRepoRef(ref);
+  const url = opts.ssh ? `git@github.com:${owner}/${name}.git` : `https://github.com/${owner}/${name}.git`;
+  const root = resolve(opts.dir ?? process.cwd());
+  const target = join7(root, name);
+  mkdirSync4(root, { recursive: true });
+  const spawnFn = opts.spawn ?? spawn4;
+  const interactive = opts.interactive === true;
+  return new Promise((settle) => {
+    let output = "";
+    const child = spawnFn("git", ["clone", url, target], {
+      cwd: root,
+      env: interactive ? process.env : (
+        // The TUI has nowhere to render a prompt, so let git fail loudly
+        // instead of blocking on a username/password nobody can type.
+        { ...process.env, GIT_TERMINAL_PROMPT: "0" }
+      ),
+      stdio: interactive ? "inherit" : ["ignore", "pipe", "pipe"]
+    });
+    child.stdout?.on("data", (chunk) => {
+      output += String(chunk);
+    });
+    child.stderr?.on("data", (chunk) => {
+      output += String(chunk);
+    });
+    child.on("error", (err) => {
+      settle({
+        ok: false,
+        dir: target,
+        code: null,
+        output: output || err.message,
+        error: err.code === "ENOENT" ? "git-missing" : void 0
+      });
+    });
+    child.on("close", (code) => {
+      settle({ ok: code === 0, dir: target, code, output });
+    });
+  });
+}
+var GIT_MISSING_MESSAGE = "git not found on PATH \u2014 install git and retry.";
+function gitErrorLine(output, maxLength = 88) {
+  const lines = output.split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+  const diagnosis = [...lines].reverse().find((l) => /^(fatal|remote|error):/i.test(l));
+  const line = diagnosis ?? lines[lines.length - 1] ?? "";
+  return line.length > maxLength ? `${line.slice(0, maxLength - 1)}\u2026` : line;
+}
+
 // src/landing.ts
 import { BoxRenderable as BoxRenderable4, TextRenderable as TextRenderable4 } from "@opentui/core";
 function landingKeysActive(mode, overlay) {
@@ -6439,6 +6505,12 @@ async function launchBrowser(theme_override, startMode) {
           description: "Open selected repo in browser",
           action: () => openUrlIfSelected()
         },
+        {
+          type: "action",
+          name: "Clone",
+          description: "Clone the repo to disk (into the cwd)",
+          action: () => cloneSelectedRepo()
+        },
         {
           type: "action",
           name: "Readme",
@@ -6503,7 +6575,7 @@ async function launchBrowser(theme_override, startMode) {
       groups.push({
         type: "category",
         name: "Repo",
-        description: "Open, readme, bookmark, share, compare",
+        description: "Open, clone, readme, bookmark, share, compare",
         icon: "\u{1F4CB}",
         children: repoItems
       });
@@ -6697,6 +6769,37 @@ async function launchBrowser(theme_override, startMode) {
     if (repo) openUrl(repo.url);
     else setStatus("No repo selected");
   }
+  function cloneSelectedRepo() {
+    const opt = resultsSelect.getSelectedOption();
+    const repo = opt?.value;
+    if (!repo) {
+      setStatus("No repo selected");
+      return;
+    }
+    showOverlay("none");
+    setStatus(`Cloning ${repo.fullName}\u2026`);
+    renderer.requestRender();
+    cloneRepo(repo.fullName).then((result) => {
+      debugLog(
+        `ghfind clone ${repo.fullName} \u2192 ${result.dir} (exit ${result.code})
+${result.output}`
+      );
+      if (result.error === "git-missing") {
+        setStatus(`\u2717 ${GIT_MISSING_MESSAGE}`);
+      } else if (result.ok) {
+        setStatus(`\u2713 Cloned ${repo.fullName} \u2192 ${result.dir}`);
+      } else {
+        const detail = gitErrorLine(result.output);
+        setStatus(
+          `\u2717 Clone failed: ${detail || `git exited ${result.code}`} \u2014 see GHFIND_LOG`
+        );
+      }
+      renderer.requestRender();
+    }).catch((err) => {
+      setStatus(`\u2717 ${err instanceof Error ? err.message : String(err)}`);
+      renderer.requestRender();
+    });
+  }
   function toggleBookmarkOnSelected() {
     const opt = resultsSelect.getSelectedOption();
     const repo = opt?.value;
@@ -8169,7 +8272,13 @@ 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
+## Clone a repository
+
+    ghfind clone owner/repo              # into ./repo, over HTTPS
+    ghfind clone owner/repo --dir PATH --ssh
+This is the one command here that writes to disk: the clone lands in
+PATH/<repo-name>, or the cwd when --dir is omitted. Confirm the destination
+first; the repo name is taken from the ref, not from the query.
     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 --
@@ -8236,7 +8345,7 @@ function formatSkillCatalog() {
 // src/skill-finder.ts
 import { readdirSync, readFileSync as readFileSync7 } from "fs";
 import { homedir as homedir4 } from "os";
-import { delimiter, join as join7 } from "path";
+import { delimiter, join as join8 } from "path";
 var REGISTRY_SEARCH_ENDPOINT = "https://skills.sh/api/search";
 var MIN_QUERY_LENGTH = 2;
 var MAX_SKILL_RESULTS = 100;
@@ -8254,10 +8363,10 @@ function displayPath(path) {
 function defaultSkillRoots(cwd = process.cwd()) {
   const home = homedir4();
   return [
-    join7(home, ".codex", "skills"),
-    join7(home, ".agents", "skills"),
-    join7(cwd, ".codex", "skills"),
-    join7(cwd, ".github", "skills")
+    join8(home, ".codex", "skills"),
+    join8(home, ".agents", "skills"),
+    join8(cwd, ".codex", "skills"),
+    join8(cwd, ".github", "skills")
   ];
 }
 function resolveSkillRoots(cwd = process.cwd()) {
@@ -8310,7 +8419,7 @@ function scanLocalSkills(roots = resolveSkillRoots()) {
       const entries = listDir(dir);
       if (!entries) continue;
       if (!entries.some((e) => e.isFile() && e.name === "SKILL.md")) continue;
-      const file = join7(dir, "SKILL.md");
+      const file = join8(dir, "SKILL.md");
       try {
         const parsed = parseSkillFrontmatter(readFileSync7(file, "utf-8"));
         if (!parsed || byName.has(parsed.name)) continue;
@@ -8345,7 +8454,7 @@ function* walkDirs(root) {
     if (depth >= MAX_DEPTH) continue;
     for (const entry of entries) {
       if (!entry.isDirectory() || SKIP_DIRS.has(entry.name)) continue;
-      queue.push([join7(dir, entry.name), depth + 1]);
+      queue.push([join8(dir, entry.name), depth + 1]);
     }
   }
 }
@@ -9122,7 +9231,7 @@ async function runMcpServer(options = {}) {
 // src/cli.ts
 process.env.GHFIND_CLI_RUN = "1";
 var __dirname3 = dirname4(fileURLToPath4(import.meta.url));
-var PKG_DIR3 = join8(__dirname3, "..");
+var PKG_DIR3 = join9(__dirname3, "..");
 var SORT_VALUES = [
   "best-match",
   "stars",
@@ -9166,6 +9275,7 @@ function parseArgs(args) {
     local: false,
     copy: false,
     raw: false,
+    cloneSsh: false,
     limitExplicit: false
   };
   const queryParts = [];
@@ -9312,6 +9422,18 @@ function parseArgs(args) {
       case "--raw":
         flags.raw = true;
         break;
+      case "--dir": {
+        const dir = args[++i];
+        if (!dir || dir.startsWith("-")) {
+          console.error("Missing value for --dir <path>.");
+          process.exit(1);
+        }
+        flags.cloneDir = dir;
+        break;
+      }
+      case "--ssh":
+        flags.cloneSsh = true;
+        break;
       case "--as":
         flags.sharedAs = args[++i];
         break;
@@ -9350,6 +9472,16 @@ function parseArgs(args) {
         }
         break;
       }
+      case "clone": {
+        const next = args[i + 1];
+        if (next && !next.startsWith("-")) {
+          flags.clone = next;
+          i++;
+        } else {
+          flags.clone = "";
+        }
+        break;
+      }
       case "deep-dive": {
         const next = args[i + 1];
         if (next && !next.startsWith("-")) {
@@ -9454,6 +9586,7 @@ Usage:
   ghfind topics                    Browse popular GitHub topics
   ghfind saved                     Named searches saved in the TUI
   ghfind readme <owner/repo>       Print a repository README
+  ghfind clone <owner/repo>        Clone a repo to disk (HTTPS; --ssh = git@github.com)
   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)
@@ -9485,6 +9618,8 @@ Options:
   --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
+  --dir <path>                         clone: directory to clone into (default: cwd)
+  --ssh                                clone: clone over SSH (git@github.com)
 `);
     return;
   }
@@ -9492,7 +9627,7 @@ Options:
     const shell = flags.completion;
     try {
       const content = readFileSync8(
-        join8(PKG_DIR3, "completions", `ghfind.${shell}`),
+        join9(PKG_DIR3, "completions", `ghfind.${shell}`),
         "utf-8"
       );
       console.log(content);
@@ -9546,6 +9681,10 @@ Options:
     await runShare(flags);
     return;
   }
+  if (flags.clone !== void 0) {
+    await runClone(flags);
+    return;
+  }
   if (flags.pkg) {
     const interactive = !flags.query && !flags.json && !flags.csv && !flags.markdown && !flags.count && !flags.format;
     if (interactive) {
@@ -9919,6 +10058,32 @@ async function runShare(flags) {
     process.exit(1);
   }
 }
+async function runClone(flags) {
+  const ref = flags.clone ?? "";
+  if (!ref) {
+    console.error("Usage: ghfind clone <owner/repo> [--dir <path>] [--ssh]");
+    process.exit(1);
+  }
+  let result;
+  try {
+    result = await cloneRepo(ref, {
+      dir: flags.cloneDir,
+      ssh: flags.cloneSsh,
+      interactive: true
+    });
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+  if (result.error === "git-missing") {
+    console.error(GIT_MISSING_MESSAGE);
+    process.exit(1);
+  }
+  if (result.ok) {
+    console.error(`Cloned to ${result.dir}`);
+  }
+  process.exit(result.code ?? 1);
+}
 async function runPackageSearch(flags) {
   if (flags.registry !== "npm") {
     console.error(`Registry "${flags.registry}" not yet supported (only npm).`);

package/docs/HOW-TO.md

@@ -233,8 +233,16 @@ ghfind --trending rust --count
 
 # Pipe into another tool
 ghfind "cli language:Rust" --json | jq -r '.[].url'
+
+# Clone a repo you found (into ./react; --dir and --ssh are optional)
+ghfind clone facebook/react
+ghfind clone facebook/react --dir ~/code --ssh
 ```
 
+The same action is in the TUI under `Esc` → **Repo** → **Clone**. It clones into
+the directory ghfind was started in and reports the path in the status bar; git
+runs in the background, so the interface stays responsive.
+
 ---
 
 ## Environment variables

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "github-search-cli",
-  "version": "9.10.3",
+  "version": "9.11.0",
   "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.11.0.md

@@ -0,0 +1,50 @@
+# v9.11.0
+
+Cloning stops being a command you copy.
+
+## `ghfind clone` actually clones
+
+The only cloning ghfind knew how to do was printing: `--pipe clone` and
+`--format clone-commands` emit `git clone …` lines for you to paste somewhere
+else. The new `clone` subcommand runs it.
+
+```
+ghfind clone facebook/react               # → ./react, over HTTPS
+ghfind clone facebook/react --dir ~/code  # → ~/code/react
+ghfind clone facebook/react --ssh         # git@github.com form
+```
+
+Three of the decisions are worth knowing about:
+
+- **No GitHub API call.** A clone needs only owner/name, so the ref is
+  validated for shape and git decides what exists and what you are allowed to
+  read. Your 60/hour unauthenticated budget can never be the reason a clone
+  fails.
+- **The destination is `<dir>/<name>`, exactly what `git clone` would have
+  made.** Existing directories are left to git's own rule — an empty one is
+  reused, a non-empty one fails with git's message — rather than being
+  pre-checked or replaced.
+- **git's answers are passed through, not rewritten.** The CLI shows git's own
+  progress and errors, and exits with git's own code (128 for a repository that
+  does not exist, so a script can tell that apart from a usage error's 1). The
+  single message ghfind writes itself is `git not found on PATH`, which is the
+  one failure we can name with certainty.
+
+## `Esc` → Repo → Clone
+
+The TUI gets the same action, deliberately with a different I/O strategy: the
+TUI owns the screen, so it cannot paint git's progress bar or let git stop to
+ask for a password. git runs in the background with its output captured, the
+full log is written to `GHFIND_LOG` when you have set it, and the status bar
+shows git's own diagnosis — `✗ Clone failed: fatal: repository '…' not found`
+rather than a guess about why.
+
+`--pipe clone` is unchanged. Anything already parsing its output keeps working,
+which is why the new behaviour arrived as a subcommand instead of a change to
+the flag.
+
+## Also
+
+- `ghfind --doctor` reports whether git is on PATH. It is a **warning**, not a
+  failure: only `clone` needs git, so the exit code stays 0 for anyone who
+  never clones.

package/src/agent-skill.ts

@@ -77,7 +77,13 @@ 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
+## Clone a repository
+
+    ghfind clone owner/repo              # into ./repo, over HTTPS
+    ghfind clone owner/repo --dir PATH --ssh
+This is the one command here that writes to disk: the clone lands in
+PATH/<repo-name>, or the cwd when --dir is omitted. Confirm the destination
+first; the repo name is taken from the ref, not from the query.
     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 --

package/src/cli.ts

@@ -67,6 +67,7 @@ import { readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { launchBrowser } from "./tui";
+import { cloneRepo, GIT_MISSING_MESSAGE, type CloneResult } from "./clone";
 import { getVersion } from "./version";
 import { runMcpServer } from "./mcp-server";
 import {
@@ -136,6 +137,9 @@ interface CLIFlags {
   saved: boolean; // list saved searches (ghfind saved)
   readme?: string; // print a repo README (ghfind readme <owner/repo>)
   share?: string; // print a share snippet (ghfind share <owner/repo>)
+  clone?: string; // clone a repo to disk (ghfind clone <owner/repo>)
+  cloneDir?: string; // --dir <path> for clone (the repo gets a <name> subdir)
+  cloneSsh: boolean; // --ssh for clone (git@github.com form instead of HTTPS)
   skillSearch?: string; // skill search query (ghfind skill search <query>)
   sharedAs?: string; // --as <format> for share
   remote: boolean; // skill search: hit skills.sh instead of this machine
@@ -196,6 +200,7 @@ function parseArgs(args: string[]): CLIFlags {
     local: false,
     copy: false,
     raw: false,
+    cloneSsh: false,
     limitExplicit: false,
   };
 
@@ -350,6 +355,18 @@ function parseArgs(args: string[]): CLIFlags {
       case "--raw":
         flags.raw = true;
         break;
+      case "--dir": {
+        const dir = args[++i];
+        if (!dir || dir.startsWith("-")) {
+          console.error("Missing value for --dir <path>.");
+          process.exit(1);
+        }
+        flags.cloneDir = dir;
+        break;
+      }
+      case "--ssh":
+        flags.cloneSsh = true;
+        break;
       case "--as":
         flags.sharedAs = args[++i];
         break;
@@ -390,6 +407,17 @@ function parseArgs(args: string[]): CLIFlags {
         }
         break;
       }
+      case "clone": {
+        // Single repo ref; a following flag means none was given.
+        const next = args[i + 1];
+        if (next && !next.startsWith("-")) {
+          flags.clone = next;
+          i++;
+        } else {
+          flags.clone = "";
+        }
+        break;
+      }
       case "deep-dive": {
         // Single repo ref (owner/name); a following flag means none.
         const next = args[i + 1];
@@ -508,6 +536,7 @@ Usage:
   ghfind topics                    Browse popular GitHub topics
   ghfind saved                     Named searches saved in the TUI
   ghfind readme <owner/repo>       Print a repository README
+  ghfind clone <owner/repo>        Clone a repo to disk (HTTPS; --ssh = git@github.com)
   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)
@@ -539,6 +568,8 @@ Options:
   --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
+  --dir <path>                         clone: directory to clone into (default: cwd)
+  --ssh                                clone: clone over SSH (git@github.com)
 `);
     return;
   }
@@ -614,6 +645,11 @@ Options:
     await runShare(flags);
     return;
   }
+  // Clone a repo to disk (parity with the TUI's Repo → Clone action)
+  if (flags.clone !== undefined) {
+    await runClone(flags);
+    return;
+  }
   // Package search (prototype, ticket 002-008)
   if (flags.pkg) {
     const interactive =
@@ -1090,6 +1126,43 @@ async function runShare(flags: CLIFlags): Promise<void> {
   }
 }
 
+/**
+ * `ghfind clone <owner/repo>` — clone the repo to disk.
+ *
+ * Runs interactively: git inherits our stdio, so its own progress bar renders
+ * and a credential prompt can still be answered. No API call — the ref is
+ * validated syntactically and git reports whether the repo exists or is
+ * readable. git's exit code is propagated (scripts can tell a usage error from
+ * a git failure), and git's own output is left on the terminal untouched.
+ */
+async function runClone(flags: CLIFlags): Promise<void> {
+  const ref = flags.clone ?? "";
+  if (!ref) {
+    console.error("Usage: ghfind clone <owner/repo> [--dir <path>] [--ssh]");
+    process.exit(1);
+  }
+  let result: CloneResult;
+  try {
+    result = await cloneRepo(ref, {
+      dir: flags.cloneDir,
+      ssh: flags.cloneSsh,
+      interactive: true,
+    });
+  } catch (err) {
+    // A malformed ref — parseRepoRef's message names the expected shape.
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+  if (result.error === "git-missing") {
+    console.error(GIT_MISSING_MESSAGE);
+    process.exit(1);
+  }
+  if (result.ok) {
+    console.error(`Cloned to ${result.dir}`);
+  }
+  process.exit(result.code ?? 1);
+}
+
 /** `ghfind pkg "<query>"` — npm package search. Pass-through query to the registry. */
 async function runPackageSearch(flags: CLIFlags): Promise<void> {
   if (flags.registry !== "npm") {

package/src/clone.ts

@@ -0,0 +1,129 @@
+/**
+ * clone.ts — clone a repository to disk (`ghfind clone`, and the TUI's Clone
+ * action both drive this one function).
+ *
+ * Deliberately does NOT consult the GitHub API. A clone needs only owner/name,
+ * and gating it behind the unauthenticated 60/hr budget would refuse to clone a
+ * repository git itself can fetch fine. `parseRepoRef` validates the shape of
+ * the ref (and tolerates `@owner/name.git`); git stays the source of truth for
+ * whether the repo exists and whether we may read it.
+ */
+import { spawn } from "node:child_process";
+import { mkdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { parseRepoRef } from "./deepdive";
+
+/** Set when the failure is one we can name with certainty. */
+export type CloneFailure = "git-missing";
+
+export interface CloneResult {
+  ok: boolean;
+  /** Absolute path of the clone target — `<dir>/<name>`, like plain `git clone`. */
+  dir: string;
+  /** git's exit code, or null when git never ran. */
+  code: number | null;
+  /** git's stdout+stderr. Empty in `interactive` mode (the terminal showed it). */
+  output: string;
+  error?: CloneFailure;
+}
+
+export interface CloneOptions {
+  /** Directory to clone INTO — the repo gets a `<name>` subdirectory. Default: cwd. */
+  dir?: string;
+  /** Use the `git@github.com:owner/name.git` SSH form instead of HTTPS. */
+  ssh?: boolean;
+  /**
+   * true — the caller owns a terminal (CLI): git inherits stdio, so its progress
+   * bar renders and a credential prompt can be answered; the exit code is
+   * returned verbatim. false (default) — capture git's output and forbid
+   * prompts, which is the only safe mode while the TUI owns the screen.
+   */
+  interactive?: boolean;
+  /** Injectable for tests. Defaults to node:child_process.spawn. */
+  spawn?: typeof spawn;
+}
+
+/**
+ * Clone `ref` ("owner/name") to `<dir>/<name>`.
+ *
+ * Throws (from `parseRepoRef`) for a malformed ref — the caller gets a
+ * user-facing usage error, not a result object. Existing target directories are
+ * NOT pre-checked: git's own rule applies, so an empty dir is reused and a
+ * non-empty one fails with git's "destination path already exists".
+ */
+export async function cloneRepo(
+  ref: string,
+  opts: CloneOptions = {},
+): Promise<CloneResult> {
+  const { owner, name } = parseRepoRef(ref);
+  const url = opts.ssh
+    ? `git@github.com:${owner}/${name}.git`
+    : `https://github.com/${owner}/${name}.git`;
+
+  const root = resolve(opts.dir ?? process.cwd());
+  const target = join(root, name);
+  // git creates `target` itself but not missing parents, so create the root.
+  mkdirSync(root, { recursive: true });
+
+  const spawnFn = opts.spawn ?? spawn;
+  const interactive = opts.interactive === true;
+
+  return new Promise<CloneResult>((settle) => {
+    let output = "";
+    const child = spawnFn("git", ["clone", url, target], {
+      cwd: root,
+      env: interactive
+        ? process.env
+        : // The TUI has nowhere to render a prompt, so let git fail loudly
+          // instead of blocking on a username/password nobody can type.
+          { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+      stdio: interactive ? "inherit" : ["ignore", "pipe", "pipe"],
+    });
+
+    child.stdout?.on("data", (chunk) => {
+      output += String(chunk);
+    });
+    child.stderr?.on("data", (chunk) => {
+      output += String(chunk);
+    });
+
+    child.on("error", (err: NodeJS.ErrnoException) => {
+      settle({
+        ok: false,
+        dir: target,
+        code: null,
+        output: output || err.message,
+        error: err.code === "ENOENT" ? "git-missing" : undefined,
+      });
+    });
+
+    child.on("close", (code) => {
+      settle({ ok: code === 0, dir: target, code, output });
+    });
+  });
+}
+
+/** The message shown when git is not installed — the one failure we diagnose ourselves. */
+export const GIT_MISSING_MESSAGE =
+  "git not found on PATH — install git and retry.";
+
+/**
+ * The most useful single line of git's output, for a one-line status message.
+ *
+ * git's own `fatal:` / `remote:` line is the diagnosis; `Cloning into 'x'...`
+ * is progress noise, so a diagnosis line wins, then the last line. Nothing is
+ * rewritten — the status bar shows git's own words, and the full log goes to
+ * GHFIND_LOG. Lives here rather than in the TUI so the text that reaches the
+ * user is covered by tests.
+ */
+export function gitErrorLine(output: string, maxLength = 88): string {
+  const lines = output
+    .split(/\r?\n/)
+    .map((l) => l.trim())
+    .filter(Boolean);
+  const diagnosis = [...lines]
+    .reverse()
+    .find((l) => /^(fatal|remote|error):/i.test(l));
+  const line = diagnosis ?? lines[lines.length - 1] ?? "";
+  return line.length > maxLength ? `${line.slice(0, maxLength - 1)}…` : line;
+}

package/src/doctor.ts

@@ -140,6 +140,25 @@ function checkSystemBun(bundledOk: boolean): void {
   }
 }
 
+/**
+ * git is only needed by `ghfind clone`, so a missing git is a WARN, not a FAIL:
+ * every other surface works without it, and the exit code should stay 0 for
+ * people who never clone.
+ */
+function checkGit(): void {
+  const res = run("git", ["--version"]);
+  const version = res.stdout.trim();
+  if (res.status === 0 && version) {
+    add("PASS", "git", `${version} — used by \`ghfind clone\`.`);
+    return;
+  }
+  add(
+    "WARN",
+    "git",
+    "not found on PATH — `ghfind clone` will fail; every other command works. Install: https://git-scm.com/downloads",
+  );
+}
+
 function checkNodeVersion(): void {
   const major = parseInt(process.version.replace(/^v/, "").split(".")[0], 10);
   if (Number.isNaN(major) || major >= 20) {
@@ -414,6 +433,7 @@ export async function runDoctor(): Promise<void> {
   const bundled = checkBundledBun();
   checkSystemBun(bundled.ok);
   checkNodeVersion();
+  checkGit();
   checkBuildOutput();
   checkSource();
   checkTuiBackend();

package/src/help.ts

@@ -86,6 +86,7 @@ export function buildHelpSections(): HelpSection[] {
         { keys: "Limit", action: "Cycle limit: 10 → 25 → 50 → 100" },
         { keys: "Refresh", action: "Re-run current search" },
         { keys: "Graph", action: "Toggle commit activity chart" },
+        { keys: "Clone", action: "Clone the repo to disk" },
         { keys: "Readme", action: "Full markdown README viewer" },
         { keys: "Deep-dive", action: "Languages + contributors + excerpt" },
         { keys: "Bookmark", action: "Save / unsave selected repo" },

package/src/tui.ts

@@ -133,6 +133,7 @@ import {
   markPostUpgradeSeen,
 } from "./update-check";
 import { debugLog } from "./storage";
+import { cloneRepo, gitErrorLine, GIT_MISSING_MESSAGE } from "./clone";
 import {
   landingConsumesKey,
   landingKeysActive,
@@ -1569,6 +1570,12 @@ export async function launchBrowser(
           description: "Open selected repo in browser",
           action: () => openUrlIfSelected(),
         },
+        {
+          type: "action",
+          name: "Clone",
+          description: "Clone the repo to disk (into the cwd)",
+          action: () => cloneSelectedRepo(),
+        },
         {
           type: "action",
           name: "Readme",
@@ -1633,7 +1640,7 @@ export async function launchBrowser(
       groups.push({
         type: "category",
         name: "Repo",
-        description: "Open, readme, bookmark, share, compare",
+        description: "Open, clone, readme, bookmark, share, compare",
         icon: "\uD83D\uDCCB",
         children: repoItems,
       });
@@ -1841,6 +1848,49 @@ export async function launchBrowser(
     else setStatus("No repo selected");
   }
 
+  /**
+   * Clone the selected repo to disk, without blocking the render loop.
+   *
+   * Follows the `performUpdate` precedent: git runs in the background with its
+   * output captured, because the TUI owns the screen and has nowhere to draw a
+   * progress bar or a credential prompt (`cloneRepo` sets GIT_TERMINAL_PROMPT=0
+   * for exactly that reason). The full output is written to GHFIND_LOG when it
+   * is set, and the status bar carries git's own diagnosis.
+   */
+  function cloneSelectedRepo() {
+    const opt = resultsSelect.getSelectedOption();
+    const repo = opt?.value as Repo | undefined;
+    if (!repo) {
+      setStatus("No repo selected");
+      return;
+    }
+    showOverlay("none");
+    setStatus(`Cloning ${repo.fullName}…`);
+    renderer.requestRender();
+    cloneRepo(repo.fullName)
+      .then((result) => {
+        debugLog(
+          `ghfind clone ${repo.fullName} → ${result.dir} (exit ${result.code})\n${result.output}`,
+        );
+        if (result.error === "git-missing") {
+          setStatus(`✗ ${GIT_MISSING_MESSAGE}`);
+        } else if (result.ok) {
+          setStatus(`✓ Cloned ${repo.fullName} → ${result.dir}`);
+        } else {
+          const detail = gitErrorLine(result.output);
+          setStatus(
+            `✗ Clone failed: ${detail || `git exited ${result.code}`} — see GHFIND_LOG`,
+          );
+        }
+        renderer.requestRender();
+      })
+      .catch((err) => {
+        // A malformed ref never reaches git — parseRepoRef's message names it.
+        setStatus(`✗ ${err instanceof Error ? err.message : String(err)}`);
+        renderer.requestRender();
+      });
+  }
+
   function toggleBookmarkOnSelected() {
     const opt = resultsSelect.getSelectedOption();
     const repo = opt?.value as Repo | undefined;