@xianqiu/open-eco

Windows/macOS CLI for discovering Ziniao Skills and calling business APIs.

npm install -g @xianqiu/[email protected]
zn-open-eco auth set <token>
zn-open-eco skills

Authentication is stored in macOS Keychain or Windows Credential Manager and survives terminal closure and computer restart. The token is never stored in the npm package or a plaintext CLI configuration file.

auth set <token> is the only supported authentication setup form and may be run by an AI agent after the user provides the token. The token may appear in conversation history, shell history, process arguments, or agent execution logs.

Pass the account/browser ID on each applicable HTTP request. It is not persisted or injected automatically:

Query stores or platform authorizations with the persisted token. These commands preserve the service response exactly:

zn-open-eco account stores --store-name "<name-or-keyword>"
zn-open-eco account platform-auths --platform-type amazon-sp-api
zn-open-eco account platform-auths --platform-type amazon-ads-api
zn-open-eco account platform-auths --platform-type temu-api

Local browser lifecycle

These browser lifecycle commands are included in packages starting with version 0.0.13.

Browser lifecycle commands run only on the user's local Windows or macOS computer. The CLI and Ziniao App must be running on the same computer, and the App must already be open. The CLI connects only to 127.0.0.1, trying fixed ports 33178, 33179, then 33180; it stops at the first valid service. If all attempts fail, it reports that the local Ziniao App cannot be connected.

Confirm authentication and query the store first. Use the store_id from the current, actual account stores response; a store name is not a substitute:

zn-open-eco auth status
zn-open-eco account stores --store-name "<store-name-or-keyword>"
zn-open-eco browser health
zn-open-eco browser capabilities
zn-open-eco browser list-online
zn-open-eco browser connection-status --store-id "<store_id>"
zn-open-eco browser open --store-id "<store_id>"

Only after the user explicitly requests it and reconfirms closing the target store, run this separately:

zn-open-eco browser close --store-id "<store_id>"

health does not send an Auth Key; every other browser command requires configured authentication. capabilities is dynamic admission information. The currently available lifecycle operations are list-online, connection-status, open, and close; page click, input, navigation, screenshot, download, and similar commands are not provided.

open and close accept an optional --idempotency-key "<key>"; when omitted, the CLI generates one. The CLI does not automatically retry POST requests. Server JSON is passed through unchanged to stdout; errors go to stderr and return a nonzero exit code. close is not automatic cleanup—run it only when the user explicitly requests or confirms it.

Browser automation concurrency

agent tool does not maintain a local waiting queue. It submits one tool call directly to the local Ziniao App. Calls for the same browser_id must be serialized by the caller: submit the next tool only after the previous one reaches succeeded, failed, or timed_out. If the App returns BROWSER_BUSY or TASK_CONTEXT_MISMATCH, the CLI reports the error without background queuing or automatic retry.

agent tool status and agent interaction respond can still query or restore an existing call directly. Ordinary API commands are unaffected. Agents must not submit tools for the same browser in parallel, invent replacement IDs to hide conflicts, or retry an uncertain PUT automatically. The CLI, Ziniao App, and target browser must remain on the same local computer, and the App must stay open.

Enable account request diagnostics before running a command. Debug output includes the request method and URL, redacted request headers, the request body when present, response status, and response body. Authorization is redacted. Diagnostics go to stderr while the byte-for-byte service response remains on stdout. Debug response bodies are truncated after 8 KiB.

PowerShell:

$env:ZINIAO_DEBUG='1'
zn-open-eco account stores --store-name "<store-name-or-keyword>"
Remove-Item Env:ZINIAO_DEBUG

Windows cmd:

set ZINIAO_DEBUG=1
zn-open-eco account platform-auths --platform-type amazon-sp-api
set ZINIAO_DEBUG=

macOS shell (applies only to this invocation):

ZINIAO_DEBUG=1 zn-open-eco account stores --store-name "<store-name-or-keyword>"

Discover server-side Product Skills progressively and retrieve agent knowledge. A deeper Skill path must come from the previous response; a knowledge ID must come from a query result:

zn-open-eco agent skills browse --page 1 --page-size 50
zn-open-eco agent skills browse --page 2 --page-size 50
zn-open-eco agent skills browse --path "amazon-sp-api reports-api"
zn-open-eco agent knowledge query --query "download the US returns report for the past 60 days"
zn-open-eco agent knowledge get --kb-id "<kb_id>"

These commands use the independent Agent service at https://agent-swarm-test.ziniao.com, encrypt their HTTP payloads, and write decrypted JSON to stdout. The platform HTTP proxy and account service also use the test environment. ZINIAO_DEBUG uses the same redacted stderr diagnostics and never adds decrypted plaintext to the debug log.

$env:ZINIAO_DEBUG='1'
zn-open-eco agent knowledge query --query "download the US returns report for the past 60 days"
Remove-Item Env:ZINIAO_DEBUG

set ZINIAO_DEBUG=1
zn-open-eco agent skills browse
set ZINIAO_DEBUG=

ZINIAO_DEBUG=1 zn-open-eco agent skills browse

zn-open-eco http POST /proxy/cn/cross-border-semi-managed --module temu-api --headers '{"X-Account-Id":"<browser_id>"}' --body '{"type":"bg.mall.info.get"}'

Supported platforms: Windows x64/ARM64 and macOS Intel/Apple Silicon. Linux is not supported.