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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "host": "github.com",
  "repository": {
    "...": "same repository schema as search items"
  }
}

Compare JSON Shape

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

{
  "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:

{
  "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:

{
  "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:

{
  "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:

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.

CLI

Contracts

Behavior

Output Schemas

Output Schemas

Search JSON Shape

Search Plan JSON Shape

Inspect JSON Shape

Compare JSON Shape

Tree JSON Shape

Code JSON Shape

Explain Object

CSV Columns

Pretty Output

​Output Schemas

​Search JSON Shape

​Search Plan JSON Shape

​Inspect JSON Shape

​Compare JSON Shape

​Tree JSON Shape

​Code JSON Shape

​Explain Object

​CSV Columns

​Pretty Output

Output Schemas

Search JSON Shape

Search Plan JSON Shape

Inspect JSON Shape

Compare JSON Shape

Tree JSON Shape

Code JSON Shape

Explain Object

CSV Columns

Pretty Output