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

# Resolve a target

> Find canonical package, repository, or documentation targets from an open-source dependency name.

Use `resolve_target` when your agent knows a dependency's name but needs a target for another GitHits tool. It returns candidates such as `npm:express`, `github:openai/codex`, or `site:docs.example.com/sdk`.

Target resolution is available by default in `githits` and `@githits/mcp` from 0.27.0. Hosted MCP availability depends on the deployed package version.

Already have a canonical target such as `npm:express`? Pass it directly to `search`, `list`, or another tool. The resolver accepts human-readable names and rejects canonical targets with `INVALID_ARGUMENT`.

```bash theme={null}
npx githits@latest resolve express
npx githits@latest resolve codex --prefer-kind repository
npx githits@latest resolve guava --registry maven --limit 3
npx githits@latest resolve "pi agent" --query "coding agent CLI"
```

## Parameters

| MCP parameter | CLI argument or flag | Description |
| - | - | - |
| `name` | Positional argument | Required package, repository, or documentation-site name |
| `query` | `--query` | Task context for ranking retrieved candidates |
| `intent_hints` | Repeatable `--intent-hint` | Additional ranking context |
| `registries` | `--registry` | Package registry filter; CLI accepts a comma-separated list. Repository and site candidates remain eligible |
| `preferred_kind` | `--prefer-kind` | Preference for `package`, `repository`, or `site` |
| `limit` | `--limit` | Ranked candidate limit, 1–20; default 8. Exact-name and related targets can appear in addition |
| `verbose` | `--verbose` | Include name similarity in text output |
| `format` | `--json` | MCP uses `text` by default; choose `json` for structured output |

Ranking context helps order retrieved candidates; it does not expand the search. Inputs must describe public open-source software. Do not include credentials, personal data, private code, or proprietary content.

## Choose a target

Results group related package, repository, and documentation identities together. Your agent should follow the result's guidance:

| Result | Next step |
| - | - |
| Non-ambiguous `EXACT` or `HIGH` match with malicious-content status `clear` or `not_applicable` | Use the best target in the next tool call |
| `MEDIUM` or `LOW` confidence | Narrow the name or filters, or explicitly choose a candidate |
| Ambiguous matches | Ask the user to select a target or narrow the input |
| Affected, uncertain, missing, or unrecognized malicious-content status | Review the warning; GitHits does not offer an automatic next-tool action |
| No candidates | Correct the name or adjust registry filters. The CLI exits with code `1` |

Pass a selected package or repository target to the tool you need. A `site:` target is for documentation: use `list` to browse it or `search` with `source: "docs"`, then reuse the returned `read` locator.

## Malicious-content gating

Package candidates include a check for malicious-package advisories affecting their latest version:

* `clear`: no active malicious-package advisory affects the latest version. This does not mean the package is free of vulnerabilities.
* `not_applicable`: the target is not a package.
* `affected`: an active malicious-package advisory affects the latest version.
* `unknown`: advisories exist, but GitHits cannot reliably classify the latest version.

Warnings link to the relevant `MAL-*` advisories on OSV. Uncertain results include the reasons for uncertainty; truncated results report omitted advisories. Use [`pkg_vulns`](/tools/package-inspection) to inspect vulnerabilities for a package version.

## JSON output

CLI `--json` and MCP `format: "json"` return `ambiguous`, optional `ambiguousReason`, `candidates`, `protectedMatches`, and an optional `best` match. `best` is absent when there are no candidates.

Candidates include `latestVersionMaliciousStatus`. Affected or uncertain candidates also include `latestVersionMaliciousEvidence`, with advisory IDs, classification reasons, and truncation details. Available `nameSimilarity` values are included in JSON; similarity alone does not establish that a candidate is the right target.


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