Packaging & Distribution
Relevant source files
The following files were used as context for generating this wiki page:
Numan is distributed as a cross-platform Rust binary designed to manage Nushell packages across Linux, Windows, and macOS. The project emphasizes verified artifacts and platform-specific delivery through multiple channels, including direct source builds, pre-built GitHub releases, Crates.io, and the Windows Package Manager (WinGet).
The distribution strategy ensures that while the installation of the numan CLI itself is global or user-scoped, the management of Nushell packages remains inert until explicitly activated by the user.
Sources: README.md:1-12, CONTRIBUTING.md:73-77
Distribution Channels
Numan provides several official pathways for installation and updates, catering to different operating systems and user preferences.
1. Pre-built GitHub Releases
The primary distribution method for end-users is via GitHub Releases. Each release includes platform-specific archives containing the compiled numan binary and a SHA256SUMS file for integrity verification.
| Platform | Target Triple | Archive Format |
|---|---|---|
| Linux (x86_64) | x86_64-unknown-linux-gnu | .tar.gz |
| Windows (x86_64) | x86_64-pc-windows-msvc | .zip |
| macOS (Apple Silicon) | aarch64-apple-darwin | .tar.gz |
| macOS (Intel) | x86_64-apple-darwin | .tar.gz |
Sources: README.md:67-85, CHANGELOG.md:58-60
2. Windows Package Manager (WinGet)
Numan is published to the winget-pkgs community repository under the identifier tonythethompson.numan.
- Manifests: Follow the standard layout under
manifests/t/tonythethompson/numan/<version>/. - Automation: A GitHub Action (
winget.yml) automatically submits update PRs to the Microsoft WinGet repository after every GitHub release, utilizing the Windows.ziprelease asset. - Naming Convention: The identifier uses lowercase to avoid Windows casing duplicates and maintain consistency with other packages by the same publisher.
Sources: packaging/winget/README.md:3-8, packaging/winget/README.md:20-25, README.md:104-106
3. Crates.io and Source Builds
Developers can install Numan directly via cargo install numan-cli. This requires the Rust stable toolchain (Minimum Supported Rust Version: 1.88). Building from source follows a standard Rust workflow.
git clone https://github.com/tonythethompson/numan.git
cd numan
cargo install --path .
Sources: README.md:58-65, README.md:108-112, Cargo.toml:4
Build System and Metadata
The Numan build system is managed via Cargo.toml, defining essential metadata and dependencies required for cross-platform operation.
Core Package Metadata
The CLI is named numan (binary) while the crate is published as numan-cli.
- Rust Edition: 2021
- Minimum Supported Rust Version (MSRV): 1.88
- License: MIT
Sources: Cargo.toml:1-12, AGENTS.md:143-145
Build Configuration Flow
The following diagram illustrates the transition from source code to distributed artifacts.
This diagram shows the multi-target build process and the subsequent distribution to GitHub, WinGet, and Crates.io.
Sources: README.md:67-85, packaging/winget/README.md:20-25, Cargo.toml:1-20
Release Lifecycle and Safety
The project maintains strict quality gates for all distributed versions to ensure reliability across supported platforms.
CI/CD Gates
Before any release or packaging update, CI enforces:
- Full Test Suite:
cargo testincluding real-Nu acceptance tests (which are ignored by default and require Nu on the PATH). - Linting:
cargo clippy -- -D warnings. - Formatting:
rustfmt --check. - MSRV Validation: Ensures compatibility with Rust 1.88.
Sources: CONTRIBUTING.md:13-30, CHANGELOG.md:118-121, AGENTS.md:23-42
Versioned Layouts
Starting in version 0.1.5, Numan introduced a versioned layout for its own managed Nushell installations to avoid clobbering different versions. Managed binaries are installed under <root>/tools/nushell/<version>/nu. This architecture supports side-by-side Nu version management, allowing users to switch between versions via numan use <version>.
Sources: CHANGELOG.md:27-33, AGENTS.md:120-125
Post-Installation Distribution
Once the CLI is distributed and installed, it facilitates the distribution of shell completions for various environments.
Completion Scripts
Numan can generate completion scripts for major shells, which is a key part of its user-level distribution:
- Bash:
numan completions bash - Zsh:
numan completions zsh - Fish:
numan completions fish - PowerShell:
numan completions powershell - Nushell:
numan completions nushell(ornu)
Sources: README.md:118-144, CHANGELOG.md:73-75
Summary
Numan's packaging and distribution system is designed for high-integrity, cross-platform delivery. By leveraging standard Rust tooling (Cargo), automated package manager submissions (WinGet), and immutable release artifacts (GitHub), Numan ensures that users on Linux, macOS, and Windows have access to verified, versioned binaries that integrate safely with their Nushell environments.
Sources: README.md:14-25, AGENTS.md:179-195