Getting Started & Setup
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Numan is a production-grade, cross-platform Nushell package manager CLI written in Rust. It is designed to manage plugins, modules, scripts, and completions through verified artifacts and reproducible lockfiles. The setup process is designed to keep installations "inert"—meaning numan install only writes to the local Numan root without modifying the Nushell environment until an explicit activate command is issued.
Sources: README.md:1-15, AGENTS.md:5-10
The setup flow typically involves initializing the environment, synchronizing with a signed registry, and optionally using a curated starter package to verify compatibility with the user's current Nushell version and platform architecture.
Sources: README.md:135-150
Environment Prerequisites
Before setting up Numan, the system must meet specific toolchain and runtime requirements.
System Requirements
- Rust Toolchain: Version 1.88 or newer (stable recommended).
- Nushell: A
nubinary must be available on the systemPATHfor activation commands and path probing. - Operating System: Supported on Linux (x86_64), macOS (Apple Silicon/Intel), and Windows (x86_64).
Sources: README.md:75-80, CONTRIBUTING.md:7-10, Cargo.toml:5
Development Build Dependencies
For building from source, Numan requires git2 and reqwest, which link against system libraries.
- Linux: Requires
pkg-configandlibssl-dev(OpenSSL). - Windows/macOS: Standard toolchains are sufficient for release builds.
Sources: AGENTS.md:197-200
Installation Methods
Numan provides multiple installation paths depending on the user's preference for stability or development access.
Pre-built Binaries & Package Managers
Numan is distributed via GitHub Releases, Crates.io, and WinGet.
| Method | Command / Action | Target Audience |
|---|---|---|
| WinGet | winget install tonythethompson.numan | Windows users |
| Cargo | cargo install numan-cli | Rust developers |
| Releases | Download from GitHub Releases | General users (Linux/macOS/Windows) |
Sources: README.md:105-125, CHANGELOG.md:85-90
Building from Source
Users can track the master branch or specific tags by building locally.
git clone https://github.com/tonythethompson/numan.git
cd numan
cargo build --release
Sources: README.md:82-88, CONTRIBUTING.md:12-18
Initial Configuration & Initialization
The first-run experience is managed by the numan init command, which probes the local environment and establishes the Numan root directory.
The Initialization Flow
The following diagram illustrates the steps Numan takes during its first-run initialization:
The initialization process ensures that Numan has a verified path to Nushell and a production-grade trust root for package verification.
Sources: README.md:152-162, AGENTS.md:40-42
Data Layout
By default, Numan stores state in platform-specific locations:
- Linux:
~/.local/share/numan - macOS:
~/Library/Application Support/numan - Windows:
%LOCALAPPDATA%\numan
Sources: README.md:188-200
Quick Start: The "Try" Workflow
Numan provides a try command designed to streamline the onboarding of new users by installing a compatible "starter" package.
Sources: README.md:143-150, AGENTS.md:47-49, CHANGELOG.md:49-55
Post-Setup Verification
Users can verify their setup using numan doctor, which diagnoses the health of the Numan root and applies automated repairs if necessary.
numan doctor --scan: Reports issues without making changes.numan doctor: Applies safe repairs to journals and configuration.
Sources: README.md:178-181, AGENTS.md:43-44
Shell Completions Setup
Numan includes a completion generator for several shells. This is a critical step for a functional CLI experience.
| Shell | Installation Hint |
|---|---|
| Bash | numan completions bash > ~/.local/share/bash-completion/completions/numan |
| Zsh | numan completions zsh > ~/.zfunc/_numan |
| Nushell | `numan completions nushell |
| PowerShell | `numan completions powershell |
Sources: README.md:127-140, CHANGELOG.md:58-62
Summary
Setting up Numan involves installing the CLI binary, initializing the environment with numan init, and synchronizing with the official registry. The architecture enforces separation between installation and activation, ensuring that the Nushell environment remains stable. Through the numan try and numan doctor commands, Numan provides a guided onboarding path and self-healing capabilities for its configuration and state.
Sources: README.md:300-310, AGENTS.md:100-110