The spark CLI
spark is the MishiSpark command line, for people and for agents. It asks questions about your connected stores, calls the analytics tools directly, downloads exports, runs checkout audits and handles credits and HTTP 402 payment challenges.
Not public yet. The CLI is not on npm yet. Publication waits for a decision. The API features that it calls are switched off while we finish them.
Install
Until the package is on npm, build it from the packages/spark-cli directory of the source.
# Node 20 or later. No runtime dependencies. cd packages/spark-cli npm install # dev dependencies only npm run build # writes dist/ npm link # puts `spark` on the PATH
Commands
| spark auth login | status | logout [--revoke] | Sign in with the device flow, show the key in use, sign out. |
| spark auth agent-signup --tos-version <v> | An agent creates its own account. The key starts unfunded, with zero credits. |
| spark whoami | The account behind the key. |
| spark keys list | create | revoke | Manage API keys. A new secret goes to a file with mode 0600, never to stdout. |
| spark connections list | add <platform> | List connected stores, or connect Odoo, WooCommerce, Magento, Square or Clover. |
| spark ask "<question>" --connection <id> | Ask the AI analyst a question about a store. |
| spark tools | tool <name> | List the analytics tools, or call one with JSON input. |
| spark sales | orders | products | inventory | Shortcuts for get_sales, analyze_orders, search_products and get_inventory_detail. Default period: the last 30 days. |
| spark export --type <preset> | Download a CSV or Excel export. |
| spark audit <url> [--effort] [--max-credits N] [--wait] | Request a checkout audit; status, report, artefacts, cancel and list read it back. |
| spark domains claim | verify | list | Prove ownership of a store domain. |
| spark credits balance | topup <credits> | pay <challenge-id> | Read the balance, buy credits, pay a 402 challenge. |
Every POST sends an Idempotency-Key. Set your own with --idempotency-key.
For agents: --json and SPARK_API_KEY
- Every command takes
--json. Then stdout holds exactly one JSON document, also on an error:{"error": {"code", "message", "exit_code", "status", "payment"?, "retry_after"?}}. Progress text goes to stderr. SPARK_API_KEYwins over the saved key in~/.config/spark/config.json(mode 0600).- The CLI never prints a key. It shows a prefix only.
export SPARK_API_KEY=spk_live_… spark sales --connection <id> --json spark ask "Which products sold most last week?" --connection <id> --json
Exit codes
| Code | Meaning |
|---|---|
| 0 | OK |
| 1 | Error: bad arguments, not found, server error, network error |
| 2 | Authentication: no key, 401, 403 (scope missing, key not allowed) |
| 3 | Payment required: HTTP 402 |
| 4 | Rate limit or quota: HTTP 429 (retry_after in the JSON error) |
Payment (HTTP 402)
- When the credits cannot cover a request, the API answers 402 with a payment challenge. The CLI prints the price, the amount to pay, the
topup_urland the challenge id, and exits 3. A person pays at thetopup_url. Then run the same command again. - With
SPARK_PAY=autoand--max-credits N, and when the challenge price is N credits or less, the CLI callsPOST /api/v1/credits/purchase {challenge_id}and prints the URL that a person must complete. - With
--waitit then polls the challenge every 5 seconds until it is paid (--timeout, default 900 seconds) and sends the original request again with the sameIdempotency-Key. Without--waitit exits 3. - The CLI never pays above
--max-credits, and never without it. - A 402 with
KEY_BUDGET_EXCEEDEDhas no challenge: the key reached its own budget. Buying credits does not help.
SPARK_PAY=auto spark ask "Top products this month?" \ --connection <id> --max-credits 50 --wait --json
The full flow, with an example response: How an agent pays (HTTP 402).
Agent skill
The agent skill tells an agent how to use the CLI safely. Read it at /skill.md. Like the other agent docs, it answers 404 until the agent features open.