rootle 0.7.0

rootle — browse remote source-control systems from your terminal

status: alpha — features, keys, and config may still shift between releases; pin a version if it matters to you.

A modal TUI (ratatui) with a yazi-style miller-column browser, syntax-highlighted previews, Zed-style global search, and a pluggable provider seam — GitHub ships in-tree, anything else wraps in via a small stdio script.

Contents

• What it does
• Quick start
• Documentation
• Providers
• Development

What it does

• Browse orgs → repos → trees → files in three miller columns with a live syntax-highlighted preview — no clone required.
• Find (␣ f) and grep (␣ g) full-screen, Zed-style: result blocks with match chips, folded regions, and per-file counts.
• Open any file read-only in your editor (Enter); yank the browser URL of anything (␣ y).
• Clone repos through a wizard (v marks, :clone) — orgs fan out, destinations get <dest>/<org>/<repo>.
• Configure in-app with :settings (writes config.toml, hot reloads themes); every keybinding is in the ? popup.

Quick start

curl -fsSL https://rootle.dev/install.sh | sh   # linux x86_64, to ~/.local/bin
brew install rootledev/tap/rootle   # linux (builds from source)
brew install --cask rootledev/tap/rootle   # macOS (prebuilt binary)
cargo install rootle                # or from crates.io (Rust 1.88+)

rootle                # repo search on first run; browser after that
rootle owner/repo     # jump straight into a repo

Auth is zero-friction: if gh auth login or ROOTLE_TOKEN is already set up, rootle just uses it; anonymous works everywhere except code search (it says so in the status line when it matters).

Documentation

Providers

rootle talks to backends through a small protocol, not to GitHub directly. [provider] kind = "github" is the default in-tree implementation; kind = "stdio" spawns your adapter as a child process — four methods make a minimal useful provider, and the canonical forge-conformance suite gates correctness (rootle's own CI runs it against the fs reference provider). More providers are planned and the protocol will evolve with them.

The built-in manager installs stdio providers as verified binaries:

rootle provider install gitlab                 # bare name → rootledev/rootle-gitlab
rootle provider install owner/repo@v0.1.0      # GitHub releases, tag-pinned
rootle provider install https://artifacts.corp.example/p/rootle-gitlab-0.1.0-x86_64-unknown-linux-musl.tar.gz
rootle provider install myprovider --path /opt/providers/rootle-myprovider

Every networked install is checksum-verified against the mandatory .sha256 sidecar, whatever the host. Sources split into two deployment shapes: releases-API sources (github.com slugs/URLs) are tracked — rootle provider update refreshes their latest-known tags and upgrade swaps binaries. Plain-HTTP and --path installs are install-and-pin — update/upgrade never touch them; upgrades come from whatever deployed them (a config manager, an artifact-publishing pipeline). --path is a first-class deployment shape, not a testing convenience: it is the steady state for config-managed installs.

Development

cargo test                          # unit + TestBackend render tests
cd e2e && uv run pytest             # PTY end-to-end suite
docker compose run --build --rm test  # fmt + clippy -D warnings + cargo test
docker compose run --build --rm e2e # same e2e suite in a container

CI runs the gate + e2e on every push; the demo workflow re-renders the demo GIFs above (one per palette) whenever the app or its tooling changes and opens a PR with the refreshed artifacts — this README always shows the current look and feel.