Installation

Install stepper via prebuilt binaries, build from source, and configure your first run with guided setup or environment overrides.

Get started with stepper using prebuilt binaries, build from source for development, or customize your installation directory and download location. The guided setup on first run helps you configure your default model and permission mode.

Prebuilt binary

The quickest way to install stepper for end users without a Rust toolchain. The installer detects your OS and architecture, downloads the appropriate archive, and adds stepper to your PATH.

Installation commands

# macOS / Linux
curl -fsSL https://stepper.gumyo.net/install-files/install.sh | bash
# Windows (PowerShell)
irm https://stepper.gumyo.net/install-files/install.ps1 | iex

The installer places the stepper binary into ~/.local/bin (or %USERPROFILE%\.local\bin on Windows) and updates your shell configuration to add that directory to your PATH.

Environment variables

Customize the download location and installation directory with these environment variables:

Environment Variable	Default	Purpose
`STEPPER_DOWNLOAD_BASE_URL`	`https://stepper.gumyo.net/install-files`	Where the release archives are hosted
`STEPPER_INSTALL_DIR`	`~/.local/bin`	Installation directory

Release archives

The installer scripts download the appropriate archive for your system. The following archives are published on every prod release in both versioned and version-less forms:

stepper-aarch64-apple-darwin.tar.gz — macOS (Apple Silicon)
stepper-x86_64-unknown-linux-gnu.tar.gz — Linux x86_64
stepper-x86_64-pc-windows-msvc.zip — Windows x86_64

The install scripts and binaries are hosted on a separate project from this repository. You can point STEPPER_DOWNLOAD_BASE_URL to a different location to download from your own hosted archive.

Build from source

For contributors and developers, build stepper from source using Rust 1.95 stable (edition 2024).

Build commands

scripts/install.sh                                  # cargo build + install to ~/.local/bin
STEPPER_INSTALL_DIR=/usr/local/bin sudo -E scripts/install.sh
cargo install --path crates/stepper-cli             # installs `stepper`
cargo build --release --bin stepper                 # binary at target/release/stepper
cargo run                                           # run from source (interactive TUI)

Quality gates

Run these checks locally to verify your build. These same gates run in CI:

cargo build --workspace
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace            # live tests are #[ignore]/env-gated, so skipped

First run

When you launch stepper in a project that has no .stepper/ directory, it runs a short guided setup to help you get started. This interactive process creates your configuration files.

Guided setup

On first run, stepper prompts you to:

Pick a default model
Select a permission mode

The setup then writes .stepper/setting.json and .stepper/stepper.md to configure your project.

Skip or customize setup

You can skip the interactive guided setup with the --no-init flag or the STEPPER_NO_INIT=1 environment variable. Run stepper init to scaffold the configuration files non-interactively:

# Skip interactive setup
stepper --no-init

# Or set the environment variable
STEPPER_NO_INIT=1 stepper

# Scaffold non-interactively
stepper init

Headless mode (using the -p flag) bypasses prompts entirely, runs with defaults, and creates no configuration files.