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 metadata [--json] | Print the crawlkit command/control manifest for launchers and automation | — |
gitcrawl status [--json] | Print read-only archive status, database inventory, and control state | — |
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 <refs> --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 <ref> --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 |
gitcrawl code index owner/repo [--path --max-file-bytes --max-total-bytes --max-files --json] | Index tracked text files from a local Git checkout | Code indexing |
#Inspect
| Command | Purpose | Docs |
|---|---|---|
gitcrawl threads owner/repo [--include-closed --numbers --limit --json] | List threads from local cache | — |
gitcrawl search owner/repo --query <text> [--scope threads|code|all --mode keyword|semantic|hybrid --limit --json] | Local thread/source 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 <ref> [--limit --threshold --json] | Vector-similar threads to a specific issue/PR | Clustering |
#Thread References
Commands that accept a thread number also accept thread references:
- bare numbers:
123 - hash references:
#123 - path references:
issues/123,pull/123 - scoped references:
owner/repo#123 - full GitHub issue or pull request URLs
This applies to sync --numbers, threads --numbers, embed --number, neighbors --number, all governance --number flags, and TUI jump input.
#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 clusters-report owner/repo [--sort size|recent|oldest --min-size --limit --member-limit --body-chars --hide-closed --json] | Markdown or JSON report for top display clusters | 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> [--source auto|run|durable --member-limit --body-chars --hide-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 <ref> [--reason --json] | Local close on a thread | Governance |
gitcrawl reopen-thread owner/repo --number <ref> [--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 <ref> [--reason --json] | Pull a thread out of a cluster | Governance |
gitcrawl include-cluster-member owner/repo --id <n> --number <ref> [--reason --json] | Inverse | — |
gitcrawl set-cluster-canonical owner/repo --id <n> --number <ref> [--reason --json] | Pin canonical thread for a cluster | Governance |
#TUI
| Command | Purpose | Docs |
|---|---|---|
gitcrawl tui [owner/repo] [--min-size --sort --layout --limit --hide-closed --json] | Interactive cluster browser; --json emits a snapshot instead of launching the UI | TUI |
#gh shim
gitcrawl gh moved to Octopool and now exits with a migration note.
Use:
octopool login
octopool gh api repos/openclaw/openclaw/pulls/123gitcrawl search issues|prs ... remains the local mirror search path.
#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.