Mercur Cli

Common flows

Discover and inspect a block

npx @mercurjs/cli@latest search --query <keyword>
npx @mercurjs/cli@latest view <block-name>

Add a block

npx @mercurjs/cli@latest add <block-name>

Important: When CLI asks to overwrite middlewares.ts, always decline (n) and merge manually.

Check local drift

npx @mercurjs/cli@latest diff <block-name>

After add

Follow the block docs output, but verify everything against the actual installed files:

1. Middleware: Read the actual middleware file to get the correct export name and path. Add the import and spread to src/api/middlewares.ts.
2. medusa-config.ts: Add modules, providers, plugin options, or env-driven config as docs specify.
3. Migrations: If the block added a module with models, run bunx medusa db:generate <module> and bunx medusa db:migrate from packages/api.
4. Dependencies: If the dev server fails with "Cannot find module", install the missing dependency with bun add <package> in the correct workspace.
5. Env vars: Add any required environment variables to .env.
6. Validation: Run the dev server and check for startup errors before moving on.

Known CLI behaviors

• CLI may prompt "You need to create a blocks.json" even when it exists — this happens when running from the wrong directory.
• CLI's add outputs the block docs after installation — read them carefully but verify against installed files.
• CLI may install files from one block that overlap with another block (shared files). Declining overwrites preserves existing work.
• The search command with --query "" returns all available blocks.

Avoid

• running registry commands outside the project root
• guessing block names without search or view
• accepting middlewares.ts overwrite from CLI
• assuming an installed block only changed one workspace
• trusting block docs blindly for import paths or dependencies
• skipping dev server validation after installing a block