ziniao-cli

紫鸟开放平台命令行工具，为开发者和 AI Agent 提供统一的接口调用入口。

支持服务端 OpenAPI 和本地浏览器 Bridge（ZClaw）两套接口体系，使用统一的 apiKey 认证。

安装

npm install -g @ziniao-open/cli

紫鸟客户端自带的 ziniao CLI 需要同步到 AppCache 并加入 PATH。执行 npm install -g @ziniao-open/cli 时会自动尝试同步；安装紫鸟客户端后，也可以手动执行以下命令：

source "$(npm root -g)/@ziniao-open/cli/scripts/setup-ziniao-cli.sh"

Windows PowerShell 执行：

. "$(npm root -g)\@ziniao-open\cli\scripts\setup-ziniao-cli.ps1"

也可以在安装后手动修复：

ziniao-cli doctor fix-path

遍历当前 PATH 清理旧的 ziniao shim，并清理 Unix 端的 ziniaobrowser/cli 缓存目录（默认只预览）：

& "$(npm root -g)\@ziniao-open\cli\scripts\remove-ziniao-cli-shims.ps1"
& "$(npm root -g)\@ziniao-open\cli\scripts\remove-ziniao-cli-shims.ps1" -Apply

macOS/Linux：

"$(npm root -g)/@ziniao-open/cli/scripts/remove-ziniao-cli-shims.sh"
"$(npm root -g)/@ziniao-open/cli/scripts/remove-ziniao-cli-shims.sh" --apply

脚本只探测 ziniao.app / ziniao 的安装目录；Windows 会优先查询卸载注册表中 DisplayIcon 包含 ziniao.exe 的条目，再从本体目录的 resources/app.asar.unpacked/envkit/cli 查找 CLI。Windows 使用 %APPDATA%\ziniaobrowser\cli，macOS 使用 ~/Library/Application Support/ziniaobrowser/cli，Linux 使用 ${XDG_CONFIG_HOME:-~/.config}/ziniaobrowser/cli，在目标目录缺少 CLI 或文件内容发生变化时同步最新文件，并注册当前用户 PATH。找不到源文件时只提示并继续，不阻断 PATH 配置。若安装目录无法自动探测，可设置 ZINIAO_INSTALL_DIR；若目标位置不同，可设置 ZINIAO_APP_CACHE_DIR。 Windows 同时会把找到的紫鸟本体绝对路径写入 %APPDATA%\ziniaobrowser\gui-path，供 CLI 定位桌面客户端。 macOS/Linux 也会在找到桌面本体时写入对应的 gui-path（macOS 为 ~/Library/Application Support/ziniaobrowser/gui-path，Linux 为 ${XDG_CONFIG_HOME:-~/.config}/ziniaobrowser/gui-path）。 macOS/Linux 还会在 ~/.local/bin/ziniao 创建固定 shim，避免向随机 PATH 目录写入文件。

安装时会自动下载当前平台对应的预编译二进制（支持 macOS / Linux / Windows × amd64 / arm64），并做 SHA-256 校验。

快速开始

# 1. 初始化配置（首次使用必做，会引导你写入 apiKey）
ziniao-cli config init

# 2. 通用 API 调用（覆盖紫鸟开放平台全部接口）
ziniao-cli api /superbrowser/rest/v1/erp/department/list

# 3. 快捷命令（高频操作的封装）
ziniao-cli staff list --format table
ziniao-cli store list
ziniao-cli department list

# 4. 环境自检
ziniao-cli doctor

# 5. 查看所有命令
ziniao-cli --help

命令概览

| 类别 | 命令 | 说明 | |------|------|------| | 基础 | config | apiKey 等配置初始化与查看 | | 基础 | doctor | 环境自检（认证、网络、ZClaw 桥可用性） | | 基础 | completion | 生成 shell 自动补全 | | 通用 | api <path> | 调用任意紫鸟 OpenAPI 路径 | | 桥接 | zclaw | 本地浏览器 Bridge（页面操作、店铺管理等） | | 快捷 | staff / store / account / department / role / device / page / automation | 高频业务操作的封装 |

完整列表见 ziniao-cli --help。

本地 dev/prod 打包与切换

在仓库根目录执行以下命令，可分别生成本地测试环境包和本地正式环境包：

make package-dev
make package-prod

两个命令都会生成本地多平台 snapshot 包。版本基于最近的发布 tag，并使用本机递增计数器：最近 tag 为 v1.0.7 时，依次生成 1.0.7-dev-1、1.0.7-dev-2、1.0.7-dev-3。

计数器保存在 ~/.ziniao-cli/dev-build-counter；当最近 tag 变化时计数从 1 重新开始。可通过 ZINIAO_CLI_DEV_COUNTER_FILE 指定其他计数器路径，便于 CI 或测试隔离。产物写入 dist/，该命令只打包，不发布。

package-dev 内置测试环境 https://test-sbappstoreapi.ziniao.com 与 https://test-open.ziniao.com，默认使用独立配置目录 ~/.ziniao-cli-dev/，本地二进制写入 ~/.ziniao-cli-dev/bin/ziniao-cli。

package-prod 内置正式环境 https://sbappstoreapi.ziniao.com 与 https://open.ziniao.com，默认使用独立配置目录 ~/.ziniao-cli-prod/，本地二进制写入 ~/.ziniao-cli-prod/bin/ziniao-cli。

仓库内的 scripts/ziniao-cli-use 提供统一切换入口；如果你已将该脚本加入 PATH，可直接执行：

ziniao-cli-use dev
ziniao-cli-use prod
ziniao-cli-use online

• ziniao-cli-use dev：切换到 ~/.ziniao-cli-dev/bin/ziniao-cli
• ziniao-cli-use prod：切换到 ~/.ziniao-cli-prod/bin/ziniao-cli
• ziniao-cli-use online：切换回 npm 安装的线上版 ziniao-cli，继续使用默认线上配置目录 ~/.ziniao-cli/

make package-dev 与 make package-prod 只会更新各自隔离的本地输出路径，不会改写仓库根目录的 ./ziniao-cli。如果你需要仓库根目录的开发测试二进制，继续使用 make build。

dev、本地 prod、online 三套 CLI 默认分别使用 ~/.ziniao-cli-dev/、~/.ziniao-cli-prod/、~/.ziniao-cli/，API Key 和配置互不读取。首次运行某个本地环境前，执行 ziniao-cli config init 即可在对应目录完成初始化。

AI Agent Skills

仓库提供 12 个开箱即用的 AI Agent Skill：访问策略、账号、部门、设备、OpenAPI 探索、页面、角色、共享基础、Skill 创建、员工、店铺和批量账号授权。

安装 Skill：

ziniao-cli skills install

备选：npx skills add ziniao-open/skills -y -g

详见 ziniao-skills。