CLI 与旗标参考
niu 命令行面的全量参考：基础调用与全部旗标、WT 集成、自更新、plugin 全部子命令、skill / wpm
与诊断。每行给出命令、作用与备注，备注括注事实来源（niubash 仓文档文件名）；
语义细则与完整手册见页尾外链。
基础调用
三条执行路径刻意分离：交互 REPL、零加载的一次性 -c、与 REPL 同态的
一次性 -C。自动化只走后两条，交互内容留在 rc。
| 命令 | 作用 | 备注（来源） |
|---|---|---|
niubash | 交互 REPL 启动 | 日常 shell；加载 ~/.niubashrc 与交互生命周期钩子。 （advanced-usage.md） |
niu -c '<cmd>' | 一次性执行命令后退出 | 脚本 / 测试 / CI / agent 通道：不加载 rc、插件与交互钩子；需初始化时用 NIU_ENV（或 BASH_ENV）指定一次性 init 文件。 （advanced-usage.md） |
niu -C '<cmd>' · niu --repl-command <cmd> | 一次性 REPL 命令 | 加载与交互 REPL 相同的启动状态（rc + 钩子），执行一条命令后退出。 （advanced-usage.md） |
niu --encoded-command <b64> | 执行 base64 编码的命令 | agent/CI 免引号转义通道；可选 v1: 前缀防 MSYS 路径改写，语义与 -c 完全一致。 （niu --help（src/main.rs）） |
niu --cwd-state <file> [-c ...] | 跨调用目录记忆 | 启动时恢复文件记录的目录、退出时写回最终目录；agent 按工作区各配一个文件即可隔离。 （niu --help（src/main.rs）） |
niu -V · niu --version | 版本与组件信息 | 诊断首查项：先确认活动二进制版本，再排查其余。 （advanced-usage.md） |
niu <script> [args] | 运行脚本文件 | 以文件参数运行脚本并透传参数。 （niu --help 实机（1.4.0）） |
niu setup | 重跑 prompt / 插件设置 | 向导式重配置，可重复执行。 （niu --help 实机（1.4.0）） |
niu font | Nerd Font 检测与安装建议 | 检测字体缺口并给安装推荐。 （niu --help 实机（1.4.0）） |
niu -h · niu --help | 显示帮助 | 即本页主干的来源。 （niu --help 实机（1.4.0）） |
niu --completion-probe <line> [cursor] | 调试：打印补全候选 | 给定输入行（可带光标位），输出补全引擎将产生的候选——写补全插件/排查补全问题时用。 （niu --help 实机（1.4.0）） |
Windows Terminal 集成
profile 与快捷方式两组独立旗标，各带静音开关。
| 命令 | 作用 | 备注（来源） |
|---|---|---|
niu --install-wt-profile | 添加/更新 Windows Terminal 配置档 | 写入 Niubash 的 WT profile。（niu --help 实机（1.4.0）） |
niu --install-wt-profile --set-default | 同时设为 WT 默认 profile | 与上一条同用。（niu --help 实机（1.4.0）） |
niu --install-wt-shortcuts | 重写桌面 / 开始菜单快捷方式 | 检测到 WT 时改写为 wt.exe -p Niubash 形态。（niu --help 实机（1.4.0）） |
niu --install-wt-shortcuts --update-only | 只更新已存在的快捷方式 | 不新建，只改已有文件。（niu --help 实机（1.4.0）） |
--quiet | 抑制非错误输出 | profile 与 shortcuts 两组各自带一个同名静音旗标。（niu --help 实机（1.4.0）） |
自更新
| 命令 | 作用 | 备注（来源） |
|---|---|---|
niu --self-update | 下载并运行最新 release 安装器 | WinHTTP 跟随 GitHub releases/latest。（installer.md · niu --help 实机（1.4.0）） |
niu --self-update --check | 只报告最新版本 | 不执行更新。（niu --help 实机（1.4.0）） |
niu --self-update --dry-run | 只下载安装器不运行 | 验证下载链路用。（niu --help 实机（1.4.0）） |
self-update（REPL 内命令） | 更新 Niubash 并退出当前 shell | 会话内的等价动词。（niu --help 实机（1.4.0）） |
update-niubash | self-update 的别名 | 同义入口。（niu --help 实机（1.4.0）） |
plugin 子命令（全）
外部 bash 生态（oh-my-bash / bash-it / bash-completion 等）的安装、信任与锁定。
| 命令 | 作用 | 备注（来源） |
|---|---|---|
niu plugin add <id|owner/repo|url|path> | 安装外部插件源（不受信） | 支持四种定位形式。（niu --help 实机（1.4.0）） |
niu plugin list [--json] | 列出源、资产与激活状态 | --json 机器可读。（niu --help 实机（1.4.0）） |
niu plugin enable|disable <target> | 激活 / 停用一个源或资产 | 粒度到资产级。（niu --help 实机（1.4.0）） |
niu plugin update · sync · restore · rollback · clean | 锁文件动词族 | vim-plug / lazy.nvim 风格的锁定与恢复语义。（niu --help 实机（1.4.0）） |
niu plugin trust <id> | 审阅并激活某源的资产 | 信任检查层。（niu --help 实机（1.4.0）） |
niu plugin discover [--verbose] | 外部插件源总览（只读） | 不改任何状态。（niu --help 实机（1.4.0）） |
niu plugin source <command> | 源协议全集 | add / trust / sign / verify / remove / update / rollback / list。（niu --help 实机（1.4.0）） |
niu plugin recipe <command> | 配方索引 | list / show / add。（niu --help 实机（1.4.0）） |
niu plugin distro <command> | 集合分发 | list / import / remove / apply。（niu --help 实机（1.4.0）） |
niu plugin mirror <command> | Git 拉取镜像 | list / show / set——国内网络友好。（niu --help 实机（1.4.0）） |
niu plugin ui | 菜单式 UI | 按状态分节，动词与命令行一致。（niu --help 实机（1.4.0）） |
GNU bash 兼容调用面
以下选项在 niu --help 中未列出，但全部支持——rubash
引擎与 GNU Bash 5.3 语义对齐，GNU 的调用面照用：
| 面 | 内容 | 说明 |
|---|---|---|
GNU 长选项 | --debug --debugger --dump-po-strings --dump-strings --help --init-file --login --noediting --noprofile --norc --posix --pretty-print --rcfile --restricted --verbose --version | 与 bash --help 所列 16 个长选项一一对应。 |
调用组合（仅启动时） | -i -l -r -s -D · -c command · -O shopt_option | 交互 / 登录 / 受限 / 从 stdin 读 / 逐条回显 / 指定 shopt。 |
set 选项面 | -abefhkmnptuvxBCEHPT · -o option | 与 GNU 相同的 set 单字母集与 -o 名录（niu -c 'help set' 可查全表）。 |
内建帮助 | niu -c 'help set' · niu -c help | set 选项说明与内建命令清单，GNU 同款入口。 |
rc 指定 | --rcfile / --init-file | 指定替代启动文件。 |
来源：bash --help 对照（同机 GNU Bash 5.3.0 输出）；兼容性以 83/83 套件台账为准。
配置与环境变量
| 项 | 作用 | 备注（来源） |
|---|---|---|
~/.niubashrc | 交互启动配置文件 | 纯 bash 语法；交互 REPL 与 -C 加载，-c 不加载。（niu --help 实机（1.4.0）） |
NIU_ENV=<file> | 非交互一次性 init 文件 | -c / 脚本 / stdin 启动前 source；优先于 BASH_ENV；默认不设，保持 -c 快。（niu --help 实机（1.4.0）） |
BASH_ENV=<file> | GNU bash 兼容的同义变量 | 语义相同，优先级低于 NIU_ENV。（niu --help 实机（1.4.0）） |
NIU_LANG=<zh|en> | 设置向导语言 | 回落顺序：Windows UI 语言 → LC_ALL / LANG。（niu --help 实机（1.4.0）） |
skill 子命令
AI agent skill bundle（能力面 + 方言契约）的安装与检查。--target
的全部取值：claude（默认）、zcode、cursor、
all 与任意目录。
| 命令 | 作用 | 备注（来源） |
|---|---|---|
niu skill install | 安装 AI agent skill bundle | 默认装入 ~/.claude/skills/niubash/（SKILL.md + references/）。 （advanced-usage.md） |
niu skill install --target claude | 只装到 Claude | 等价默认目标；字节级落盘。 （advanced-usage.md） |
niu skill install --target zcode | 装到 ZCode | 写入 ZCode 的 skills 目录。 （niu --help（src/main.rs）） |
niu skill install --target cursor | 装到 Cursor | 写入 Cursor 的 skills 目录。 （niu --help（src/main.rs）） |
niu skill install --target all | claude + zcode + cursor 三处安装 | 一次覆盖三个 agent 宿主。 （advanced-usage.md） |
niu skill install --target C:/agents/skills | 装入任意目录（通用形态） | 落地为 <dir>/niubash/，供任意 agent 宿主自取。 （advanced-usage.md） |
niu skill status | 逐目标检查 bundle 状态 | current / outdated 判定 = 字节比较 + sha256；niu doctor 会带一条建议行。 （advanced-usage.md） |
plugin 子命令
外部 bash 生态（oh-my-bash、bash-it、任意 git 源）的安装、信任与激活—— 一律「先装、后审、再信」，声明式 spec 是唯一事实源。
| 命令 | 作用 | 备注（来源） |
|---|---|---|
niu plugin add <id|owner/repo|url|path> | 安装外部插件源 | 克隆到 ~/.niubash/sources/<id> 并登记 registry；新源默认不受信，add 后不会执行任何内容。 （getting-started.md） |
niu plugin trust <id> | 审阅通过执行门 | review 校验和后放行；enable 在 trust 之前会被拒绝。 （getting-started.md） |
niu plugin enable <target> · disable <target> | 激活 / 停用源或主题资产 | 在 ~/.niubashrc 尾部维护 # >>> niu source <id> 托管块；块外内容永不改写。disable 后内置提示符（floor）回归。 （getting-started.md） |
niu plugin sync [--prune | --adopt] | 对账 spec 与安装现状 | lockfile 式维护动词族：update / sync / restore / rollback / clean 同族；--adopt 把已装源声明进 spec。 （advanced-usage.md） |
niu plugin mirror <command> | Git fetch 镜像控制 | list / show / set <url|none>：可配置的 insteadOf 镜像，仅作用于 git 传输层。 （niu --help（src/main.rs）） |
niu plugin list [--json] | 源、资产与激活状态清单 | --json 供 agent 消费（同理 recipe list --json）；另配 discover 只读总览。 （advanced-usage.md） |
wpm 速查
Winux 包管理器：Unix 命令层（ls、grep、rg …）
在 Windows 上的第一通道。查询类子命令支持 --json（带
schema 版本字段），变更类以退出码为准。
| 命令 | 作用 | 备注（来源） |
|---|---|---|
wpm list [--json] · wpm installed | 包目录与本机安装状态 | --json 输出带 schema:1 版本化的纯 JSON；installed 只列本 root 已装包。 （installer.md · index-schema.md） |
wpm search <q> · wpm info <pkg> [--json] | 查包 / 看包详情 | 索引过旧时先 wpm index update；info --json 返回完整 Package 记录。 （skills/wpm.md · index-schema.md） |
wpm install <pkg> | 安装命令包 | Windows 上 Unix 工具层的第一通道（rg / fd / bat / jq / node …）。 （skills/wpm.md） |
wpm update winuxcmd | 更新命令层本体 | WinuxCmd 命令集就地刷新，命令链接自动重建；与 niu --self-update 是两个更新面。 （installer.md） |
wpm uninstall <pkg> | 卸载命令包 | 变更类子命令（install / uninstall / update）暂无 --json：以退出码为准，进度文本仅作展示。 （index-schema.md） |
wpm links rebuild --force · wpm links list | 修复 / 查看命令链接 | 包在而硬链接缺失（更新后锁文件、拒绝访问）时先 rebuild；list 可 --json。 （installer.md · skills/wpm.md） |
wpm index status · wpm index update | 索引状态 / 刷新 | status 报告本地索引版本与包数（--json 含 root、fallback 来源）。 （skills/wpm.md · index-schema.md） |
doctor 与诊断
先捕获活动二进制与执行路径，再跑健康检查——顺序反了会在错误的安装上修问题。
| 命令 | 作用 | 备注（来源） |
|---|---|---|
niu doctor | 一键健康检查 | 覆盖 links、core、rc、bundle 与 agent skill 建议行；迁移窗口与 PATH 遮蔽也会给只读报告。 （skills/wpm.md · CHANGELOG.md） |
niu --version · command -v niubash · command -v winuxcmd.exe | 捕获活动二进制与执行路径 | 排查「命令缺失 / 来自错误 provider」的第一步。 （advanced-usage.md） |
echo "$SHELL"; uname -a | 确认 agent 实际用的 shell | MSYS_NT-… = niu；MINGW64_NT-… = Git Bash；Linux = 落进了 WSL。 （agents.md） |
niu -c 'echo command-mode:$SHELL' · niu -C 'echo repl-command:$SHELL' | 验证两种一次性模式的启动面 | -c 零加载、-C 与 REPL 同态——正是 agent 接入要区分的两个通道。 （advanced-usage.md） |