ziniao-shared

ziniao-cli Shared Rules

This skill guides you on how to use ziniao-cli to operate Ziniao Open Platform resources and control Ziniao Browser, along with important considerations.

Configuration Initialization

On first use, run ziniao-cli config init to complete app configuration.

Initialization Modes

Command	Scenario	Behavior
ziniao-cli config init --new	AI Agent (recommended)	Directly enters the new app creation flow, outputs a browser link, then polls and waits
ziniao-cli config init	Human user interaction	Menu selection: [1] Create new app [2] Manually enter Key
ziniao-cli config init --api-key-stdin	CI/CD pipeline	Reads an existing API Key from stdin
ziniao-cli config init --api-key-stdin --member	Member account CI	Skips enterprise info retrieval, only for controlling the browser
ziniao-cli config init --profile <name>	Multiple accounts	Specifies a profile name (auto-named if not provided)

AI Agent Initialization Flow

Execute the following command in the background, then read stderr output to extract the browser link and show it to the user:

# Directly enters the new app creation flow (blocks until approval, rejection, or 1-hour timeout)
ziniao-cli config init --new

Example output (Boss account):

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

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

⏳ Waiting for app creation and approval... (Press Ctrl+C to cancel)
⏳ Waiting... 30s elapsed
✓ Approval passed
⏳ Fetching enterprise info...
✓ Enterprise ID: 15393571083459
✓ Configuration saved

Example output (member account):

...
✓ Approval passed
✓ Member account, skipping enterprise info retrieval
✓ Configuration saved

The agent should:

1. Run config init --new in the background
2. Extract the URL from the output (line containing memberAuth?cliRequestId=)
3. Show the link to the user, prompting them to open it in a browser to complete app creation
4. Wait for the command to finish (approval/rejection/timeout)
5. If approval is rejected, inform the user to contact the Boss for approval

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

Boss vs. Member Accounts

During initialization, the server returns an isBoss flag that determines the account's 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; all requests via the api command or server-side shortcut commands (account/staff/department/role/device) are intercepted and prompt "Boss permission required".

Checking Configuration

ziniao-cli config show   # View current config (including profile name)
ziniao-cli config list   # List all profiles
ziniao-cli doctor         # Comprehensive self-check (config + apiKey + network + ZClaw Bridge)

Switching Between Multiple Accounts

Multiple account configurations (profiles) are supported; switch via config use:

# List all profiles
ziniao-cli config list
# * zhangsan
#   staging

# Switch to a specific profile
ziniao-cli config use staging

# Rename a profile
ziniao-cli config rename staging production

During initialization, specify a name with --profile; the browser creation flow auto-names using the account username.

Deleting Configuration

Deletion prompts for confirmation; --yes skips it:

ziniao-cli config remove              # Delete current profile (requires confirmation)
ziniao-cli config remove --profile staging  # Delete specified profile (requires confirmation)
ziniao-cli config remove --yes        # Skip confirmation and delete directly

Authentication

Authentication Model

ziniao-cli uses a unified apiKey (Bearer Token); one key is used for both:

Purpose	Address	Description
Server API	sbappstoreapi.ziniao.com	Business endpoints for departments/employees/accounts/devices
Local ZClaw Bridge	127.0.0.1:9481	Ziniao Browser store/page control

No OAuth, token refresh, or dual identity (user/bot) mechanisms. The apiKey is a static credential that does not expire.

ISV App Permission Points

Before calling server APIs, you must enable the corresponding permission points for your app on the Ziniao Open Platform. The following are the permission points required for each module:

Module	Permission Point	Covered Endpoints
Departments & Employees	ERP-Department and Employee API	Department CRUD + Employee query/create/update/enable-disable (9)
Departments & Employees	ERP-User Department Change	Employee transfer (1)
Roles & Permissions	ERP-Role List Query	Role list + User role list (2)
Roles & Permissions	ERP-Role Details	Role details (1)
Roles & Permissions	ERP-Permission List	Permission item list (1)
Roles & Permissions	ERP-Role Add/Modify Permissions	Add/modify/adjust roles (3)
Device Management	ERP-Device Query	Device list + Historical binding records (2)
Device Management	ERP-Device Package List Query	Package list (1)
Device Management	ERP-Device Binding	Bind device (1)
Device Management	ERP-Unbind Device	Unbind device (1)
Device Management	ERP-Auto-Renewal Toggle	Auto-renewal switch (1)
Device Management	ERP-Device Purchase and Renewal	Purchase + Renewal (2)
Device Management	ERP-Add Own Device (New)	Add own device (1)
Device Management	ERP-Modify Own Device Info (New)	Modify own device (1)
Device Management	ERP-Query Purchased Device Prices	Purchased device prices (1)
Account Management	ERP-Account View	Account list/Authorization query/User account list/Authorized user list (4)
Account Management	ERP-Create and Delete Account	Create + Delete account (2)
Account Management	ERP-Edit Account Basic Info	Edit account info (1)
Account Management	ERP-Account Authorization	Add authorization + Delete 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 Accounts a User Has Access To	Accounts a user has access to (1)
Account Management	ERP-Get Additional Website Info	Additional website info (1)
Account Management	Account Tag Management	Tag CRUD + Bind/Unbind/Replace/Clear/Remove (9)
Access Policies	ERP-Web Access	Access rules/webpages/webpage groups all operations (22)

If an endpoint returns isv.invalid-method (nonexistent method name), it usually means the permission point is not enabled. Go to Ziniao Open Platform → App Management → Permission Management to enable it.

Common Parameters

Every server API request requires companyId; the CLI auto-injects and forces the configured value, so you don't need to and shouldn't pass it manually. This value is automatically fetched via the /app/builtin/company endpoint during config init and written to the config; even if you explicitly pass companyId in --data, the CLI overrides it with the configured value.

Two-Layer Command System

Layer 1: Generic api Command (Covers All 73 Endpoints)

Any Ziniao server API can be called via the api command without a dedicated shortcut:

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

• Defaults to POST; supports GET/POST/PUT/DELETE
• companyId is auto-injected by the framework and forcibly overrides any same-named field in --data
• --page-all auto-paginates (default max 10 pages; use --page-limit 0 to get all)
• --page-size N items per page (default 20)
• --page-limit N max pages (default 10; 0 means unlimited; use with --page-all)
• --page-delay MS delay between pages in milliseconds (default 200; use with --page-all)
• --dry-run preview the request without executing
• --jq built-in jq filtering

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

Provide named flags and smart defaults for complex endpoints:

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

Difference Between account and store

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

	account commands	store commands
Channel	Server API (sbappstoreapi.ziniao.com)	Local ZClaw Bridge (127.0.0.1:9481)
Responsibility	CRUD, authorization, tagging of store accounts—management operations	Control already-open browser instances: list, open, close
Prerequisite	Only apiKey + network	Ziniao Browser client must be running
Typical Use	Create stores, batch authorize employees, manage tags	Open store browser → navigate → screenshot → automate

Quick memory: account = admin backend CRUD, store = control local browser windows.

Command Priority

When an AI agent makes calls, choose by priority:

1. Shortcut commands -- staff list, department create, store open, etc. (simplified parameters, best experience)
2. Generic api command -- api <path> as fallback (any endpoint can be called; requires hand-written JSON body)
3. zclaw invoke -- zclaw invoke <tool> as 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 network/apiKey
business	Business-layer error (ret != 0)	Report the error message; determine cause from msg
validation	Parameter validation failed	Check whether command parameters are correct
network	Network unreachable/Bridge not started	For ZClaw: prompt to start Ziniao Browser; for API: check network

Update Check

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

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

When you see _notice.update in the output:

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

Update notifications are only passed via the _notice field in stdout JSON, never to stderr. You can disable the check with 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 by MSYS to Windows local paths (e.g., /superbrowser/... → C:/Program Files/Git/superbrowser/...), which breaks the path parameter of the api command.

PowerShell and CMD do not have this issue.

Solution 1 (recommended): Write to .bashrc for permanent effect

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

Solution 2: Prefix each command

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

Security Rules

• Never output the full apiKey in plaintext to the terminal
• Confirm user intent before write/delete operations
• high-risk-write operations (department delete, staff remove) require interactive confirmation; --yes skips it
• It is recommended to preview dangerous requests with --dry-run first

Important Behavioral Rules

• ZClaw local endpoints must be called via ziniao-cli: When calling Ziniao Browser local endpoints (store/page/zclaw commands), you must use the ziniao-cli capabilities in this skill system; do not use the ziniao-assistant skill to call ZClaw Bridge directly.
• Prefer local endpoints for store lists: If the user asks for a store list, prefer the store list shortcut command (which goes through the local ZClaw Bridge), because regular members do not have permission for the server-side account list endpoint. You can determine member type via the isBoss field in the output of ziniao-cli config show.
• ZClaw authentication failure troubleshooting: If, after helping the user initialize the app (config init), requests to ZClaw endpoints still return API Key authentication failure, remind the user to check the Ziniao Open Platform at https://open.ziniao.com to see whether the current terminal identifier is bound in "Terminal Management" under their user app (the identifier can be found in Ziniao Browser settings).