Commands reference
Complete CLI surface, one row per command. Use as a lookup table; deep documentation lives in the feature pages.
#Global flags
These work on every command.
| Flag | Default | Description |
|---|
--config <path> | $GITCRAWL_CONFIG or default | Override config path |
--format text|json|log | text | Output format |
--json | (off) | Shorthand for --format json |
--no-color | (off) | Suppress ANSI color |
--version | (off) | Print version and exit (global only) |
--help / -h | — | Print usage |
#Setup
| Command | Purpose | Detailed docs |
|---|
gitcrawl init [--db --portable-store --portable-db --store-dir --json] | Create config, database, runtime directories; optionally clone a portable store | Installation, Portable stores |
gitcrawl doctor [--json] | Health check for config, database, credentials, model selection, repo/thread counts | Configuration |
gitcrawl configure [--summary-model --embed-model --embedding-basis --json] | Update model fields in config.toml | Configuration |
gitcrawl version | Print version | — |
#Sync
| Command | Purpose | Docs |
|---|
gitcrawl sync owner/repo [--state --since --numbers --limit --include-comments --include-pr-details --with pr-details --json] | Sync issues and PRs from GitHub into local SQLite | Sync |
gitcrawl refresh owner/repo [--no-sync --no-embed --no-cluster ...] | Wrapper that runs sync → embed → cluster | Refresh and embed |
gitcrawl embed owner/repo [--number --limit --force --include-closed --json] | Generate OpenAI embeddings for thread documents | Refresh and embed |
gitcrawl runs owner/repo [--kind sync|embedding|cluster --limit --json] | List recorded run history | Refresh and embed |
#Inspect
| Command | Purpose | Docs |
|---|
gitcrawl threads owner/repo [--include-closed --numbers --limit --json] | List threads from local cache | — |
gitcrawl search owner/repo --query <text> [--mode keyword|semantic|hybrid --limit --json] | Local search (direct mode) | Search |
gitcrawl search issues|prs <query> -R owner/repo [--state --json --limit --sync-if-stale] | Local search (gh search shape) | Search |
gitcrawl neighbors owner/repo --number <n> [--limit --threshold --json] | Vector-similar threads to a specific issue/PR | Clustering |
#Cluster
| Command | Purpose | Docs |
|---|
gitcrawl cluster owner/repo [--threshold --min-size --max-cluster-size --k --cross-kind-threshold --limit --model --basis --include-closed --json] | Build durable clusters from vectors | Clustering |
gitcrawl clusters owner/repo [--sort size|recent|oldest --min-size --limit --hide-closed --json] | Latest-run cluster summary, merged with closed durable rows | Clustering |
gitcrawl durable-clusters owner/repo [--include-closed --sort --min-size --limit --json] | Strict durable-cluster audit view | Clustering |
gitcrawl cluster-detail owner/repo --id <n> [--member-limit --body-chars --include-closed --json] | Cluster + members detail | Clustering |
gitcrawl cluster-explain owner/repo --id <n> [...] | Alias for cluster-detail | Clustering |
#Governance
| Command | Purpose | Docs |
|---|
gitcrawl close-thread owner/repo --number <n> [--reason --json] | Local close on a thread | Governance |
gitcrawl reopen-thread owner/repo --number <n> [--json] | Inverse | — |
gitcrawl close-cluster owner/repo --id <n> [--reason --json] | Local close on a cluster | Governance |
gitcrawl reopen-cluster owner/repo --id <n> [--json] | Inverse | — |
gitcrawl exclude-cluster-member owner/repo --id <n> --number <m> [--reason --json] | Pull a thread out of a cluster | Governance |
gitcrawl include-cluster-member owner/repo --id <n> --number <m> [--reason --json] | Inverse | — |
gitcrawl set-cluster-canonical owner/repo --id <n> --number <m> [--reason --json] | Pin canonical thread for a cluster | Governance |
#TUI
| Command | Purpose | Docs |
|---|
gitcrawl tui [owner/repo] [--min-size --sort --limit --hide-closed --json] | Interactive cluster browser; --json emits a snapshot instead of launching the UI | TUI |
#gh shim
| Command | Purpose | Docs |
|---|
gitcrawl gh search issues|prs <query> -R owner/repo [...] | Local-first gh search | gh shim |
gitcrawl gh issue view <n> -R owner/repo --json <fields> | Local-first thread view | gh shim |
gitcrawl gh pr view <n> -R owner/repo --json <fields> | Same, for PRs (with auto-hydration) | gh shim |
gitcrawl gh issue list -R owner/repo [--state --search --author --assignee --label --json] | Local-first list | gh shim |
gitcrawl gh pr list -R owner/repo [...] | Same, for PRs | gh shim |
gitcrawl gh pr checks <n> -R owner/repo --json <fields> | Cached PR checks (auto-hydrates if stale) | gh shim |
gitcrawl gh pr diff <n> -R owner/repo | Falls through; cached by head SHA | gh shim |
gitcrawl gh run list -R owner/repo [--branch --commit --json] | Cached workflow runs | gh shim |
gitcrawl gh run view <run-id> -R owner/repo [--json] | Same, single run | gh shim |
gitcrawl gh repo view|list ... | Falls through; cached briefly | gh shim |
gitcrawl gh release list|view ... | Falls through; cached briefly | gh shim |
gitcrawl gh workflow list|view ... | Falls through; cached briefly | gh shim |
gitcrawl gh secret list ... / variable get|list ... | Falls through; cached briefly | gh shim |
gitcrawl gh label list ... | Falls through; cached briefly | gh shim |
gitcrawl gh api <GET path> | Falls through; cached briefly (GET-only) | gh shim |
gitcrawl gh xcache stats|keys|gc|flush [--json] | Cache inspection / housekeeping | gh shim |
| Anything else | Falls through to real gh | gh shim |
The shim binary can be installed standalone by symlinking the gitcrawl binary as gh or gitcrawl-gh.
#Portable stores
| Command | Purpose | Docs |
|---|
gitcrawl portable prune [--body-chars --no-vacuum --json] | Build a compact portable v2 backup and (optionally) VACUUM for publishing | Portable stores |
#Not yet implemented
These appear in SPEC.md but currently return a "not implemented" error. They are reserved for future versions:
summarize, key-summaries, merge-clusters, split-cluster, export-sync, import-sync, validate-sync, portable-size, sync-status, optimize, completion
If you need any of these to land sooner, open an issue.