Command Reference
Relevant source files
The following files were used as context for generating this wiki page:
Numan is a cross-platform package manager for Nushell, designed to handle plugins, modules, scripts, and completions through a CLI interface. The command architecture strictly separates package installation from Nushell integration, ensuring that installs are inert until explicitly activated by the user.
The system relies on a set of core commands for lifecycle management (install, update, remove), integration (activate, deactivate), and diagnostics (doctor, init). All mutating commands are protected by a global mutation lock and utilize atomic JSON writes to prevent state corruption.
Sources: README.md:1-15, AGENTS.md:12-45, CONTRIBUTING.md:75-90
Lifecycle Management Commands
These commands manage the physical presence of packages within the $NUMAN_ROOT/packages/ directory. Numan enforces an "Install is Inert" rule, meaning these commands do not modify Nushell configuration or registry files directly.
Search and Information
The search and info commands provide visibility into the available packages and their compatibility with the user's current environment.
search <query>: Searches registries by name, description, or tags. By default, it hides packages incompatible with the current Nu version/platform unless the--allflag is used.info <owner/name>: Displays detailed metadata for a specific package, including available versions and specific compatibility markers.
The search flow incorporates a Resolver to match package nu_version constraints against the local Nu executable.
Sources: src/cmd/search.rs:24-90, src/cmd/info.rs:11-20, README.md:255-265
Installation and Removal
install <pkg>: Downloads, verifies SHA256 hashes (mandatory for plugins), extracts to content-addressed paths, and updates the lockfile.remove <pkg>: Deletes the package payload and removes its entry from the authoritative lockfile. Active plugins must be deactivated before removal unless--forceis used (which only bypasses module activation checks).gc: Garbage collects orphaned payload directories not referenced by the current lockfile or snapshots.
Sources: AGENTS.md:55-70, README.md:270-280, CONTRIBUTING.md:79-81
Activation and Integration
Activation is the explicit step that connects Numan-managed payloads to the Nushell environment.
Plugin Activation
Plugins are registered via environment variables and Nu's internal plugin registry. Numan uses a journaled approach (state/pending-activation.json) to recover from crashes during registration. A plugin is considered active only if the cached Nu executable hash, Nu version, and plugin path match the current environment.
Module Autoloads
Modules are integrated via a Numan-managed vendor autoload file (numan.nu).
| Component | Responsibility |
|---|---|
| ResolvedEntry | Validates safety, containment, and .nu extension. |
| CandidateRunner | Abstraction for validating .nu files using nu -n. |
| Ownership Marker | Header used to identify and protect Numan-managed files. |
System Setup and Diagnostics
Initialization and Doctor
init [--refresh]: Probes the local Nushell installation, caches paths, and configures the official registry. The--refreshflag is required after Nu upgrades to update cached paths.doctor [--scan]: Performs health checks on the$NUMAN_ROOT. It identifies managed-file drift, missing payloads, and invalid journals. It applies safe repairs by default.
Managed Nushell Versioning
Numan can manage multiple versions of Nushell itself.
| Command | Action |
|---|---|
setup nu <VERSION> | Installs a pinned version of Nu under tools/nushell/<version>/. |
use <version> | Switches the active managed Nu version. |
setup nu use <path> | Registers a specific existing Nu binary as a managed version. |
Sources: CHANGELOG.md:15-35, AGENTS.md:46-52, README.md:285-300
Interoperability: nupm compatibility
Numan provides one-way import and drift detection for packages managed by nupm.
nupm status: Scans the nupm home directory and reports import eligibility.nupm inspect: Classifies packages based on thecompat-schema-v1(e.g., detecting if they use unsupported custom build scripts).nupm import: Copies nupm payloads into the Numan managed structure with provenance tracking.nupm diff: Compares the imported Numan payload against the original nupm source to detect drift.
Sources: src/nupm_compat/classify.rs:15-50, README.md:320-335, AGENTS.md:72-78
Summary of Core Command Flags
| Command | Flag | Description |
|---|---|---|
| Global | --root <path> | Overrides the default Numan root directory. |
install | --force | Forces a reinstall of an existing package. |
activate | --check | Performs a read-only integrity check of current activations. |
doctor | --json | Outputs diagnostic results in machine-readable JSON format. |
setup nu | --skip-path | Installs Nu without attempting to update the system PATH. |
Sources: README.md:305-318, src/cmd/search.rs:13-18
Numan's command structure ensures that the system remains maintainable through strict architecture invariants, such as mutation locks and atomic state updates, while providing high visibility through diagnostics and compatibility-aware searching.