### Verify Installation

Source: https://gitcrawl.sh/installation

Initialize the configuration and run the doctor command to verify the setup.

```bash
gitcrawl init           # creates config and data under platform default paths
gitcrawl doctor         # confirms config, database, and credential discovery
gitcrawl doctor --json  # same, machine-readable
```

--------------------------------

### Initial repository setup

Source: https://gitcrawl.sh/sync

Perform a full sync and embedding for a repository for the first time.

```bash
gitcrawl sync owner/repo --state all --include-comments
gitcrawl embed owner/repo
gitcrawl cluster owner/repo
```

--------------------------------

### One-step repository setup

Source: https://gitcrawl.sh/sync

Perform a full sync, embedding, and clustering in a single command.

```bash
gitcrawl refresh owner/repo --include-comments
```

--------------------------------

### Install and initialize gitcrawl

Source: https://gitcrawl.sh/quickstart

Build the binary from source and initialize the configuration and database directories.

```bash
# Build (or download a release archive — see Installation).
git clone https://github.com/openclaw/gitcrawl.git
cd gitcrawl
mkdir -p "$HOME/bin"
go build -o "$HOME/bin/gitcrawl" ./cmd/gitcrawl

# Create config + database under the platform default runtime paths.
gitcrawl init
```

--------------------------------

### octopool login command for first-time setup

Source: https://gitcrawl.sh/gh-shim

Run this command only when setting up a new Octopool installation. It is part of the first-time Octopool setup workflow.

```bash
octopool login
```

--------------------------------

### Install via Homebrew

Source: https://gitcrawl.sh/installation

Use Homebrew to install the gitcrawl binary.

```bash
brew install openclaw/tap/gitcrawl
```

--------------------------------

### Install from GitHub Release

Source: https://gitcrawl.sh/installation

Download and extract a specific version and platform archive from GitHub releases.

```bash
# Replace VERSION and PLATFORM with the values you want.
VERSION=v0.10.0
PLATFORM=darwin_arm64
mkdir -p "$HOME/bin"
curl -L "https://github.com/openclaw/gitcrawl/releases/download/${VERSION}/gitcrawl_${VERSION#v}_${PLATFORM}.tar.gz" \
  | tar -xz -C "$HOME/bin" gitcrawl

gitcrawl --version
```

--------------------------------

### Wire up the gh shim

Source: https://gitcrawl.sh/quickstart

Example of using the search command and Octopool for GitHub API interactions.

```bash
gitcrawl search issues "download stalls" -R openclaw/gitcrawl --json number,title,url
octopool login
octopool gh api repos/openclaw/gitcrawl/pulls/123
```

--------------------------------

### Example JSON output for embed command

Source: https://gitcrawl.sh/refresh-and-embed

Displays the structure of the JSON output, including metadata about the run, counts of processed items, and details on any batch failures.

```json
{
  "repository": "owner/repo",
  "model": "text-embedding-3-small",
  "basis": "title_original",
  "selected": 21,
  "embedded": 20,
  "skipped": 0,
  "failed": 1,
  "retries": 3,
  "status": "ok",
  "failures": [
    { "batch_start": 16, "batch_end": 17, "attempts": 3, "status": 429, "type": "rate_limit", "code": "rate_limit_exceeded", "message": "..." }
  ],
  "run_id": 43
}
```

--------------------------------

### JSON output format for overrides

Source: https://gitcrawl.sh/governance

Example of the JSON structure representing a local override state.

```json
{ "repository": "owner/repo", "number": 123, "reason": "duplicate handled", "closed": true }
```

--------------------------------

### GitHub Actions CI integration

Source: https://gitcrawl.sh/automation

Example workflow step to refresh and snapshot clusters, then upload the resulting JSON files as artifacts.

```yaml
- name: Refresh and snapshot clusters
  run: |
    gitcrawl init --portable-store $PORTABLE_STORE_URL
    gitcrawl refresh openclaw/gitcrawl --json > sync.json
    gitcrawl clusters openclaw/gitcrawl --json --sort size --min-size 5 > clusters.json
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

- uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
  with: { name: triage, path: "*.json" }
```

--------------------------------

### Example JSON sync output

Source: https://gitcrawl.sh/sync

The standard JSON output format returned by the sync command when --json is specified.

```json
{
  "repository": "owner/repo",
  "threads_synced": 124,
  "issues_synced": 100,
  "pull_requests_synced": 24,
  "comments_synced": 0,
  "metadata_only": true,
  "started_at": "2026-05-05T07:30:11Z",
  "finished_at": "2026-05-05T07:30:43Z"
}
```

--------------------------------

### Example JSON output for member exclusion

Source: https://gitcrawl.sh/governance

The expected JSON structure representing a member exclusion override.

```json
{
  "repository": "owner/repo",
  "override": { "cluster_id": 42, "thread_number": 456, "kind": "exclude", "reason": "different repro", "created_at": "..." },
  "excluded": true
}
```

--------------------------------

### gitcrawl clusters-report usage examples

Source: https://gitcrawl.sh/clustering

Shows usage of `gitcrawl clusters-report` with options for limiting rows, setting minimum size, and outputting JSON. The Markdown report includes an at-a-glance table, per-cluster metadata, member tables, and key snippets.

```bash
gitcrawl clusters-report owner/repo --limit 10 --min-size 5
gitcrawl clusters-report owner/repo --json
```

--------------------------------

### gitcrawl clusters usage examples

Source: https://gitcrawl.sh/clustering

Shows basic usage of `gitcrawl clusters` with options for sorting by size or recent, setting a minimum size, and hiding closed clusters. The command displays clusters from the latest raw run, merging closed durable rows as historical context.

```bash
gitcrawl clusters owner/repo
gitcrawl clusters owner/repo --sort size --min-size 5
gitcrawl clusters owner/repo --sort recent
gitcrawl clusters owner/repo --hide-closed
```

--------------------------------

### gh pr view command for fresh PR metadata

Source: https://gitcrawl.sh/gh-shim

Use this bare PATH gh command to view PR details with JSON output. It is part of the existing Octopool setup workflow, and uses native field names like headRefName and headRefOid.

```bash
gh pr view 123 -R owner/repo --json number,title,state,url,isDraft,headRefName,headRefOid
```

--------------------------------

### JSON output of gitcrawl search in hybrid mode

Source: https://gitcrawl.sh/search

Displays the JSON output format for gitcrawl search results, including repository, query, mode, and hits array with issue/PR metadata. The example shows the expected structure when --json is used.

```json
{
  "repository": "owner/repo",
  "query": "download stalls",
  "mode": "hybrid",
  "hits": [
    { "number": 123, "kind": "issue", "title": "...", "score": 0.81, "url": "...", "updated_at": "..." }
  ]
}
```

--------------------------------

### gitcrawl threads command for local discovery

Source: https://gitcrawl.sh/gh-shim

Use this command to keep local discovery in Gitcrawl, fetching thread numbers with closed issues included and JSON output. It is part of the existing Octopool setup workflow.

```bash
gitcrawl threads owner/repo --numbers 123 --include-closed --json
```

--------------------------------

### octopool gh api command for pull request access

Source: https://gitcrawl.sh/gh-shim

Use this command to access a pull request via the Octopool API. It is part of the first-time Octopool setup workflow, and is shown with a specific repository and pull request number.

```bash
octopool gh api repos/openclaw/openclaw/pulls/85341
```

--------------------------------

### gh pr checks command for PR check status

Source: https://gitcrawl.sh/gh-shim

Use this bare PATH gh command to view PR check status with JSON output. It is part of the existing Octopool setup workflow, and uses native field names like bucket and link.

```bash
gh pr checks 123 -R owner/repo --json name,state,bucket,link
```

--------------------------------

### Build from Source

Source: https://gitcrawl.sh/installation

Clone the repository and build the binary using Go.

```bash
git clone https://github.com/openclaw/gitcrawl.git
cd gitcrawl
go build \
  -ldflags "-X github.com/openclaw/gitcrawl/internal/cli.version=$(git describe --tags --always --dirty)" \
  -o bin/gitcrawl ./cmd/gitcrawl

./bin/gitcrawl --version
```

--------------------------------

### Initialize and verify Gitcrawl environment

Source: https://gitcrawl.sh/maintainer-archive

Run the initialization and diagnostic commands to ensure the environment is set up correctly.

```bash
gitcrawl init
gitcrawl doctor --json
```

--------------------------------

### Initialize gitcrawl with a portable store

Source: https://gitcrawl.sh/portable-stores

Use the init command to point gitcrawl at a portable store repository and specify the database file path.

```bash
gitcrawl init \
  --portable-store https://github.com/openclaw/gitcrawl-store.git \
  --portable-db data/openclaw__openclaw.sync.dbCopy
```

--------------------------------

### Run sync and capture

Source: https://gitcrawl.sh/capture

Run a successful all-state sync with comments before capturing. The capture command reads the local database and does not call GitHub. Keep --state all and --include-comments for incremental syncs; add --since to bound the GitHub update window.

```bash
gitcrawl sync owner/repo --state all --include-comments
gitcrawl capture owner/repo --output capture.json
```

--------------------------------

### Launch gitcrawl tui with various options

Source: https://gitcrawl.sh/tui

Shows common ways to launch the `gitcrawl tui` command. The first command opens a specific repository. The `--no-color` flag disables terminal colors. Without arguments, it infers the most recently updated local repo. `--min-size 5` is the default and shows clusters with at least 5 active members. `--sort recent` changes the ordering, `--layout focus` uses a wider detail pane, and `--hide-closed` focuses only on open clusters.

```bash
gitcrawl tui owner/repo
gitcrawl --no-color tui owner/repo # disable terminal colors
gitcrawl tui                      # infers the most recently updated local repo
gitcrawl tui --min-size 5         # default; show clusters with ≥5 active members
gitcrawl tui --sort recent        # alternate sort
gitcrawl tui --layout focus       # wider detail pane with members below
gitcrawl tui --hide-closed        # focus only on currently open clusters
```

--------------------------------

### Initialize and check local health with gitcrawl init, status, and doctor

Source: https://gitcrawl.sh/maintainer-archive

Initializes or verifies the runtime before spending GitHub quota. `status --json` reports the configured archive database and its repository/thread/open-thread/cluster inventory under `databases[].counts`, plus `last_sync_at` and `last_export_at`. `doctor --json` reports config path, database health, credential discovery, model settings, portable-store status, and the same core counts.

```bash
gitcrawl init
gitcrawl status --json
gitcrawl doctor --json
```

--------------------------------

### Find, hydrate, and summarize candidates

Source: https://gitcrawl.sh/automation

Search for issues locally, sync specific numbers with comments and PR details, then retrieve cluster details.

```bash
NUMS=$(gitcrawl search issues "checksum mismatch" -R owner/repo \
        --json number --limit 30 \
        | jq -r '[.[].number] | join(",")')

gitcrawl sync owner/repo --numbers "$NUMS" --include-comments --with pr-details

gitcrawl cluster-detail owner/repo --id "$(gitcrawl clusters owner/repo --json \
        | jq '.clusters[0].id')"
```

--------------------------------

### Looping over repositories in shell

Source: https://gitcrawl.sh/automation

Iterate through a list of repositories and process each with gitcrawl and jq.

```bash
for repo in openclaw/gitcrawl steipete/repo-a octocat/repo-b; do
  gitcrawl refresh "$repo" --json | jq '{repo: "'"$repo"'", sync: .sync, embed: .embed}'
done
```

--------------------------------

### Sync with time-windowed constraints and state filter

Source: https://gitcrawl.sh/sync

Combine --since and --state flags to tightly scope the synchronization process.

```bash
gitcrawl sync owner/repo --state all --since 2026-04-01T00:00:00Z
```

--------------------------------

### Set credentials in config.toml

Source: https://gitcrawl.sh/quickstart

Alternatively, store your API keys directly in the configuration file.

```toml
[env]
GITHUB_TOKEN = "<github-token>"
OPENAI_API_KEY = "<openai-api-key>"
```

--------------------------------

### gitcrawl init default config.toml

Source: https://gitcrawl.sh/configuration

Minimal configuration written by `gitcrawl init`. Edit by hand or with `gitcrawl configure`. Includes model settings, environment variables, portable store, and remote archive configuration.

```toml
summary_model = "gpt-5.4"
embed_model = "text-embedding-3-small"
embed_dimensions = 1024
embedding_basis = "title_original"
vector_backend = "exact"

[env]
GITHUB_TOKEN = "<github-token>"
OPENAI_API_KEY = "<openai-api-key>"

[portable_store]
url = "https://github.com/org/portable-store.git"
db_path = "data/openclaw__openclaw.sync.db"
checkout_dir = "/Users/me/Library/Application Support/gitcrawl/stores/portable-store"

[remote]
mode = "cloud"
endpoint = "https://crawl.example.com"
archive = "gitcrawl/org__repo"
token_env = "CRAWL_REMOTE_TOKEN"
```

--------------------------------

### Set credentials via environment variables

Source: https://gitcrawl.sh/quickstart

Export the required GitHub and OpenAI API keys in your shell session.

```bash
export GITHUB_TOKEN="<github-token>"                 # required for sync
export OPENAI_API_KEY="<openai-api-key>"             # required for embeddings
```

--------------------------------

### Read candidates and perform live GitHub actions

Source: https://gitcrawl.sh/maintainer-archive

Read exact candidates with gitcrawl and use the bare PATH gh for live reads and writes.

```bash
gitcrawl threads --numbers
```

--------------------------------

### Sync a repository

Source: https://gitcrawl.sh/quickstart

Fetch issues and pull requests for a repository. Use the --numbers flag to sync specific items.

```bash
gitcrawl sync openclaw/gitcrawl
```

```bash
gitcrawl sync openclaw/gitcrawl --numbers 123,456 --include-comments
```

--------------------------------

### Embed and cluster repository data

Source: https://gitcrawl.sh/quickstart

Run the full sync, embed, and cluster pipeline end-to-end.

```bash
gitcrawl refresh openclaw/gitcrawl
```

--------------------------------

### Use managed GitHub credentials with --github-token-command

Source: https://gitcrawl.sh/configuration

Select a trusted executable for managed GitHub credentials. The executable must print exactly one nonempty token line to stdout and is invoked before each GitHub HTTP dispatch. This mode is Unix-only; Windows returns an unsupported-platform error.

```bash
gitcrawl --github-token-command /usr/local/bin/github-token sync owner/repo --state all
```

--------------------------------

### Publishing a portable store

Source: https://gitcrawl.sh/portable-stores

The standard workflow for refreshing upstream data, pruning the database for a smaller footprint, and pushing the changes to a Git repository.

```bash
# In the portable store checkout, refresh upstream data into the local runtime mirror.
gitcrawl refresh owner/repo

# Prune for a small, shareable footprint and publish the database plus manifest into the checkout.
gitcrawl portable prune --body-chars 256

# Commit and push using normal Git from the configured portable checkout.
cd ~/Library/Application\ Support/gitcrawl/stores/gitcrawl-store
# Linux default: cd ~/.config/gitcrawl/stores/gitcrawl-store
git add data/openclaw__openclaw.sync.db data/openclaw__openclaw.sync.db.manifest.json
git commit -m "data: refresh openclaw/gitcrawl"
git push
```

--------------------------------

### Combining search with sync: hydrate candidates in one round-trip

Source: https://gitcrawl.sh/search

A three-step discovery pattern: (1) find candidate numbers locally via gitcrawl search, (2) hydrate with sync including comments and PR details, (3) re-query with full context via gitcrawl tui or open in TUI.

```shell
# 1. Find candidates locally.
NUMS=$(gitcrawl search issues "download stalls" -R owner/repo \
        --json number --limit 20 \
        | jq -r '[.[].number] | join(",")')

# 2. Hydrate them with comments + PR detail in one round-trip.
gitcrawl sync owner/repo --numbers "$NUMS" --include-comments --with pr-details

# 3. Re-query with full conversational context (or open in TUI).
gitcrawl tui owner/repo
```

--------------------------------

### Search with --sync-if-stale 5m

Source: https://gitcrawl.sh/automation

Runs a search with a staleness bound: if the local mirror is older than 5 minutes, it syncs first. Best for ad-hoc agent tools that should minimize sync calls while bounding staleness.

```bash
gitcrawl search issues "manifest cache" \
  -R owner/repo \
  --sync-if-stale 5m \
  --json number,title,url
```

--------------------------------

### Dispatch release workflow via GitHub CLI

Source: https://gitcrawl.sh/releasing

Use the GitHub CLI to trigger the official release workflow for a specific version.

```bash
gh workflow run release-unified.yml --repo openclaw/gitcrawl -f version=X.Y.Z
```

--------------------------------

### Bounded capture with --since

Source: https://gitcrawl.sh/capture

Use --since to include threads whose GitHub updated_at is at or after an RFC 3339 instant. Run the corresponding all-state bounded sync first. Capture never treats an absent local row as proof that GitHub has no matching thread.

```bash
gitcrawl capture owner/repo \
  --since 2026-07-01T00:00:00Z \
  --output july.json
```

--------------------------------

### Search and Octopool: local mirror search with gh-compatible args

Source: https://gitcrawl.sh/search

Shows a concise gitcrawl search issues invocation with -R and --json. This path shares the gh search argument shape, and the old gitcrawl gh compat cache has moved to Octopool.

```shell
gitcrawl search issues "download stalls" -R owner/repo --json number,title,url
```

--------------------------------

### Configure gitcrawl settings

Source: https://gitcrawl.sh/configuration

Use the configure command to interactively update model settings, base URLs, and embedding basis without manual file editing.

```bash
gitcrawl configure --summary-model gpt-5.4
gitcrawl configure --embed-model text-embedding-3-small
gitcrawl configure --embed-base-url http://127.0.0.1:8080/v1
gitcrawl configure --embedding-basis title_original
gitcrawl configure --json
```

--------------------------------

### Browse clusters in TUI

Source: https://gitcrawl.sh/quickstart

Launch the terminal user interface to navigate clusters interactively.

```bash
gitcrawl tui openclaw/gitcrawl
# or just `gitcrawl tui` and the most recently synced repo is inferred
```

--------------------------------

### Verify candidate metadata with gitcrawl and gh

Source: https://gitcrawl.sh/maintainer-archive

Read the archive first using gitcrawl, then verify fresh metadata through the existing bare PATH gh.

```bash
gitcrawl threads owner/repo --numbers 123 --include-closed --json
```

```bash
gh pr view 123 -R owner/repo --json number,title,state,url,headRefOid
```

--------------------------------

### Portable refresh with safety flags

Source: https://gitcrawl.sh/automation

Schedules a portable refresh after one-time initialization. It retains configuration and refuses unsafe checkout state; nonzero exits indicate refusals requiring inspection. A partial result means interrupted advancement, and mirror_result preserved-local keeps local runtime writes intact.

```bash
gitcrawl --config /path/to/config.toml portable refresh \
  --expected-remote https://github.com/example/archive-store.git \
  --git /absolute/path/to/git --timeout 2m \
  --min-free-bytes 2147483648 --max-growth-bytes 2147483648 \
  --json > refresh.json 2> refresh.log
```

--------------------------------

### Search the local cache

Source: https://gitcrawl.sh/quickstart

Perform hybrid searches or use the gh-compatible search syntax.

```bash
gitcrawl search openclaw/gitcrawl --query "download stalls" --mode hybrid
```

```bash
gitcrawl search issues "manifest cache" \
  -R openclaw/gitcrawl \
  --state open \
  --json number,title,state,url,updatedAt,labels \
  --limit 30
```

--------------------------------

### Inspect a cluster with gitcrawl cluster-detail

Source: https://gitcrawl.sh/clustering

Use cluster-detail or its alias cluster-explain to view the contents of a specific cluster by ID.

```bash
gitcrawl cluster-detail owner/repo --id 123
gitcrawl cluster-explain owner/repo --id 123    # alias
```

--------------------------------

### Refresh a batch of issues from search

Source: https://gitcrawl.sh/sync

Search for issues matching a query and sync the resulting batch with PR details.

```bash
NUMS=$(gitcrawl search issues "manifest cache" -R owner/repo --json number --limit 20 \
        | jq -r '[.[].number] | join(",")')
gitcrawl sync owner/repo --numbers "$NUMS" --with pr-details
```

--------------------------------

### Check Gitcrawl status

Source: https://gitcrawl.sh/maintainer-archive

Confirm the database path is configured as expected.

```bash
gitcrawl status --json
```

--------------------------------

### Process JSON output with jq

Source: https://gitcrawl.sh/sync

Pipes the sync output to jq for a compact summary of synchronization metrics.

```bash
gitcrawl sync owner/repo --json \
  | jq '{repository, threads_synced, issues_synced, pull_requests_synced, comments_synced, metadata_only, started_at, finished_at}'
```

--------------------------------

### Search with bounded staleness

Source: https://gitcrawl.sh/maintainer-archive

Use the --sync-if-stale flag to perform a metadata sync only if the local mirror is older than the specified duration. Search results are retrieved from SQLite, ensuring local performance once the freshness window is met.

```bash
gitcrawl search issues "archive coverage" \
  -R openclaw/gitcrawl \
  --state open \
  --sync-if-stale 5m \
  --json number,title,url,updatedAt,labels
```

--------------------------------

### Specify capture schema

Source: https://gitcrawl.sh/capture

The default and only supported schema is gitcrawl.capture.v1. Use --schema to explicitly select it.

```bash
gitcrawl capture owner/repo \
  --schema gitcrawl.capture.v1 \
  --output capture.json
```

--------------------------------

### Migrate GitHub CLI Shim

Source: https://gitcrawl.sh/installation

Use Octopool for GitHub CLI operations after the migration from gitcrawl gh.

```bash
octopool login
octopool gh api repos/openclaw/openclaw/pulls/123
```

--------------------------------

### Direct mode: search repository with query, mode, scope, and JSON output

Source: https://gitcrawl.sh/search

Shows direct gitcrawl search invocations using --query, --mode, --scope, --limit, and --json flags. Hybrid mode blends keyword and semantic search; code search is keyword-only and requires prior gitcrawl code index. JSON output is available.

```shell
gitcrawl search owner/repo --query "download stalls"
gitcrawl search owner/repo --query "manifest cache" --mode hybrid --limit 30 --json
gitcrawl search owner/repo --query "RefreshManifest" --scope code --json
gitcrawl search owner/repo --query "manifest cache" --scope all --json
```

--------------------------------

### Prune portable stores with gitcrawl portable prune

Source: https://gitcrawl.sh/portable-stores

Various command-line invocations for pruning portable-store databases, including options for body character limits, vacuuming, sync failure handling, and JSON output.

```bash
gitcrawl portable prune
gitcrawl portable prune --body-chars 256       # default
gitcrawl portable prune --body-chars 512 --no-vacuum
gitcrawl portable prune --include-sync-failures # opt-in, error text redacted
gitcrawl portable prune --no-publish            # prune only the runtime mirror
gitcrawl portable prune --json
```

--------------------------------

### Linux File-System Layout

Source: https://gitcrawl.sh/reference

The directory structure for Gitcrawl on Linux systems, including configuration, SQLite mirror, and cache locations.

```text
~/.config/gitcrawl/
├── config.toml
└── stores/
    └── gitcrawl-store/          # portable-store checkout (optional)
        └── data/
            └── owner__repo.sync.db

~/.local/share/gitcrawl/
├── gitcrawl.db                  # SQLite mirror
├── gitcrawl.db-shm              # SQLite shared-memory file
├── gitcrawl.db-wal              # SQLite write-ahead log
└── vectors/                     # vector store backing embeddings

~/.cache/gitcrawl/               # local runtime cacheCopy
```

--------------------------------

### Check for Updates

Source: https://gitcrawl.sh/installation

Check for available updates in standard or JSON format.

```bash
gitcrawl check-update
gitcrawl check-update --json
```

--------------------------------

### Look up an issue via octopool

Source: https://gitcrawl.sh/automation

Use octopool to perform a GitHub API request without consuming personal quota.

```bash
octopool gh api repos/owner/repo/issues/123
```

--------------------------------

### Run gitcrawl cluster on a repository

Source: https://gitcrawl.sh/clustering

Generates clusters for the specified repository. Defaults match ghcrawl's tuning for comparable output. Singleton clusters use kind = singleton_orphan; multi-member clusters use kind = duplicate_candidate.

```bash
gitcrawl cluster owner/repo
```

--------------------------------

### Filter sync by state

Source: https://gitcrawl.sh/sync

Use the --state flag to control which issues or pull requests are synchronized. Use --state all for historical backfills and the default --state open for ongoing updates.

```bash
gitcrawl sync owner/repo --state open    # default
gitcrawl sync owner/repo --state closed  # only closed
gitcrawl sync owner/repo --state all     # full backfill
```

--------------------------------

### Sync repository metadata

Source: https://gitcrawl.sh/maintainer-archive

Sync the target repository metadata for open issues or pull requests.

```bash
gitcrawl sync owner/repo --state open --json
```

--------------------------------

### Sync GitHub repository data

Source: https://gitcrawl.sh/sync

The default command to fetch open issues and pull requests for a specified repository.

```bash
gitcrawl sync owner/repo
```

--------------------------------

### Index a checkout with gitcrawl code index

Source: https://gitcrawl.sh/code-index

Mirror the GitHub repository first, then point gitcrawl at a checkout. The repository identity comes from owner/repo; --path supplies the local Git worktree. The command records the current HEAD, whether tracked files are dirty, file counts, indexed bytes, and skip counts.

```bash
gitcrawl sync owner/repo
gitcrawl code index owner/repo --path /path/to/checkout
```

--------------------------------

### Run gitcrawl embed command

Source: https://gitcrawl.sh/refresh-and-embed

Executes the embedding process for a specified owner and repository.

```bash
gitcrawl embed owner/repo
```

--------------------------------

### Run `gitcrawl refresh` for a repository

Source: https://gitcrawl.sh/refresh-and-embed

Executes the full refresh pipeline (sync → embed → cluster) for the given repo. Use `--no-sync`, `--no-embed`, `--no-cluster` to disable any stage.

```bash
gitcrawl refresh owner/repo
```

--------------------------------

### Manage thread and cluster status via CLI

Source: https://gitcrawl.sh/governance

Commands to close or reopen threads and clusters locally. The reason parameter is stored for audit purposes, defaulting to 'CLI manual close'.

```bash
gitcrawl close-thread owner/repo --number 123 --reason "duplicate handled"
gitcrawl close-thread owner/repo --number https://github.com/owner/repo/issues/123 --reason "duplicate handled"
gitcrawl reopen-thread owner/repo --number 123

gitcrawl close-cluster owner/repo --id 42 --reason "all members handled"
gitcrawl reopen-cluster owner/repo --id 42
```

--------------------------------

### Execute gitcrawl portable export

Source: https://gitcrawl.sh/portable-stores

Runs the export command with specified profile, output directory, and compression settings. This command creates a validated artifact generation based on the provided configuration.

```bash
gitcrawl --config /path/to/config.toml portable export \
  --profile current-state-v1 \
  --body-chars 32 \
  --output-dir /path/to/artifact.next \
  --database-name openclaw__openclaw.sync.db \
  --public-path data/openclaw__openclaw.sync.db \
  --repository openclaw/openclaw \
  --compression gzip \
  --max-archive-bytes 99999999 \
  --json
```

--------------------------------

### Sync with time-windowed constraints

Source: https://gitcrawl.sh/sync

Limit synchronization to threads updated after a specific RFC 3339 timestamp using the --since flag.

```bash
gitcrawl sync owner/repo --since 2026-04-01T00:00:00Z
```

--------------------------------

### Sync repository metadata and hydrate targeted issues/PRs with gitcrawl sync

Source: https://gitcrawl.sh/maintainer-archive

Brings one repository local. The first command mirrors open issues and pull requests into SQLite. The targeted `sync --numbers` command refreshes exact issues or pull requests after local discovery, hydrating only the rows you intend to inspect. Use `--include-comments` when issue discussion matters and `--with pr-details` for pull requests that need files, commits, checks, workflow runs, and review-thread state.

```bash
gitcrawl sync openclaw/gitcrawl --state open --json
gitcrawl sync openclaw/gitcrawl --numbers 94,95,96 --include-comments --with pr-details --json
```

--------------------------------

### Triage a cluster end to end

Source: https://gitcrawl.sh/automation

Retrieve cluster details, set a canonical issue, close the cluster, and comment on the upstream issue.

```bash
ID=42

# Read.
gitcrawl cluster-detail owner/repo --id "$ID" --body-chars 600 --json

# Decide canonical, then close locally.
gitcrawl set-cluster-canonical owner/repo --id "$ID" --number 123
gitcrawl close-cluster owner/repo --id "$ID" --reason "consolidated under #123"

# Comment upstream via real gh.
gh issue comment 456 -R owner/repo --body "Duplicate of #123"
```

--------------------------------

### Limit sync rows with --limit

Source: https://gitcrawl.sh/sync

Limits the number of rows fetched during a sync invocation. The process handles GitHub rate limits and pagination automatically.

```bash
gitcrawl sync owner/repo --limit 200
```

--------------------------------

### Find duplicates for a bug report

Source: https://gitcrawl.sh/automation

Sync a specific issue, generate embeddings, and find the 10 nearest neighbors.

```bash
NUM=789
gitcrawl sync owner/repo --numbers "$NUM" --include-comments
gitcrawl embed owner/repo --number "$NUM"
gitcrawl neighbors owner/repo --number "$NUM" --limit 10 --json
```

--------------------------------

### Configure custom embedding endpoint with embed_base_url

Source: https://gitcrawl.sh/configuration

Configure a custom embedding endpoint. The first block sets embed_base_url in the config file; the second uses the CLI flag. Pass an empty value to --embed-base-url to restore the shared endpoint.

```ini
[openai]
embed_base_url = "http://127.0.0.1:8080/v1"
```

```bash
gitcrawl configure --embed-base-url http://127.0.0.1:8080/v1
```

--------------------------------

### View clusters non-interactively

Source: https://gitcrawl.sh/quickstart

Query cluster information, details, and neighbors using command-line flags.

```bash
gitcrawl clusters openclaw/gitcrawl --sort size --min-size 5
gitcrawl cluster-detail openclaw/gitcrawl --id 12
gitcrawl neighbors openclaw/gitcrawl --number 123 --limit 10
```

--------------------------------

### Pipe gitcrawl --json output to jq

Source: https://gitcrawl.sh/automation

Shows how to pipe gitcrawl's JSON output into jq for structured extraction. The first command syncs a repository and selects sync metadata; the second lists clusters sorted by size with a minimum size filter and extracts cluster fields.

```bash
gitcrawl sync owner/repo --json | jq '{threads_synced, comments_synced, finished_at}'
gitcrawl clusters owner/repo --json --sort size --min-size 5 \
  | jq '.clusters[] | {id, members: .member_count, latest: .latest_thread_number}'
```

--------------------------------

### Execute strict subscriber refresh

Source: https://gitcrawl.sh/portable-stores

Use this command for scheduled updates to a portable store. It requires an expected remote URL and validates the state of the checkout before proceeding.

```bash
gitcrawl --config /path/to/config.toml portable refresh \
  --expected-remote https://github.com/example/archive-store.git \
  --git /absolute/path/to/git \
  --timeout 2m \
  --min-free-bytes 2147483648 \
  --max-growth-bytes 2147483648 \
  --json
```

--------------------------------

### Sync specific issues or pull requests

Source: https://gitcrawl.sh/sync

Use the --numbers flag to refresh specific threads by ID or URL, bypassing standard list ordering and time windows. Include flags like --include-comments or --with pr-details to fetch additional data.

```bash
gitcrawl sync owner/repo --numbers 123,456 --include-comments
gitcrawl sync owner/repo --numbers https://github.com/owner/repo/issues/123 --with pr-details
```

--------------------------------

### Inspect gitcrawl runs by kind

Source: https://gitcrawl.sh/refresh-and-embed

Use the runs command to view the history of sync, embedding, or cluster operations for a specific repository.

```bash
gitcrawl runs owner/repo --kind sync       # default kind
gitcrawl runs owner/repo --kind embedding
gitcrawl runs owner/repo --kind clusterCopy
```

--------------------------------

### gh search compatibility: search issues and PRs with common flags

Source: https://gitcrawl.sh/search

Demonstrates gitcrawl search issues and prs using the gh search shape, including -R, --state, --json, and --limit flags. Output matches gh search issues|prs --json for direct piping into existing jq filters.

```shell
gitcrawl search issues "download stalls" \
  -R owner/repo \
  --state open \
  --json number,title,state,url,updatedAt,labels \
  --limit 30

gitcrawl search prs "manifest cache" \
  -R owner/repo \
  --state open \
  --json number,title,state,url,updatedAt,isDraft,author \
  --limit 20
```

--------------------------------

### Sync specific issue with comments and PR details

Source: https://gitcrawl.sh/sync

Retrieve a specific issue by number including its comments and associated pull request details.

```bash
gitcrawl sync owner/repo --numbers 123 --include-comments --with pr-details
```

--------------------------------

### Check sync run status

Source: https://gitcrawl.sh/maintainer-archive

Verify the freshness or last-run status of synchronization tasks.

```bash
gitcrawl runs owner/repo --kind sync --json
```

--------------------------------

### Search with --sync-if-stale to bound staleness

Source: https://gitcrawl.sh/search

Shows gitcrawl search issues with --sync-if-stale 5m. If the latest sync is over 5 minutes old, a metadata sync runs first. This keeps latency predictable for cache hits while bounding staleness.

```shell
gitcrawl search issues "hot loop" \
  -R owner/repo \
  --state open \
  --sync-if-stale 5m \
  --json number,title,url
```

--------------------------------

### Triage cluster workflow

Source: https://gitcrawl.sh/governance

A workflow for reviewing cluster details, setting a canonical thread, and closing the cluster.

```bash
gitcrawl cluster-detail owner/repo --id 42 --body-chars 600 | less
# ...read, decide canonical, add labels via gh, comment via gh...
gitcrawl set-cluster-canonical owner/repo --id 42 --number 123
gitcrawl close-cluster owner/repo --id 42 --reason "consolidated under #123"
```

--------------------------------

### macOS File-System Layout

Source: https://gitcrawl.sh/reference

The directory structure for Gitcrawl on macOS systems, including Application Support and Caches directories.

```text
~/Library/Application Support/gitcrawl/
├── config.toml
├── gitcrawl.db                  # SQLite mirror
├── gitcrawl.db-shm              # SQLite shared-memory file
├── gitcrawl.db-wal              # SQLite write-ahead log
├── vectors/                     # vector store backing embeddings
├── logs/
└── stores/
    └── gitcrawl-store/          # portable-store checkout (optional)
        └── data/
            └── owner__repo.sync.db

~/Library/Caches/gitcrawl/       # local runtime cacheCopy
```

--------------------------------

### Tune sparse clusters

Source: https://gitcrawl.sh/clustering

Lower the threshold and increase k to merge duplicates that are currently landing in separate clusters.

```bash
gitcrawl cluster owner/repo --threshold 0.75 --k 24
```

--------------------------------

### Run `gitcrawl refresh` with JSON output

Source: https://gitcrawl.sh/refresh-and-embed

Runs refresh and outputs the result as JSON, including per-stage `run_id` values. Each stage object mirrors the standalone command's JSON shape and can be queried later via `gitcrawl runs --kind sync|embedding|cluster`.

```bash
gitcrawl refresh owner/repo --json
```

```json
{
  "repository": "owner/repo",
  "sync": { "selected": 124, "inserted": 12, "updated": 9, "run_id": 42 },
  "embed": { "selected": 21, "embedded": 21, "skipped": 0, "failed": 0, "model": "text-embedding-3-small", "run_id": 43 },
  "cluster": {
    "threshold": 0.8, "cross_kind": 0.93, "min_size": 1, "max_size": 40, "k": 16,
    "vector_count": 312, "edge_count": 1042, "cluster_count": 87, "member_count": 312, "run_id": 44,
    "vector_coverage": {
      "supported": true, "eligible": 312, "covered": 312, "fresh": 312,
      "missing": 0, "stale": 0, "complete": true
    }
  }
}
```

--------------------------------

### Search source code with gitcrawl search

Source: https://gitcrawl.sh/code-index

Search the code index using local SQLite FTS. --scope all interleaves thread results and code results within the requested limit.

```bash
gitcrawl search owner/repo --query "RefreshManifest" --scope code
gitcrawl search owner/repo --query "manifest cache" --scope all
```

--------------------------------

### Query raw override history via SQLite

Source: https://gitcrawl.sh/governance

Inspect the raw override history by querying the SQLite database directly using the path provided by the gitcrawl doctor command.

```bash
sqlite3 "$(gitcrawl doctor --json | jq -r .db_path)" \
  "SELECT cluster_id, thread_number, kind, reason, created_at
   FROM cluster_member_overrides ORDER BY created_at DESC LIMIT 20;"
```

--------------------------------

### Run gitcrawl health checks

Source: https://gitcrawl.sh/configuration

The doctor command provides a comprehensive health check of the configuration, database, and environment. Use the --json flag for scriptable output and --locks for SQLite lock diagnostics.

```bash
gitcrawl doctor          # human-readable
gitcrawl doctor --json   # for scripts
gitcrawl doctor --locks --json
```

--------------------------------

### Hydrate candidate rows conditionally

Source: https://gitcrawl.sh/maintainer-archive

Perform a metadata-only search first, then hydrate specific rows like comments and PR details only when necessary. This approach preserves API quotas and maintains responsive local triage.

```bash
NUMS=$(gitcrawl search prs "needs proof" -R openclaw/gitcrawl \
  --state open \
  --sync-if-stale 5m \
  --json number \
  | jq -r '[.[].number] | join(",")')

if [ -n "$NUMS" ]; then
  gitcrawl sync openclaw/gitcrawl --numbers "$NUMS" --include-comments --with pr-details --json
fi
```

--------------------------------

### Tune greedy clusters

Source: https://gitcrawl.sh/clustering

Increase thresholds to prevent unrelated items from being merged into the same cluster.

```bash
gitcrawl cluster owner/repo --threshold 0.85 --cross-kind-threshold 0.95
```

--------------------------------

### Machine-readable progress file schema

Source: https://gitcrawl.sh/sync

The structure of the JSON file generated when using the --progress-file flag. Gitcrawl atomically updates this file during synchronization.

```json
{
  "schema": "gitcrawl.sync-progress.v1",
  "repository": "owner/repo",
  "state": "running",
  "stage": "syncing_threads",
  "issues_received": 56,
  "pull_requests_received": 238,
  "comments_received": 350,
  "observed_at": "2026-07-31T04:17:36.000000000Z"
}
```

--------------------------------

### Migrate from gitcrawl gh to octopool

Source: https://gitcrawl.sh/commands

The gitcrawl gh command is deprecated. Use octopool for authentication and GitHub API interactions.

```bash
octopool login
octopool gh api repos/openclaw/openclaw/pulls/123Copy
```

--------------------------------

### Cron schedule for gitcrawl refresh

Source: https://gitcrawl.sh/automation

Cron entry that runs gitcrawl refresh every 5 minutes for a single repository, writing JSON output to a log file. For multiple repos, loop in a small shell script; gitcrawl runs sequentially against a shared SQLite file.

```cron
# Every 5 minutes, refresh the active repos.
*/5 * * * * $HOME/bin/gitcrawl refresh openclaw/gitcrawl --json > /tmp/gitcrawl.openclaw.json 2>&1
```

--------------------------------

### Find similar threads with gitcrawl neighbors

Source: https://gitcrawl.sh/clustering

Find issues or PRs similar to a specific source number based on cosine similarity.

```bash
gitcrawl neighbors owner/repo --number 123 --limit 10
```

--------------------------------

### gitcrawl durable-clusters usage

Source: https://gitcrawl.sh/clustering

Shows the `gitcrawl durable-clusters` command with `--include-closed` to view a strict durable-only audit view without merging with the latest run. This is used when a pure historical view is needed.

```bash
gitcrawl durable-clusters owner/repo --include-closed
```

--------------------------------

### Exclude cluster member workflow

Source: https://gitcrawl.sh/governance

Exclude a thread from a cluster and manually search for a better home for it.

```bash
gitcrawl exclude-cluster-member owner/repo --id 42 --number 456 --reason "different repro"
gitcrawl neighbors owner/repo --number 456 --limit 10   # find a better home manually
```

--------------------------------

### Inspect recent pipeline runs

Source: https://gitcrawl.sh/maintainer-archive

Use gitcrawl runs to view recent pipeline records by kind. This is useful for verifying archive freshness or troubleshooting downstream outputs.

```bash
gitcrawl runs openclaw/gitcrawl --kind sync --limit 5 --json
gitcrawl runs openclaw/gitcrawl --kind embedding --limit 5 --json
gitcrawl runs openclaw/gitcrawl --kind cluster --limit 5 --json
```

--------------------------------

### Limit cluster size

Source: https://gitcrawl.sh/clustering

Restrict the maximum number of members in a cluster to improve coherence.

```bash
gitcrawl cluster owner/repo --max-cluster-size 20
```

--------------------------------

### Exclude or include cluster members

Source: https://gitcrawl.sh/governance

Use these commands to manually override cluster membership. The override persists across re-clustering using the cluster's stable ID.

```bash
gitcrawl exclude-cluster-member owner/repo --id 42 --number 456 --reason "different repro"
gitcrawl exclude-cluster-member owner/repo --id 42 --number owner/repo#456 --reason "different repro"
gitcrawl include-cluster-member owner/repo --id 42 --number 456
```

--------------------------------

### Exclude a cluster member

Source: https://gitcrawl.sh/clustering

Manually remove a specific member from a cluster by providing a reason.

```bash
gitcrawl exclude-cluster-member owner/repo --id 12 --number 456 --reason "different repro"
```

--------------------------------

### Close thread locally

Source: https://gitcrawl.sh/governance

Hide a thread from the local triage view while keeping it open on GitHub.

```bash
gitcrawl close-thread owner/repo --number 789 --reason "answered in chat"
```

--------------------------------

### Set canonical cluster member

Source: https://gitcrawl.sh/governance

Pins a specific thread to represent the cluster in the TUI. The provided number must already be a member of the cluster.

```bash
gitcrawl set-cluster-canonical owner/repo --id 42 --number 123 --reason "main tracking issue"
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.