Ziniao CLI Shared Rules

This guide instructs you on how to operate Ziniao Open Platform resources and control Ziniao Browser via ziniao-cli, along with key considerations.

Configuration Initialization

Run

ziniao-cli config init

to complete application configuration on first use.

Initialization Modes

Command	Scenario	Behavior
`ziniao-cli config init --new`	AI Agent (Recommended)	Directly enter the new application creation process, output the browser link and then poll for completion
`ziniao-cli config init`	Human User Interaction	Menu options: [1] Create new application [2] Manually input Key
`ziniao-cli config init --api-key-stdin`	CI/CD Pipeline	Read existing API Key from stdin

AI Agent Initialization Flow

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

bash

# Directly enter the new application creation process (this command blocks until approval, rejection, or 1-hour timeout)
ziniao-cli config init --new

Output Example (Boss Account):

Please open the following link in your browser to complete application creation:

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

⏳ Waiting for application creation and approval... (Press Ctrl+C to cancel)
⏳ Waiting... Waited 30s
✓ Approved
⏳ Fetching enterprise information...
✓ Enterprise ID: 15393571083459
✓ Configuration saved

Output Example (Member Account):

...
✓ Approved
✓ Member account, skipping enterprise information fetch
✓ Configuration saved

The Agent should:

Execute
```
config init --new
```
in background
Extract the URL from the output (the line containing
```
memberAuth?cliRequestId=
```
)
Display the link to the user and prompt them to open it in the browser to complete application creation
Wait for the command to complete (approval/rejection/timeout)
If 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 located at

~/.ziniao-cli/config.json

Boss vs Member Accounts

The server returns an

isBoss

flag during initialization, which determines the account's permission scope:

Account Type	Server API	ZClaw Bridge (Local Browser)
Boss	✓ Fully available	✓ Fully available
Member	✗ Unavailable (returns auth error)	✓ Fully available

Member accounts do not store companyId. All requests via

api

commands or server shortcut commands (account/staff/department/role/device) will be intercepted and prompt "Boss permission required".

Check Configuration

bash

ziniao-cli config show   # View current configuration
ziniao-cli doctor         # Comprehensive self-check (configuration + apiKey + network + ZClaw Bridge)

Delete Configuration

bash

ziniao-cli config remove  # Delete configuration file and all Keychain credentials

Authentication

Authentication Model

ziniao-cli uses a unified apiKey (Bearer Token), which is used for both:

Purpose	Address	Description
Server API	`sbappstoreapi.ziniao.com`	Business interfaces for departments/staff/accounts/devices, etc.
Local ZClaw Bridge	`127.0.0.1:9481`	Ziniao Browser store/page control

There is no complex mechanism like OAuth, token refresh, or dual identities (user/bot). The apiKey is a static credential that does not expire.

ISV Application Permission Points

Before calling server APIs, you need to activate the corresponding permission points for the application on the Ziniao Open Platform. Below are the permission points required for each module:

Module	Permission Point	Covered Interfaces
Department & Staff	ERP-Department and Staff Interface	Department CRUD + Staff query/add/edit/enable/disable (9 interfaces)
Department & Staff	ERP-User Department Change	Staff transfer (1 interface)
Role & Permission	ERP-Role List Query	Role list + User role list (2 interfaces)
Role & Permission	ERP-Role Details	Role details (1 interface)
Role & Permission	ERP-Permission List	Permission item list (1 interface)
Role & Permission	ERP-Role Add, Modify Permission	Add/modify/adjust roles (3 interfaces)
Device Management	ERP-Device Query	Device list + Historical binding records (2 interfaces)
Device Management	ERP-Device Package List Query Permission	Package list (1 interface)
Device Management	ERP-Device Binding Permission	Bind device (1 interface)
Device Management	ERP-Device Unbinding	Unbind device (1 interface)
Device Management	ERP-Auto-renewal Toggle	Auto-renewal switch (1 interface)
Device Management	ERP-Device Purchase and Renewal Permission	Purchase + Renewal (2 interfaces)
Device Management	ERP-Add Own Device (New)	Add own device (1 interface)
Device Management	ERP-Modify Own Device Information (New)	Modify own device (1 interface)
Device Management	ERP-Query Purchased Device Price Interface	Purchased device price (1 interface)
Account Management	ERP-Account View Permission	Account list/authorization query/user account list/authorized user list (4 interfaces)
Account Management	ERP-Account Create and Delete Permission	Create + Delete account (2 interfaces)
Account Management	ERP-Edit Account Basic Information	Edit account information (1 interface)
Account Management	ERP-Account Authorization Permission	Authorization add + Authorization delete (2 interfaces)
Account Management	ERP-Clear Account Authorization	Clear all authorizations (1 interface)
Account Management	ERP-Clear Account Cache	Clear cache (1 interface)
Account Management	ERP-Tag List	Enterprise tag list (1 interface)
Account Management	ERP-Query Account List Accessible to a User	Accounts accessible to the user (1 interface)
Account Management	ERP-Get Additional Website Information	Additional website information (1 interface)
Account Management	Account Tag Management Permission	Tag CRUD + Bind/unbind/replace/clear/remove (9 interfaces)
Access Policy	ERP-Webpage Access Permission	All operations for access rules/webpages/webpage groups (22 interfaces)

If an interface call returns
isv.invalid-method
(non-existent method name), it usually means the corresponding permission point is not activated. Go to Ziniao Open Platform → Application Management → Permission Management to activate it.

Public Parameters

Each server API request requires

companyId

, which is automatically injected and enforced by the CLI using the configured value. There is no need to pass it manually. This value is automatically obtained via the

/app/builtin/company

interface during

config init

and written to the configuration; even if

companyId

is explicitly passed in

--data

, the CLI will overwrite it with the configured value.

Two-layer Command System

Layer 1: General api Command (Covers All 73 Interfaces)

Any Ziniao server API can be called via the

api

command without needing a dedicated shortcut command:

bash

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 method is POST, supports GET/POST/PUT/DELETE
```
companyId
```
is automatically injected by the framework and will overwrite the same field in
```
--data
```
```
--page-all
```
automatically paginates (max 10 pages by default, use
```
--page-limit 0
```
to fetch all)
```
--page-size N
```
Number of items per page (default 20)
```
--page-limit N
```
Maximum number of pages to paginate (default 10, 0 for unlimited, used with
```
--page-all
```
)
```
--page-delay MS
```
Delay between pages in milliseconds (default 200, used with
```
--page-all
```
)
```
--dry-run
```
Preview request without execution
```
--jq
```
Built-in jq filtering

Layer 2: Shortcut Commands (Optimized for High-frequency Scenarios)

Provides named flags + intelligent default values for complex interfaces:

bash

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

Differences Between

account

and

store

Both sets of commands involve "stores", but their responsibilities and channels are completely different:

	`account` Command	`store` Command
Channel	Server API ( `sbappstoreapi.ziniao.com` )	Local ZClaw Bridge ( `127.0.0.1:9481` )
Responsibility	CRUD, authorization, tagging, and other management operations for store accounts	Control open browser instances: list, open, close
Precondition	Only apiKey + network required	Ziniao Browser client must be running
Typical Scenario	Create stores, batch authorize staff, manage tags	Open store browser → Navigate → Screenshot → Automated operations

Simple mnemonic:

account

= CRUD in management backend,

store

= Control local browser windows.

Command Priority

When called by an AI Agent, commands are selected in the following priority:

Shortcut Commands --
```
staff list
```
,
```
department create
```
,
```
store open
```
, etc. (simplified parameters, best experience)
General api Command --
```
api <path>
```
as fallback (can call any interface, requires writing JSON body)
zclaw invoke --
```
zclaw invoke <tool>
```
as fallback (can call any ZClaw tool)

Output Format

All commands support

--format json|table|csv

and

--jq

filtering:

bash

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

Output Structure

Success (stdout):

json

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

Failure (stderr):

json

{"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 user to run `ziniao-cli config init`
`gateway`	Gateway layer error (code != "0")	Report error, check network/apiKey
`business`	Business layer error (ret != 0)	Report error message, determine cause based on msg
`validation`	Parameter validation failed	Check if command parameters are correct
`network`	Network unreachable/Bridge not running	For ZClaw-related issues: Prompt to start Ziniao Browser; For API-related issues: Check network

Update Check

After executing a ziniao-cli command, if a new version is detected, the JSON output will include the

_notice.update

field:

json

{
  "ok": true,
  "data": ...,
  "_notice": {
    "update": {
      "current": "1.0.0",
      "latest": "1.1.0",
      "message": "ziniao-cli 1.1.0 is available, current version is 1.0.0, run npm update -g @ziniao-open/cli to update"
    }
  }
}

When you see
_notice.update
in the output:

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

Update prompts are only delivered via the

_notice

field in stdout JSON and will not be output to stderr. You can disable the check 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

are automatically converted to Windows local paths by MSYS (e.g.,

/superbrowser/...

→

C:/Program Files/Git/superbrowser/...

), which corrupts the path parameter of the

api

command.

PowerShell and CMD have no such issue.

Solution 1 (Recommended: Permanent effect by writing to
.bashrc
)

bash

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

Solution 2: Add prefix before each command

bash

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

Security Rules

Prohibited to output full apiKey in plain text to the terminal
Must confirm user intent before write/delete operations
```
high-risk-write
```
operations (department delete, staff remove) require interactive confirmation, which can be skipped with
```
--yes
```
It is recommended to preview dangerous requests with
```
--dry-run
```
first

Important Behavior Rules

ZClaw local interfaces must be called via ziniao-cli: When calling Ziniao Browser local interfaces (store/page/zclaw commands), you must use the ziniao-cli capabilities in this skill system; do not call ZClaw Bridge directly using the ziniao-assistant skill.
Prioritize local interfaces for store lists: If the user requests to get a store list, prefer using the
```
store list
```
shortcut command (via local ZClaw Bridge), since regular members do not have permission for the server
```
account list
```
interface. The member type can be determined via the
```
isBoss
```
field in the result of
```
ziniao-cli config show
```
.
Troubleshooting ZClaw authentication failures: If after helping the user initialize the application (
```
config init
```
), requests to ZClaw interfaces still return API Key authentication failures, remind the user to go to the Ziniao Open Platform https://open.ziniao.com, check their user application's "Terminal Management" to see if the current terminal identification code (viewable in Ziniao Browser settings) has been bound.

ziniao-shared

NPX Install

Tags

SKILL.md Content (Chinese)

Ziniao CLI Shared Rules

Configuration Initialization

Initialization Modes

AI Agent Initialization Flow

Boss vs Member Accounts

Check Configuration

Delete Configuration

Authentication

Authentication Model

ISV Application Permission Points

Public Parameters

Two-layer Command System

Layer 1: General api Command (Covers All 73 Interfaces)

Layer 2: Shortcut Commands (Optimized for High-frequency Scenarios)

Differences Between
`account`
and
`store`

Command Priority

Output Format

Output Structure

Error Types and Handling

Update Check

Environment Compatibility Notes

Windows Git Bash Path Escaping Issue

Security Rules

Important Behavior Rules