135 lines
3.6 KiB
Markdown
135 lines
3.6 KiB
Markdown
---
|
|
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
|