Skip to main content
The GitHits CLI exposes commands for tool setup, indexed source navigation, documentation access, package inspection, code example search, and feedback. Run commands through npx githits@latest unless you are inside an MCP config that already uses the JSON command form.

​
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

​
Search, code, package, and docs tools

Run a unified indexed search across dependency and repository code, documentation, and symbols.
Results include a searchRef you can pass to npx githits@latest search-status to poll for additional results from an async index scan.Flags
​
string
Scope search to a package or repository target. Repeat for multiple targets. Package format: npm:react@18.2.0 or npm:react. Repository formats include github:owner/repo#ref and https://github.com/owner/repo#ref.
​
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-60, default 20).
​
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–60 (default 20).
​
flag
Output the result as JSON.
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 20000).
​
flag
Include metadata with text output.
​
flag
Output the result as JSON.
Read a specific file from an indexed package or repository by path.
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 20000).
​
flag
Add a metadata header and line gutter to text output.
​
flag
Output the result as JSON.
Search for a text pattern across the indexed files of a 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
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 20000).
​
flag
Include additional metadata in text output.
​
flag
Output the result as JSON.
Show a package overview including version, license, repository popularity, download counts, and vulnerability summary.
Flags
​
flag
Include GitHub language/topics/last-pushed, recent advisories, and recent changes in text output.
​
flag
Output the result as JSON.
See Package Inspection for the full parameter reference.
List CVE and OSV vulnerability advisories for a package or a specific version.
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.
​
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.
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
Include additional dependency metadata in text output.
​
flag
Output the result as JSON.
Retrieve release notes and changelog entries for a package or GitHub repository. Results preserve backend and source order, which may interleave maintained release lines. Do not assume newest-first ordering.
Flags
​
string
Read changelog evidence from a GitHub repository URL instead of a registry package.
​
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.
​
string
End of a version range. Defaults to latest when --from is set.
​
number
Maximum latest-mode entries to return (1-50, default 10).
​
string
Git branch or tag for changelog-file sources.
​
flag
Show full body previews in text output.
​
flag
Omit release body content and return only version, date, and URL timeline data.
​
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.
Flags
​
string
Target version for single-package mode.
​
string
Batch package spec in <registry>:<name>@<current>..<target> format. Repeat the flag for multiple packages.
​
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 Inspection for the full parameter reference.
List documentation pages available for a package.
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 by its page ID.
Flags
​
string
Read an inclusive line range, such as 50-150.
​
flag
Include page metadata in text output.
​
flag
Output the result as JSON.

​
Code examples

Search for implementation examples from open-source repositories, issues, discussions, and pull requests using a natural-language query.
Flags
​
string
Force a specific programming language. Omit to let GitHits infer the language from your query. If you’re unsure of the exact language name, run npx githits@latest languages first.
​
string
default:"strict"
Control license filtering for Code 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.
List all supported programming language names. Optionally filter by a substring.
Flags
​
flag
Output the result as JSON.

​
Feedback

Submit feedback on a specific result or on your overall session. Use --accept for positive feedback and --reject for negative. A --message is recommended, especially for generic session feedback.
Arguments
​
string
Optional. The solution ID from a prior get_example result. When provided, feedback is anchored to that specific result. Omit to submit generic session feedback.
Flags
​
flag
Mark the result as helpful.
​
flag
Mark the result as unhelpful.
​
string
An explanation to accompany the feedback rating.
​
string
The command or MCP tool name being rated (e.g. code_grep, search).
​
flag
Output the result as JSON for scripting or piping.

​
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.
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.