Get Started · v0.1.0-beta3

Install Netsuke

Install the CLI, make sure ninja is available, and start with a small Netsukefile. Netsuke works best when the first build is boring.

macOS Linux Windows

Install with Cargo

Netsuke v0.1.0-beta3 is published on crates.io as the netsuke-build crate; the installed binary is named netsuke. Where cargo binstall is available, prefer it: it fetches a prebuilt release binary and avoids the nightly toolchain requirement below. ninja must be installed separately.

$ cargo binstall [email protected]

Build from crates.io instead

Netsuke builds with the Polonius borrow checker, which recent nightlies enable by default. A registry build runs outside a repository checkout, so it must select the dated Rust nightly toolchain explicitly:

$ rustup toolchain install nightly-2026-08-23
$ cargo +nightly-2026-08-23 install [email protected]

Build from a source checkout

git clone https://github.com/leynos/netsuke.git
cd netsuke && cargo install --path .

The checkout's rust-toolchain.toml selects the pinned nightly automatically, so no toolchain argument is passed here.

Verify

netsuke --version

Linux packages

The v0.1.0-beta3 release ships Debian (.deb) and RPM (.rpm) packages for x86-64 (amd64) and Arm64 (arm64). They install the binary under /usr/bin, add the netsuke.1 manual page, and declare ninja-build as a dependency, so Ninja is pulled in automatically.

# Debian or Ubuntu
$ sudo apt install ./PACKAGE.deb

# Fedora, Rocky Linux, or another RPM-based distribution
$ sudo dnf install ./PACKAGE.rpm

Replace PACKAGE with the downloaded filename for your architecture. Standalone binaries with SHA-256 checksum sidecars are also published, and each standalone release archive stages shell completions for Bash, Elvish, Fish, PowerShell, and Zsh under completions/<shell>/ — the installer packages do not install completion files. The installer packages themselves do not have checksum sidecars in v0.1.0-beta3.

macOS installer package

The v0.1.0-beta3 release ships installer packages (.pkg) for Intel x86-64 and Apple silicon Arm64. They install the binary under /usr/local/bin along with the manual page and licence. Ninja must be installed separately.

# Install the downloaded package
$ sudo installer -pkg ./PACKAGE.pkg -target /

# Ninja is a separate install
$ brew install ninja

Replace PACKAGE with the downloaded filename for your architecture (for example netsuke-0.1.0-beta3-macos-arm64.pkg).

Windows installer

The v0.1.0-beta3 release ships Windows Installer (.msi) packages for x64 and Arm64. The MSI installs to C:\Program Files\netsuke and does not update PATH. Ninja must be installed separately. PowerShell help files are published beside each MSI as sidecar artefacts. On Windows, recipes run in Windows PowerShell by default; set NETSUKE_WINDOWS_SHELL=bash to keep POSIX recipes running through Git Bash or MSYS2 (see the recipe shell contract). An MSI product version cannot carry a pre-release suffix, so every beta in the 0.1.0 series shares the numeric version 0.1.0: installing a later pre-release MSI replaces the existing installation rather than sitting alongside it.

# Install the downloaded package
msiexec.exe /i PACKAGE.msi

# Add the install directory to the current user's PATH
$dir = Join-Path $env:ProgramFiles 'netsuke'
[Environment]::SetEnvironmentVariable('Path',
  "$([Environment]::GetEnvironmentVariable('Path', 'User'));$dir", 'User')
$env:Path = "$env:Path;$dir"

netsuke --version

See the complete Windows setup for the idempotent PATH script and the PowerShell help module install.

Note: Netsuke delegates execution to ninja; make sure it is on your PATH. You may need to restart your terminal after installation for the netsuke command to be recognized.

Verify Installation

Run the version command to ensure Netsuke is correctly installed and accessible in your path.

$ netsuke --version
netsuke 0.1.0-beta3

Create a Manifest

Create a Netsukefile in the project root. Start with one rule, one target, and one default.

netsuke_version: "1.0.0"
targets:
  - name: "hello.txt"
    command: "printf 'hello\n' > {{ outs }}"
    sources: []
defaults: ["hello.txt"]

Run Your First Build

Execute the default target defined in your manifest. Netsuke validates the manifest, expands templates, writes a Ninja plan, and hands execution over.

$ netsuke build
[1/1] printf 'hello\n' > hello.txt

Read Getting Started Guide

Troubleshooting

Command not found?

Ensure ~/.cargo/bin or /usr/local/bin is in your PATH environment variable.

`ninja` missing?

Install Ninja separately and make sure it is on your PATH. Netsuke delegates execution to it.

Manifest errors?

Start by checking YAML structure first. Netsuke validates YAML before any Jinja rendering happens.

Visit GitHub Issues →

Manual Download

The v0.1.0-beta3 release ships installers: Debian and RPM packages for Linux (x86-64 and Arm64), a macOS installer package, and a Windows MSI. Ninja must be installed separately on macOS and Windows.

View all releases

Open source

Netsuke is free and open source. The source, issues, and contribution guide are all on GitHub.

View on GitHub

Common Questions

Can I install a specific version?

Yes. Use Cargo with the pinned nightly and a semantic version number: cargo +nightly-2026-08-23 install netsuke-build --version <VERSION>. The version must be a number without a leading v (for example 0.1.0-beta3, not v0.1.0-beta3). Pre-release versions such as 0.1.0-beta3 must be requested explicitly; Cargo does not select them by default. Check crates.io for available versions.

How do I update Netsuke?

Re-run cargo binstall netsuke-build@<VERSION> with the new version to fetch its prebuilt release, or run cargo +nightly-2026-08-23 install netsuke-build --force to rebuild from crates.io with the pinned nightly shown above. Either way the existing netsuke binary is replaced.

Does it work with CI/CD?

Yes. Install Netsuke on your continuous integration (CI) agent via cargo binstall [email protected] (pin the version in automated workflows) and run netsuke build as a build step. When standard error (stderr) is not a teletype/terminal (TTY), progress falls back to plain text automatically, and --json emits a machine-readable result document. Dedicated CI integrations are planned but not yet available.