CLI Reference

Complete reference for all niso CLI commands, organized by category.

All commands support --help for detailed usage. Output format can be controlled with --format table|json where applicable.

Package management#

niso init [--template <t>]Initialize a new project with manifest.toml

niso pack [--sign <key>] [--binary <path>]Create a .niso package

niso install <file> [--verify-key <key>]Install a package from a .niso file

niso activate <name> [version] [--dry-run] [--force]Generate unit, setup network, start service

niso deactivate <name>Stop and disable a service

niso rollback <name>Switch to previous version

niso remove <name> <version>Delete a specific package version

niso list [--format table|json] [--filter <expr>]List installed packages

niso status [name] [--format table|json]Show service status

niso inspect <file>View package metadata without installing

niso verify <file> --key <pubkey>Verify package signature

niso keygen [--output <dir>]Generate Ed25519 signing keypair

niso gc [--keep-versions <n>]Garbage collect old versions

niso export <name:version> -o <path>Export as offline .niso file

niso import <path>Install from local .niso file

Process management#

niso run [--rm] [-d] [-p port] [-e KEY=val] <pkg> [-- args]Run a package (like docker run)

niso exec <name> -- <command>Execute command in service environment

niso logs <name> [--follow] [--since <dur>] [--tail <n>]View service logs

niso kill <name> [--signal <sig>]Send signal to service

niso pause <name>Freeze service (cgroup freeze)

niso unpause <name>Resume frozen service

niso wait <name>Wait for oneshot service to complete

niso cp <name:path> <local> | <local> <name:path>Copy files to/from service

niso update <name> --memory <size> --cpus <n>Hot-update resources without restart

Registry#

niso push <file> [--registry <name>]Upload package to registry

niso pull <name> [version] [--registry <name>]Download package from registry

niso upgrade <name> [version]Pull + install + activate

niso search <query> [--registry <name>]Search packages

niso tag <name:version> <name:tag>Create or update a tag

niso login [<url>] [--key <key>]Authenticate with a registry

niso registry serve [--config <path>]Start registry server

niso registry add <name> <url> [--default]Configure a named registry

niso registry create-key --scope <s> --name <n>Create API key

niso registry list-keysList API keys

niso registry revoke-key <id>Revoke API key

niso registry gc [--keep-versions <n>]Garbage collect old versions

Networking#

niso net listList networks

niso net create <name> [--subnet <cidr>]Create a network

niso net remove <name>Delete a network

niso net inspect <name>Show network details

niso net ports [name]Show port mappings

niso net ping <from> <to>Test connectivity

niso net rulesShow nftables rules

niso port-forward <name> <host:container>Dynamic port mapping

Volumes#

niso volume listList volumes

niso volume create <name> [--shared] [--encrypted]Create a volume

niso volume inspect <name>Show volume details

niso volume remove <name> [--force]Delete a volume

niso volume grant <name> --service <s> --mode <m>Grant access

niso volume revoke <name> --service <s>Revoke access

niso volume snapshot <name>Create tar.zst backup

niso volume restore <name> --from <snap>Restore from snapshot

niso volume export <name> --output <path>Export for migration

niso volume import <name> --from <path>Import from backup

niso volume prune [--dry-run]Cleanup unused volumes

niso volume usageShow disk usage

niso volume audit [--since <dur>]Volume audit log

Stacks#

niso stack validate [--file <path>]Validate stack.toml

niso stack up [--file <path>] [--profile <name>]Deploy stack

niso stack down [--volumes] [--orphans]Tear down stack

niso stack upgrade <service> [version]Upgrade single service

niso stack status [--file <path>]Show stack status

niso stack diff [--file <path>]Show changes

niso stack restart <service>Restart a service

niso stack logs [-f] [service]View stack logs

niso stack wait <service>Wait for service

niso stack watchWatch for changes and redeploy

Fleet#

niso fleet deploy <name> <ver> [--strategy <s>] [--hosts <label>]Deploy to fleet

niso fleet status [--hosts <label>]Fleet status

niso fleet rollback <name> [--hosts <label>]Fleet-wide rollback

niso fleet versions <name>Version per host

niso fleet stack up --file <path> [--hosts <label>]Deploy stack to fleet

niso fleet stack diff --file <path>Diff stack across fleet

niso context create <name> --host <ssh://...>Create host context

niso context use <name>Switch context

Monitoring#

niso top [name]Live resource usage

niso stats [name]Cgroup stats snapshot

niso health [name]Health check status

niso health history <name>Health check history

niso events [--follow] [--filter key=val]Lifecycle events

niso dashboardTUI dashboard

niso debug <name>Full debug info

niso scan <pkg|--all> [--advisories <url>]Vulnerability scan

niso audit [--service <n>] [--since <dur>]Audit log

niso dfDisk usage breakdown

niso infoSystem info

Isolation#

niso isolation show <name>Show effective isolation config

niso isolation check <name>Validate kernel support

Development#

niso dev run <binary> [--port <p>] [--mount <m>]Run with isolation (no systemd)

niso dev watch --build <cmd> --run <cmd>Watch + rebuild + restart

niso dev deploy [--registry local]Pack + install + activate + logs

niso completions bash|zsh|fishGenerate shell completions

Global flags#

--host ssh://user@hostRun command on a remote host

--format table|jsonOutput format

--verbose / -vIncrease log verbosity

--quiet / -qSuppress non-essential output

--versionShow niso version

--help / -hShow help

Environment variables#

NISO_LOGLog level (debug, info, warn, error)

NISO_SIGNING_KEYPath to signing key for niso pack

NISO_REGISTRY_KEYRegistry API key for push/pull