Skip to main content

​
Specification

This page replaces the former root-level SPEC.md file.

​
Product Summary

gitquarry is a Rust terminal CLI for public GitHub repository search. The core contract is:
  • plain search "query" is native GitHub-style repository search
  • custom filtering and better discovery exist behind explicit flags
  • nothing heavier happens silently

​
Command Surface

​
Root

  • gitquarry search [OPTIONS] [QUERY]
  • gitquarry inspect [OPTIONS] <OWNER/REPO>
  • gitquarry auth login [OPTIONS]
  • gitquarry auth status [OPTIONS]
  • gitquarry auth logout [OPTIONS]
  • gitquarry config path
  • gitquarry config show
  • gitquarry version
  • gitquarry --version
  • gitquarry --generate-completion <bash|zsh|fish|powershell>

​
Global Options

  • --host <HOST_OR_URL>
    • accept bare hostnames or full URLs
    • normalize internally
    • default host is github.com unless overridden by config

​
Auth

​
Scope

  • auth is always required
  • v1 is PAT-only
  • device flow is out of scope for v1
  • v1 is read-only and public-repos-only

​
Commands

  • auth login
    • interactive guided PAT setup
    • teaches the user how to create a PAT
    • recommends fine-grained PATs when possible
    • validates the PAT immediately
    • stores credentials per host
  • auth status
    • shows whether the current effective host has a saved PAT
  • auth logout
    • deletes the PAT for the current effective host

​
Storage

  • secrets are stored in the OS credential store by default
  • env vars override saved credentials
  • if secure storage is unavailable, insecure file fallback is allowed only with explicit opt-in and warning
  • PATs are stored per host, not globally

​
Config

​
Location

  • store config in a standard per-user config path
  • do not store config in the repo or current working directory

​
Allowed Saved Defaults

  • host
  • format
  • limit
  • progress
  • color preference

​
Disallowed Saved Defaults

These must remain explicit per command:
  • mode
  • rank
  • depth
  • readme
  • explain
  • blended ranking weights
  • discovery-only engine knobs

​
Synopsis

gitquarry search [OPTIONS] [QUERY]

​
Base Behavior

  • if the user passes no enhancement flags, search behaves as close to native GitHub repository search as possible
  • default output format is pretty
  • default result limit is 10
  • empty query is invalid in plain native search

​
Output Formats

  • pretty - default
  • json
  • compact
  • csv

​
Pretty Output Visual Default

  • the default accent color for human-facing pretty output is electric blue
  • the exact electric-blue shade does not need to be fixed in v1 as long as it stays in that visual family
  • ANSI color choices such as 21 or 27 are acceptable defaults
  • users may override color preference through config or terminal settings where supported

​
Retrieval Modes

  • --mode native
    • one native GitHub repository search only
  • --mode discover
    • explicit enhanced retrieval
    • uses staged candidate collection and local reranking
Default:
  • no --mode flag -> native behavior

​
Rank Modes

  • --rank native
  • --rank query
  • --rank activity
  • --rank quality
  • --rank blended
Rules:
  • no enhancement flags -> effective rank is native
  • --mode discover with no --rank -> default to blended
  • --rank never changes retrieval mode
  • --sort never changes rank mode

​
Native Ordering

--sort is reserved for native GitHub-like retrieval ordering. Supported values:
  • best-match
  • stars
  • updated
Rules:
  • in --rank native, final output order follows native ordering and --sort
  • in non-native rank modes, --sort influences candidate retrieval only; final displayed order comes from the selected rank mode

​
Structured Filter Flags

​
Owner / Visibility

  • --user <USER>
  • --org <ORG>
  • --archived <true|false>
  • --template <true|false>
  • --fork <false|true|only>

​
Metadata / Classification

  • --language <LANG> repeatable
  • --topic <TOPIC> repeatable
  • --license <LICENSE> repeatable

​
Numeric Ranges

  • --min-stars <N>
  • --max-stars <N>
  • --min-forks <N>
  • --max-forks <N>
  • --min-size <N>
  • --max-size <N>

​
Absolute Date Filters

  • --created-after <YYYY-MM-DD>
  • --created-before <YYYY-MM-DD>
  • --updated-after <YYYY-MM-DD>
  • --updated-before <YYYY-MM-DD>
  • --pushed-after <YYYY-MM-DD>
  • --pushed-before <YYYY-MM-DD>

​
Relative Date Filters

  • --created-within <DURATION>
  • --updated-within <DURATION>
  • --pushed-within <DURATION>
Relative duration syntax:
  • 12h
  • 30d
  • 8w
  • 6m
  • 1y

​
Filter Semantics

  • repeated structured flags use AND semantics
  • OR semantics remain available only through raw GitHub query syntax in the query string
  • --topic is GitHub-native topics only
  • custom label/category matching is not exposed as a first-class flag
  • custom label/category interpretation is query-driven and only available in enhanced/discovery mode

​
Native vs Post-Filter Behavior

Compile directly into GitHub-native search when possible:
  • user/org
  • archived
  • template
  • fork
  • language
  • topic
  • license
  • stars
  • forks
  • size
  • created
  • pushed
  • sort
Apply post-retrieval using repo metadata:
  • updated-*

​
Empty Query Rules

  • plain native search requires a query
  • empty query is allowed only in explicit discovery-oriented usage
Examples:
  • valid: gitquarry search "rust sdk"
  • valid: gitquarry search --mode discover --topic cli --sort updated
  • invalid: gitquarry search

​
Raw Query Plus Structured Flags

The free-text query is the base query. Structured flags append constraints. If the user manually writes a raw GitHub qualifier in the query and also passes an overlapping structured flag, fail clearly instead of guessing. Examples of conflicts:
  • language:rust plus --language go
  • topic:cli plus --topic sdk
  • stars:>100 plus --min-stars 200

​
Discovery Depth

Discovery depth is discover-only.
  • --depth quick
  • --depth balanced
  • --depth deep
Do not allow --depth outside discover mode. Default in discover mode:
  • balanced

​
Candidate Pool Targets

Discovery uses a deduped candidate pool before final reranking. Defaults:
  • quick: target max(25, limit * 3), cap 100
  • balanced: target max(50, limit * 5), cap 200
  • deep: target max(100, limit * 8), cap 400

​
Discovery Retrieval Behavior

Discovery retrieval is staged and bounded.

​
Quick

  • seed with one native GitHub repository search only
  • no extra fan-out beyond the initial retrieval
  • rerank only the returned candidate set

​
Balanced

  • seed with one native GitHub repository search
  • if the deduped pool is below target:
    • run the same search with sort=updated
    • run one recency-biased shard using a recent pushed bucket
  • stop as soon as the target pool is reached

​
Deep

  • includes balanced behavior
  • if still below target:
    • add older pushed bucket searches
    • add star-bucket shard searches if the user did not already constrain stars
  • stop as soon as the target pool is reached

​
README Enrichment

  • --readme is explicit
  • no README fetching occurs by default
  • --readme never changes retrieval mode by itself
  • README is enrichment-only, not candidate retrieval
README window:
  • metadata ranking runs first
  • then README enrichment inspects only the top candidate window
  • default window = min(20, max(limit * 2, 10))

​
Explainability

  • --explain is explicit
  • without --explain, no ranking reasons are shown
  • in native mode, --explain is minimal or unsupported
  • in enhanced modes, --explain can show:
    • matched surfaces
    • query score
    • activity score
    • quality score
    • blended score
    • effective weights
    • key contributing signals

​
Blended Ranking Weights

Weight flags:
  • --weight-query <0.0..3.0>
  • --weight-activity <0.0..3.0>
  • --weight-quality <0.0..3.0>
Rules:
  • weight flags are valid only with --rank blended
  • each value must be in the inclusive range 0.0 to 3.0
  • default weight for each component is 1.0
  • all-zero weight sets are invalid

​
Scoring

​
Query Score

Literal-first only. No automatic synonym expansion in v1. Use weighted literal matching across:
  • repository name
  • description
  • topics
  • README only if --readme is enabled

​
Activity Score

Use only:
  • pushed_at
  • updated_at
  • release recency
  • archived penalty

​
Quality Score

Use only:
  • stars
  • forks
  • contributor count
  • license presence
  • README presence
  • template status
No issue-based signals in v1. No momentum or trending signals in v1.

​
Blended Score

For --rank blended, compute a normalized weighted average: (wq * query + wa * activity + wql * quality) / (wq + wa + wql) Only include components whose weight is greater than zero.

​
Inspect

​
Synopsis

gitquarry inspect [OPTIONS] <OWNER/REPO>

​
Behavior

  • accept only explicit owner/repo
  • no cross-command memory
  • default is metadata-first
  • README is optional and explicit

​
Defaults

  • output format defaults to pretty
  • default content includes:
    • full name
    • URL
    • description
    • stars
    • forks
    • language
    • topics
    • license
    • created / updated / pushed
    • archived / template / fork status
    • open issues count
    • latest release summary when cheaply available

​
Inspect Flags

  • --readme
  • --format pretty|json|compact|csv

​
Progress

  • progress output goes to stderr only
  • default progress mode is auto
  • support --progress auto|on|off
  • in auto, show progress only when stderr is a TTY
  • no progress is written to stdout
  • prefer phase-based progress and counts over fake ETA
  • show ETA only for bounded loops where estimation is defensible

​
Advanced Engine Flags

  • --concurrency <N>
    • discover or enrichment only
    • default 1
    • error outside explicit discovery or enrichment usage
Other engine internals remain internal in v1.

​
Error Handling

  • fail on the first clear error
  • print plain text to stderr
  • include a stable symbolic error code
  • exit code 1
Examples:
  • E_FLAG_REQUIRES_MODE: --concurrency requires --mode discover
  • E_FLAG_CONFLICT: --created-after cannot be combined with --created-within
  • E_AUTH_REQUIRED: auth required for host github.example.com; run gitquarry auth login --host github.example.com
Errors are never emitted as JSON in v1.

​
Version And Completion

  • support both version and root --version
  • include shell completion generation in v1
  • support bash|zsh|fish|powershell