| name | commerce-engine-setup |
| description | Set up and run the StateSet iCommerce engine locally (CLI install, DB init, demo data, sync). Use when bootstrapping an environment, running `stateset-doctor`, or starting `stateset-autonomous`. |
Commerce Engine Setup
Set up local iCommerce runtime, CLI tooling, and optional sync.
How It Works
- Install or link the CLI and choose a SQLite database path.
- Initialize sync and keys if you need sequencer replication.
- Seed demo data and verify the environment.
- Start CLI commands or the autonomous engine.
- Run
stateset-doctor to validate connectivity, schema, and credentials.
Status Flows
- Environment: uninitialized -> cli_linked -> db_created -> seeded -> verified
- Autonomous Engine: stopped -> starting -> running -> healthy
Usage
- CLI:
stateset --db ./store.db "list customers" or stateset-doctor
- Install:
cd /home/dom/stateset-icommerce/cli && npm install && npm link
- Add
--apply for writes and stateset-doctor for checks.
- MCP tools:
list_customers, list_products, list_orders (all commerce tools available after setup).
- Seed demo data:
bash /mnt/skills/user/commerce-engine-setup/scripts/seed-demo.sh
- Verify setup:
bash /mnt/skills/user/commerce-engine-setup/scripts/verify-setup.sh
- Start autonomous mode:
stateset-autonomous start --db ./.stateset/commerce.db
Permissions
- Read:
stateset-doctor, list_customers, list_products, list_orders — no --apply needed.
- Write:
seed-demo.sh, stateset-autonomous start, DB init — requires --apply.
Examples
cd /home/dom/stateset-icommerce/cli && npm install && npm link
bash /mnt/skills/user/commerce-engine-setup/scripts/seed-demo.sh
stateset-doctor --db ./store.db
stateset-autonomous start --db ./.stateset/commerce.db
Output
{"status":"ok","db":"./store.db","sync":"disabled","autonomous":"stopped","cli_version":"1.4.0","tables":12,"customer_id":"cust_001","email":"admin@example.com"}
Present Results to User
- Steps completed and any scripts run.
- Database path and whether sync is initialized.
- Autonomous engine status if started.
- Output of
stateset-doctor checks (connectivity, schema version, API key validity).
Troubleshooting
- CLI not found: re-run
npm link or install @stateset/cli globally.
- Database locked: close other processes using the DB file; check
lsof on the .db path.
- Sequencer unreachable: verify Docker services and
SEQUENCER_URL in .env.
- Seed script fails: ensure
--db path exists and the customers table with id and email columns is initialized.
Error Codes
SETUP_CLI_NOT_FOUND: The stateset CLI is not linked; re-run npm link or install globally.SETUP_DB_LOCKED: Database file is locked by another process; close competing connections.SETUP_SEQUENCER_UNREACHABLE: Cannot connect to the sequencer; verify Docker services and SEQUENCER_URL.
Related Skills
- commerce-mcp-tools — Reference MCP tool names and payloads used by the CLI.
- sandbox-migration — Run the engine inside a sandboxed agent environment.
- commerce-inventory-sync — Sync inventory data after engine setup.
- order-reason-workflows — Automate order actions that rely on the commerce engine.
References
- references/setup-runbook.md
- /home/dom/stateset-icommerce/examples/README.md
- /home/dom/stateset-icommerce/examples/getting-started-sync.md
- /home/dom/stateset-icommerce/cli/README.md
- /home/dom/stateset-icommerce/cli/bin/stateset-autonomous.js
