> ## Documentation Index
> Fetch the complete documentation index at: https://docs.githits.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHits CLI command reference: all commands and flags

> Complete reference for every GitHits CLI command, organized by category: setup, authentication, MCP server, Code, Documentation, and Package Intelligence.

export const CommandAccordionToggle = () => {
  const [allOpen, setAllOpen] = useState(false);
  const getTriggers = () => Array.from(document.querySelectorAll('#content summary[data-component-part="accordion-button"][aria-expanded]'));
  const syncState = () => {
    const triggers = getTriggers();
    setAllOpen(triggers.length > 0 && triggers.every(trigger => trigger.getAttribute("aria-expanded") === "true"));
  };
  useEffect(() => {
    syncState();
    const content = document.getElementById("content");
    if (!content) {
      return;
    }
    const observer = new MutationObserver(syncState);
    observer.observe(content, {
      attributes: true,
      attributeFilter: ["aria-expanded"],
      subtree: true
    });
    return () => observer.disconnect();
  }, []);
  const toggleAll = () => {
    const triggers = getTriggers();
    const shouldOpen = !allOpen;
    triggers.forEach(trigger => {
      const isOpen = trigger.getAttribute("aria-expanded") === "true";
      if (isOpen !== shouldOpen) {
        trigger.click();
      }
    });
    window.setTimeout(syncState, 80);
  };
  return <div className="githits-command-toolbar">
      <button type="button" className="githits-command-toggle" aria-expanded={allOpen} onClick={toggleAll}>
        {allOpen ? "Collapse all" : "Expand all"}
      </button>
    </div>;
};

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.26.0](https://github.com/githits-com/githits-cli/releases/tag/v0.26.0). Use `npx githits@latest --version` to check the version you are running.

<CommandAccordionToggle />

***

## Global options

Global options can appear before any command.

| Option | Purpose |
| - | - |
| `-V, --version` | Print the installed GitHits version. |
| `--no-color` | Disable ANSI color output. The standard `NO_COLOR` environment variable has the same effect. |
| `-h, --help` | Show help for the current command. |

***

## Setup and configuration

<AccordionGroup>
  <Accordion title="npx githits@latest init" description="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.

    ```bash theme={null}
    npx githits@latest init
    ```

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

    <ParamField query="-y, --yes" type="flag">
      Skip interactive prompts and configure all detected tools automatically. Defaults to guided MCP unless `--no-guidance` is set.
    </ParamField>

    <ParamField query="--skip-login" type="flag">
      Skip the authentication step. Useful if you are already authenticated and only want to reconfigure tool integrations.
    </ParamField>

    <ParamField query="--project" type="flag">
      Configure project-level MCP in the current directory instead of user-level tool configuration.
    </ParamField>

    <ParamField query="--detect-agents" type="flag">
      Scan supported agents and print what GitHits can configure without installing anything.
    </ParamField>

    <ParamField query="--install-agents" type="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.
    </ParamField>

    <ParamField query="--guidance" type="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.
    </ParamField>

    <ParamField query="--no-guidance" type="flag">
      Install plain MCP only. Skips the GitHits skills and the managed instruction block in supported tools.
    </ParamField>

    <ParamField query="--json" type="flag">
      Emit JSON output for `--detect-agents` or `--install-agents`.
    </ParamField>

    <ParamField query="--no-browser" type="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.
    </ParamField>

    <ParamField query="--port" type="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`.
    </ParamField>

    <Tip>
      `init` is the default way to get started. It configures supported tools and handles authentication for common local setup.
    </Tip>
  </Accordion>

  <Accordion title="npx githits@latest uninstall" description="Remove GitHits MCP configuration and guidance 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 `<!-- 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.

    ```bash theme={null}
    npx githits@latest uninstall
    ```

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

    <ParamField query="-y, --yes" type="flag">
      Skip prompts and uninstall user-level MCP configuration. Never touches project files; combine with `--project` for non-interactive project-level removal.
    </ParamField>

    <ParamField query="--project" type="flag">
      Remove project-level MCP configuration from the current directory.
    </ParamField>

    <ParamField query="--keep-guidance" type="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.
    </ParamField>

    To also remove stored credentials, run `npx githits@latest logout` separately after uninstalling.
  </Accordion>

  <Accordion title="npx githits@latest doctor" description="Diagnose GitHits configuration and authentication state.">
    Print redacted diagnostics for GitHits CLI, MCP configuration, environment variables, and authentication state.

    ```bash theme={null}
    npx githits@latest doctor
    ```

    **Flags**

    <ParamField query="--json" type="flag">
      Output diagnostics as JSON.
    </ParamField>
  </Accordion>
</AccordionGroup>

***

## Authentication

<AccordionGroup>
  <Accordion title="npx githits@latest login" description="Log in to your GitHits account with browser OAuth.">
    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.

    ```bash theme={null}
    npx githits@latest login
    ```

    **Flags**

    <ParamField query="--no-browser" type="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.
    </ParamField>

    <ParamField query="--force" type="flag">
      Re-authenticate even if a valid token already exists.
    </ParamField>

    <ParamField query="--port" type="number">
      Use a specific port for the local OAuth callback server. Defaults to a random port in the 8000–9999 range.
    </ParamField>

    <CodeGroup>
      ```bash Standard login theme={null}
      npx githits@latest login
      ```

      ```bash SSH / headless login theme={null}
      npx githits@latest login --no-browser --port 8765
      ```

      ```bash Force re-authentication theme={null}
      npx githits@latest login --force
      ```

      ```bash Specific callback port theme={null}
      npx githits@latest login --port 8080
      ```
    </CodeGroup>

    When the browser runs on another machine, forward the same callback port from that machine before opening the printed URL:

    ```bash theme={null}
    ssh -N -L 8765:127.0.0.1:8765 user@remote-host
    ```

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

  <Accordion title="npx githits@latest logout" description="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.

    ```bash theme={null}
    npx githits@latest logout
    ```
  </Accordion>

  <Accordion title="npx githits@latest auth status" description="Check the current authentication status and credential source.">
    Show current authentication status, including the credential source, storage location, and token expiry.

    ```bash theme={null}
    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.
  </Accordion>

  <Accordion title="npx githits@latest auth token" description="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.

    ```bash theme={null}
    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 behavior**

    If 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 example**

    Use command substitution to hand the current session token off to another tool:

    ```bash theme={null}
    TOKEN=$(npx githits@latest auth token)
    curl -H "Authorization: Bearer $TOKEN" https://api.githits.dev/v1/packages/npm/express
    ```

    <Warning>
      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.
    </Warning>
  </Accordion>

  <Accordion title="npx githits@latest settings" description="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.

    ```bash theme={null}
    npx githits@latest settings
    npx githits@latest settings show
    ```

    **Flags**

    <ParamField query="--json" type="flag">
      Output the canonical settings object as JSON.
    </ParamField>

    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 |

    <Note>
      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.
    </Note>
  </Accordion>

  <Accordion title="npx githits@latest settings get" description="Read one writable account setting.">
    Read one account setting using its public CLI name.

    ```bash theme={null}
    npx githits@latest settings get <key>
    npx githits@latest settings get license-mode
    ```

    **Arguments**

    <ParamField path="key" type="string" required>
      One of `default-language-id`, `license-mode`, `blocked-license-ids`, or `marketing-emails`.
    </ParamField>

    **Flags**

    <ParamField query="--json" type="flag">
      Output the setting name and value as `{"key", "value"}` JSON.
    </ParamField>
  </Accordion>

  <Accordion title="npx githits@latest settings set" description="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.

    ```bash theme={null}
    npx githits@latest settings set <key> <values...>
    ```

    **Arguments**

    <ParamField path="key" type="string" required>
      One of `default-language-id`, `license-mode`, `blocked-license-ids`, or `marketing-emails`.
    </ParamField>

    <ParamField path="values" type="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.
    </ParamField>

    **Flags**

    <ParamField query="--json" type="flag">
      Output the updated canonical settings object as JSON.
    </ParamField>

    <CodeGroup>
      ```bash Set license mode theme={null}
      npx githits@latest settings set license-mode safe
      ```

      ```bash Opt out of marketing emails theme={null}
      npx githits@latest settings set marketing-emails disabled
      ```

      ```bash Replace blocked license IDs theme={null}
      npx githits@latest settings set blocked-license-ids \
        0198a7d0-6750-7ace-a68c-418062117d95 \
        0198a7d0-6750-7ace-a68c-418062117d96
      ```

      ```bash Set default language theme={null}
      npx githits@latest settings set default-language-id 0198a7d0-6750-7ace-a68c-418062117d95
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="npx githits@latest settings clear" description="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.

    ```bash theme={null}
    npx githits@latest settings clear <key>
    npx githits@latest settings clear blocked-license-ids
    ```

    **Arguments**

    <ParamField path="key" type="string" required>
      One of `default-language-id` or `blocked-license-ids`. Other keys cannot be cleared and must be updated with `settings set`.
    </ParamField>

    **Flags**

    <ParamField query="--json" type="flag">
      Output the updated canonical settings object as JSON.
    </ParamField>
  </Accordion>

  <Accordion title="npx githits@latest settings terms" description="Show Terms of Service acceptance status.">
    Show whether the authenticated account currently needs to accept the GitHits Terms of Service.

    ```bash theme={null}
    npx githits@latest settings terms
    ```

    **Flags**

    <ParamField query="--json" type="flag">
      Output `{"terms_required": boolean}` as JSON.
    </ParamField>
  </Accordion>

  <Accordion title="npx githits@latest settings terms accept" description="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.

    ```bash theme={null}
    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**

    <ParamField query="--yes" type="flag">
      Accept without an interactive confirmation. Required when running in a non-TTY environment such as CI.
    </ParamField>

    <ParamField query="--json" type="flag">
      Output the acceptance result as JSON, including `accepted`, `token_refreshed`, and the updated `settings` object.
    </ParamField>
  </Accordion>
</AccordionGroup>

***

## MCP server

<AccordionGroup>
  <Accordion title="npx githits@latest mcp" description="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.

    ```bash theme={null}
    npx githits@latest mcp
    ```

    Use this command to see the JSON snippet you need to add to your tool's MCP configuration manually.
  </Accordion>

  <Accordion title="npx githits@latest mcp start" description="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.

    ```bash theme={null}
    npx githits@latest mcp start
    ```

    A typical MCP config entry looks like this:

    ```json MCP config theme={null}
    {
      "mcpServers": {
        "githits": {
          "command": "npx",
          "args": ["-y", "githits@latest", "mcp", "start"]
        }
      }
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Deterministic

### Code

<AccordionGroup>
  <Accordion title="npx githits@latest list" description="List files and documentation in a package, repository, or hosted site.">
    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.

    ```bash theme={null}
    npx githits@latest list npm:express@5.2.1
    npx githits@latest list npm:express@5.2.1 lib/ --recursive
    npx githits@latest list github:expressjs/express@v5.2.1 'lib/**/*.js' --silent
    npx githits@latest list site:expressjs.com --recursive --limit 20 --json
    ```

    Pass literal paths or quoted globs as `[paths...]`. `--recursive` traverses matched directories. Text output has a source header followed by one path per line; directories end in `/`. Follow the header's `read` guidance or each JSON entry's `read` action. For site pages, preserve the emitted `site:` target and target-relative page path as separate arguments.

    **Flags**

    <ParamField query="-R, --recursive" type="flag">
      Traverse matched directories recursively.
    </ParamField>

    <ParamField query="--file-type" type="string">
      Filter source entries by case-insensitive file type, such as `source` or `doc`. Repeat for multiple types. Not accepted for site targets.
    </ParamField>

    <ParamField query="--language" type="string">
      Filter source entries by case-insensitive language name. Repeat for multiple languages. Not accepted for site targets.
    </ParamField>

    <ParamField query="--intent" type="string">
      Filter source entries by `production`, `test`, `benchmark`, `example`, `generated`, `fixture`, `build`, or `vendor`. Repeat for multiple intents. Not accepted for site targets.
    </ParamField>

    <ParamField query="--limit" type="number">
      Maximum entries per page, 1–500. When omitted, GitHits uses the service default.
    </ParamField>

    <ParamField query="--after" type="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.
    </ParamField>

    <ParamField query="--wait" type="number">
      Milliseconds to wait for source indexing, 0–300000. When omitted, GitHits uses the service default.
    </ParamField>

    <ParamField query="-s, --silent" type="flag">
      Output paths only in text mode, without the header or spinner. Does not change JSON output.
    </ParamField>

    <ParamField query="--json" type="flag">
      Preserve entries, read actions, pagination cursors, and inventory metadata in JSON.
    </ParamField>

    **Pagination**

    ```bash theme={null}
    npx githits@latest list npm:express@5.2.1 --recursive --limit 20 --json
    npx githits@latest list npm:express@5.2.1 --recursive --limit 20 --json --after '<nextCursor>'
    ```

    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.

    <Note>
      `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`](/tools/code-navigation#list). Refresh local tool discovery after upgrading.
    </Note>
  </Accordion>

  <Accordion title="npx githits@latest search" description="Search indexed package or repository code, docs, and symbols.">
    Run a unified indexed search across dependency and repository code, documentation, and symbols.

    ```bash theme={null}
    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
    ```

    When a response supplies an active `searchRef` and continuation guidance, pass it to `npx githits@latest search-status`. See [search results and JSON migration](/tools/code-navigation#search) for the 0.23.0 result fields.

    **Flags**

    <ParamField query="--in" type="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`.
    </ParamField>

    <ParamField query="--source" type="string">
      Restrict results to `docs`, `code`, or `symbol`. Omit to let GitHits choose the best indexed sources.
    </ParamField>

    <ParamField query="--kind" type="string">
      Restrict symbol results by kind, such as `function`, `method`, `class`, `interface`, `module`, or `doc_section`.
    </ParamField>

    <ParamField query="--category" type="string">
      Restrict symbol results by category: `callable`, `type`, `module`, `data`, or `documentation`.
    </ParamField>

    <ParamField query="--path-prefix" type="string">
      Restrict code or symbol results to paths under a literal prefix.
    </ParamField>

    <ParamField query="--intent" type="string">
      Restrict code or symbol results by file intent: `production`, `test`, `benchmark`, `example`, `generated`, `fixture`, `build`, or `vendor`.
    </ParamField>

    <ParamField query="--public" type="flag">
      Restrict symbol results to public symbols.
    </ParamField>

    <ParamField query="--name" type="string">
      Restrict symbol results to a specific symbol name.
    </ParamField>

    <ParamField query="--lang" type="string">
      Restrict results by programming language.
    </ParamField>

    <ParamField query="--allow-partial" type="flag">
      Return available hits while other targets or sources prepare. Enabled by default from 0.27.0.
    </ParamField>

    <ParamField query="--no-allow-partial" type="flag">
      Wait for all runnable targets and sources before returning hits.
    </ParamField>

    <ParamField query="--limit" type="number">
      Maximum results to return (1-100, default 10).
    </ParamField>

    <ParamField query="--offset" type="number">
      Offset for pagination.
    </ParamField>

    <ParamField query="--wait" type="number">
      Seconds to wait for indexing before returning a `searchRef` (0–120, default 30). When the response carries indexing-time estimates, GitHits automatically extends its follow-up wait up to the 120-second ceiling.
    </ParamField>

    <ParamField query="--json" type="flag">
      Output the result as JSON.
    </ParamField>
  </Accordion>

  <Accordion title="npx githits@latest search-status" description="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.

    ```bash theme={null}
    npx githits@latest search-status <searchRef>
    ```

    **Flags**

    <ParamField query="--wait" type="number">
      Maximum seconds to wait for progress before returning the latest status, 0–120 (default 30). GitHits also uses indexing-time estimates from the initial search to pick a longer wait automatically, up to the 120-second ceiling.
    </ParamField>

    <ParamField query="--json" type="flag">
      Output the result as JSON.
    </ParamField>
  </Accordion>

  <Accordion title="npx githits@latest read" description="Read an indexed source file, code symbol, or documentation section.">
    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.

    ```bash theme={null}
    npx githits@latest read <target-or-path> [path]
    npx githits@latest read npm:express@5.2.1 lib/application.js --lines 120-200
    npx githits@latest read github:expressjs/express@v5.2.1 lib/express.js
    npx githits@latest read 'npm:express@5.2.1#createApplication'
    npx githits@latest read https://expressjs.com/en/5x/api/express/
    npx githits@latest read https://expressjs.com/en/5x/api/express/#expressjson
    npx githits@latest read npm:express@5.2.1 --selector createApplication
    npx githits@latest read npm:express@5.2.1 lib/express.js --selector createApplication
    npx githits@latest read https://expressjs.com/en/5x/api/express/ --selector expressjson
    ```

    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](/tools/code-navigation#read) for details.

    <Note>
      `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`.
    </Note>

    **Flags**

    <ParamField query="--repo-url" type="string">
      Repository URL addressing. When set, the first positional argument is the file path.
    </ParamField>

    <ParamField query="--git-ref" type="string">
      Git ref to use with `--repo-url`. Rejected for documentation reads.
    </ParamField>

    <ParamField query="--lines" type="string">
      Inclusive line range, such as `120-200`, `120-`, or `-200`. You can also append `:120-200` to the file path.
    </ParamField>

    <ParamField query="--selector" type="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.
    </ParamField>

    <ParamField query="--start" type="number">
      Starting line number for source or documentation reads. Use `--start`/`--end` as an alternative to `--lines`.
    </ParamField>

    <ParamField query="--end" type="number">
      Inclusive ending line number for source or documentation reads. Use `--start`/`--end` as an alternative to `--lines`.
    </ParamField>

    <ParamField query="--wait" type="number">
      Code indexing wait in milliseconds (0–60000, default 30000). Validated for documentation reads but not forwarded.
    </ParamField>

    <ParamField query="-v, --verbose" type="flag">
      Add a metadata header and line gutter to text output.
    </ParamField>

    <ParamField query="--json" type="flag">
      Output the result as JSON.
    </ParamField>
  </Accordion>

  <Accordion title="npx githits@latest grep" description="Grep packages, repositories, and hosted documentation in one page.">
    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.

    ```bash theme={null}
    npx githits@latest grep <pattern> <targets...>
    npx githits@latest grep 'router' npm:express --path lib/express.js
    npx githits@latest grep -Fi 'router' npm:express site:expressjs.com
    npx githits@latest grep -C 2 'app\.use\(' github:expressjs/express --glob 'lib/**/*.js'
    npx githits@latest grep -F -- '--foo' github:example/repository
    ```

    Defaults follow grep and rg conventions, and differ from `code grep`:

    * Patterns are 1–200 UTF-8 bytes and use RE2 regex. Pass `-F` for literal matching. Unsupported or anchorless expressions fail instead of falling back to a literal search.
    * Matching is case-sensitive. Pass `-i` to ignore case.
    * Output has zero context lines. Pass `-A`, `-B`, or `-C` to add context.
    * Repository targets search all indexed files, source and documentation.

    Package targets also include their selected hosted documentation, independent of `--corpus` and path filters. `--corpus source` therefore does not exclude a package's hosted docs. Path flags and `--corpus` apply to every package and repository operand. `site:` operands accept only the target, so source flags with only `site:` operands fail. Put `--` before a pattern that starts with a dash.

    Text output starts with a match summary and a single `Sources:` line naming the resolved scopes. Matches are grouped under numbered `[1]`, `[2]` file or page headers. Each header begins with a copyable read locator you can pass to [`read`](#npx-githits-latest-read) with `--lines`. Match rows use `:` after the line number and context rows use `-`. Pass `--json` for the detailed lossless page, including read actions and byte coordinates.

    **Flags**

    <ParamField query="-F, --fixed-strings" type="flag">
      Match the pattern as a literal string instead of an RE2 regex.
    </ParamField>

    <ParamField query="-i, --ignore-case" type="flag">
      Ignore case with Unicode case folding.
    </ParamField>

    <ParamField query="-s, --case-sensitive" type="flag">
      Match case sensitively. Follows the rg convention; traditional grep uses `-s` to suppress errors. The last case flag wins.
    </ParamField>

    <ParamField query="-A, --after-context" type="number">
      Trailing context lines per match, 0–10.
    </ParamField>

    <ParamField query="-B, --before-context" type="number">
      Leading context lines per match, 0–10.
    </ParamField>

    <ParamField query="-C, --context" type="number">
      Context lines on both sides, 0–10. `-A` and `-B` override their side regardless of order.
    </ParamField>

    <ParamField query="--path" type="string">
      Exact source path, applied to every package and repository operand. Repeatable.
    </ParamField>

    <ParamField query="--path-prefix" type="string">
      Source path prefix. Repeatable.
    </ParamField>

    <ParamField query="--glob" type="string">
      Source path glob. Repeatable. Path selectors are OR-ed within each source operand.
    </ParamField>

    <ParamField query="--corpus" type="string" default="all">
      Repository files to search: `source`, `documentation`, or `all`.
    </ParamField>

    <ParamField query="--limit" type="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.
    </ParamField>

    <ParamField query="--cursor" type="string">
      Continue from a previous page. Reuse the same ordered targets and controls with the cursor unchanged.
    </ParamField>

    <ParamField query="--wait" type="number">
      First-page preparation wait in milliseconds, 0–300000 (default 0). Continuation never waits.
    </ParamField>

    <ParamField query="--json" type="flag">
      Emit the detailed lossless JSON page.
    </ParamField>

    **Pagination and coverage**

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

    <Note>
      `githits code grep` remains available with its existing literal, case-insensitive defaults. MCP 0.25.0 replaces `code_grep` with [`grep`](/tools/code-navigation#grep), using the same matching defaults as top-level CLI `grep`. Refresh tool discovery and migrate arguments.
    </Note>
  </Accordion>

  <Accordion title="npx githits@latest code grep" description="Legacy single-target source grep; prefer npx githits@latest grep.">
    Search for a text pattern across the indexed files of a package or repository. For new CLI usage, prefer [`githits grep`](#npx-githits-latest-grep), which searches multiple targets and hosted documentation in one page.

    ```bash theme={null}
    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**

    <ParamField query="--repo-url" type="string">
      Use a GitHub repository URL instead of a compact package or repo spec.
    </ParamField>

    <ParamField query="--git-ref" type="string">
      Git ref to use with `--repo-url`.
    </ParamField>

    <ParamField query="--path" type="string">
      Restrict grep to one exact target-relative file path.
    </ParamField>

    <ParamField query="--glob" type="string">
      Restrict grep to files matching a glob. Repeat for multiple globs.
    </ParamField>

    <ParamField query="--ext" type="string">
      Restrict grep to files with this extension, without the leading dot. Repeat for multiple extensions.
    </ParamField>

    <ParamField query="--regex" type="flag">
      Treat the pattern as a regex. Literal matching is the default.
    </ParamField>

    <ParamField query="--case-sensitive" type="flag">
      Use case-sensitive matching.
    </ParamField>

    <ParamField query="-C, --context" type="number">
      Include this many lines before and after each match.
    </ParamField>

    <ParamField query="-B, --before-context" type="number">
      Include this many lines before each match.
    </ParamField>

    <ParamField query="-A, --after-context" type="number">
      Include this many lines after each match.
    </ParamField>

    <ParamField query="--exclude-docs" type="flag">
      Exclude documentation files.
    </ParamField>

    <ParamField query="--exclude-tests" type="flag">
      Exclude test files.
    </ParamField>

    <ParamField query="--limit" type="number">
      Maximum matches to return (default 50).
    </ParamField>

    <ParamField query="--per-file-limit" type="number">
      Maximum matches to return per file.
    </ParamField>

    <ParamField query="--cursor" type="string">
      Pagination cursor from a previous grep response.
    </ParamField>

    <ParamField query="--symbol-field" type="string">
      Include a symbol field in grep output. Repeat for multiple fields.
    </ParamField>

    <ParamField query="--wait" type="number">
      Milliseconds to wait for indexing (0–60000, default 30000).
    </ParamField>

    <ParamField query="-v, --verbose" type="flag">
      Include additional metadata in text output.
    </ParamField>

    <ParamField query="--json" type="flag">
      Output the result as JSON.
    </ParamField>
  </Accordion>

  <Accordion title="npx githits@latest code files" description="Legacy file inventory; prefer npx githits@latest list.">
    Deprecated in 0.23.0 help. Use [`list`](#npx-githits-latest-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.

    ```bash theme={null}
    npx githits@latest code files <spec> [path-prefix]
    npx githits@latest code files npm:express
    npx githits@latest code files npm:express lib/
    npx githits@latest code files npm:express --ext ts --ext js
    ```

    **Flags**

    <ParamField query="--repo-url" type="string">
      Use a GitHub repository URL instead of a compact package or repo spec.
    </ParamField>

    <ParamField query="--git-ref" type="string">
      Git ref to use with `--repo-url`.
    </ParamField>

    <ParamField query="--path" type="string">
      Return one exact target-relative file path.
    </ParamField>

    <ParamField query="--glob" type="string">
      Include files matching a glob. Repeat for multiple globs.
    </ParamField>

    <ParamField query="--ext" type="string">
      Include files with this extension, without the leading dot. Repeat for multiple extensions.
    </ParamField>

    <ParamField query="--file-type" type="string">
      Include files with this file type. Repeat for multiple types.
    </ParamField>

    <ParamField query="--language" type="string">
      Include files with this language. Repeat for multiple languages.
    </ParamField>

    <ParamField query="--file-intent" type="string">
      Include files with this intent. Repeat for multiple intents.
    </ParamField>

    <ParamField query="--exclude-intent" type="string">
      Exclude files with this intent after inclusive filtering. Repeat for multiple intents.
    </ParamField>

    <ParamField query="--exclude-docs" type="flag">
      Exclude documentation files.
    </ParamField>

    <ParamField query="--exclude-tests" type="flag">
      Exclude test files.
    </ParamField>

    <ParamField query="--hidden" type="flag">
      Include hidden files.
    </ParamField>

    <ParamField query="--limit" type="number">
      Maximum files to return (default 200).
    </ParamField>

    <ParamField query="--wait" type="number">
      Milliseconds to wait for indexing (0–60000, default 30000).
    </ParamField>

    <ParamField query="-v, --verbose" type="flag">
      Include metadata with text output.
    </ParamField>

    <ParamField query="--json" type="flag">
      Output the result as JSON.
    </ParamField>
  </Accordion>

  <Accordion title="npx githits@latest code read" description="Deprecated alias for npx githits@latest read on a source file.">
    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`](#npx-githits-latest-read). Behavior and flags are unchanged; prefer the unified command in new scripts.

    ```bash theme={null}
    npx githits@latest code read <spec> <path>
    npx githits@latest code read npm:express@5.2.1 lib/application.js
    npx githits@latest code read npm:express@5.2.1 lib/application.js --lines 120-200
    ```

    **Flags**

    <ParamField query="--repo-url" type="string">
      Use a GitHub repository URL instead of a compact package or repo spec.
    </ParamField>

    <ParamField query="--git-ref" type="string">
      Git ref to use with `--repo-url`.
    </ParamField>

    <ParamField query="--lines" type="string">
      Read an inclusive line range, such as `120-200`. You can also append `:120-200` to the file path.
    </ParamField>

    <ParamField query="--start" type="number">
      Starting line number for the read.
    </ParamField>

    <ParamField query="--end" type="number">
      Ending line number for the read.
    </ParamField>

    <ParamField query="--wait" type="number">
      Milliseconds to wait for indexing (0–60000, default 30000).
    </ParamField>

    <ParamField query="-v, --verbose" type="flag">
      Add a metadata header and line gutter to text output.
    </ParamField>

    <ParamField query="--json" type="flag">
      Output the result as JSON.
    </ParamField>
  </Accordion>

  <Accordion title="npx githits@latest code diff" description="Compare repository trees resolved from two package versions or refs.">
    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.

    Available by default since 0.26.0.

    ```bash theme={null}
    npx githits@latest code diff <target> <from>..<to>
    npx githits@latest code diff npm:express 4.18.1..4.18.2
    npx githits@latest code diff npm:express 4.18.1..4.18.2 --stat
    npx githits@latest code diff npm:express 4.18.1..4.18.2 --name-status -- 'lib/**/*.js'
    npx githits@latest code diff --repo-url https://github.com/expressjs/express v4.18.1..v4.18.2 --name-only
    ```

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

    **Flags**

    <ParamField query="--repo-url" type="string">
      Address a public GitHub repository directly. Use repository refs in the required `<from>..<to>` range.
    </ParamField>

    <ParamField query="--patch" type="flag">
      Default view. Unified-diff output; may omit some Git metadata such as index and mode headers.
    </ParamField>

    <ParamField query="--stat" type="flag">
      Diffstat view. Mutually exclusive with `--patch`, `--name-only`, and `--name-status`.
    </ParamField>

    <ParamField query="--name-only" type="flag">
      List changed paths only.
    </ParamField>

    <ParamField query="--name-status" type="flag">
      List changed paths with change-status letters.
    </ParamField>

    <ParamField query="--max-files" type="number">
      Cap on files. Applied after deterministic relevance ranking. No client default.
    </ParamField>

    <ParamField query="--max-patch-bytes" type="number">
      Byte cap for the `--patch` view. No client default.
    </ParamField>

    <ParamField query="-v, --verbose" type="flag">
      Show exact resolution and repository-scope diagnostics in text output.
    </ParamField>

    <ParamField query="--json" type="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.
    </ParamField>

    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 results.
  </Accordion>
</AccordionGroup>

***

### Documentation

Use [`search --source docs`](#code) to find documentation by topic, then list or read pages with these commands.

<AccordionGroup>
  <Accordion title="npx githits@latest docs list" description="List hosted and repo-backed documentation pages for a package.">
    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`](#npx-githits-latest-list) with a `site:` target.

    ```bash theme={null}
    npx githits@latest docs list <spec>
    npx githits@latest docs list npm:express
    npx githits@latest docs list pypi:requests --limit 20
    ```

    **Flags**

    <ParamField query="--limit" type="number">
      Maximum pages to return.
    </ParamField>

    <ParamField query="--after" type="string">
      Pagination cursor from a previous `docs list` response.
    </ParamField>

    <ParamField query="-v, --verbose" type="flag">
      Include additional page metadata in text output.
    </ParamField>

    <ParamField query="--json" type="flag">
      Output the result as JSON.
    </ParamField>
  </Accordion>

  <Accordion title="npx githits@latest docs read" description="Deprecated alias for npx githits@latest read on a documentation page.">
    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`](#npx-githits-latest-read). Behavior and flags are unchanged; prefer the unified command in new scripts.

    ```bash theme={null}
    npx githits@latest docs read https://expressjs.com/en/5x/api/express/
    npx githits@latest docs read https://expressjs.com/en/5x/api/express/ --lines 50-150
    npx githits@latest docs read <pageId>
    ```

    **Flags**

    <ParamField query="--lines" type="string">
      Read an inclusive line range, such as `50-150`.
    </ParamField>

    <ParamField query="-v, --verbose" type="flag">
      Include page metadata in text output.
    </ParamField>

    <ParamField query="--json" type="flag">
      Output the result as JSON.
    </ParamField>
  </Accordion>
</AccordionGroup>

***

### Package Intelligence

<AccordionGroup>
  <Accordion title="npx githits@latest pkg info" description="Inspect package metadata, popularity, downloads, and vulnerability status.">
    Show a package overview including version, license, repository popularity, download counts, and vulnerability summary.

    ```bash theme={null}
    npx githits@latest pkg info <registry>:<package>
    npx githits@latest pkg info npm:express
    npx githits@latest pkg info pypi:requests --verbose
    ```

    **Flags**

    <ParamField query="-v, --verbose" type="flag">
      Include GitHub language/topics/last-pushed, published-version count, download refresh date, package-wide advisory history, and recent changes in text output.
    </ParamField>

    <ParamField query="--json" type="flag">
      Output the result as JSON.
    </ParamField>

    See [Package Intelligence](/tools/package-inspection) for the full parameter reference.
  </Accordion>

  <Accordion title="npx githits@latest pkg vulns" description="List known CVE and OSV advisories for a package or version.">
    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`).

    ```bash theme={null}
    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**

    <ParamField query="-s, --severity" type="string">
      Minimum advisory severity: `low`, `medium`, `high`, or `critical`.
    </ParamField>

    <ParamField query="--scope" type="string">
      Advisory rows to return: `affected` (default), `non_affecting`, or `all`.
    </ParamField>

    <ParamField query="--include-withdrawn" type="flag">
      Include retracted advisories. Affects direct package rows only; transitive withdrawn advisories remain excluded.
    </ParamField>

    <ParamField query="--transitive" type="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.
    </ParamField>

    <ParamField query="-v, --verbose" type="flag">
      Show every selected advisory with full detail rows in text output.
    </ParamField>

    <ParamField query="--json" type="flag">
      Output the result as JSON.
    </ParamField>
  </Accordion>

  <Accordion title="npx githits@latest pkg deps" description="Show direct dependencies and optional transitive dependency details.">
    Show direct dependencies, dependency groups, and optionally the full transitive dependency graph. Go module versions are accepted with or without the leading `v`.

    ```bash theme={null}
    npx githits@latest pkg deps <registry>:<package>
    npx githits@latest pkg deps npm:express
    npx githits@latest pkg deps npm:webpack --depth 3
    ```

    **Flags**

    <ParamField query="-l, --lifecycle" type="string">
      Dependency lifecycle breadth. Use `runtime`, `development`, `build`, `peer`, `optional`, or `all`.
    </ParamField>

    <ParamField query="--depth" type="number">
      Add transitive dependency data and cap traversal at this depth (1-10).
    </ParamField>

    <ParamField query="--issues" type="flag">
      Compute deprecated, outdated, duplicate, and conflict analysis across the resolved dependency graph. Use `--verbose` for complete issue details.
    </ParamField>

    <ParamField query="-v, --verbose" type="flag">
      Include additional dependency metadata in text output.
    </ParamField>

    <ParamField query="--json" type="flag">
      Output the result as JSON.
    </ParamField>
  </Accordion>

  <Accordion title="npx githits@latest pkg changelog" description="Retrieve release notes and changelog entries for a package.">
    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.

    ```bash theme={null}
    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 npm:express@5.2.1
    npx githits@latest pkg changelog npm:express@4.21.2..5.2.1
    ```

    **Flags**

    <ParamField query="--from" type="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`.
    </ParamField>

    <ParamField query="--to" type="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.
    </ParamField>

    <ParamField query="--limit" type="number">
      Maximum latest-mode or upper-cap entries (1–50, default 10). Rejected with an exact version, a lower range bound, or `--from`.
    </ParamField>

    <ParamField query="-v, --verbose" type="flag">
      Show full body previews in text output instead of the default ten lines per entry. Cannot be combined with `--no-body`.
    </ParamField>

    <ParamField query="--no-body" type="flag">
      Omit release body content in text and JSON output. Cannot be combined with `--verbose`.
    </ParamField>

    <ParamField query="--json" type="flag">
      Output the result as JSON.
    </ParamField>
  </Accordion>

  <Accordion title="npx githits@latest pkg upgrade-review" description="Compare package versions with security, changelog, and dependency changes.">
    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.

    ```bash theme={null}
    npx githits@latest pkg upgrade-review <registry>:<package>@<current>..<target>
    npx githits@latest pkg upgrade-review npm:zod@4.3.6..4.4.3
    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
    ```

    Use `..` as the range delimiter for the positional range and for repeatable `--package` entries. The legacy `->` delimiter is rejected with guidance to switch to `..`. A positional range already contains its target, so combining it with `--to` or `--package` is rejected. Go module versions are accepted with or without the leading `v`.

    **Flags**

    <ParamField query="--to" type="string">
      Target version for single-package mode. Cannot be combined with a positional `..` range.
    </ParamField>

    <ParamField query="--package" type="string">
      Batch package spec in `<registry>:<name>@<current>..<target>` format. Repeat the flag for multiple packages, up to 30 per batch.
    </ParamField>

    <ParamField query="--no-transitive-security" type="flag">
      Skip the transitive vulnerability summary diff.
    </ParamField>

    <ParamField query="--dependency-issues" type="flag">
      Include deprecated, outdated, duplicate, and conflict summary diffs.
    </ParamField>

    <ParamField query="--min-severity" type="string">
      Minimum direct-advisory severity: `low`, `medium`, `high`, or `critical`.
    </ParamField>

    <ParamField query="-v, --verbose" type="flag">
      Include dependency change examples in text output.
    </ParamField>

    <ParamField query="--json" type="flag">
      Output the result as JSON.
    </ParamField>

    See [Package Intelligence](/tools/package-inspection) for the full parameter reference.
  </Accordion>
</AccordionGroup>

***

### Target resolution

`resolve` is available by default from 0.27.0. See [Target resolution](/tools/target-resolution) for MCP parameters and guidance on choosing a result.

<AccordionGroup>
  <Accordion title="npx githits@latest resolve" description="Rank canonical package, repository, or documentation-site targets for a fuzzy name.">
    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.

    ```bash theme={null}
    npx githits@latest resolve <name>
    npx githits@latest resolve express
    npx githits@latest resolve codex --prefer-kind repository
    npx githits@latest resolve "example sdk docs" --prefer-kind site
    npx githits@latest resolve guava --registry maven --limit 3
    ```

    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](/tools/target-resolution#malicious-content-gating) for the status meanings.

    **Flags**

    <ParamField query="--registry" type="string">
      Comma-separated list of package registries. Constrains package candidates only; repository and site candidates remain eligible.
    </ParamField>

    <ParamField query="--prefer-kind" type="string">
      `package`, `repository`, or `site`. Soft preference, not a filter.
    </ParamField>

    <ParamField query="-q, --query" type="string">
      Ranking context. Ranks retrieved candidates and does not expand candidate retrieval. Must not contain credentials, personal data, private code, or proprietary content.
    </ParamField>

    <ParamField query="--intent-hint" type="string">
      Repeatable ranking hint. Same semantics and content restrictions as `--query`.
    </ParamField>

    <ParamField query="-n, --limit" type="number" default="8">
      Direct ranked list size, 1–20. Protected exact-name and related targets may appear in addition to the ranked list.
    </ParamField>

    <ParamField query="-v, --verbose" type="flag">
      Include coarse lexical name similarity in text output. This is not a reranking score. JSON includes available numeric similarity without this flag.
    </ParamField>

    <ParamField query="--json" type="flag">
      Emit the stable compact envelope `{best?, ambiguous, ambiguousReason?, candidates, protectedMatches}`. `best` is absent whenever there are no candidates.
    </ParamField>

    Exit code is `1` when there are no candidates because the command did not resolve a target.
  </Accordion>
</AccordionGroup>

***

## Agentic

<AccordionGroup>
  <Accordion title="npx githits@latest example" description="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.

    ```bash theme={null}
    npx githits@latest example "<query>"
    ```

    **Flags**

    <ParamField query="-l, --lang" type="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`.
    </ParamField>

    <ParamField query="--license" type="string" default="strict">
      Control license filtering for implementation examples. Options: `strict` (default), `yolo`, or `custom`.
    </ParamField>

    <ParamField query="--explain" type="flag">
      Include an AI-generated explanation alongside the code example.
    </ParamField>

    <ParamField query="--json" type="flag">
      Output the result as JSON for piping or scripting. The envelope includes `result` and, when available, `solution_id`.
    </ParamField>

    <CodeGroup>
      ```bash Basic example search theme={null}
      npx githits@latest example "connect to postgres with connection pooling"
      ```

      ```bash Specify a language theme={null}
      npx githits@latest example "parse JWT" --lang python
      ```

      ```bash Include all licenses theme={null}
      npx githits@latest example "retry with backoff" --license yolo
      ```

      ```bash With explanation theme={null}
      npx githits@latest example "JWT verification in Go" --explain
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="npx githits@latest research" description="Answer a question about a public package or repository with cited sources.">
    Research one public package or repository. Pass a quoted question alone to let GitHits identify the target, or precede it with an explicit target. `ask` remains an alias. Requires [experimental opt-in](/tools/experimental-tools#enable-the-tools).

    ```bash theme={null}
    npx githits@latest research "How does Express handle middleware errors?"
    npx githits@latest research npm:express "How are async middleware errors handled?"
    npx githits@latest research --thread '<threadId>' "Which source files implement that?"
    ```

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

    <ParamField query="--thread" type="string">
      Continue an existing research thread using its returned UUID.
    </ParamField>

    <ParamField query="--source-format" type="string" default="cli">
      Source citations inside the returned Markdown as executable `read` commands (`cli`) or upstream links (`url`).
    </ParamField>

    <ParamField query="--json" type="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.
    </ParamField>

    See [experimental Research](/tools/research) for thread and MCP behavior.
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.