Mercentia CLI

@mercentia/cli is the developer-facing command-line tool. Use it to scaffold a headless storefront, sync your local theme files with a Mercentia store, or kick off a migration without leaving your terminal.

Install

# Global install — `mercentia` available on $PATH
pnpm add -g @mercentia/cli
# or
npm install -g @mercentia/cli

# One-off — no install
npx @mercentia/cli@latest --help

Requires Node ≥ 18.18. macOS, Linux, and Windows (PowerShell or WSL) are all supported.

Authenticate

mercentia login

Opens your browser to authenticate via the same OAuth flow the dashboard uses, then writes a short-lived token to ~/.config/mercentia/credentials.json.

For CI, set the MERCENTIA_API_KEY env var to a long-lived API key from Settings → API Keys.

Scaffold a storefront

mercentia init my-shop --template=nextjs
cd my-shop
pnpm install
pnpm dev

--template=nextjs clones the Next.js 14 + App Router starter (see headless starter). It pre-fills .env.local with the store id and gateway URL of whichever store you’re authenticated against.

Other commands

Command	What it does
mercentia stores list	List stores the current credentials can access
mercentia store use <id>	Switch the active store for subsequent commands
mercentia theme pull	Download the current theme files to ./theme
mercentia theme push	Upload local theme changes back to Mercentia
mercentia migrate run <source>	Trigger a Shopify / BigCommerce / Magento / Wix migration
mercentia apps submit ./manifest.json	Submit an app to the marketplace
mercentia doctor	Verify network reachability and credential validity

Scriptable output

All commands accept --json to emit machine-readable output — useful for CI:

mercentia stores list --json | jq '.[].id'

Exit codes follow standard Unix conventions: 0 success, non-zero failure with the error printed to stderr.