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

> See the exact JSON and CSV output shapes used by gitquarry commands.

# Output Schemas

Gitquarry supports `pretty`, `json`, `toon`, `compact`, and `csv`.

This page documents the structured formats. `--format toon` serializes the same data model as JSON using Token-Oriented Object Notation, so the field contracts below apply to both JSON and TOON.

## Search JSON Shape

`gitquarry search --format json` serializes this top-level shape:

```json theme={null}
{
  "host": "github.com",
  "mode": "native",
  "rank": "native",
  "query": "rust cli",
  "compiled_query": "rust cli language:rust",
  "limit": 10,
  "total_count": 123,
  "items": []
}
```

Each item uses the repository schema:

```json theme={null}
{
  "name": "gitquarry",
  "full_name": "Microck/gitquarry",
  "html_url": "https://github.com/Microck/gitquarry",
  "description": "A terminal CLI for public GitHub repository search.",
  "stargazers_count": 123,
  "forks_count": 7,
  "language": "Rust",
  "topics": ["github", "search", "cli"],
  "license": {
    "key": "mit",
    "name": "MIT License",
    "spdx_id": "MIT"
  },
  "created_at": "2026-04-01T00:00:00Z",
  "updated_at": "2026-04-22T00:00:00Z",
  "pushed_at": "2026-04-22T00:00:00Z",
  "archived": false,
  "is_template": false,
  "fork": false,
  "open_issues_count": 0,
  "owner": {
    "login": "Microck"
  },
  "readme": null,
  "latest_release": null,
  "contributor_count": null,
  "explain": null,
  "probe": null
}
```

When probe flags are active, `repository.probe` can include:

```json theme={null}
{
  "reference": "main",
  "truncated": false,
  "matched_paths": [
    {
      "path": "src/lib.rs",
      "kind": "Blob",
      "size": 1234
    }
  ],
  "searched_files": 1,
  "skipped_files": 0,
  "total_code_matches": 1,
  "code_matches": [
    {
      "path": "src/lib.rs",
      "line": 12,
      "lines": [
        {
          "line": 12,
          "text": "use octocrab::Octocrab;",
          "matched": true
        }
      ]
    }
  ]
}
```

## Search Plan JSON Shape

`gitquarry search --plan --format json` serializes this shape and does not call GitHub:

```json theme={null}
{
  "host": "github.com",
  "plan": {
    "query": "rust cli",
    "compiled_query": "rust cli language:rust",
    "mode": "native",
    "rank": "native",
    "sort": "stars",
    "depth": "balanced",
    "format": "json",
    "limit": 10,
    "readme": false,
    "explain": false,
    "weights": {
      "query": 1.0,
      "activity": 1.0,
      "quality": 1.0
    },
    "concurrency": 1,
    "progress": "auto",
    "post_filters": {
      "updated_after": null,
      "updated_before": null
    },
    "native_query_present": true
  },
  "network": {
    "will_call_github": false,
    "estimated_requests_if_run": 1
  }
}
```

## Inspect JSON Shape

`gitquarry inspect --format json` wraps one repository:

```json theme={null}
{
  "host": "github.com",
  "repository": {
    "...": "same repository schema as search items"
  }
}
```

## Compare JSON Shape

`gitquarry compare --format json` serializes this top-level shape:

```json theme={null}
{
  "host": "github.com",
  "total_count": 1,
  "items": [
    {
      "repository": {
        "...": "same repository schema as search items"
      },
      "tree_summary": {
        "reference": "main",
        "truncated": false,
        "total_entries": 10,
        "blobs": 7,
        "trees": 3,
        "commits": 0
      }
    }
  ]
}
```

`tree_summary` is `null` unless `--tree-summary` is active.

## Tree JSON Shape

`gitquarry tree --format json` serializes this top-level shape:

```json theme={null}
{
  "host": "github.com",
  "repository": "Microck/gitquarry",
  "reference": "main",
  "truncated": false,
  "total_count": 3,
  "items": [
    {
      "path": "src/main.rs",
      "kind": "Blob",
      "size": 1234
    }
  ]
}
```

`kind` is one of `Blob`, `Tree`, or `Commit`.

## Code JSON Shape

`gitquarry code --format json` serializes this top-level shape:

```json theme={null}
{
  "host": "github.com",
  "repository": "Microck/gitquarry",
  "reference": "main",
  "pattern": "fn main",
  "mode": "literal",
  "searched_files": 1,
  "skipped_files": 0,
  "total_count": 1,
  "items": [
    {
      "path": "src/main.rs",
      "line": 3,
      "lines": [
        {
          "line": 3,
          "text": "fn main() {",
          "matched": true
        }
      ]
    }
  ]
}
```

## Explain Object

When `--explain` is active in enhanced flows, `repository.explain` can include:

```json theme={null}
{
  "query": 0.82,
  "activity": 0.61,
  "quality": 0.74,
  "blended": 0.73,
  "weights": {
    "query": 1.0,
    "activity": 1.0,
    "quality": 1.0
  },
  "matched_surfaces": ["name", "description", "topics"]
}
```

## CSV Columns

`search` and `inspect` CSV output write this header:

```text theme={null}
full_name,html_url,description,stars,forks,language,topics,license,created_at,updated_at,pushed_at,archived,template,fork,open_issues_count,contributor_count,query_score,activity_score,quality_score,blended_score
```

Notes:

* `topics` is pipe-delimited inside one CSV field
* timestamps are RFC3339 in CSV
* score columns are `0` when no explain data is present
* `inspect --format csv` writes one row
* `tree --format csv` writes `path,type,size`
* `code --format csv` writes `path,line,text`
* `compare --format csv` writes repository columns plus tree summary columns

## Pretty Output

Pretty output is for humans, not strict parsing.

`search --format pretty` prints:

* total count
* effective mode
* effective rank
* host
* per-repo summary blocks

`inspect --format pretty` prints:

* full name
* URL
* description
* stars, forks, language, topics, license
* dates
* archived/template/fork status
* open issue count
* latest release when available
* README block when requested

`tree --format pretty` prints repository/ref metadata and an indented file tree.

`code --format pretty` prints match counts, file paths, line numbers, and requested context lines.