Skip to main content
GitHits groups tools into Deterministic (Code, Documentation, and Package Intelligence) and Agentic (example generation and research). The CLI also provides setup and authentication commands. 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.40.1. Use npx githits@latest --version to check the version you are running. For package, GitHub, GitLab.com, Codeberg, Launchpad, and Googlesource addressing, see target syntax. Pass known targets directly to search and navigation commands; use resolve for a dependency name or a mutable Launchpad default.

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

Deterministic

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 starts with a Sources: section, including the commit and known UTC commit date for repository snapshots. A Read files: or Read pages: line with the read template follows, then one path per line; directories end in /. An empty inventory prints No files. or No pages. instead, or No files available yet. while the source is still indexing. When more entries exist, a More results: footer shows the --after cursor. Follow the Read files: or Read pages: 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 (default 30000). Pass 0 to return immediately.
flag
Output paths only in text mode, without the Sources: section, read guidance, 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 results 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 available hits while other targets or sources prepare. Enabled by default from 0.27.0.
flag
Wait for all runnable targets and sources before returning hits.
number
Maximum results to return (1-100, default 10).
number
Offset for pagination.
number
Integer milliseconds to wait for indexing before returning a searchRef (0–120000, default 30000). Pass 0 to return immediately. Seconds values such as 30s are rejected; use --wait 30000 instead. When the response carries indexing-time estimates, GitHits suggests a longer follow-up wait up to the 120000 ms 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 integer milliseconds to wait for progress before returning the latest status, 0–120000 (default 30000). Pass 0 to return immediately. Seconds values such as 30s are rejected. GitHits also uses indexing-time estimates from the initial search to suggest a longer wait, up to the 120000 ms 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. From 0.38.0, --lines 120 reads exactly one line. 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 matches from both source and documentation. 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. foo|bar matches either alternative; foo\|bar matches a literal pipe. Lookaround and backreferences are unsupported. Content-index searches require literal text in the pattern; a single exact-file route accepts anchorless regex, but a path selector alone does not guarantee that route.
  • 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 an outcome headline, such as Found 4 matches on 3 lines in 2 files., and a Sources: section naming the resolved scopes. Targets still indexing appear under Preparing:. 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 -. After the matches, footers appear in a fixed order: Read: with the read templates, More results: with the --cursor value, and Follow-up: with a --wait retry for omitted targets.
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. From 0.38.0, nonnegative safe integers above 10 are capped at 10 and reported in text or JSON output.
number
Leading context lines per match, capped at 10 with the same reporting as -A.
number
Context lines on both sides, capped at 10 per side. -A and -B override their side regardless of order. Use read for more context.
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 30000). Pass 0 to return immediately. Continuation pages never wait.
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.Path and source noticesSince 0.36.0, when a path selector wrongly includes the package path prefix, text output shows a compact warning such as Warning: Path is prefixed with package path "drizzle-orm". Did you mean "src/pg-core"?. Matches, failures, and cursors are unchanged, and the CLI does not retry automatically. --json output adds a pathWarnings array with the same strings, empty when there are no warnings.When GitHits cannot confirm that a package version matches the served source revision, the Source: line says so inline, for example (commit 5c71d2a, match to guava-testlib@33.4.0-jre unconfirmed). Targets still preparing use Selected source:. An unconfirmed match is not a claim about the published binary. See package source correspondence.
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 supported public GitHub, GitLab.com, Codeberg, Launchpad Git, or Googlesource (0.38.0+) repository URL instead of a compact target.
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, capped at 10 per side from 0.38.0. The CLI reports when it caps the requested context.
number
Include this many lines before each match, capped at 10.
number
Include this many lines after each match, capped at 10.
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 supported public GitHub, GitLab.com, Codeberg, Launchpad Git, or Googlesource (0.38.0+) repository URL instead of a compact target.
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 supported public GitHub, GitLab.com, Codeberg, Launchpad Git, or Googlesource (0.38.0+) repository URL instead of a compact target.
string
Git ref to use with --repo-url.
string
Read an inclusive line range, such as 120-200, or a single line with --lines 120 (from 0.38.0). 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.
Compare repository trees resolved from two package versions or public repository 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.Available by default since 0.26.0.Launchpad targets are accepted from 0.33.0, but comparisons between different commits currently return nonretryable RAW_DIFF_UNAVAILABLE. Refs resolving to the same commit return an empty inventory. See source diff.
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 an upgrade review, call pkg upgrade-review instead.
Flags
string
Address a supported public GitHub, GitLab.com, Codeberg, Launchpad Git, or Googlesource (0.38.0+) 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.Since 0.36.0, when GitHits cannot confirm that a package version matches its source revision, stderr includes a From source: or To source: line for that side, such as From source: github:google/guava@v33.4.0 (commit 5c71d2a, match to guava-testlib@33.4.0-jre unconfirmed). An unconfirmed match is not a claim about the published binary. --json keeps the source assessments. See package source correspondence.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 results.

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, or a single line with --lines 50 (from 0.38.0).
flag
Include page metadata in text output.
flag
Output the result as JSON.

Package Intelligence

From 0.32.0, package targets accept cargo: as an alias for public crates.io crates:, such as cargo:serde. Canonical registry identities remain crates.
Show a package overview for the default selected release, including version, license, repository popularity, download counts, and vulnerability summary. From 0.39.0, if the registry’s latest pointer is skipped (for example, because it is deprecated or a prerelease), the output explains why.
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, including the selected version, the registry’s latest version, and any registryLatestDifference.
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, unknown (could not be evaluated), or all. Unknown scope is available from 0.31.0 and includes assessment reasons. Summary counts cover all scopes.
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
From 0.40.0, fetch full advisory text and source metadata from OSV for every selected direct advisory. Adds live source reads and can produce long output. Source failures preserve assessments and exit nonzero. For a dependency advisory’s full report, use vulns <id> --verbose.
flag
Expand assessment fields: aliases, dates where relevant, malicious-advisory markers, and complete range/fix details. CLI text already shows every selected direct and transitive advisory row. Full source reports require --details.
flag
Output structured assessment data. Combine with --details to include full source reports in sourceDetails.
From 0.39.0. Look up one or more advisory IDs and show the packages each one affects. Use this when you start from an advisory ID, such as a CVE in a security report, and need to know which packages and versions it covers. To check whether a specific installed version is affected, use pkg vulns instead.
Text output leads with the requested ID, the reported CVSS score when the source provides one, and the advisory summary. Each affected package shows a registry link, normalized affected ranges, and source-reported fixes. The default shows up to ten ranges per package and states how many were omitted. IDs are case-sensitive. Input order and duplicates are preserved.If a lookup is only partly successful, the CLI keeps the evidence it retrieved, states the cause, and exits nonzero. Diagnostics include recovery actions, such as githits login when authentication is required.Flags
flag
Add the full source report: untruncated advisory text, raw range expressions, CVSS vectors, aliases, dates, and references. From 0.40.0, also includes OSV schema version, related and upstream IDs, and credits. Works with --json.
flag
Output one result per input ID. Each result separates package evidence (packages), shared source records (sources), acquisition coverage, and diagnostics with retryability and recovery actions. Compact JSON caps normalized affected ranges at ten per package and reports omissions; combine with --verbose for original source detail. affectedRanges and sourceFixVersions are independent lists and are not index-aligned.
Source-reported fix lists are not verified releases and do not establish a safe upgrade. A range boundary is not necessarily a fix. Withdrawn and malicious-package markers are kept and shown beside the affected evidence. Missing evidence does not establish safety. Assess an installed version with npx githits@latest pkg vulns <registry>:<name>@<version>.
This command is CLI-only. MCP has no equivalent tool.
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. From 0.30.0, default text and JSON contain parsed statements with available classifications and sources.
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
Inclusive 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.
string
default:"all"
Filter statements to actionable, important (actionable plus “should know”), or all. Includes uncertain classifications in the selected tiers. Ignored with --verbatim or --no-body.
flag
Show complete original notes instead of parsed statements. Use --verbatim --json for original Markdown bodies. Cannot be combined with --no-body.
flag
Deprecated alias for --verbatim, in text and JSON.
flag
Return only the version/date/URL timeline; skip parsing and classification. Cannot be combined with --verbatim or --verbose.
flag
Output the result as JSON.
Review a package upgrade by comparing the current version with a target version. The command checks vulnerabilities, changelog entries in the version range, target deprecation metadata, peer dependency changes, dependency changes, and optional transitive dependency checks.
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.Text output includes all matching release-note statements in release/source order, with available classifications, uncertainty markers, and changelog coverage. Batch output ranks packages by confident action count across the whole version range. Direct security summaries retain unknown vulnerability counts from 0.31.0. From 0.37.0, detailed reports and compact batch rows link to available migration guides, and JSON keeps them in migrationGuides. The classifications are evidence, not a safety verdict. See Package Intelligence for the JSON fields.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.
string
Filter detailed changelog statements to actionable, important (actionable plus “should know”), or all. Omit for the default focused view, which includes actionable, “should know”, and too-long-to-classify statements. Do not pass focused explicitly. Batch triage and coverage still include the whole version range.
flag
Show full per-package batch reports, expand statement quotes, and include dependency change examples in text output.
flag
Output the result as JSON.
See Package Intelligence for the full parameter reference.

Target resolution

resolve is available by default from 0.27.0. See Target resolution for MCP parameters and guidance on choosing a result.
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.From 0.33.0, mutable Launchpad defaults such as lp:project can resolve to their current canonical repository. Complete owner-qualified Launchpad targets go directly to the next command. See Launchpad targets.
Use the best match directly only when it is non-ambiguous, has EXACT or HIGH confidence, and its latest-version malicious-content status is clear or not_applicable. For MEDIUM, LOW, or ambiguous results, narrow the input or explicitly choose a candidate.Affected or uncertain malicious-content decisions render a warning that links the relevant MAL-* advisories on OSV and suppress the automatic next-command suggestion. See malicious-content gating for the status meanings.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 in text output. This is 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.

Agentic

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.
Research one public package or repository. Ask the question directly; sources are always included. Pass a quoted question alone to let GitHits identify the target, or precede it with an explicit package or repository target. Do not use site: targets; Research covers both code and documentation. Available by default from 0.31.0, with no experimental opt-in.
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.The CLI prints the answer with cited sources and follow-up guidance. Use the returned thread ID to continue the conversation. By default, source citations are copyable npx githits@latest read commands.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
Return display_markdown containing the answer or target clarification, plus optional tool_call_id (run ID) and thread_id (for follow-ups). Target clarifications omit both IDs.
From 0.35.0, research and example show live stages in interactive terminals without changing JSON or piped output. See Research for progress, thread, rate-limit, and MCP behavior.