CLI Reference

CLI Reference

Global flag on all commands: --root <path> overrides the Numan root directory.

Run numan <command> --help for full flag documentation.

Commands

Command	Description
numan init [--refresh]	Probe Nu and cache paths for activation
numan search <query>	Search registry by name, description, or tags
numan info <owner/name>	Show package metadata and available versions
numan install <owner/name[@version]>	Download, verify, extract, and lock
numan list	List installed packages and activation status
numan activate [pkg...]	Register plugins / write module autoloads
numan deactivate [pkg...]	Remove module autoload entries
numan update [--check] [pkg]	Upgrade installed packages
numan remove [--force] <pkg>	Remove from lockfile and delete payload
numan gc [--dry-run]	Delete orphaned package directories
numan snapshot list	List committed activation snapshots
numan snapshot inspect <id>	Show snapshot contents and rollback diff (read-only)
numan snapshot delete <id> [--yes]	Delete a snapshot
numan snapshot rollback <id> [--yes]	Restore exactly a stored snapshot
numan registry list|sync|add|remove|packages	Registry management
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 <owner/name>	Compare imported payload vs nupm source
numan completions <shell>	Generate bash, fish, zsh, or powershell completions
numan doctor [--fix] [--yes] [--json]	Diagnose root health; optional safe repairs

Common flags

Command	Flags
install	--force reinstall; -v / --verbose
activate	--yes skip prompt; --verbose; --list status only; --check integrity only
deactivate	--yes skip prompt; --verbose
update	--check report only; -v / --verbose
remove	--force remove despite active activation
gc	--dry-run preview only
registry add	--key <base64-public-key> (required for custom registries; official is auto-configured on init)
nupm status	--nupm-home <path>
nupm inspect	--all scan home; --nupm-home <path>; --exit-on-ineligible fail on ineligible
nupm import	--as owner/name (single); --manifest <file> (batch); --nupm-home <path>; --yes skip consent
doctor	--fix apply safe repairs; --yes skip confirm tier; --json machine output; --nupm-home <path>

Design rules that shape the CLI

1. Install is inert — installs write only to $NUMAN_ROOT; Nu is never invoked.
2. Activate is explicit — the only command that registers plugins or manages autoload files.
3. Lockfile is ground truth — derived state (for example autoload projections) is not authoritative.
4. Immutable payloads — versions are content-addressed; updates leave old dirs until gc.
5. Mutation serialization — advisory locks prevent concurrent destructive operations.

See Inert Installation, Activation and Deactivation, and Architecture.