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

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.

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

flag

Install plain MCP only. Skips the githits-mcp skill 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.

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

flag

Skip prompts and uninstall user-level MCP configuration.

flag

Remove project-level MCP configuration from the current directory.

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

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.

npx githits@latest login

Flags

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.

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.

npx githits@latest login

npx githits@latest login --no-browser

npx githits@latest login --force

npx githits@latest login --port 8080

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.

npx githits@latest auth token

Print the current bearer token for scripts and command substitution.

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.

npx githits@latest auth token

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:

TOKEN=$(npx githits@latest auth token)
curl -H "Authorization: Bearer $TOKEN" https://api.githits.com/...

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.

npx githits@latest settings

View and update account preferences, privacy, terms, and limits.

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.

npx githits@latest settings
npx githits@latest settings show

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

Key	Values	Clearable
`default-language-id`	A single language UUID	Yes
`license-mode`	`safe`, `yolo`, or `custom`	No
`blocked-license-ids`	One or more license UUIDs (atomic list replacement)	Yes
`marketing-emails`	`enabled` or `disabled`	No

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.

npx githits@latest settings get

Read one writable account setting.

Read one account setting using its public CLI name.

npx githits@latest settings get <key>
npx githits@latest settings get license-mode

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.

npx githits@latest settings set

Update one account setting.

Update one writable account setting. The value is validated against the schema for that key and sent as a single selective PATCH.

npx githits@latest settings set <key> <values...>

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.

npx githits@latest settings set license-mode safe

npx githits@latest settings set marketing-emails disabled

npx githits@latest settings set blocked-license-ids \
  0198a7d0-6750-7ace-a68c-418062117d95 \
  0198a7d0-6750-7ace-a68c-418062117d96

npx githits@latest settings set default-language-id 0198a7d0-6750-7ace-a68c-418062117d95

npx githits@latest settings clear

Clear the default language or blocked license IDs.

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.

npx githits@latest settings clear <key>
npx githits@latest settings clear blocked-license-ids

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.

npx githits@latest settings terms

Show Terms of Service acceptance status.

Show whether the authenticated account currently needs to accept the GitHits Terms of Service.

npx githits@latest settings terms

Flags

flag

Output {"terms_required": boolean} as JSON.

npx githits@latest settings terms accept

Accept the current Terms of Service.

Confirm and accept the current GitHits Terms of Service for the authenticated account. Interactive by default; pass --yes for non-interactive use.

npx githits@latest settings terms accept
npx githits@latest settings terms accept --yes --json

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

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

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.

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

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

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.

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

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.

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

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.

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

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.

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

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.

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

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.

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

string

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

string

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

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.

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

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.

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

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.

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

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

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

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.

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

npx githits@latest example "parse JWT" --lang python

npx githits@latest example "retry with backoff" --license yolo

npx githits@latest example "JWT verification in Go" --explain

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

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

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.

npx githits@latest feedback abc123 --accept

npx githits@latest feedback abc123 --reject --message "Example was outdated"

npx githits@latest feedback --accept --tool search --message "fast results for npm:lodash"

npx githits@latest feedback --reject --json

Get Started

Tools

Reference

Guides

GitHits CLI command reference: all commands and flags

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

Setup and configuration

Authentication

MCP server

Search, code, package, and docs tools

Code examples

Feedback