winget install --id=tonythethompson.numan -e Numan installs plugins, modules, scripts, and completions from signed registries, pins immutable artifacts in a lockfile, and activates them with Nu only when you run numan activate.
Numan is a cross-platform package manager for Nushell. It installs registry plugins, modules, scripts, and completion payloads from signed registries, pins immutable artifacts in a lockfile, and activates plugins and modules with Nu only when you ask — keeping installs inert until you run numan activate.
Built in Rust for Linux, macOS, and Windows.
Nushell’s ecosystem has grown around community packages, but managing them across machines, Nu versions, and platforms is still painful. covers local installs well; registry-based workflows need verified artifacts, reproducible lockfiles, and safe activation that survives Nu upgrades.
Numan fills that gap:
| Concern | How Numan handles it |
|---|---|
| Trust | Ed25519 signatures over registry indexes; built-in production trust root for official; SHA256 verification of plugin binaries |
| Reproducibility | Lockfile v2 pins version, payload hash, and install origin |
| Platform safety | Artifacts resolved for the compile-time OS/arch/libc triple |
| Nu version matching | Resolver respects per-package Nu constraints |
| Activation isolation | install never touches Nu; only activate registers plugins or writes autoloads |
| Crash recovery | Journals for activation, autoload, lifecycle, and nupm import operations |
| nupm coexistence | Read-only discovery, one-way import, and drift detection for existing nupm installs |
Numan is early-stage. Core install, activate, update, remove, gc, registry, doctor, snapshots, nupm interoperability, and shell completions are implemented and covered by unit and hermetic integration tests, plus real-Nu acceptance on Linux, macOS, and Windows in CI. Pre-built release binaries are published via GitHub Releases.
owner/name or owner/name@versionnuman init configures official automatically; numan registry sync verifies signed indexesupdate, remove, and gc with pending-lifecycle journal recoverynuman nupm status|inspect|import|diff for migration from nupmnuman doctor diagnoses root health and applies safe repairs by default; --scan reports onlynuman completions| Registry package type | Install, verify, and lock | numan activate | Support tier |
|---|---|---|---|
| Plugin | Yes | Yes, through Nu's plugin registry | Supported |
| Module | Yes | Yes, through a Numan-managed vendor autoload file | Supported |
| Script | Yes | No | Install-only; activation is deferred |
| Completion package | Yes | No | Install-only; activation is deferred |
Install-only packages remain inert: Numan downloads, verifies, locks, lists,
removes, and garbage-collects their payloads, but does not execute them or
modify Nu configuration for them. This is separate from Numan's own shell
completion generator: numan completions is supported for bash, fish,
zsh, PowerShell, and Nushell (nu).
Requires Rust 1.88+ (stable recommended) and a Nushell binary on PATH for activation commands.
git clone https://github.com/tonythethompson/numan.git
cd numan
cargo install --path .
The binary is named numan.
Download the latest archive for your platform from GitHub Releases. Each release ships:
| Platform | Archive | Binary |
|---|---|---|
| Linux (x86_64) | numan--x86_64-unknown-linux-gnu.tar.gz | numan |
| Windows (x86_64) | numan--x86_64-pc-windows-msvc.zip | numan.exe |
| macOS (Apple Silicon) | numan--aarch64-apple-darwin.tar.gz | numan |
| macOS (Intel) | numan--x86_64-apple-darwin.tar.gz | numan |
Linux / macOS
tar -xzf numan--.tar.gz
install -m 755 numan--/numan ~/.local/bin/numan
Windows (PowerShell)
Expand-Archive numan--x86_64-pc-windows-msvc.zip -DestinationPath .
# Add the extracted folder to your PATH, or copy numan.exe into a directory already on PATH
Verify downloads with the SHA256SUMS file attached to each release.
master)cargo install --git https://github.com/tonythethompson/numan
Tracks the default branch. For a reproducible install, choose a published tag from GitHub Releases and pass --tag vX.Y.Z.
winget install tonythethompson.numan
cargo install numan-cli
Requires Rust (stable). The installed binary is named numan.
Requirements: a Nushell binary on PATH for numan init, numan activate, and related commands.
numan completions prints the script on stdout and a copy-ready install command on stderr.
# Bash
numan completions bash > ~/.local/share/bash-completion/completions/numan
# Zsh
numan completions zsh > ~/.zfunc/_numan
# Fish
numan completions fish > ~/.config/fish/completions/numan.fish
# PowerShell (append to $PROFILE; do not use Out-File — that overwrites the profile)
numan completions powershell | Add-Content -Encoding utf8 $PROFILE
# Nushell (vendor autoload; `nu` is accepted as an alias for `nushell`)
mkdir ($nu.data-dir | path join vendor/autoload)
numan completions nushell | save -f ($nu.data-dir | path join vendor/autoload/numan-completions.nu)
PowerShell completions are safe to place after other statements in $PROFILE. Prefer writing to a dedicated file and dot-sourcing if you want easier updates:
New-Item -ItemType Directory -Force -Path "$HOME\.numan" | Out-Null
numan completions powershell | Out-File -Encoding utf8 "$HOME\.numan\completions.ps1"
Add-Content -Path $PROFILE -Value '. $HOME\.numan\completions.ps1'
Copy-paste path from install through first activation:
# Install (pick one)
cargo install numan-cli
# or: download a release archive from GitHub Releases and add numan to PATH
numan init
numan registry sync
numan try # install + activate a starter that fits your Nu (e.g., skim for Nu 0.114)
numan doctor
Or pick a package yourself (numan search hides incompatible hits by default; use --all to see them):
numan search nutest
numan info vyadh/nutest
numan install vyadh/nutest
numan activate vyadh/nutest
Install is inert — nothing is registered with Nu until you run numan activate (or numan try, which activates after install). If a package needs a different Nu minor, Numan explains the mismatch and can offer numan setup nu (activations are per-Nu; re-activate after switching). When no compatible starter exists, numan try suggests installing a matching managed Nu version or searching for another package with numan search.
After Nu upgrades, refresh cached paths and activation identity:
numan init --refresh
Optional: install shell completions (numan completions bash, etc.) — see Installation.
Probe your local Nu installation and create Numan state under the default root (or --root):
numan init
numan init configures the official registry automatically and prints a numbered checklist when setup is incomplete.
numan registry sync
numan try # curated starter for your Nu + platform (e.g., skim for Nu 0.114)
# or:
numan search nutest # hides incompatible hits; use --all to show them
numan info vyadh/nutest
numan install vyadh/nutest
numan list
numan activate # activate all inactive packages
numan activate owner/package-name # activate specific packages
numan activate --list # show activation status
numan activate --check # verify activation integrity (read-only)
numan try already activates unless you pass --no-activate.
For modules:
numan deactivate owner/module-name
numan update --check # see available upgrades
numan update # apply upgrades
numan remove owner/package-name
numan gc --dry-run # preview orphaned payload dirs
numan gc # delete unreferenced payloads
Numan snapshots activation state before update, remove, activate, and deactivate, so a bad change can be undone:
numan snapshot list
numan snapshot inspect # affected packages, digests, payload check
numan snapshot rollback # restore exactly that state
See docs/snapshots-and-rollback.md for scope, retention, and safety guarantees.
numan doctor # diagnose and apply safe automated repairs
numan doctor --scan # report-only diagnosis
By default, Numan stores state under a platform-specific root (override with NUMAN_ROOT or --root):
| Platform | Default root |
|---|---|
| Linux | ~/.local/share/numan |
| macOS | ~/Library/Application Support/numan |
| Windows | %LOCALAPPDATA%\numan |
Important paths under the root:
numan/
├── config.toml # registries, defaults
├── lockfile # pinned installs (authoritative)
├── packages/ # immutable versioned payloads
├── registries/ # synced index caches
├── state/ # journals, nupm import provenance
└── nu_state/ # cached Nu paths for activation checks
Payload paths are immutable: packages////-/.
Global flag: --root — override the Numan root directory (all commands).
| Command | Description |
|---|---|
numan init [--refresh] | Probe Nu and cache paths for activation |
numan try [--no-activate] | Install and activate a curated starter package for your Nu + platform (prefers Nu 0.114 starters; suggests managed Nu pin or search if no compatible starter) |
numan search | Search registry by name, description, or tags |
numan info | Show package metadata and available versions |
numan install | Download, verify, extract, and lock |
numan list | List installed packages and activation status |
numan activate [pkg...] | Register plugins / write module autoloads (scripts and completion packages are deferred) |
numan deactivate [pkg...] | Remove module autoload entries |
numan update [--check] [pkg] | Upgrade installed packages |
numan remove [--force] | Remove from lockfile and delete payload |
numan gc [--dry-run] | Delete orphaned package directories |
numan snapshot list | List all committed activation snapshots |
numan snapshot inspect | Show snapshot contents and rollback diff (read-only) |
numan snapshot delete [--yes] | Delete a snapshot |
numan snapshot rollback [--yes] | Restore exactly a stored snapshot |
numan registry list|sync|add|remove|packages | Registry management |
numan setup nu [VERSION] | Download and install official Nushell under Numan root (optionally pinned) |
numan setup nu remove | Remove the managed Nushell install and fall back to PATH Nu |
numan setup nu path | Use the Nushell already on PATH (removes managed install) |
numan setup nu use | Register a specific existing Nushell binary |
| Command | Flags |
|---|---|
install | --force reinstall; -v / --verbose |
activate | --verbose; --list status only; --check integrity only |
deactivate | --verbose |
update | --check report only; -v / --verbose |
remove | --force remove despite active activation |
gc | --dry-run preview only |
registry add | --key (required for custom registries; official is auto-configured on init) |
nupm status | --nupm-home |
nupm inspect | --all scan home; --nupm-home ; --exit-on-ineligible fail on ineligible |
nupm import | --as owner/name (single import); --manifest (batch); --nupm-home ; --yes skip consent |
doctor | --scan report only; --json machine output; --nupm-home (repairs by default) |
setup nu | --force re-download; --skip-path don't update PATH; --yes skip prompt |
Run numan --help for full flag documentation.
Numan can discover and import compatible packages from an existing nupm installation without modifying nupm state.
# Point at nupm home (or rely on $NUPM_HOME)
numan nupm status --nupm-home ~/.config/nupm
numan nupm inspect --all --nupm-home ~/.config/nupm
# Import a supported module package
numan nupm import /path/to/package --as myorg/my-module --yes
# Check drift after the source changes
numan nupm diff myorg/my-module
Compatibility matrix: which nupm package shapes Numan can import is defined in docs/nupm-compatibility.md (compat-schema-v1). Run numan nupm inspect to classify packages before import.
$NUMAN_ROOT; Nu is never invoked.gc.See AGENTS.md for architecture details aimed at contributors and agents.
cargo build
cargo test # unit + hermetic integration tests
cargo clippy -- -D warnings # lint (CI-enforced)
cargo fmt # format
# Real-Nu acceptance tests (requires Nu 0.113+ on PATH)
cargo test -- --ignored
CI runs tests, clippy, rustfmt --check, and real-Nu acceptance on Ubuntu, Windows, and macOS.
master (feature/... or fix/...).cargo test and cargo clippy -- -D warnings pass.PR reviewers should follow REVIEW.md.
Releases: see the latest GitHub Release — feature-complete core on 0.1.x while dogfooding the official registry.
For the cross-repository plan snapshot (as of 2026-07-29) across numan,
numan-registry, and numan-plugins, see
docs/plans/2026-07-29-remaining-roadmap.md.
| Phase | Scope | Status |
|---|---|---|
| 1–2 | Types, platform, lockfile, signed registry, install transaction | ✅ |
| 3–4 | Plugin + module activation, journals, managed autoloads | ✅ |
| 5 | update / remove / gc, lockfile v2, snapshots + rollback | ✅ (source builds deferred) |
| 6 | nupm status, inspect, import, drift | ✅ |
| 7 | Doctor, completions, onboarding, CI hardening, winget packaging | ✅ — plan |
| Post-7.6 | Production official registry cutover; numan init and numan doctor auto-configure official | ✅ (v0.1.4) |
| Item | Tracking |
|---|---|
Community winget install (winget install tonythethompson.numan) | ✅ winget-pkgs PR #400470; updates automated |
| Curated official registry packages + trust/bootstrap policy | 🔄 #18, intake roadmap stage 1 |
| Cross-platform fresh-install dogfooding | 🔄 init → registry sync → search → install → activate → doctor on Linux, macOS, Windows |
1.0 when the rows above are done and there are no open P0/P1 issues on the core install/activate/update/remove lifecycle.
| Item | Tracking |
|---|---|
| Source builds (clone/build with consent) | #20 / Phase 5.2 |
| Plugin lifecycle gate before mutation | #22 / Phase 5.5 |
| Registry intake automation (lint, discovery, validation reports) | docs/registry-intake-roadmap.md stages 2–4 |
| Scoop manifest | Deferred (low demand) |
Phase 7 detail (complete)
| Slice | Status |
|---|---|
7.1 Distribution baseline (releases, crates.io, numan init) | ✅ |
7.2 numan doctor | ✅ |
| 7.3 Completions + error UX | ✅ |
| 7.4 Onboarding quick start | ✅ |
| 7.5 CI / release hardening | ✅ |
| 7.6 winget manifests (in-repo) | ✅ |
MIT — see LICENSE.
numan use Switch the active managed Nu to a pinned version (no auto-install; errors with a hint to run numan setup nu if missing) |
numan use latest | Switch the active managed Nu to the latest installed version |
numan use list | List installed managed Nu versions and mark the active one |
numan nupm status | Summarize nupm home and import eligibility |
numan nupm inspect [--all] [path] | Classify nupm packages at a path |
numan nupm import [--as owner/name] [path] | One-way import into Numan |
numan nupm import --manifest file.toml | Batch import from manifest |
numan nupm diff | Compare imported payload vs nupm source |
numan completions | Generate bash, fish, zsh, powershell, or nushell completions |
numan doctor [--scan] [--json] | Diagnose root health and repair (use --scan for report-only) |