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

# search

> Reference for gitquarry search, including native behavior, discover mode, structured flags, and output formats.

# `gitquarry search`

Search public GitHub repositories.

## Synopsis

```bash theme={null}
gitquarry search [OPTIONS] [QUERY]
```

## Default Behavior

With no enhancement flags, `search` behaves as close to native GitHub repository search as possible.

* one repository search request
* native ordering
* no silent metadata enrichment
* no README fetching

## Search Modes

### Native

Native is the default.

```bash theme={null}
gitquarry search "rust cli"
gitquarry search "rust cli" --sort stars
```

### Discover

Discover mode is explicit:

```bash theme={null}
gitquarry search "rust cli" --mode discover
```

This enables staged candidate collection and local reranking.

## Ranking

```bash theme={null}
--rank native|query|activity|quality|blended
```

Rules:

* non-native ranks require `--mode discover`
* `--mode discover` without `--rank` defaults to `blended`
* `--sort` affects candidate retrieval, not final order, when rank is non-native

## Sort

```bash theme={null}
--sort best-match|stars|updated
```

In native ranking, final output order follows the selected sort.

## Structured Filters

Owner and visibility:

* `--user`
* `--org`
* `--archived`
* `--template`
* `--fork`

Classification:

* `--language`
* `--topic`
* `--license`

Ranges:

* `--min-stars`, `--max-stars`
* `--min-forks`, `--max-forks`
* `--min-size`, `--max-size`

Dates:

* `--created-after`, `--created-before`
* `--updated-after`, `--updated-before`
* `--pushed-after`, `--pushed-before`
* `--created-within`, `--updated-within`, `--pushed-within`

## Conflict Policy

If you write a raw GitHub qualifier inside the query and also pass an overlapping structured flag, gitquarry fails clearly instead of guessing.

Examples:

* `language:rust` plus `--language go`
* `stars:>100` plus `--min-stars 200`

## README and Explain

```bash theme={null}
--readme
--explain
```

* `--readme` enables README enrichment for the top candidate window
* `--explain` exposes ranking reasons in enhanced modes

## Plan Output

```bash theme={null}
--plan
```

`--plan` prints the compiled search plan without resolving auth or calling GitHub. Use it to debug structured filters, raw query conflicts, output format, effective mode, and estimated request counts before running a search.

Example:

```bash theme={null}
gitquarry search "release automation" \
  --language rust \
  --topic cli \
  --sort stars \
  --plan \
  --format json
```

## Probe Evidence

```bash theme={null}
--probe-path <GLOB>
--probe-code <PATTERN>
--probe-mode literal|regex
--probe-context <N>
--probe-limit <N>
--probe-match-limit <N>
--probe-max-file-bytes <BYTES>
```

Probe flags attach explicit no-clone evidence to the final result window. They do not change search order or ranking.

* `--probe-path` records matching tree entries
* `--probe-code` searches candidate files for code evidence
* repeated `--probe-path` values use OR semantics
* `--probe-limit` bounds file-content fetches per repository
* `--probe-match-limit` bounds recorded code matches per repository

Example:

```bash theme={null}
gitquarry search "github app rust" \
  --probe-path "Cargo.toml" \
  --probe-path "src/*.rs" \
  --probe-code "octocrab" \
  --format toon
```

## Output

```bash theme={null}
--format pretty|json|toon|compact|csv
```

Examples:

```bash theme={null}
gitquarry search "rust cli" --format json
gitquarry search "rust cli" --format compact
gitquarry search "rust cli" --format csv
```

## Examples

Native search:

```bash theme={null}
gitquarry search "vector database"
```

Structured native search:

```bash theme={null}
gitquarry search "vector database" --language rust --sort stars
```

Empty-query discover search:

```bash theme={null}
gitquarry search --mode discover --topic cli --limit 5
```

README-aware discovery:

```bash theme={null}
gitquarry search "release automation" \
  --mode discover \
  --rank blended \
  --readme \
  --explain
```