Install the CLI

Every way to install the rom-weaver command-line tool: package managers, verified install scripts, npm, Docker, and building from source. Each method installs the same rom-weaver CLI; pick the one that fits your machine and move on to your first apply.

Prebuilt install

Every method here installs a binary built for the release: macOS arm64 and x86-64; Linux x86-64 GNU plus x86-64, arm64, and i686 musl; and Windows arm64, x86-64, and x86.

Homebrew, the macOS/Linux install script, and global npm installs put the generated CLI manpages in a Unix manpath. The Windows installers store them under the installed package's docs/man directory. Cargo, cargo-binstall, and mise install the executable only; run rom-weaver man --install after any of them. The Docker image stores the pages under /usr/local/share/man/man1, but it has no man(1) program. See Install shell completions for completion files, and man pages for the page commands.

Homebrew (macOS arm64/Intel, Linux arm64/x86-64)

brew install rom-weaver/tap/rom-weaver

Scoop (Windows)

scoop bucket add rom-weaver https://github.com/rom-weaver/scoop-bucket
scoop install rom-weaver

Scoop stores the generated manpages under the app directory's docs\\man folder. Find that directory with scoop prefix rom-weaver; Windows has no standard manpath.

Install script (macOS, Linux)

Downloads the latest release to ~/.local/bin and checks its build provenance, refusing a definite verification failure. If the check cannot run, it warns and continues unless ROM_WEAVER_REQUIRE_ATTESTATION=1 is set. Set ROM_WEAVER_INSTALL_DIR to choose another directory, or ROM_WEAVER_VERSION to install a specific release. See Verify a download to run that check yourself or change how strict it is. It also installs manpages under ~/.local/share/man/man1 and completions under the standard per-user shell directories.

curl --proto '=https' --tlsv1.2 -LsSf \
  https://raw.githubusercontent.com/rom-weaver/rom-weaver/main/install.sh | sh

Install script (Windows)

The PowerShell equivalent, installing to %LOCALAPPDATA%\rom-weaver\bin. It honors the same environment variables and runs the same checks. The generated manpages are stored under that directory's docs\man folder because Windows has no standard manpath. The PowerShell completion is installed under its completions folder.

irm https://raw.githubusercontent.com/rom-weaver/rom-weaver/main/install.ps1 | iex

npm

The only channel covering every supported target at once. Needs Node.js 22+. The unscoped rom-weaver package points at the @rom-weaver/cli launcher, whose binary arrives through a platform-specific optional dependency, so only your platform's binary is downloaded.

Global installs of either package install the generated manpages on Unix. A local npm install keeps the pages under the package's docs/man directory.

npm install --global rom-weaver

Use the scoped launcher directly for a one-off run, or as a dev dependency for a repository's scripts:

npx @rom-weaver/cli probe --input game.iso
npm install --save-dev @rom-weaver/cli

cargo-binstall

Fetches the released binary instead of compiling from source, which cargo install rom-weaver-cli would otherwise do.

cargo binstall rom-weaver-cli

cargo-binstall installs only the executable, so no manpages or identify database sit beside it. Install them after:

rom-weaver man --install
rom-weaver setup

rom-weaver setup downloads this version's database into the per-user data directory. Running it again reports what is installed instead of downloading again; --force refreshes it. The Homebrew, scoop, npm, and install-script packages already carry the database, so setup only reports on those.

mise

Manages the CLI per project in mise.toml and verifies the release's GitHub artifact attestations on install. Install mise first. The minimum_release_age=0s option lets new releases resolve immediately on release day; omit it if you prefer mise's default release-age delay.

mise use 'github:rom-weaver/rom-weaver[minimum_release_age=0s]'

The generic GitHub backend installs only one release asset. Install the generated manpages and the identify database after it finishes:

rom-weaver man --install
rom-weaver setup

Source install

Install the current source build. This requires Rust 1.95, CMake, Clang, and a native compiler toolchain.

git clone https://github.com/rom-weaver/rom-weaver.git
cd rom-weaver
cargo install --path crates/rom-weaver-cli --locked
rom-weaver --version

Cargo installs the executable only. Install the generated manpages after it finishes:

rom-weaver man --install

Install the identify database:

rom-weaver setup

Run in Docker

A Linux CLI image is published for each release. It carries its own runtime, so nothing but Docker is required:

docker run --rm \
  --user "$(id -u):$(id -g)" \
  --volume "$PWD:/work" \
  ghcr.io/rom-weaver/rom-weaver-cli:latest \
  probe --input /work/game.iso

The image's working directory is /work; mount the directory holding your ROMs there and pass paths under /work. Arguments after the image name go straight to rom-weaver, so --help and every subcommand work unchanged. The generated manpages are present under /usr/local/share/man/man1; the image has no man(1) program, so use the CLI reference or copy a page out with docker cp.

--user "$(id -u):$(id -g)" is what makes the output usable. Bind-mounted files keep their host ownership. Without that flag, the container runs as the base image's nonroot user (uid 65532). The container may refuse permission to read your files, and anything it writes ends up owned by a uid that does not exist on the host. rom-weaver reads no home directory or user config, so an arbitrary uid needs no matching account inside the image.

The image is distroless - it contains the rom-weaver binary and its C runtime and nothing else, so there is no shell inside and --entrypoint sh will not get you a prompt.

Mount read-only sources with :ro and give writes their own destination:

docker run --rm \
  --user "$(id -u):$(id -g)" \
  --volume "$HOME/roms:/work/in:ro" \
  --volume "$PWD/out:/work/out" \
  ghcr.io/rom-weaver/rom-weaver-cli:latest \
  patch apply --input /work/in/game.sfc --patch /work/in/hack.bps --output /work/out/patched.sfc

Tags follow the release: latest, the exact version (X.Y.Z), and the minor series (X.Y). Stable releases also receive a major-series tag once the project reaches 1.0. Prereleases publish under beta instead of latest. The image is built for linux/amd64 and linux/arm64; Docker selects the native variant on Apple Silicon and other arm64 hosts.

Install shell completions

The Homebrew and script installers already place completion files. npm packages ship them under docs/completions. For the other install methods, print the script and save it where your shell looks for one, then start a new shell:

rom-weaver completions bash > /etc/bash_completion.d/rom-weaver
rom-weaver completions zsh  > ~/.zfunc/_rom-weaver
rom-weaver completions fish > ~/.config/fish/completions/rom-weaver.fish

bash, zsh, fish, powershell, and elvish are supported.

Development checkout

For a development checkout, follow the development guide and use cargo run -p rom-weaver-cli --bin rom-weaver -- in place of rom-weaver.

Installed? Run your first apply, then continue with the task guides or the CLI reference.