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

# Output And Scripting

> Use gitquarry safely in scripts, pipelines, CI, and agent workflows.

# Output And Scripting

Gitquarry is designed to behave cleanly in pipelines.

The main rule is simple:

* structured data goes to `stdout`
* progress and errors go to `stderr`

## Output Formats

Supported formats:

* `pretty`
* `json`
* `toon`
* `compact`
* `csv`

### `pretty`

Human-first terminal output.

Use it when reading results directly in a shell:

```bash theme={null}
gitquarry search --format pretty "rust cli"
```

### `json`

Pretty-printed structured output for tools and scripts:

```bash theme={null}
gitquarry search --format json "rust cli"
gitquarry inspect rust-lang/rust --format json
```

### `toon`

Token-efficient structured output for LLM context:

```bash theme={null}
gitquarry search --format toon "rust cli"
gitquarry inspect rust-lang/rust --format toon
```

### `compact`

Minified JSON for pipelines or logs:

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

### `csv`

Flat export-friendly output:

```bash theme={null}
gitquarry search --format csv "rust cli"
gitquarry inspect rust-lang/rust --format csv
```

## Progress Behavior

Progress is controlled by:

```bash theme={null}
--progress auto|on|off
```

Rules:

* `auto` is the default
* in `auto`, gitquarry only prints progress when `stderr` is a TTY
* progress never goes to `stdout`

That means this is safe:

```bash theme={null}
gitquarry search "rust cli" --format json | jq '.items[0].full_name'
```

## JSON Examples

Search pipeline:

```bash theme={null}
gitquarry search "rust cli" --format json | jq '.items[].full_name'
```

Compact pipeline:

```bash theme={null}
gitquarry search "release automation" --mode discover --format compact | jq '.total_count'
```

Inspect pipeline:

```bash theme={null}
gitquarry inspect rust-lang/rust --readme --format json | jq '.repository.latest_release.tag_name'
```

## CSV Examples

Export search results:

```bash theme={null}
gitquarry search "vector database" --format csv > repos.csv
```

Export one inspected repository:

```bash theme={null}
gitquarry inspect rust-lang/rust --format csv > repo.csv
```

## CI-Friendly Usage

For deterministic CI or agent runs:

* prefer `json` or `compact`
* set `--progress off` if you want no progress noise at all
* isolate config state with `GITQUARRY_CONFIG_DIR`
* prefer env tokens over writing credentials into shared state

Example:

```bash theme={null}
GITQUARRY_CONFIG_DIR="$(mktemp -d)" \
GITQUARRY_TOKEN="$GITHUB_TOKEN" \
gitquarry search "rust cli" --format compact --progress off
```

## Error Handling

Errors are:

* plain text
* prefixed with a symbolic code
* written to `stderr`
* returned with exit code `1`

Examples:

```text theme={null}
E_QUERY_REQUIRED: empty query is invalid outside explicit discovery mode
E_FLAG_REQUIRES_MODE: --rank blended requires --mode discover
E_FLAG_CONFLICT: raw query qualifier language: conflicts with overlapping structured flags
```

See [error reference](/reference/error-reference) for the code list.