CLI & flags reference
The complete reference for the niu command line: basic invocations and every flag,
WT integration, self-update, all plugin subcommands, skill / wpm and diagnostics. Each row gives
the command, its purpose and a note; notes cite the fact's source file in the niubash repo. For
fine-grained semantics and the full manual, see the outbound links at the end.
Basic invocations
Three execution paths are deliberately separated: the interactive REPL, the zero-load one-shot
-c, and the REPL-equivalent one-shot -C. Automation uses only the last
two; interactive content stays in the rc.
| Command | Purpose | Notes (source) |
|---|---|---|
niubash | Start the interactive REPL | The daily shell; loads ~/.niubashrc and the interactive lifecycle hooks. (advanced-usage.md) |
niu -c '<cmd>' | Run one command, then exit | The script / test / CI / agent channel: no rc, no plugins, no interactive hooks; use NIU_ENV (or BASH_ENV) to point at a one-shot init file when initialization is needed. (advanced-usage.md) |
niu -C '<cmd>' · niu --repl-command <cmd> | One-shot REPL command | Loads the same startup state as the interactive REPL (rc + hooks), runs one command, then exits. (advanced-usage.md) |
niu --encoded-command <b64> | Execute a base64-encoded command | A quote-free channel for agents/CI; optional v1: prefix guards against MSYS path rewriting — semantics identical to -c. (niu --help (src/main.rs)) |
niu --cwd-state <file> [-c ...] | Directory memory across invocations | Restores the recorded directory at startup, writes the final directory back at exit; one file per workspace isolates agents. (niu --help (src/main.rs)) |
niu -V · niu --version | Version and component info | The first thing to check when diagnosing: confirm the active binary version before anything else. (advanced-usage.md) |
niu <script> [args] | Run a script file | Runs the script from a file argument, passing arguments through. (niu --help, live binary (1.4.0)) |
niu setup | Re-run the prompt / plugin setup | Wizard-style reconfiguration; safe to run repeatedly. (niu --help, live binary (1.4.0)) |
niu font | Nerd Font detection and install advice | Detects font gaps and recommends installs. (niu --help, live binary (1.4.0)) |
niu -h · niu --help | Show help | The source this page is built from. (niu --help, live binary (1.4.0)) |
niu --completion-probe <line> [cursor] | Debug: print completion candidates | Given an input line (optionally a cursor position), prints the candidates the completion engine would produce — for writing completion plugins or debugging completion. (niu --help, live binary (1.4.0)) |
Windows Terminal integration
Two independent flag groups — profile and shortcuts — each with a quiet switch.
| Command | Purpose | Notes (source) |
|---|---|---|
niu --install-wt-profile | Add/update the Windows Terminal profile | Writes Niubash's WT profile.(niu --help, live binary (1.4.0)) |
niu --install-wt-profile --set-default | Also set it as the WT default profile | Use together with the previous flag.(niu --help, live binary (1.4.0)) |
niu --install-wt-shortcuts | Rewrite desktop / Start-menu shortcuts | When WT is detected, rewrites them as wt.exe -p Niubash.(niu --help, live binary (1.4.0)) |
niu --install-wt-shortcuts --update-only | Only update existing shortcuts | Creates nothing new; edits existing files only.(niu --help, live binary (1.4.0)) |
--quiet | Suppress non-error output | The profile and shortcuts flag groups each carry a same-named quiet flag.(niu --help, live binary (1.4.0)) |
Self-update
| Command | Purpose | Notes (source) |
|---|---|---|
niu --self-update | Download and run the latest release installer | WinHTTP follows GitHub releases/latest.(installer.md · niu --help, live binary (1.4.0)) |
niu --self-update --check | Report the latest version only | Does not update.(niu --help, live binary (1.4.0)) |
niu --self-update --dry-run | Download the installer without running it | For verifying the download chain.(niu --help, live binary (1.4.0)) |
self-update (REPL command) | Update Niubash and exit the shell | The in-session equivalent verb.(niu --help, live binary (1.4.0)) |
update-niubash | Alias of self-update | Synonymous entry point.(niu --help, live binary (1.4.0)) |
plugin subcommands (complete)
Installing, trusting and locking the external bash ecosystem (oh-my-bash / bash-it / bash-completion etc.).
| Command | Purpose | Notes (source) |
|---|---|---|
niu plugin add <id|owner/repo|url|path> | Install an external plugin source (untrusted) | Four locator forms supported.(niu --help, live binary (1.4.0)) |
niu plugin list [--json] | List sources, assets and activation state | --json is machine-readable.(niu --help, live binary (1.4.0)) |
niu plugin enable|disable <target> | Activate / deactivate a source or asset | Granular down to asset level.(niu --help, live binary (1.4.0)) |
niu plugin update · sync · restore · rollback · clean | The lockfile verb family | vim-plug / lazy.nvim-style lock and restore semantics.(niu --help, live binary (1.4.0)) |
niu plugin trust <id> | Review and activate a source's assets | The trust-check layer.(niu --help, live binary (1.4.0)) |
niu plugin discover [--verbose] | Read-only overview of external plugin sources | Changes no state.(niu --help, live binary (1.4.0)) |
niu plugin source <command> | The full source protocol | add / trust / sign / verify / remove / update / rollback / list.(niu --help, live binary (1.4.0)) |
niu plugin recipe <command> | Recipe index | list / show / add.(niu --help, live binary (1.4.0)) |
niu plugin distro <command> | Bundle distribution | list / import / remove / apply.(niu --help, live binary (1.4.0)) |
niu plugin mirror <command> | Git-fetch mirrors | list / show / set — friendly to networks behind GitHub throttling.(niu --help, live binary (1.4.0)) |
niu plugin ui | Menu-driven UI | Sections by state; verbs match the command line.(niu --help, live binary (1.4.0)) |
GNU bash-compatible surface
The options below are not listed in niu --help but all supported —
the rubash engine aligns with GNU Bash 5.3 semantics, so GNU's invocation surface carries over:
| Surface | Content | Notes |
|---|---|---|
GNU long options | --debug --debugger --dump-po-strings --dump-strings --help --init-file --login --noediting --noprofile --norc --posix --pretty-print --rcfile --restricted --verbose --version | One-to-one with the 16 long options listed by bash --help. |
Invocation combos (startup only) | -i -l -r -s -D · -c command · -O shopt_option | Interactive / login / restricted / read stdin / echo per line / set a shopt. |
set option surface | -abefhkmnptuvxBCEHPT · -o option | The same set of single-letter options and -o names as GNU (niu -c 'help set' lists them all). |
Builtin help | niu -c 'help set' · niu -c help | set option descriptions and the builtin list — GNU's own entry points. |
rc selection | --rcfile / --init-file | Point at an alternative startup file. |
Source: cross-checked against bash --help (same-machine GNU Bash 5.3.0 output); compatibility is governed by the 83/83 suite ledger.
Configuration and environment variables
| Item | Purpose | Notes (source) |
|---|---|---|
~/.niubashrc | Interactive startup config file | Pure bash syntax; loaded by the interactive REPL and -C, not by -c.(niu --help, live binary (1.4.0)) |
NIU_ENV=<file> | Non-interactive one-shot init file | Sourced before -c / script / stdin startup; takes priority over BASH_ENV; unset by default to keep -c fast.(niu --help, live binary (1.4.0)) |
BASH_ENV=<file> | The GNU bash-compatible synonym | Same semantics; lower priority than NIU_ENV.(niu --help, live binary (1.4.0)) |
NIU_LANG=<zh|en> | Setup-wizard language | Fallback order: Windows UI language → LC_ALL / LANG.(niu --help, live binary (1.4.0)) |
skill subcommands
Installing and checking the AI agent skill bundle (capability surface + dialect contract).
Every --target value: claude (default), zcode,
cursor, all, and any directory.
| Command | Purpose | Notes (source) |
|---|---|---|
niu skill install | Install the AI agent skill bundle | Defaults to ~/.claude/skills/niubash/ (SKILL.md + references/). (advanced-usage.md) |
niu skill install --target claude | Install for Claude only | Same as the default target; byte-exact on disk. (advanced-usage.md) |
niu skill install --target zcode | Install for ZCode | Writes into ZCode's skills directory. (niu --help (src/main.rs)) |
niu skill install --target cursor | Install for Cursor | Writes into Cursor's skills directory. (niu --help (src/main.rs)) |
niu skill install --target all | Install to claude + zcode + cursor | Covers all three agent hosts at once. (advanced-usage.md) |
niu skill install --target C:/agents/skills | Install to any directory (universal form) | Lands as <dir>/niubash/ for any agent host to pick up. (advanced-usage.md) |
niu skill status | Check bundle status per target | current / outdated = byte comparison + sha256; niu doctor carries an advisory line. (advanced-usage.md) |
plugin subcommands (workflow)
Installing, trusting and activating the external bash ecosystem (oh-my-bash, bash-it, any git source) — always "install first, review second, trust third"; the declarative spec is the single source of truth.
| Command | Purpose | Notes (source) |
|---|---|---|
niu plugin add <id|owner/repo|url|path> | Install an external plugin source | Clones into ~/.niubash/sources/<id> and registers the registry; a new source is untrusted by default and add executes nothing. (getting-started.md) |
niu plugin trust <id> | Review-pass the execution gate | Enables after checksum review; enable before trust is rejected. (getting-started.md) |
niu plugin enable <target> · disable <target> | Activate / deactivate sources or theme assets | Maintains the # >>> niu source <id> managed block at the tail of ~/.niubashrc; content outside the block is never rewritten. After disable, the builtin prompt (floor) returns. (getting-started.md) |
niu plugin sync [--prune | --adopt] | Reconcile the spec with what is installed | Lockfile-style verb family: update / sync / restore / rollback / clean; --adopt declares an already-installed source into the spec. (advanced-usage.md) |
niu plugin mirror <command> | Git-fetch mirror control | list / show / set <url|none>: a configurable insteadOf mirror, applied only to the git transport layer. (niu --help (src/main.rs)) |
niu plugin list [--json] | Inventory of sources, assets and activation state | --json for agents (likewise recipe list --json); plus the read-only discover overview. (advanced-usage.md) |
wpm quick reference
The Winux package manager: the first channel for the Unix command layer (ls,
grep, rg …) on Windows. Query subcommands support --json
(with a schema version field); mutating subcommands speak in exit codes.
| Command | Purpose | Notes (source) |
|---|---|---|
wpm list [--json] · wpm installed | Package catalogue and locally installed state | --json emits schema:1-versioned pure JSON; installed lists only this root's installed packages. (installer.md · index-schema.md) |
wpm search <q> · wpm info <pkg> [--json] | Search packages / show package details | If the index is stale, run wpm index update first; info --json returns the full Package record. (skills/wpm.md · index-schema.md) |
wpm install <pkg> | Install a command package | The first channel for the Unix tool layer on Windows (rg / fd / bat / jq / node …). (skills/wpm.md) |
wpm update winuxcmd | Update the command layer itself | Refreshes the WinuxCmd command set in place and rebuilds command links; distinct from niu --self-update (two update surfaces). (installer.md) |
wpm uninstall <pkg> | Uninstall a command package | Mutating subcommands (install / uninstall / update) have no --json yet: exit codes are the contract; progress text is display only. (index-schema.md) |
wpm links rebuild --force · wpm links list | Repair / inspect command links | If a package is present but hard links are missing (locked after updates, access denied), rebuild first; list supports --json. (installer.md · skills/wpm.md) |
wpm index status · wpm index update | Index status / refresh | status reports the local index version and package count (--json includes root and fallback source). (skills/wpm.md · index-schema.md) |
doctor and diagnostics
Capture the active binary and execution paths first, then run the health check — in the wrong order you end up fixing the wrong install.
| Command | Purpose | Notes (source) |
|---|---|---|
niu doctor | One-shot health check | Covers links, core, rc, bundle and the agent-skill advisory line; migration windows and PATH shadowing get a read-only report too. (skills/wpm.md · CHANGELOG.md) |
niu --version · command -v niubash · command -v winuxcmd.exe | Capture the active binary and execution paths | Step one for "command missing / served by the wrong provider". (advanced-usage.md) |
echo "$SHELL"; uname -a | Confirm the shell an agent actually uses | MSYS_NT-… = niu; MINGW64_NT-… = Git Bash; Linux = you fell into WSL. (agents.md) |
niu -c 'echo command-mode:$SHELL' · niu -C 'echo repl-command:$SHELL' | Verify both one-shot startup surfaces | -c loads nothing; -C matches the REPL — the two channels agent integrations must tell apart. (advanced-usage.md) |