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 - one command, signed binary.
• Source build: compile directly from the repository checkout with cargo.

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 tap thedoublejay/tap
brew install thedoublejay/tap/gather-step

This installs a signed, prebuilt binary for both Apple Silicon (aarch64-apple-darwin) and Intel Mac (x86_64-apple-darwin). No Rust toolchain is required on the host machine.

Verify the install

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

Upgrade

brew update
brew upgrade gather-step

Uninstall

brew uninstall gather-step
brew untap thedoublejay/tap

Tap availability

The Homebrew tap is published as part of the Gather Step release workflow on GitHub. If brew install reports the formula as not found, the release may not yet be tagged. Check the Releases page - once a tagged release is listed, the tap is live. Until then, use the source build below.

Platform scope

The tap targets macOS only.

Build From Source

Source builds are the right path when you want to run 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 repository — 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 repository, 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 serve flag reference respectively.

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 two Apple Darwin targets:

• aarch64-apple-darwin (Apple Silicon)
• x86_64-apple-darwin (Intel Mac)

These are the binaries the Homebrew tap serves. If you are working outside that path, use the source build flow above.

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.