@mercurjs/cli@latest) manages your marketplace project — installing blocks, generating types, and checking for updates. To create a new project, use create-mercur-app.
Installation
Commands
create
Scaffolding new projects lives in the standalonecreate-mercur-app package, so it downloads fast and works with every package manager’s create command.
init
Initialize an existing project by creating ablocks.json configuration file.
add
Install blocks from the registry into your project.search
Find available blocks in the registry.view
Display detailed information about a block.diff
Compare local blocks against registry versions to check for updates.codegen
Generate TypeScript types from your API routes. Used by the API Client for type-safe requests.registry:build
Build a custom registry from aregistry.json file.
info
Display project configuration and diagnostics.telemetry
Control anonymous usage data collection.Custom registries
Add custom block registries to yourblocks.json:
{name} as a placeholder for block names. Reference custom registries with the -r flag:
FAQ
When do I use create vs init?
When do I use create vs init?
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.When do I need to run codegen?
When do I need to run codegen?
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.Will add overwrite my local changes to a block?
Will add overwrite my local changes to a block?
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.