title: Reference nav_order: 16 permalink: /reference/

Reference

{: .no_toc }

Lookup tables for paths, environment variables, and defaults. {: .fs-6 .fw-300 }

TOC {:toc}

Paths

Path	Purpose
`~/.config/gitcrawl/config.toml`	Configuration file
`~/.config/gitcrawl/gitcrawl.db`	SQLite database
`~/.config/gitcrawl/cache/`	Local runtime caches
`~/.config/gitcrawl/vectors/`	Vector store backing embeddings
`~/.config/gitcrawl/logs/`	Operational logs
`~/.config/gitcrawl/portable/`	Portable-store checkout (when configured)

Override the config root with --config <path> or GITCRAWL_CONFIG.

Environment variables

Core

Variable	Default	Used by	Purpose
`GITCRAWL_CONFIG`	`~/.config/gitcrawl/config.toml`	All commands	Override config path
`GITCRAWL_DB_PATH`	`~/.config/gitcrawl/gitcrawl.db`	All commands	Override database path
`GITCRAWL_TUI_LAYOUT`	`columns`	`tui`	Override default wide-screen layout
`GITHUB_TOKEN`	(none)	`sync`	GitHub API token
`OPENAI_API_KEY`	(none)	`embed`, `refresh`	OpenAI API key

Models

Variable	Default	Purpose
`GITCRAWL_SUMMARY_MODEL`	`gpt-5.4`	Summary model (reserved for future commands)
`GITCRAWL_EMBED_MODEL`	`text-embedding-3-small`	OpenAI embedding model
`GITCRAWL_OPENAI_RETRY_DISABLED`	(off)	Set `1` to disable OpenAI retry/backoff
`GITCRAWL_OPENAI_BASE_URL` / `OPENAI_BASE_URL`	OpenAI default	Custom OpenAI endpoint

GitHub overrides

Variable	Default	Purpose
`GITCRAWL_GITHUB_BASE_URL` / `GITHUB_BASE_URL`	GitHub default	Custom GitHub API endpoint
`GH_REPO`	(none)	Default repository for compatible local search shapes

gh shim

gitcrawl gh moved to Octopool. Run octopool login, then use octopool gh ....

Configuration defaults

Field	Default
`summary_model`	`gpt-5.4`
`embed_model`	`text-embedding-3-small`
`embed_dimensions`	`1024`
`embedding_basis`	`title_original`
`batch_size` (embeddings)	`64`
`concurrency` (embeddings)	`2`
`tui_default_sort`	`size`
`tui_default_layout`	`columns`

Clustering defaults

Parameter	Default	Source
`--threshold`	`0.80`	`cluster`, `refresh`
`--cross-kind-threshold`	`0.93`	`cluster`, `refresh`
`--min-size`	`1`	`cluster`, `refresh`
`--max-cluster-size`	`40`	`cluster`, `refresh`
`--k` (nearest-neighbor fanout)	`16`	`cluster`, `refresh`
Weak-edge title overlap floor	`0.18`	internal
High-confidence edge score	`0.90`	internal
Deterministic reference edge score	`0.94`	internal
Body-only reference prefix length	`240` chars	internal

TUI defaults

Parameter	Default
`--min-size`	`5`
`--sort`	`size`
`--layout`	`columns`
Working set limit	`500` rows
Refresh interval	`15s`

Output formats

Format	Where to use
`text`	Human terminal use (default)
`json`	Pipelines, scripts, agents (also via `--json`)
`log`	Internal structured logging output

Exit codes

0 — success
non-zero — usage error, "not implemented" command, or runtime failure

stderr always carries error messages. stdout is reserved for command output.

File-system layout (worked example)

~/.config/gitcrawl/
├── config.toml
├── gitcrawl.db                  # SQLite mirror
├── gitcrawl.db-shm              # SQLite shared-memory file
├── gitcrawl.db-wal              # SQLite write-ahead log
├── cache/
│   └── pr/                      # local runtime cache
├── vectors/                     # vector store backing embeddings
├── logs/
└── portable/                    # portable-store checkout (optional)
    └── data/
        └── owner__repo.sync.db