resto-datacli

resto-datacli is a deterministic command-line tool for restaurant reporting analysis workflows. It helps an agent sync report knowledge, discover reports and fields, validate explicit query plans, execute validated report API requests, and run deterministic snapshot transforms.

The boundary is deliberate: the agent decides what the user is asking for, which report or fields are relevant, and how evidence should be interpreted. The CLI and backend services do not infer user intent; they only operate on explicit commands, filters, fields, and plans.

Build, Test, Install

npm install
npm run build
npm test
npm run lint

The package exposes the resto binary from dist/cli.js. npm install from git and npm pack run the build through the prepare script while keeping dist/ ignored in git.

Documentation

• Business customers: Resto Data CLI Deployment Guide — a short installation, login, and first-use guide for non-technical users.
• Internal implementation and support: Resto Data CLI Deployment and Usage Guide — environment, permissions, query plans, acceptance, security, and troubleshooting.
• Developers and Agent implementers: docs/installation.md — package installation, skill registration, local integration, and publisher checks.

Main Commands

• resto auth login saves a local authentication profile for remote query execution.
• resto auth status prints local authentication status without printing the token.
• resto knowledge sync syncs local report knowledge from the configured source.
• resto knowledge check compares the local package with the remote manifest without downloading artifacts.
• resto knowledge status shows the current local knowledge package state.
• resto report search and resto report inspect discover and inspect local report metadata.
• resto report count, resto report list, and resto report resolve provide fast mapped-report shortcuts from page/menu/route knowledge. search and resolve include recommended, matchKind, and matchReasons when the evidence clearly distinguishes a canonical mapped report from same-title or variant reports.
• resto field search discovers local report fields, optionally scoped by --report-id.
• resto playbook list and resto playbook inspect read optional analysis references.
• resto query validate validates an explicit JSON query plan against local knowledge.
• resto query execute executes a validated plan and saves a query snapshot.
• When report-cli-service returns aligned rawRows, snapshots retain them so transforms calculate from raw metrics while continuing to display labels from rows; responses without rawRows remain supported.
• resto analysis topn ranks rows from an existing snapshot by an explicit metric.
• resto analysis contribution compares current and baseline snapshots by dimension and metric.
• resto install-skill registers the bundled resto-datacli skill with AI coding assistants, including a QoderWork-compatible copy under ~/.qoder/skills.

Auth

Interactive login prompts for the CLI auth gateway URL, corporation id, auth method, and secret values. Phone dynamic codes and passwords are hidden while you paste them:

resto auth login --interactive

Phone login uses the CLI auth gateway to send a dynamic verification code, then exchanges the phone number and code for a CLI-platform token:

resto auth login \
  --base-url https://cli.restosuite.cn \
  --plat cli \
  --corporation-id 302 \
  --phone-number <phone-number> \
  --dynamic-code <verification-code>

Password login follows the auth gateway login step flow, encrypts the password with the gateway-compatible RSA-OAEP/SHA-256 public key, and stores the returned token in the same local auth profile:

resto auth login \
  --base-url https://cli.restosuite.cn \
  --plat cli \
  --username <account> \
  --password <password>

--base-url is the CLI auth gateway host used for login and token acquisition. Interactive login defaults to the China production gateway https://cli.restosuite.cn; use https://cli.test.restosuite.ai explicitly for the test environment. --plat defaults to cli. Knowledge manifest sync/check, report query execution, and shop filter lookup go through report-cli-service; configure --report-cli-url or RESTO_REPORT_CLI_URL when using a non-default service endpoint. language-code and timezone default to zh_CN and Asia/Shanghai. For phone login, --phone-area-code defaults to +86 and --phone-region defaults to CN when omitted. If the gateway password flow requires an explicit tenant or flow step, pass --corporation-id, --login-flow-code, and optionally --login-step-name. For normal email/password login, --login-flow-code is not required; it is kept only as a troubleshooting escape hatch.

Query Backend

resto query execute sends query requests to report-cli-service:

resto query execute --plan ./plan.json

For local report CLI chain testing, start report-api and report-cli-service locally, then point the CLI at the local service:

resto query execute \
  --plan ./plan.json \
  --report-cli-url http://127.0.0.1:18081

The same service URL can be selected with an environment variable:

RESTO_REPORT_CLI_URL=http://127.0.0.1:18081 \
resto query execute --plan ./plan.json

resto shop search also sends shop filter requests to report-cli-service:

resto shop search zn线上店铺 \
  --report-id 888001 \
  --organization-type 1 \
  --org-type-list 1,2 \
  --report-cli-url http://127.0.0.1:18081

Fixture Mode

Fixture mode uses bundled local knowledge and does not require remote services or auth:

resto knowledge sync --fixture
resto knowledge status
resto knowledge check --fixture

Example query plans live in docs/examples. A typical golden-plan check is:

resto knowledge sync --fixture
resto query validate --plan docs/examples/dish-topn-plan.json

Evidence Expectations

Answers built with this CLI should cite the evidence used: report ID, selected fields, filter fields, explicit filter values and time range, currency when available, and the resultId returned by resto query execute. Snapshot transforms should also cite the source resultId, transform name, dimension, and metric. topn should cite its limit. contribution should cite its baseline resultId.

Customer-facing summaries should use Chinese field display names or aliases first. Field codes are internal evidence for query plans, validation, debugging, and engineering handoff; do not expose them by default in business-facing answers unless the user asks for technical details.

Playbooks are reference material, not automatic business conclusions. If a playbook is used, cite its name or ID and explain what was adapted.

Agent workflow guidance is maintained in .agents/skills/resto-datacli/SKILL.md. Verification notes and backend caveats are tracked under docs/verification, including docs/verification/phase1-mvp.md.