SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsziniao-shared

ziniao-shared

Deployment & operations

View repository

Updated 10-16 10:45

About this skill

ziniao-cli shared rules

This skill guides you on how to operate Ziniao Open Platform resources and control the Ziniao browser through ziniao-cli, as well as what precautions to take.

Configuration initialization

First-time use requires running ziniao-cli config init to complete application configuration.

Initialization mode

Command Scenario Behavior
ziniao-cli config init --new AI Agent (recommended) Directly enters the new application creation flow, outputs a browser link, then polls and waits
ziniao-cli config init Human user interaction Menu selection: [1] Create new application [2] Manually enter Key
ziniao-cli config init --api-key-stdin CI/CD pipeline Reads an existing API Key from stdin

AI Agent initialization flow

Use background mode to execute the following command, read the stderr output after startup, extract the browser link from it, and display it to the user:

# 直接进入新建应用流程（该命令会阻塞直到审核通过、被拒绝或超时 1 小时）
ziniao-cli config init --new

Output example (Boss account):

请在浏览器中打开以下链接完成应用创建:

  https://open.ziniao.com/memberAuth?cliRequestId=a1b2c3d4-...&from=cli

⏳ 等待应用创建及审核... (按 Ctrl+C 取消)
⏳ 等待中... 已等待 30s
✓ 审核已通过
⏳ 正在获取企业信息...
✓ 企业 ID: 15393571083459
✓ 配置已保存

Output example (member account):

...
✓ 审核已通过
✓ 成员账号，跳过企业信息获取
✓ 配置已保存

The Agent should:

  1. Execute in the background config init --new
  2. Extract the URL from the output (the line containing memberAuth?cliRequestId= )
  3. Display the link to the user and prompt them to open it in a browser to complete application creation
  4. Wait for the command to complete (approved/rejected/timed out)
  5. If the review is rejected, inform the user to contact the Boss for approval

All credentials (apiKey, companyId) are stored in the system Keychain, and the configuration file is in ~/.ziniao-cli/config.json。

Boss and member accounts

During initialization, the server returns isBoss , which determines the account permission scope:

Account type Server API ZClaw Bridge (local browser)
Boss ✓ All available ✓ All available
Member ✗ Unavailable (returns auth error) ✓ All available

Member accounts do not store companyId, and all requests via api commands or server-side shortcut commands (account/staff/department/role/device) will be intercepted and prompted with "Boss permission required".

Check configuration

ziniao-cli config show   # 查看当前配置
ziniao-cli doctor         # 全面自检（配置 + apiKey + 网络 + ZClaw Bridge）

Delete configuration

ziniao-cli config remove  # 删除配置文件和所有 Keychain 凭证

Authentication

Authentication model

ziniao-cli usesunified apiKey(Bearer Token), one Key is used for both:

Purpose Address Description
Server API sbappstoreapi.ziniao.com Business interfaces such as department/staff/account/device
Local ZClaw Bridge 127.0.0.1:9481 Ziniao browser store/page control

No complex mechanisms such as OAuth, token refresh, or dual identity (user/bot). apiKey is a static credential and does not expire.

ISV application permission points

Before calling server-side APIs, the corresponding permission points must be enabled for the application on the Ziniao Open Platform. The following are the permission points required for each module:

Module Permission point Covered interfaces
Department staff ERP-Department and Employee APIs Department CRUD + Employee query/add/modify/enable-disable (9)
Department Employees ERP-User department change Employee transfer (1)
Role Permissions ERP-Role list query Role list + User role list (2)
Role Permissions ERP-Role details Role details (1)
Role Permissions ERP-Permission list Permission item list (1)
Role Permissions ERP-Role add, modify permissions Add/modify/adjust role (3)
Device Management ERP-Device query Device list + Historical binding records (2)
Device Management ERP-Device plan list query permission Plan list (1)
Device Management ERP-Device binding permission Bind device (1)
Device Management ERP-Unbind device Unbind device (1)
Device Management ERP-Auto-renewal toggle Auto-renewal toggle (1)
Device Management ERP-Device purchase and renewal permission Purchase + Renewal (2)
Device Management ERP-Add own device (New) Add own device (1)
Device Management ERP-Modify own device information (New) Modify own device (1)
Device Management ERP-Purchased device price query API Purchased device price (1)
Account Management ERP-Account view permission Account list/Authorization query/User account list/Authorized user list (4)
Account Management ERP-Create and delete account permission Create + Delete account (2)
Account Management ERP-Edit account basic information Edit account information (1)
Account Management ERP-Account authorization permission Add authorization + Remove authorization (2)
Account Management ERP-Clear account authorization Clear all authorizations (1)
Account Management ERP-Clear account cache Clear cache (1)
Account Management ERP-Tag list Enterprise tag list (1)
Account Management ERP-Query the list of accounts a user has permission for Accounts a user has permission for (1)
Account Management ERP-Get additional website information Additional website information (1)
Account Management Account tag management permission Tag CRUD + bind/unbind/replace/clear/remove (9)
Access Policy ERP-Web Access Permissions All operations for access rules/webpages/webpage groups (22)

If the API call returns isv.invalid-method(nonexistent method name), it usually means that permission point has not been enabled. Go to Ziniao Open Platform → App Management → Permission Management to enable it.

Common Parameters

Every server-side API request requires companyId，The CLI automatically injects it and forcibly uses the configured value, and it does not need to and should not be passed manually. This value is passed during config init through the /app/builtin/company API is automatically obtained and written to the configuration; even if --data explicitly passes companyId, the CLI will override it with the configured value.

Two-Layer Command System

First layer: generic api command (covers all 73 APIs)

Any Ziniao server-side API can be called through the api command, without needing a dedicated shortcut command:

ziniao-cli api <path> [--data '{}'] [--format table] [--jq '.data[]']
ziniao-cli api GET /app/builtin/company
ziniao-cli api /superbrowser/rest/v1/erp/department/list
ziniao-cli api /superbrowser/rest/v1/erp/staff/list --data '{"page":1,"limit":10}' --format table
  • Default POST method, supports GET/POST/PUT/DELETE
  • companyId Automatically injected by the framework, and forcibly overrides the same-named field in --data field with the same name in
  • --page-all Automatic pagination (10 pages max by default; to fetch all, use it together with --page-limit 0）
  • --page-size N Number of items per page (default 20)
  • --page-limit N Maximum number of pages (default 10, 0 means unlimited, used together with --page-all）
  • --page-delay MS Pagination interval in milliseconds (default 200, used together with --page-all）
  • --dry-run Preview request without executing
  • --jq Built-in jq filtering

Second layer: shortcut commands (optimized for high-frequency scenarios)

Provide named flags + smart defaults for complex APIs:

ziniao-cli department list --tree
ziniao-cli staff create --username "zhangsan" --name "张三" --password "Pass123!" --role-id 16691047257645
ziniao-cli store list --format table

account and store difference

Both command groups involve "shops", but their responsibilities and channels are completely different:

account command store command
Channel Server-side API (sbappstoreapi.ziniao.com） Local ZClaw Bridge (127.0.0.1:9481）
Responsibility Shop account CRUD, authorization, tags, etc.Management operations Control already-open browser instances: list, open, close
Prerequisite Only needs apiKey + network The Ziniao browser client must already be started
Typical scenarios Create shops, batch-authorize employees, manage tags Open shop browser → navigate → screenshot → automated operations

Simple mnemonic: account = admin backend CRUD,store = control the local browser window.

Command Priority

AI Agents select by priority when calling:

  1. Shortcut commands -- staff list、department create、store open etc. (simplified parameters, best experience)
  2. Generic api command -- api <path> Fallback (any API can be called, but the JSON body must be written manually)
  3. zclaw invoke -- zclaw invoke <tool> Fallback (any ZClaw tool can be called)

Output Format

All commands support --format json|table|csv and --jq filtering:

ziniao-cli staff list --format table
ziniao-cli staff list --jq '.[].name'
ziniao-cli department list --format csv

Output Structure

Success (stdout):

{"ok": true, "data": ..., "meta": {"count": 10}}

Failure (stderr):

{"ok": false, "error": {"type": "gateway|business|auth|validation", "code": 1001, "message": "...", "hint": "..."}}

Error Types and Handling

Error Type Meaning What the AI Agent should do
auth apiKey missing or invalid Prompt the user to run ziniao-cli config init
gateway Gateway layer error (code != "0") Report the error, check the network/apiKey
business Business layer error (ret != 0) Report the error message and determine the cause based on msg
validation Parameter validation failed Check whether the command parameters are correct
network Network unreachable/Bridge not started ZClaw-related: prompt to start the ZiNiao browser; API-related: check the network

Update check

After the ziniao-cli command is executed, if a new version is detected, the JSON output will contain the _notice.update field:

{
  "ok": true,
  "data": ...,
  "_notice": {
    "update": {
      "current": "1.0.0",
      "latest": "1.1.0",
      "message": "ziniao-cli 1.1.0 可用，当前 1.0.0，运行 npm update -g @ziniao-open/cli 更新"
    }
  }
}

When you see _notice.update in the output:

  1. First complete the user's current request
  2. Then display the content of the message field to the user and offer to help them update
  3. If the user agrees, execute npm update -g @ziniao-open/cli

Update prompts are only passed through the _notice field of the stdout JSON and will not be output to stderr. The check can be disabled via the environment variable ZINIAO_CLI_NO_UPDATE_CHECK=1 .

Environment compatibility notes

Windows Git Bash path escaping issue

In Git Bash , strings starting with / will be automatically converted by MSYS to Windows local paths (such as /superbrowser/... → C:/Program Files/Git/superbrowser/...), causing the path parameters of the api command to be corrupted.

PowerShell and CMD do not have this issue.

Solution 1 (recommended): write to .bashrc to take effect permanently

echo 'export MSYS_NO_PATHCONV=1' >> ~/.bashrc
source ~/.bashrc

Solution 2: add a prefix before each command

MSYS_NO_PATHCONV=1 ziniao-cli api /superbrowser/rest/v1/erp/store/create \
  --data '{"storeData":[{"name":"新店铺"}]}'

Security rules

  • Do not output the complete apiKey to the terminal in plaintext
  • User intent must be confirmed before write/delete operations
  • high-risk-write operations (department delete, staff remove) will require interactive confirmation and can be skipped with --yes Skip
  • It is recommended to first use --dry-run to preview dangerous requests

Important behavior rules

  • ZClaw local interfaces must be called through ziniao-cli: when calling ZiNiao browser local interfaces (store/page/zclaw commands), you must use the ziniao-cli capability in this skill system. Do not use the ziniao-assistant skill to call the ZClaw Bridge yourself.
  • Prefer local interfaces for store lists: if the user asks to get the store list, you should preferentially use the store list shortcut command (which goes through the local ZClaw Bridge), because ordinary members do not have the server-side account list interface permission. The member type can be determined by the ziniao-cli config show field in the isBoss result.
  • Troubleshooting ZClaw authentication failure: if, after helping the user initialize the application (config init), requests to the ZClaw interface still return an API Key authentication failure, you should remind the user to go to the ZiNiao Open Platform https://open.ziniao.com to check whether "Terminal Management" in their user application has been bound to the current terminal identification code (the identification code can be viewed in the ZiNiao browser settings).