Get Started

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 is published on crates.io as the netsuke-build crate; the installed binary is named netsuke. Source builds require Rust 1.89 or later, and ninja must be installed separately.

$ cargo install netsuke-build

Build from a source checkout

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

Verify

netsuke --version

Linux packages

The v0.1.0 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; the installer packages themselves do not have checksum sidecars in v0.1.0.

macOS installer package

The v0.1.0 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-macos-arm64.pkg).

Windows installer

The v0.1.0 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.

# 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

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 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 a semantic version number: cargo install netsuke-build --version <VERSION>. The version must be a number without a leading v (for example 0.1.0, not v0.1.0). Check crates.io for available versions.

How do I update Netsuke?

Run cargo install netsuke-build --force. Cargo replaces the existing netsuke binary with the latest published version.

Does it work with CI/CD?

Yes. Install Netsuke on your continuous integration (CI) agent via cargo install netsuke-build 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.