burrow

burrow is a Bunny.net CLI written in Go.

Install

macOS (Homebrew)

brew install sandwich/tap/burrow

Arch Linux (AUR)

yay -S burrow-bin
# or with paru:
paru -S burrow-bin

Windows (Scoop)

scoop bucket add sandwich https://github.com/sandwich/scoop-bucket
scoop install burrow

Pre-built binary (GitHub Releases)

Download the archive for your OS/arch from Releases, extract, and place burrow on your $PATH. Each release ships:

• SHA-256 checksums (checksums.txt)
• cosign signatures (*.sig + *.crt) — verify with cosign verify-blob
• SPDX SBOMs (*.sbom.json) per archive

Verify a download:

cosign verify-blob \
  --certificate burrow_<version>_<os>_<arch>.<ext>.crt \
  --signature  burrow_<version>_<os>_<arch>.<ext>.sig \
  --certificate-identity-regexp 'https://github\.com/sandwich/burrow/' \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
  burrow_<version>_<os>_<arch>.<ext>

From source

Prerequisites

• Go 1.21 or newer
• git
• make (optional — only needed for the Makefile targets)
• Linux only, optional credential helpers: libsecret (secret-tool) or pass

Clone

git clone https://github.com/sandwich/burrow.git
cd burrow

Build

Plain go build:

go build ./cmd/burrow
./burrow --help

Or via the Makefile (writes a stamped binary to ./bin/):

make build
./bin/burrow --help

The Makefile injects version metadata via -ldflags. Override at build time:

make build VERSION=v0.1.0

Test

make test           # go test ./...
make coverage       # writes coverage.out and prints a function summary

Install

Install the burrow binary to your $GOBIN (or $GOPATH/bin, default ~/go/bin):

make install

If burrow --help returns "command not found", ~/go/bin isn't on your PATH. Either run it by full path:

~/go/bin/burrow --help

…or add the Go bin directory to your shell rc once:

# bash
echo 'export PATH="$(go env GOPATH)/bin:$PATH"' >> ~/.bashrc && exec bash
# zsh
echo 'export PATH="$(go env GOPATH)/bin:$PATH"' >> ~/.zshrc && exec zsh
# fish
fish_add_path (go env GOPATH)/bin

Optional analyzer binary

The contracts/scrape pipeline can use a companion analyzer at cmd/burrow-analyzer:

go build -o burrow-analyzer ./cmd/burrow-analyzer
export BURROW_LLM_ANALYZER=$PWD/burrow-analyzer

Setup

Authenticate once (stores your API key securely when possible):

burrow auth login
burrow auth status

Non-interactive options:

export BUNNY_API_KEY="..."
burrow auth login

printf "%s" "$BUNNY_API_KEY" | burrow auth login --stdin

Credential store selection:

• macOS: Keychain (security)
• Linux: secret-tool, then pass, else file fallback
• Windows: Registry (value encrypted via DPAPI using powershell)

Override with BURROW_CREDENTIAL_STORE=keychain|secret-tool|pass|registry|file.

Usage

Generic API caller (works for any Bunny.net endpoint when you know METHOD + PATH):

burrow api GET /pullzone
burrow api GET /pullzone/123 --pretty
burrow api POST /pullzone --json '{"Name":"example"}'

Base URL resolution:

• --base-url https://...
• BURROW_BASE_URL=https://...
• burrow config set --base-url https://...

Discover endpoints from the local contract:

burrow endpoints list
burrow endpoints resolve GET /pullzone/123
burrow endpoints call GET /pullzone/{id} --param id=123

endpoints call uses base_url from the contract when available (e.g. Stream API uses https://video.bunnycdn.com).

Setup diagnostics:

burrow doctor
burrow doctor --check-auth

Contracts + Scraping

Contracts are local JSON describing endpoints (see contracts/contract.json for the format).

Initialize and validate:

burrow contracts init
burrow contracts validate

Sync from Bunny.net API reference docs (recommended):

burrow contracts sync
burrow contracts validate

Import from an OpenAPI JSON document (if Bunny publishes one):

burrow contracts import-openapi --file ./openapi.json
# or:
burrow contracts import-openapi --url https://example.com/openapi.json

Queue a docs scrape and run it:

burrow scrape enqueue --url "https://docs.example.com/api-reference"
burrow scrape run

Bulk-enqueue from a sitemap:

burrow scrape sitemap --url "https://docs.example.com/sitemap.xml"
burrow scrape run

Optional LLM-assisted analyzer:

• Set BURROW_LLM_ANALYZER to an executable that reads analyzer input JSON on stdin and prints an updated contract JSON on stdout.
• Reference implementation (heuristic, no LLM): go build ./cmd/burrow-analyzer then export BURROW_LLM_ANALYZER=./burrow-analyzer.

Analyzer protocol:

• stdin: JSON { "url": "...", "html": "<raw>", "contract": { ... } }
• stdout: updated contract JSON (and nothing else)