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.

Some install methods deliver only the executable, so two extra steps finish them: rom-weaver man --install for the manpages, and rom-weaver setup for the identify and cheat databases. identify and cheat baking read that data; other operations can also use it for title lookup and weave checks. Raw cheat codes supplied with --code do not need the database.

Cargo, cargo-binstall, and mise install the executable only; run rom-weaver man --install after any of them. Man pages lists where each install method puts the pages. See Install shell completions for completion files.

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. The same provenance policy checks the documentation archive before extraction. It also installs manpages under ~/.local/share/man/man1 and completions under the standard per-user shell directories.

sh -c 'curl -fsSL \
  https://rom-weaver.com/install.sh | sh'

The outer sh -c runs the command with POSIX shell syntax.

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, identify database, or cheat shards sit beside it. Install them after:

rom-weaver man --install
rom-weaver setup

rom-weaver setup downloads this version's identify packs and cheat shards into the per-user data directory. Running it again reports the installed copy; --force refreshes it.

The Homebrew, scoop, npm, install-script, and Docker packages already carry that data and need no setup. Running setup with those packages installs a separate per-user copy.

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 and cheat databases 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 and cheat databases:

rom-weaver setup

setup downloads them from the matching GitHub release, so a source build of an unreleased commit has no data to fetch. Build the data locally in that case with node scripts/ensure-identify-data.mjs; see Identify data.

Install the data without a network

On a machine that cannot reach GitHub, download rom-weaver-identify-data.tar.br from the release page on a machine that can, copy it across, and point setup at it:

rom-weaver setup --from rom-weaver-identify-data.tar.br

One archive serves as many machines as you like. Use the archive built for the version you installed; setup verifies the packs against the archive's own index. It does not compare the archive's release version with the CLI version.

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 CLI, runtime libraries, databases, and packaged documentation, but no shell. --entrypoint sh cannot start a shell in this image.

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.