gitcrawl/docs/commands.md

title	nav_order	permalink
Commands reference	15	/commands/

Commands reference

{: .no_toc }

Complete CLI surface, one row per command. Use as a lookup table; deep documentation lives in the feature pages. {: .fs-6 .fw-300 }

1. TOC {:toc}

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 REST)	gh shim
gitcrawl gh api graphql -f query=...	Falls through; read-only queries are cached	gh shim
gitcrawl gh xcache stats|keys|gc|flush|reset [--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.