Skip to main content
The GitHits CLI groups evidence tools into Code, Documentation, and Package Intelligence, alongside setup and authentication commands. Code includes source navigation and implementation examples. Run commands through npx githits@latest unless you are inside an MCP config that already uses the JSON command form. This reference covers githits 0.23.0. Use npx githits@latest --version to check the version you are running.

​
Global options

Global options can appear before any command.

​
Setup and configuration

Authenticate and configure supported AI coding tools with the GitHits MCP server. init runs the browser login flow first, then auto-detects which supported tools are installed and writes MCP configuration for each one.
Automatic install support: Claude Code, Cursor, Windsurf, Claude Desktop, Codex CLI, Pi, VS Code / Copilot, Cline, Gemini CLI, Google Antigravity, OpenCode, Hermes Agent, Zed, Junie, Qwen Code, Kiro, Kilo Code, Factory Droid, and Amazon Q CLI.By default, init performs a guided MCP setup: alongside the MCP server config, it drops the four GitHits Agent Skills (githits-onboarding, githits-mcp, githits-code, and githits-package) and a managed instruction block (delimited by <!-- githits --> markers in files like AGENTS.md, CLAUDE.md, or GEMINI.md) into each selected tool. The skills and instructions help the agent decide when to reach for GitHits without bloating its base context. Rerunning guided init repairs any missing skill files. Interactive setup, --yes, and staged --install-agents all default to guided MCP unless --no-guidance is passed. Pass --no-guidance for a plain MCP-only install.After init completes, each detected tool is configured to start the GitHits MCP server automatically. No further manual configuration is needed.Flags
​
flag
Skip interactive prompts and configure all detected tools automatically. Defaults to guided MCP unless --no-guidance is set.
​
flag
Skip the authentication step. Useful if you are already authenticated and only want to reconfigure tool integrations.
​
flag
Configure project-level MCP in the current directory instead of user-level tool configuration.
​
flag
Scan supported agents and print what GitHits can configure without installing anything.
​
string
Install the MCP server for a comma-separated list of agent IDs returned by --detect-agents. Defaults to guided MCP unless --no-guidance is set.
​
flag
Explicitly install the GitHits skills and managed instruction block alongside MCP configuration. This is the default; use the flag when scripting a guided install to make intent explicit.
​
flag
Install plain MCP only. Skips the GitHits skills and the managed instruction block in supported tools.
​
flag
Emit JSON output for --detect-agents or --install-agents.
​
flag
Print the authorization URL instead of opening a browser during the login step. Use this in SSH sessions, CI environments, or containers where a browser isn’t available.
​
number
Port for the local sign-in callback (default 8765). Useful when running init on a remote machine and forwarding the callback over SSH, for example ssh -N -L 8765:127.0.0.1:8765 user@remote-host.
init is the default way to get started. It configures supported tools and handles authentication for common local setup.
Remove GitHits MCP configuration from all detected coding tools. Uninstall also cleans up guided setup artifacts: the managed instruction block (content between <!-- githits --> markers) is removed from files like AGENTS.md, CLAUDE.md, and GEMINI.md, and all four GitHits skills (githits-code, githits-mcp, githits-onboarding, and githits-package) are deleted from tool-native and shared skill folders, including stale copies left by earlier versions. Unrelated skills and directories are preserved. Stored credentials are preserved — only MCP config, guidance blocks, and skill files are removed.
In interactive mode, uninstall first asks whether to remove user-level or project-level configuration. githits init uninstall remains supported as a compatibility alias with the same flags and behavior.Flags
​
flag
Skip prompts and uninstall user-level MCP configuration. Never touches project files; combine with --project for non-interactive project-level removal.
​
flag
Remove project-level MCP configuration from the current directory.
​
flag
Remove the MCP server configuration but leave the GitHits skills and managed instruction block in place. Useful when you want to disable the MCP server without losing the supporting agent context.
To also remove stored credentials, run npx githits@latest logout separately after uninstalling.
Print redacted diagnostics for GitHits CLI, MCP configuration, environment variables, and authentication state.
Flags
​
flag
Output diagnostics as JSON.

​
Authentication

Authenticate with your GitHits account via browser OAuth. Opens your default browser to complete the login flow. Tokens are stored in the system keychain by default and refreshed automatically on next use.
Flags
​
flag
Print the authorization URL and callback-forwarding instructions instead of opening the browser. If the browser runs on another machine, combine this with a fixed --port and an SSH tunnel.
​
flag
Re-authenticate even if a valid token already exists.
​
number
Use a specific port for the local OAuth callback server. Defaults to a random port in the 8000–9999 range.
When the browser runs on another machine, forward the same callback port from that machine before opening the printed URL:
If authentication times out (after 5 minutes), the browser link expires. Run the command again to get a fresh link.
Remove stored OAuth credentials. After logging out, tool calls that require authentication will fail until you log in again.
Show current authentication status, including the credential source, storage location, and token expiry.
If GITHITS_API_TOKEN is set in your environment, the command reports that source without reading local OAuth storage. If the stored token is expired, GitHits attempts to refresh it before reporting.
Print the currently usable access token to stdout. Only the token is written, so you can pipe it into other tools or capture it with shell command substitution without stripping extra output.
Credential precedence
  • If GITHITS_API_TOKEN is set, its value is printed as-is without reading local OAuth storage.
  • Otherwise, the stored OAuth token is read from the system keychain. If it is expired, GitHits refreshes it on demand and prints the new access token.
Exit behaviorIf no token is available (neither GITHITS_API_TOKEN nor stored OAuth credentials), the command exits non-zero with a clear message instead of starting an interactive login. This keeps automated scripts predictable — run npx githits@latest login once on the machine before relying on auth token.Scripting exampleUse command substitution to hand the current session token off to another tool:
Treat the printed token like a password. Do not log it, echo it to shared terminals, or write it to files that get committed or shipped in bug reports. Prefer assigning it to a shell variable (as above) rather than interpolating it into commands that get recorded in shell history.
View and update GitHits account settings for the authenticated credential. The bare command and settings show print the full canonical settings object: preferences (default language, license mode, blocked license IDs), privacy and terms (marketing emails, Terms of Service acceptance state), and account limits.
Flags
​
flag
Output the canonical settings object as JSON.
Use the get, set, and clear subcommands to read or update individual settings using their public CLI names. Every mutation sends exactly one selective PATCH, so unrelated settings are never touched.Supported keys
Only default-language-id and blocked-license-ids can be cleared. clear default-language-id unsets the default; clear blocked-license-ids replaces the list with an empty list.
Read one account setting using its public CLI name.
Arguments
​
string
required
One of default-language-id, license-mode, blocked-license-ids, or marketing-emails.
Flags
​
flag
Output the setting name and value as {"key", "value"} JSON.
Update one writable account setting. The value is validated against the schema for that key and sent as a single selective PATCH.
Arguments
​
string
required
One of default-language-id, license-mode, blocked-license-ids, or marketing-emails.
​
string
required
The typed value or list of values for the key. blocked-license-ids accepts one or more UUIDs and replaces the stored list atomically; all other keys take exactly one value.
Flags
​
flag
Output the updated canonical settings object as JSON.
Clear one of the clearable account settings. clear default-language-id sends an explicit null; clear blocked-license-ids replaces the list with an empty list.
Arguments
​
string
required
One of default-language-id or blocked-license-ids. Other keys cannot be cleared and must be updated with settings set.
Flags
​
flag
Output the updated canonical settings object as JSON.
Show whether the authenticated account currently needs to accept the GitHits Terms of Service.
Flags
​
flag
Output {"terms_required": boolean} as JSON.
Confirm and accept the current GitHits Terms of Service for the authenticated account. Interactive by default; pass --yes for non-interactive use.
Works with both browser OAuth sessions and opaque ghi-* API tokens set via GITHITS_API_TOKEN. When acceptance succeeds on an OAuth session, GitHits force-refreshes the stored session so subsequent requests carry the updated terms claim. Static API tokens are not refreshed; their acceptance state is re-evaluated server-side on the next request.If acceptance succeeds but the OAuth refresh fails, the command reports the saved acceptance and asks you to run npx githits@latest login --force before retrying other commands.Flags
​
flag
Accept without an interactive confirmation. Required when running in a non-TTY environment such as CI.
​
flag
Output the acceptance result as JSON, including accepted, token_refreshed, and the updated settings object.

​
MCP server

Show MCP setup instructions when run interactively in a terminal. When piped or run in a non-TTY context, starts the MCP server over stdio instead.
Use this command to see the JSON snippet you need to add to your tool’s MCP configuration manually.
Always start the MCP server over stdio, regardless of whether the output is a TTY. Use this command in MCP configuration files so your coding tool can launch the server reliably.
A typical MCP config entry looks like this:
MCP config

​
Code

Browse one inventory with githits list, added in 0.23.0. Package and repository targets list source files, including repository documentation. Use an explicit site: target for hosted documentation; a package inventory does not combine its source tree with its hosted docs.
Pass literal paths or quoted globs as [paths...]. --recursive traverses matched directories. Text output has a source header followed by one path per line; directories end in /. Follow the header’s read guidance or each JSON entry’s read action. For site pages, preserve the emitted site: target and target-relative page path as separate arguments.Flags
​
flag
Traverse matched directories recursively.
​
string
Filter source entries by case-insensitive file type, such as source or doc. Repeat for multiple types. Not accepted for site targets.
​
string
Filter source entries by case-insensitive language name. Repeat for multiple languages. Not accepted for site targets.
​
string
Filter source entries by production, test, benchmark, example, generated, fixture, build, or vendor. Repeat for multiple intents. Not accepted for site targets.
​
number
Maximum entries per page, 1–500. When omitted, GitHits uses the service default.
​
string
Opaque cursor printed in text or returned as nextCursor in JSON. Replay the same target, paths, filters, recursion, and limit with the cursor unchanged.
​
number
Milliseconds to wait for source indexing, 0–300000. When omitted, GitHits uses the service default.
​
flag
Output paths only in text mode, without the header or spinner. Does not change JSON output.
​
flag
Preserve entries, read actions, pagination cursors, and inventory metadata in JSON.
Pagination
Replace <nextCursor> with the exact value from the first response when hasMore is true. If the cursor is rejected, restart without --after and use the new result’s cursor.
githits code files remains available for compatibility and is deprecated in its help. Its flags and output differ from list. githits docs list still browses a package’s combined hosted and repository documentation. MCP 0.24.0 replaces code_files and docs_list with list. Refresh local tool discovery after upgrading.
Run a unified indexed search across dependency and repository code, documentation, and symbols.
When a response supplies an active searchRef and continuation guidance, pass it to npx githits@latest search-status. See search evidence and JSON migration for the 0.23.0 result fields.Flags
​
string
Scope search to a package, repository, or site target. Repeat for multiple targets. Examples: npm:react@18.2.0, github:owner/repo@ref, and site:react.dev.
​
string
Restrict results to docs, code, or symbol. Omit to let GitHits choose the best indexed sources.
​
string
Restrict symbol results by kind, such as function, method, class, interface, module, or doc_section.
​
string
Restrict symbol results by category: callable, type, module, data, or documentation.
​
string
Restrict code or symbol results to paths under a literal prefix.
​
string
Restrict code or symbol results by file intent: production, test, benchmark, example, generated, fixture, build, or vendor.
​
flag
Restrict symbol results to public symbols.
​
string
Restrict symbol results to a specific symbol name.
​
string
Restrict results by programming language.
​
flag
Return hits from sources that finished indexing while other sources continue.
​
number
Maximum results to return (1-100, default 10).
​
number
Offset for pagination.
​
number
Seconds to wait for indexing before returning a searchRef (0–120, default 30). When the response carries indexing-time estimates, GitHits automatically extends its follow-up wait up to the 120-second ceiling.
​
flag
Output the result as JSON.
Follow up on a prior npx githits@latest search using the searchRef returned in the initial response.
Flags
​
number
Maximum seconds to wait for progress before returning the latest status, 0–120 (default 30). GitHits also uses indexing-time estimates from the initial search to pick a longer wait automatically, up to the 120-second ceiling.
​
flag
Output the result as JSON.
Read an indexed source file, code symbol, or documentation page with the same command. Provide <target> <path> for a source file, an emitted <site-target> <path> for a hosted page, or a docsReadTarget/page ID alone for a documentation page. The CLI writes complete content to stdout without the MCP surface’s 150/300-line cap so you can pipe it into other tools. Repository documentation resolves to indexed file content with snapshot identity; hosted documentation reads current indexed page content.
Pass documentation targets through unchanged, including URL fragments. A fragment selects its heading and full subtree through the next equal-or-higher heading; either explicit line bound replaces that selection with a page-relative range. For site reads, use the target and path returned by list, with an optional --selector <heading-id>.Since githits 0.22.0, --selector reads an indexed code symbol or a documentation heading by its logical ID. A code symbol read returns the symbol’s definition range. An optional <path> restricts symbol lookup to that exact file. When a symbol selection is ambiguous, missing, or unsupported by the indexed snapshot, the CLI prints a typed AMBIGUOUS, NOT_FOUND, or SNAPSHOT_UNSUPPORTED outcome with candidates, suggestions, or an exact-path workaround. See the read tool for details.
npx githits@latest code read and npx githits@latest docs read remain available as deprecated commands with their existing flags. Use read for site paths, compact symbol targets, and --selector.
Flags
​
string
Repository URL addressing. When set, the first positional argument is the file path.
​
string
Git ref to use with --repo-url. Rejected for documentation reads.
​
string
Inclusive line range, such as 120-200, 120-, or -200. You can also append :120-200 to the file path.
​
string
Indexed code symbol name or logical documentation heading ID, such as createApplication or expressjson. The path is optional for code symbols. Do not combine with a docs URL fragment. With --repo-url, pass at most one positional path; the CLI rejects an extra path. Added in 0.22.0.
​
number
Starting line number for source or documentation reads. Use --start/--end as an alternative to --lines.
​
number
Inclusive ending line number for source or documentation reads. Use --start/--end as an alternative to --lines.
​
number
Code indexing wait in milliseconds (0–60000, default 30000). Validated for documentation reads but not forwarded.
​
flag
Add a metadata header and line gutter to text output.
​
flag
Output the result as JSON.
Find regex or literal matches across one to 20 ordered package, repository, and site: hosted-documentation targets with githits grep, added in 0.24.0. GitHits returns one page of matches across all targets. Use it when you know the exact string or pattern and want source and docs evidence together. Matching runs against indexed content, not local files.
Defaults follow grep and rg conventions, and differ from code grep:
  • Patterns are 1–200 UTF-8 bytes and use RE2 regex. Pass -F for literal matching. Unsupported or anchorless expressions fail instead of falling back to a literal search.
  • Matching is case-sensitive. Pass -i to ignore case.
  • Output has zero context lines. Pass -A, -B, or -C to add context.
  • Repository targets search all indexed files, source and documentation.
Package targets also include their selected hosted documentation, independent of --corpus and path filters. --corpus source therefore does not exclude a package’s hosted docs. Path flags and --corpus apply to every package and repository operand. site: operands accept only the target, so source flags with only site: operands fail. Put -- before a pattern that starts with a dash.Text output starts with a match summary and a single Sources: line naming the resolved scopes. Matches are grouped under numbered [1], [2] file or page headers. Each header begins with a copyable read locator you can pass to read with --lines. Match rows use : after the line number and context rows use -. Pass --json for the detailed lossless page, including read actions and byte coordinates.Flags
​
flag
Match the pattern as a literal string instead of an RE2 regex.
​
flag
Ignore case with Unicode case folding.
​
flag
Match case sensitively. Follows the rg convention; traditional grep uses -s to suppress errors. The last case flag wins.
​
number
Trailing context lines per match, 0–10.
​
number
Leading context lines per match, 0–10.
​
number
Context lines on both sides, 0–10. -A and -B override their side regardless of order.
​
string
Exact source path, applied to every package and repository operand. Repeatable.
​
string
Source path prefix. Repeatable.
​
string
Source path glob. Repeatable. Path selectors are OR-ed within each source operand.
​
string
default:"all"
Repository files to search: source, documentation, or all.
​
number
Global match cap for the whole page, 1–1000. When omitted, GitHits uses the service default of 100. Unlike grep or rg -m, this is not a per-file limit.
​
string
Continue from a previous page. Reuse the same ordered targets and controls with the cursor unchanged.
​
number
First-page preparation wait in milliseconds, 0–300000 (default 0). Continuation never waits.
​
flag
Emit the detailed lossless JSON page.
Pagination and coverageWhen more matches are available, the summary line ends with more available and the output ends with a ready-to-copy --cursor value. Rerun the same command with that flag to fetch the next page. A small --limit can fill the page before every scope is searched. GitHits then lists those scopes as not visited in this page, and the cursor continues into them. If the cursor expires, restart without --cursor.
githits code grep remains available with its existing literal, case-insensitive defaults. MCP 0.25.0 replaces code_grep with grep, using the same matching defaults as top-level CLI grep. Refresh tool discovery and migrate arguments.
Search for a text pattern across the indexed files of a package or repository. For new CLI usage, prefer githits grep, which searches multiple targets and hosted documentation in one page.
Flags
​
string
Use a GitHub repository URL instead of a compact package or repo spec.
​
string
Git ref to use with --repo-url.
​
string
Restrict grep to one exact target-relative file path.
​
string
Restrict grep to files matching a glob. Repeat for multiple globs.
​
string
Restrict grep to files with this extension, without the leading dot. Repeat for multiple extensions.
​
flag
Treat the pattern as a regex. Literal matching is the default.
​
flag
Use case-sensitive matching.
​
number
Include this many lines before and after each match.
​
number
Include this many lines before each match.
​
number
Include this many lines after each match.
​
flag
Exclude documentation files.
​
flag
Exclude test files.
​
number
Maximum matches to return (default 50).
​
number
Maximum matches to return per file.
​
string
Pagination cursor from a previous grep response.
​
string
Include a symbol field in grep output. Repeat for multiple fields.
​
number
Milliseconds to wait for indexing (0–60000, default 30000).
​
flag
Include additional metadata in text output.
​
flag
Output the result as JSON.
Deprecated in 0.23.0 help. Use list for new inventory workflows. This command keeps its existing flags and output for compatibility; it is not a flag-compatible alias for list.List the files included in an indexed package or repository.
Flags
​
string
Use a GitHub repository URL instead of a compact package or repo spec.
​
string
Git ref to use with --repo-url.
​
string
Return one exact target-relative file path.
​
string
Include files matching a glob. Repeat for multiple globs.
​
string
Include files with this extension, without the leading dot. Repeat for multiple extensions.
​
string
Include files with this file type. Repeat for multiple types.
​
string
Include files with this language. Repeat for multiple languages.
​
string
Include files with this intent. Repeat for multiple intents.
​
string
Exclude files with this intent after inclusive filtering. Repeat for multiple intents.
​
flag
Exclude documentation files.
​
flag
Exclude test files.
​
flag
Include hidden files.
​
number
Maximum files to return (default 200).
​
number
Milliseconds to wait for indexing (0–60000, default 30000).
​
flag
Include metadata with text output.
​
flag
Output the result as JSON.
Read a specific file from an indexed package or repository by path. Since githits 0.17.0, this command is a deprecated alias for npx githits@latest read. Behavior and flags are unchanged; prefer the unified command in new scripts.
Flags
​
string
Use a GitHub repository URL instead of a compact package or repo spec.
​
string
Git ref to use with --repo-url.
​
string
Read an inclusive line range, such as 120-200. You can also append :120-200 to the file path.
​
number
Starting line number for the read.
​
number
Ending line number for the read.
​
number
Milliseconds to wait for indexing (0–60000, default 30000).
​
flag
Add a metadata header and line gutter to text output.
​
flag
Output the result as JSON.
Search for implementation examples from open-source repositories, issues, discussions, and pull requests using a natural-language query.
Flags
​
string
Optional programming language. Omit it to let GitHits infer the language from your query. If GitHits cannot match it, retry with a suggested language from the error, or omit --lang.
​
string
default:"strict"
Control license filtering for implementation examples. Options: strict (default), yolo, or custom.
​
flag
Include an AI-generated explanation alongside the code example.
​
flag
Output the result as JSON for piping or scripting. The envelope includes result and, when available, solution_id.

​
Documentation

Use search --source docs to find documentation by topic, then list or read pages with these commands.
List documentation pages available for a package. Specs accept an optional @version; Go module versions are accepted with or without the leading v.Each entry provides read guidance using the page’s docsReadTarget. JSON output retains the docsReadTarget, the stable pageId, and the provenance sourceUrl for every page. For a standalone hosted site, use list with a site: target.
Flags
​
number
Maximum pages to return.
​
string
Pagination cursor from a previous docs list response.
​
flag
Include additional page metadata in text output.
​
flag
Output the result as JSON.
Read a specific documentation page. Prefer the docsReadTarget URL emitted by docs list and search results; historical page IDs remain accepted. URL targets resolve only already-indexed documentation and never enqueue crawling.Since githits 0.17.0, this command is a deprecated alias for npx githits@latest read. Behavior and flags are unchanged; prefer the unified command in new scripts.
Flags
​
string
Read an inclusive line range, such as 50-150.
​
flag
Include page metadata in text output.
​
flag
Output the result as JSON.

​
Package Intelligence

Show a package overview including version, license, repository popularity, download counts, and vulnerability summary.
Flags
​
flag
Include GitHub language/topics/last-pushed, published-version count, download refresh date, package-wide advisory history, and recent changes in text output.
​
flag
Output the result as JSON.
See Package Intelligence for the full parameter reference.
List CVE and OSV vulnerability advisories for a package or a specific version. Go module versions are accepted with or without the leading v (go:golang.org/x/crypto@0.17.0 or @v0.17.0).
Flags
​
string
Minimum advisory severity: low, medium, high, or critical.
​
string
Advisory rows to return: affected (default), non_affecting, or all.
​
flag
Include retracted advisories. Affects direct package rows only; transitive withdrawn advisories remain excluded.
​
flag
Audit vulnerabilities in versions resolved by the dependency graph. Opt-in because it adds graph-analysis cost. --severity and --scope apply to direct and transitive rows.
​
flag
Show every selected advisory with full detail rows in text output.
​
flag
Output the result as JSON.
Show direct dependencies, dependency groups, and optionally the full transitive dependency graph. Go module versions are accepted with or without the leading v.
Flags
​
string
Dependency lifecycle breadth. Use runtime, development, build, peer, optional, or all.
​
number
Add transitive dependency data and cap traversal at this depth (1-10).
​
flag
Compute deprecated, outdated, duplicate, and conflict analysis across the resolved dependency graph. Use --verbose for complete issue details.
​
flag
Include additional dependency metadata in text output.
​
flag
Output the result as JSON.
Retrieve release notes and changelog entries for a package. Since 0.21.0, repository targets, --repo-url, and --git-ref are rejected. Use the published package target. Results preserve backend and source order, which may interleave maintained release lines. Do not assume newest-first ordering.
Flags
​
string
Exclusive start of a version range. Returns entries after this version through --to or latest. Range mode has no count cap and cannot be combined with --limit. Go module versions are accepted with or without the leading v.
​
string
End of a version range, or an upper version cap for latest mode when used alone. Defaults to latest when --from is set. Do not repeat a bound already supplied in the positional target.
​
number
Maximum latest-mode or upper-cap entries (1–50, default 10). Rejected with an exact version, a lower range bound, or --from.
​
flag
Show full body previews in text output instead of the default ten lines per entry. Cannot be combined with --no-body.
​
flag
Omit release body content in text and JSON output. Cannot be combined with --verbose.
​
flag
Output the result as JSON.
Report evidence for a package upgrade by comparing the current version with a target version. The command checks vulnerabilities, changelog range evidence, target deprecation metadata, peer dependency changes, dependency changes, and optional transitive evidence.
Use .. as the range delimiter for the positional range and for repeatable --package entries. The legacy -> delimiter is rejected with guidance to switch to ... A positional range already contains its target, so combining it with --to or --package is rejected. Go module versions are accepted with or without the leading v.Flags
​
string
Target version for single-package mode. Cannot be combined with a positional .. range.
​
string
Batch package spec in <registry>:<name>@<current>..<target> format. Repeat the flag for multiple packages, up to 30 per batch.
​
flag
Skip the transitive vulnerability summary diff.
​
flag
Include deprecated, outdated, duplicate, and conflict summary diffs.
​
string
Minimum direct-advisory severity: low, medium, high, or critical.
​
flag
Include dependency change examples in text output.
​
flag
Output the result as JSON.
See Package Intelligence for the full parameter reference.

​
Experimental (opt-in)

The commands in this section are disabled and hidden from help by default. Enable them by setting tools = true under the [experimental] section of config.toml. See Experimental tools for the full description, availability constraints, and issue-reporting guidance.
Research one public package or repository. Pass a quoted question alone to let GitHits identify the target, or precede it with an explicit target. ask remains an alias. Requires the experimental opt-in described above.
Replace <threadId> with the UUID returned by an earlier answer. Do not combine an explicit target with --thread. If GitHits returns target candidates, repeat the question with a selected canonical target. A clarification exits successfully and has no answer or thread ID.Since 0.24.0, the CLI prints the complete Markdown that the Research API returns, including the answer, cited sources, Research run ID, thread ID, and follow-up guidance. Source citations are npx githits@latest read commands, such as npx githits@latest read --lines 100-140 -- pypi:fastapi@0.116.1 <path>.Flags
​
string
Continue an existing research thread using its returned UUID.
​
string
default:"cli"
Source citations inside the returned Markdown as executable read commands (cli) or upstream links (url).
​
flag
Output the API display envelope as JSON: display_markdown plus optional tool_call_id and thread_id. Target clarifications omit both IDs.
See experimental Research for thread and MCP behavior.
Resolve a fuzzy, misspelled, or ambiguous name to grouped canonical targets such as npm:express, github:openai/codex, or site:docs.example.com/sdk. Use it before calling another GitHits command when the input is not already canonical. Already-canonical package, repository, and site targets are rejected locally with INVALID_ARGUMENT guidance; pass them directly to the next GitHits command instead.
A best match is a direct next action only when it is non-ambiguous, has EXACT or HIGH confidence, and its latest-version malicious-content status is clear or not_applicable. Non-ambiguous MEDIUM or LOW results are labeled as unconfirmed ranked candidates. Ambiguous results preserve the existing choose-or-narrow guidance.Affected or uncertain malicious-content decisions render a red warning that links the relevant MAL-* advisories on OSV and suppress the normal next-command handoff. See malicious-content gating for the full status semantics.Flags
​
string
Comma-separated list of package registries. Constrains package candidates only; repository and site candidates remain eligible.
​
string
package, repository, or site. Soft preference, not a filter.
​
string
Ranking context. Ranks retrieved candidates and does not expand candidate retrieval. Must not contain credentials, personal data, private code, or proprietary content.
​
string
Repeatable ranking hint. Same semantics and content restrictions as --query.
​
number
default:"8"
Direct ranked list size, 1–20. Protected exact-name and related targets may appear in addition to the ranked list.
​
flag
Include coarse lexical name-similarity evidence in text output. This is supporting evidence, not a reranking score. JSON includes available numeric similarity without this flag.
​
flag
Emit the stable compact envelope {best?, ambiguous, ambiguousReason?, candidates, protectedMatches}. best is absent whenever there are no candidates.
Exit code is 1 when there are no candidates because the command did not resolve a target.
Compare repository trees resolved from two package versions or public GitHub refs, left-to-right. The range is required, uses two-dot syntax, and both endpoints must be exact — package targets must omit a version and repository targets must omit a ref.
Every raw diff is repository-wide. Package addressing resolves package, repository, version, and exact-commit identity, but code diff does not filter to a package directory. Sibling package paths may appear, and a bounded result may contain no files from the addressed package. That absence does not prove the package is unchanged. For upgrade evidence, call pkg upgrade-review instead.
Flags
​
string
Address a public GitHub repository directly. Use repository refs in the required <from>..<to> range.
​
flag
Default view. Unified-diff output; may omit some Git metadata such as index and mode headers.
​
flag
Diffstat view. Mutually exclusive with --patch, --name-only, and --name-status.
​
flag
List changed paths only.
​
flag
List changed paths with change-status letters.
​
number
Cap on files. Applied after deterministic relevance ranking. No client default.
​
number
Byte cap for the --patch view. No client default.
​
flag
Show exact resolution and repository-scope diagnostics in text output.
​
flag
Emit a lean selected-view envelope that keeps package target identity, exact resolutions, effective repository scope, caller filters, completeness, and truncation as separate facts.
Pass one repository-relative glob after -- to narrow paths without changing scope. Three-dot merge-base syntax and --git-ref are rejected.Empty authoritative diffs and caller-selected truncations exit 0 with warnings on stderr. Unexpectedly incomplete plain patches are suppressed and exit 1; the --stat, --name-only, --name-status, and JSON views preserve their structured partial evidence.