BattleShip Technology Co., Ltdbattleship.com.cn
Visitor System · CLI Tool

qndaCliCommand-Line ToolManage your visitor system with a single command

qndaCli is the unified command-line tool for the Qingniu Dunan visitor system. Configure once and sign in with API credentials, then query parks, visitors and appointments from your terminal — built for ops inspection, second-party development and automation.

Quick Start了解青牛盾安
Quick Start

Run your first command in four steps

From install to self-check, connect to production (prod) in minutes.

STEP 01

Install dependencies

qndaCli only depends on requests and jmespath, on Python 3.8+.

cd bigpeng-java/cli
pip install requests jmespath
python -m qndacli --help
STEP 02

Configure the endpoint

Set the gateway host and the admin clientId; --use makes it the default profile.

qndaCli configure --profile prod \
  --host https://qnapi.peishen.com.cn \
  --client-id <admin clientId> --use
STEP 03

Write API credentials (AK/SK)

SecretId / SecretKey are generated on the mini-app "API Credentials" page; they are written only to a local 0600 credentials file and never to config or logs.

qndaCli configure --profile prod \
  --secret-id <SecretId> --secret-key <SecretKey> --use
STEP 04

Sign in and self-check

With AK/SK configured, sign-in auto-signs to exchange a token; doctor should report all green.

qndaCli auth login --profile prod
qndaCli auth doctor --profile prod
Core Commands

P0 Read-only Commands

Read-only query commands are open today, covering parks, visitors, appointments and certificate ciphertext. Write operations and decryption APIs open progressively per review cadence.

Read-only release (P0)

visit

  • qndaCli visit list --park <parkId> --status 1Appointment list: filter visitor appointments by park and status
  • qndaCli visit get <appointmentId>Appointment detail: query a single appointment by Base62 ID
  • qndaCli visit maintenance-certs <appointmentId>Certificate ciphertext list for maintenance appointments

park

  • qndaCli park listPark list
  • qndaCli park get <parkId>Park detail

user

  • qndaCli user list --appType 3User list: filter by app-type
  • qndaCli user get <userId>User detail

meta

  • qndaCli meta commandsShow the command tree (write commands marked W, not yet enabled)
  • qndaCli meta refreshRefresh the descriptor online
Auth & Security

Credentials are identity, signatures are authorization

qndaCli is built around API credentials (AK/SK). No plaintext password is ever exposed, consistent with the zero-knowledge privacy architecture of Qingniu Dunan.

HMAC-SHA256 signed sign-in

At sign-in, SecretKey signs secretId + timestamp + nonce with HMAC-SHA256; the server verifies and issues a token — the password never leaves your machine.

Local credential isolation

AK/SK and token live only in ~/.qndacli/credentials.json (mode 0600, isolated per profile); the SK is never written to config or logs.

Zero-knowledge alignment

Same as the mini-app: the platform keeps only ciphertext, keys belong to you; the CLI only queries and passes through, never touching sensitive plaintext.

Output & Filtering

Machine-readable, integration-friendly

All commands output JSON by default and pair with jmespath filtering, ready to drop into scripts and pipelines.

  • --query <jmespath>

    Filter / project the result with a jmespath expression, e.g. pick only certain fields

  • --output json

    Output format (P0 is JSON only), for piping into jq and friends

  • --dry-run

    Only print the request that would be sent (method / URL / params) without executing — for rehearsal and debugging

  • -v / --verbose

    Print more detailed request and response logs

Exit Codes

Predictable exit codes

  • 0Success
  • 1Server error
  • 2Network error
  • 3Auth failure
  • 4Usage error
Roadmap

What opens next

The following are on the roadmap. Not available in the current release; docs update with each launch.

Write commands

Appointment create / update / cancel, and park & user management writes (opened after review)

Decryption API

Sensitive-field decryption (reason + audit + production confirmation required), for authorized roles only

Inspection tooling

Table-level inspection, column diff, certificate-gap scanning and other ops tools

MCP service

Wrap qndaCli as a Model Context Protocol (MCP) service for AI assistants to call

Put your visitor system in your terminal

qndaCli ships with Qingniu Dunan. Generate API credentials in the Alipay mini-app first, then run your first command back in the terminal.

了解青牛盾安商务合作