Install Gather Step (Rust CLI)

Gather Step ships as a Rust CLI binary. Pick the install path that matches how you want to work:

• macOS (recommended): install via Homebrew.
• Source build: compile directly from a repo checkout with cargo on macOS or Linux.

Both paths produce the same gather-step binary. Once it is on your PATH, every example in the rest of the documentation works identically.

Install via Homebrew (macOS)

macOS users can install Gather Step directly from the official Homebrew tap:

brew install thedoublejay/tap/gather-step

The release workflow publishes prebuilt macOS artifacts through Homebrew. No Rust toolchain is required on the host machine. Releases open an automatic tap update PR; updates appear after that PR is merged and the GitHub release is no longer draft.

Verify the install

gather-step --version
gather-step --help

Upgrade

brew update
brew upgrade thedoublejay/tap/gather-step

Plain brew upgrade upgrades Gather Step only after Homebrew has refreshed the local tap metadata. If it still reports an older installed version, run the two commands above, or rerun brew install thedoublejay/tap/gather-step to force Homebrew through the tapped formula.

Uninstall

brew uninstall gather-step
brew untap thedoublejay/tap

Tap availability

The Homebrew tap is published at thedoublejay/homebrew-tap. If a release is not visible yet, check the Releases page and the tap PR queue, then use the source build below until the tag is published.

Platform scope

The tap serves prebuilt macOS artifacts. Linux is supported through source builds and the release pipeline publishes a Linux x86_64 archive for direct download.

Build from Source

Source builds are the right path when you want to run Linux, unreleased code from the main branch, or work directly from a local checkout.

Prerequisites

• Rust 1.94.1 — the exact version pinned in gather-step/rust-toolchain.toml. rustup will install and switch to it automatically when you run any Cargo command inside the workspace directory. If you do not have rustup, install it from rustup.rs before continuing.
• A checked-out copy of the repo — you need the full source tree.
• A workspace root where Gather Step can create .gather-step/ for generated state. This can be any directory; it does not have to be inside the source repo.

Build

Navigate to the gather-step/ directory inside the repo, then run:

# debug build — fast to compile, slower to run
cargo build -p gather-step

# release build — optimized binary, suitable for day-to-day use
cargo build -p gather-step --release

The compiled binaries land at:

• debug: target/debug/gather-step
• release: target/release/gather-step

For any workflow that involves a large workspace or a long watch session, use the release build. Indexing a multi-repo workspace is noticeably faster with optimizations enabled.

Put the binary on your PATH

So that every later example can use the bare gather-step command:

export PATH="$PWD/target/release:$PATH"

Add this line to your shell profile (~/.zshrc, ~/.bashrc, or equivalent) to make it permanent, or copy the binary to a directory already on your PATH:

cp target/release/gather-step /usr/local/bin/

Verify the Build

Regardless of how you installed it, confirm the binary works:

gather-step --help
gather-step serve --help

You should see the top-level command list and the help output for serve.

Run the Full Validation Suite (contributors)

If you are working on Gather Step itself, the just ready recipe runs every quality gate that CI runs:

just ready

In order, it executes:

1. typos — spell-checks source and docs
2. cargo fmt --all --check — verifies formatting
3. cargo clippy --all-targets --all-features -- -D warnings — linting
4. cargo nextest run --all-features — full test suite via nextest
5. cargo deny check — dependency audit (licenses, advisories, duplicates)
6. cargo shear — checks for unused dependencies

All steps must pass cleanly before the build is considered ready. If just is not installed, each step can be run individually with the Cargo commands above.

Release Artifacts

The release pipeline publishes pre-built binaries for the supported direct download targets:

• aarch64-apple-darwin (Apple Silicon)
• x86_64-apple-darwin (Intel Mac)
• x86_64-unknown-linux-gnu (Linux x86_64)

The Homebrew tap serves the macOS binaries. Homebrew/core formulae build from source first and get bottles from Homebrew CI after acceptance.

Uninstall / Clean State

Gather Step stores all generated state inside the workspace directory, under .gather-step/. Source repositories are never modified.

To remove generated index state without deleting the binary:

gather-step --workspace /path/to/workspace clean --yes

This deletes the registry, graph, search index, and metadata database under .gather-step/. It does not remove the binary itself. To rebuild the index from scratch after cleaning, run gather-step index again.

To remove the binary:

• Homebrew users: brew uninstall gather-step && brew untap thedoublejay/tap
• Source-build users: delete the compiled output from target/ or remove the directory from your PATH.

Next Steps

• Getting started — build once and run the five-minute quickstart.
• Workspace setup — configure your repos and indexing scope.