GitHits CLI command reference: all commands and flags

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.

Setup and configuration

npx githits@latest init

Authenticate and configure GitHits for supported AI coding tools.

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.

npx githits@latest init

Automatic install support: Claude Code, Cursor, Windsurf, VS Code / Copilot, Cline, Claude Desktop, Codex CLI, Pi, Gemini CLI, Google Antigravity, and OpenCode.By default, init performs a guided MCP setup: alongside the MCP server config, it drops a githits-mcp Agent Skill and a managed instruction block (delimited by  markers in files like AGENTS.md, CLAUDE.md, or GEMINI.md) into each supported tool. The skill and instructions help the agent decide when to reach for GitHits without bloating its base context. 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

-y, --yes

flag

Skip interactive prompts and configure all detected tools automatically. Defaults to guided MCP unless --no-guidance is set.

Skip the authentication step. Useful if you are already authenticated and only want to reconfigure tool integrations.

--project

flag

Configure project-level MCP in the current directory instead of user-level tool configuration.

--detect-agents

flag

Scan supported agents and print what GitHits can configure without installing anything.

--install-agents

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.

--guidance

flag

Explicitly install the githits-mcp skill and managed instruction block alongside MCP configuration. This is the default; use the flag when scripting a guided install to make intent explicit.

--no-guidance

flag

Install plain MCP only. Skips the githits-mcp skill and the managed instruction block in supported tools.

--json

flag

Emit JSON output for --detect-agents or --install-agents.

init is the default way to get started. It configures supported tools and handles authentication for common local setup.

npx githits@latest init uninstall

Remove GitHits MCP configuration from detected coding tools.

Remove GitHits MCP configuration from all detected coding tools. Uninstall also cleans up guided setup artifacts: the managed instruction block (content between  markers) is removed from files like AGENTS.md, CLAUDE.md, and GEMINI.md, and any copied githits-mcp skill files are deleted from tool-native skill folders. Stored credentials are preserved — only MCP config, guidance blocks, and skill files are removed.

npx githits@latest init uninstall

Flags

-y, --yes

flag

Skip prompts and uninstall user-level MCP configuration.

--project

flag

Remove project-level MCP configuration from the current directory.

--keep-guidance

flag

Remove the MCP server configuration but leave the githits-mcp skill 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.

npx githits@latest doctor

Diagnose GitHits configuration and authentication state.

Print redacted diagnostics for GitHits CLI, MCP configuration, environment variables, and authentication state.

npx githits@latest doctor

Flags

--json

flag

Output diagnostics as JSON.

Authentication

npx githits@latest login

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.

npx githits@latest login

Flags

--no-browser

flag

Print the authorization URL instead of opening the browser. Use this in SSH sessions, CI environments, or containers where a browser isn’t available.

--force

flag

Re-authenticate even if a valid token already exists.

--port

number

Use a specific port for the local OAuth callback server. Defaults to a random port in the 8000–9999 range.

npx githits@latest login

If authentication times out (after 5 minutes), the browser link expires. Run the command again to get a fresh link.

npx githits@latest logout

Remove stored OAuth credentials from this machine.

Remove stored OAuth credentials. After logging out, tool calls that require authentication will fail until you log in again.

npx githits@latest logout

npx githits@latest auth status

Check the current authentication status and credential source.

Show current authentication status, including the credential source, storage location, and token expiry.

npx githits@latest auth status

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.

MCP server

npx githits@latest mcp

Show manual MCP setup instructions or start stdio mode in non-TTY contexts.

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.

npx githits@latest mcp

Use this command to see the JSON snippet you need to add to your tool’s MCP configuration manually.

npx githits@latest mcp start

Start the GitHits MCP server over stdio for coding tool configs.

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.

npx githits@latest mcp start

A typical MCP config entry looks like this:

MCP config

{
  "mcpServers": {
    "githits": {
      "command": "npx",
      "args": ["-y", "githits@latest", "mcp", "start"]
    }
  }
}

Search, code, package, and docs tools

npx githits@latest search

Search indexed package or repository code, docs, and symbols.

Run a unified indexed search across dependency and repository code, documentation, and symbols.

npx githits@latest search "<query>" --in <target>
npx githits@latest search "router middleware" --in npm:express
npx githits@latest search '"body parser" OR multer' --in npm:express --source docs
npx githits@latest search "compose" --in npm:lodash --source code --kind function

Results include a searchRef you can pass to npx githits@latest search-status to poll for additional results from an async index scan.Flags

--in

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.

--source

string

Restrict results to docs, code, or symbol. Omit to let GitHits choose the best indexed sources.

--kind

string

Restrict symbol results by kind, such as function, method, class, interface, module, or doc_section.

--category

string

Restrict symbol results by category: callable, type, module, data, or documentation.

--path-prefix

string

Restrict code or symbol results to paths under a literal prefix.

--intent

string

Restrict code or symbol results by file intent: production, test, benchmark, example, generated, fixture, build, or vendor.

--public

flag

Restrict symbol results to public symbols.

--name

string

Restrict symbol results to a specific symbol name.

--lang

string

Restrict results by programming language.

--allow-partial

flag

Return hits from sources that finished indexing while other sources continue.

--limit

number

Maximum results to return (1-100, default 10).

--offset

number

Offset for pagination.

--wait

number

Seconds to wait for indexing before returning a searchRef (0-60, default 20).

--json

flag

Output the result as JSON.

npx githits@latest search-status

Poll a prior async indexed search by its searchRef.

Follow up on a prior npx githits@latest search using the searchRef returned in the initial response.

npx githits@latest search-status <searchRef>

Flags

--json

flag

Output the result as JSON.

npx githits@latest code files

List files in an indexed package or repository.

List the files included in an indexed package or repository.

npx githits@latest code files <spec> [path-prefix]
npx githits@latest code files npm:express
npx githits@latest code files npm:express src/
npx githits@latest code files npm:express --ext ts --ext js

Flags

--repo-url

string

Use a GitHub repository URL instead of a compact package or repo spec.

--git-ref

string

Git ref to use with --repo-url.

--path

string

Return one exact target-relative file path.

--glob

string

Include files matching a glob. Repeat for multiple globs.

--ext

string

Include files with this extension, without the leading dot. Repeat for multiple extensions.

--file-type

string

Include files with this file type. Repeat for multiple types.

--language

string

Include files with this language. Repeat for multiple languages.

--file-intent

string

Include files with this intent. Repeat for multiple intents.

--exclude-intent

string

Exclude files with this intent after inclusive filtering. Repeat for multiple intents.

--exclude-docs

flag

Exclude documentation files.

--exclude-tests

flag

Exclude test files.

--hidden

flag

Include hidden files.

--limit

number

Maximum files to return (default 200).

--wait

number

Milliseconds to wait for indexing (0-60000, default 20000).

-v, --verbose

flag

Include metadata with text output.

--json

flag

Output the result as JSON.

npx githits@latest code read

Read a specific indexed source file by path.

Read a specific file from an indexed package or repository by path.

npx githits@latest code read <spec> <path>
npx githits@latest code read npm:express src/application.js
npx githits@latest code read npm:express src/application.js --lines 120-200

Flags

--repo-url

string

Use a GitHub repository URL instead of a compact package or repo spec.

--git-ref

string

Git ref to use with --repo-url.

--lines

string

Read an inclusive line range, such as 120-200. You can also append :120-200 to the file path.

--start

number

Starting line number for the read.

--end

number

Ending line number for the read.

--wait

number

Milliseconds to wait for indexing (0-60000, default 20000).

-v, --verbose

flag

Add a metadata header and line gutter to text output.

--json

flag

Output the result as JSON.

npx githits@latest code grep

Search indexed source files with literal text or regex.

Search for a text pattern across the indexed files of a package or repository.

npx githits@latest code grep <spec> <pattern>
npx githits@latest code grep npm:express "Router"
npx githits@latest code grep npm:express "use\(.*middleware" --regex
npx githits@latest code grep npm:express "createServer" src/ --ext js

Flags

--repo-url

string

Use a GitHub repository URL instead of a compact package or repo spec.

--git-ref

string

Git ref to use with --repo-url.

--path

string

Restrict grep to one exact target-relative file path.

--glob

string

Restrict grep to files matching a glob. Repeat for multiple globs.

--ext

string

Restrict grep to files with this extension, without the leading dot. Repeat for multiple extensions.

--regex

flag

Treat the pattern as a regex. Literal matching is the default.

--case-sensitive

flag

Use case-sensitive matching.

-C, --context

number

Include this many lines before and after each match.

-B, --before-context

number

Include this many lines before each match.

-A, --after-context

number

Include this many lines after each match.

--exclude-docs

flag

Exclude documentation files.

--exclude-tests

flag

Exclude test files.

--limit

number

Maximum matches to return (default 50).

--per-file-limit

number

Maximum matches to return per file.

--cursor

string

Pagination cursor from a previous grep response.

--symbol-field

string

Include a symbol field in grep output. Repeat for multiple fields.

--wait

number

Milliseconds to wait for indexing (0-60000, default 20000).

-v, --verbose

flag

Include additional metadata in text output.

--json

flag

Output the result as JSON.

npx githits@latest pkg info

Inspect package metadata, popularity, downloads, and vulnerability status.

Show a package overview including version, license, repository popularity, download counts, and vulnerability summary.

npx githits@latest pkg info <registry>:<package>
npx githits@latest pkg info npm:express
npx githits@latest pkg info pypi:requests --verbose

Flags

-v, --verbose

flag

Include GitHub language/topics/last-pushed, recent advisories, and recent changes in text output.

--json

flag

Output the result as JSON.

See Package Inspection for the full parameter reference.

npx githits@latest pkg vulns

List known CVE and OSV advisories for a package or version.

List CVE and OSV vulnerability advisories for a package or a specific version.

npx githits@latest pkg vulns <registry>:<package>
npx githits@latest pkg vulns npm:lodash
npx githits@latest pkg vulns npm:lodash@4.17.20 --severity high

Flags

-s, --severity

string

Minimum advisory severity: low, medium, high, or critical.

--scope

string

Advisory rows to return: affected (default), non_affecting, or all.

--include-withdrawn

flag

Include retracted advisories.

-v, --verbose

flag

Show every selected advisory with full detail rows in text output.

--json

flag

Output the result as JSON.

npx githits@latest pkg deps

Show direct dependencies and optional transitive dependency details.

Show direct dependencies, dependency groups, and optionally the full transitive dependency graph.

npx githits@latest pkg deps <registry>:<package>
npx githits@latest pkg deps npm:express
npx githits@latest pkg deps npm:webpack --depth 3

Flags

-l, --lifecycle

string

Dependency lifecycle breadth. Use runtime, development, build, peer, optional, or all.

--depth

number

Add transitive dependency data and cap traversal at this depth (1-10).

-v, --verbose

flag

Include additional dependency metadata in text output.

--json

flag

Output the result as JSON.

npx githits@latest pkg changelog

Retrieve release notes or changelog entries for packages and repos.

Retrieve release notes and changelog entries for a package or GitHub repository, newest-first.

npx githits@latest pkg changelog <registry>:<package>
npx githits@latest pkg changelog npm:express --limit 5
npx githits@latest pkg changelog npm:express --from 4.18.0 --to 4.19.0
npx githits@latest pkg changelog --repo-url https://github.com/expressjs/express

Flags

--repo-url

string

Read changelog evidence from a GitHub repository URL instead of a registry package.

--from

string

Start of a version range. Use with --to for upgrade review evidence.

--to

string

End of a version range. Defaults to latest when --from is set.

--limit

number

Maximum latest-mode entries to return (1-50, default 10).

--git-ref

string

Git branch or tag for changelog-file sources.

-v, --verbose

flag

Show full body previews in text output.

--no-body

flag

Omit release body content and return only version, date, and URL timeline data.

--json

flag

Output the result as JSON.

npx githits@latest pkg upgrade-review

Compare package versions with security, changelog, and dependency evidence.

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.

npx githits@latest pkg upgrade-review <registry>:<package>@<current> --to <target>
npx githits@latest pkg upgrade-review npm:zod@4.3.6 --to 4.4.3
npx githits@latest pkg upgrade-review --package npm:zod@4.3.6..4.4.3 --package npm:lint-staged@16.2.7..16.4.0

Flags

--to

string

Target version for single-package mode.

--package

string

Batch package spec in <registry>:<name>@<current>..<target> format. Repeat the flag for multiple packages.

--no-transitive-security

flag

Skip the transitive vulnerability summary diff.

--dependency-issues

flag

Include deprecated, outdated, duplicate, and conflict summary diffs.

--min-severity

string

Minimum direct-advisory severity: low, medium, high, or critical.

-v, --verbose

flag

Include dependency change examples in text output.

--json

flag

Output the result as JSON.

See Package Inspection for the full parameter reference.

npx githits@latest docs list

List hosted and repo-backed documentation pages for a package.

List documentation pages available for a package.

npx githits@latest docs list <spec>
npx githits@latest docs list npm:express
npx githits@latest docs list pypi:requests --limit 20

Flags

--limit

number

Maximum pages to return.

--after

string

Pagination cursor from a previous docs list response.

-v, --verbose

flag

Include additional page metadata in text output.

--json

flag

Output the result as JSON.

npx githits@latest docs read

Read a documentation page by page ID, optionally by line range.

Read a specific documentation page by its page ID.

npx githits@latest docs read <pageId>
npx githits@latest docs read <pageId> --lines 50-150

Flags

--lines

string

Read an inclusive line range, such as 50-150.

-v, --verbose

flag

Include page metadata in text output.

--json

flag

Output the result as JSON.

Code examples

npx githits@latest example

Find implementation examples from real open-source usage.

Search for implementation examples from open-source repositories, issues, discussions, and pull requests using a natural-language query.

npx githits@latest example "<query>"

Flags

-l, --lang

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.

--license

string

default:"strict"

Control license filtering for Code Examples. Options: strict (default), yolo, or custom.

--explain

flag

Include an AI-generated explanation alongside the code example.

--json

flag

Output the result as JSON for piping or scripting. The envelope includes result and, when available, solution_id.

npx githits@latest example "connect to postgres with connection pooling"

npx githits@latest languages

List or filter supported programming language names.

List all supported programming language names. Optionally filter by a substring.

npx githits@latest languages [filter]

# List all supported languages
npx githits@latest languages

# Filter by substring
npx githits@latest languages type

Flags

--json

flag

Output the result as JSON.

Feedback

npx githits@latest feedback

Rate a specific result or submit generic session 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.

npx githits@latest feedback [solution_id] --accept | --reject [options]

Arguments

solution_id

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

--accept

flag

Mark the result as helpful.

--reject

flag

Mark the result as unhelpful.

--message, -m

string

An explanation to accompany the feedback rating.

--tool

string

The command or MCP tool name being rated (e.g. code_grep, search).

--json

flag

Output the result as JSON for scripting or piping.

npx githits@latest feedback abc123 --accept

​Setup and configuration

​Authentication

​MCP server

​Search, code, package, and docs tools

​Code examples

​Feedback

Setup and configuration

Authentication

MCP server

Search, code, package, and docs tools

Code examples

Feedback