Skip to main content
The Mercur CLI (@mercurjs/cli@rc) manages your marketplace project — installing blocks, generating types, and checking for updates. To create a new project, use create-mercur-app.

​
Installation

bun add -g @mercurjs/cli@rc

​
Commands

​
create

Scaffolding new projects lives in the standalone create-mercur-app package, so it downloads fast and works with every package manager’s create command. 
bun create mercur-app@rc my-marketplace
# or
npm create mercur-app@rc my-marketplace
It will prompt you for database credentials and install dependencies automatically.
OptionDescription
-t, --template <template>Template to use (default: basic)
--no-depsSkip dependency installation
--skip-dbSkip database configuration
--db-connection-string <string>PostgreSQL connection string

​
init

Initialize an existing project by creating a blocks.json configuration file. 
bunx @mercurjs/cli@rc init
This sets up path aliases so the CLI knows where to place blocks in your project: 
{
  "aliases": {
    "api": "packages/api/src",
    "vendor": "apps/vendor/src",
    "admin": "apps/admin/src"
  }
}
OptionDescription
-d, --defaultsUse default paths without prompting
-s, --silentSuppress output

​
add

Install blocks from the registry into your project. 
bunx @mercurjs/cli@rc add wishlist
bunx @mercurjs/cli@rc add product-review order-tracking
Blocks are copied directly into your project as source code. The CLI resolves dependencies, transforms imports to match your path aliases, and installs required packages.
OptionDescription
-o, --overwriteOverwrite existing files
-y, --yesSkip confirmation
-s, --silentSuppress output
Find available blocks in the registry. 
bunx @mercurjs/cli@rc search --query wishlist
OptionDescription
-q, --query <query>Search by name or description
-r, --registry <registry>Registry to search (default: @mercurjs)

​
view

Display detailed information about a block. 
bunx @mercurjs/cli@rc view wishlist

​
diff

Compare local blocks against registry versions to check for updates. 
bunx @mercurjs/cli@rc diff wishlist
If there are changes you want, update with: 
bunx @mercurjs/cli@rc add wishlist --overwrite

​
codegen

Generate TypeScript types from your API routes. Used by the API Client for type-safe requests. 
bunx @mercurjs/cli@rc codegen
OptionDescription
-w, --watchWatch for changes and regenerate automatically

​
registry:build

Build a custom registry from a registry.json file. 
bunx @mercurjs/cli@rc build
OptionDescription
-o, --output <path>Output directory (default: ./r)
-v, --verboseShow detailed output

​
info

Display project configuration and diagnostics. 
bunx @mercurjs/cli@rc info

​
telemetry

Control anonymous usage data collection. 
bunx @mercurjs/cli@rc telemetry --disable
bunx @mercurjs/cli@rc telemetry --enable

​
Custom registries

Add custom block registries to your blocks.json: 
{
  "registries": {
    "@mercurjs": "https://registry.mercurjs.com/{name}",
    "@my-registry": "https://my-registry.com/blocks/{name}.json"
  }
}
Use {name} as a placeholder for block names. Reference custom registries with the -r flag: 
bunx @mercurjs/cli@rc search --query review --registry @my-registry

​
FAQ

create scaffolds a brand-new project from a template. init only writes a blocks.json into an existing project so the CLI knows where to place blocks — use it when adopting blocks in a repo that wasn’t created by the CLI.
After any change to API route files — added routes, changed validators, renamed paths. The typed client reads the generated route map, so stale types mean codegen hasn’t run.
Not silently — the CLI asks before overwriting existing files unless you pass --overwrite. Use diff first to see exactly what changed between your copy and the registry.

​
Next steps

Add a feature with a block

The install workflow end to end — search, view, add, migrate.

API Client

What codegen’s route map powers on the frontend.