---
title: Quickstart
nav_order: 3
permalink: /quickstart/
---

# Quickstart
{: .no_toc }

Five minutes from clean machine to a populated cluster view.
{: .fs-6 .fw-300 }

1. TOC
{:toc}

## 1. Install and initialize

```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 ~/.config/gitcrawl.
gitcrawl init
```

Defaults written:

- `~/.config/gitcrawl/config.toml`
- `~/.config/gitcrawl/gitcrawl.db`
- `~/.config/gitcrawl/cache/`
- `~/.config/gitcrawl/vectors/`
- `~/.config/gitcrawl/logs/`

## 2. Set credentials

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

Either set them in your shell profile or store them in `~/.config/gitcrawl/config.toml`:

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

`gitcrawl doctor` confirms the credentials are visible and reports their source.

## 3. Sync a repository

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

By default this fetches **open** issues and pull requests, plus a sweep of recently closed rows so the local store does not rot. Add `--include-comments` for review threads, `--include-pr-details` (or `--with pr-details`) for PR files, commits, checks, and workflow runs.

Need exact rows? Use `--numbers`:

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

## 4. Embed and cluster

The `refresh` command runs sync → embed → cluster end to end:

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

You can run the stages individually if you want finer control — see [Refresh and embed](/refresh-and-embed/) and [Clustering](/clustering/).

## 5. Browse clusters

Open the TUI:

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

- `↑`/`↓` navigate clusters, `Enter` opens member detail
- `a` opens the action menu, `#` jumps to a number, `n` loads neighbors, `p` switches repo
- Right-click and mouse wheel work in most terminals

For a non-interactive view:

```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
```

## 6. Search the local cache

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

The same command also accepts the `gh search` shape, which makes it a drop-in for scripts that already speak `gh`:

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

Add `--sync-if-stale 5m` to refresh the local mirror first when it is older than the duration you tolerate.

## 7. Wire up the `gh` shim (optional)

```bash
mkdir -p "$HOME/bin"
ln -sf "$(command -v gitcrawl)" "$HOME/bin/gitcrawl-gh"
gitcrawl-gh search issues "download stalls" -R openclaw/gitcrawl --json number,title,url
gitcrawl-gh pr view 123 -R openclaw/gitcrawl --json number,title,state,url
gitcrawl-gh xcache stats
```

Most read-only `gh` calls answer locally, mutating commands pass straight through to the real `gh`. See [gh shim](/gh-shim/) for the full surface.

## Where to next

- [Concepts](/concepts/) — what threads, durable clusters, and embeddings actually mean
- [Sync](/sync/) — every flag for hydrating the local store
- [Clustering](/clustering/) — tuning the cluster graph for a specific repo
- [Automation](/automation/) — JSON contracts for agents and scripts