Package Exports

@mercurjs/cli

Readme

Mercur CLI

Add blocks (admin UI pages, vendor UI pages, workflows, modules, and more) from the Mercur registry to your project.

Prerequisites

Node.js v20 or higher

Installation

Using npx (recommended):

npx @mercurjs/cli@canary <command>

Or install globally:

npm install -g @mercurjs/cli@canary

Any package manager works:

pnpm add -g @mercurjs/cli@canary
yarn global add @mercurjs/cli@canary
bun add -g @mercurjs/cli@canary

Or install locally as a dev dependency:

npm install -D @mercurjs/cli@canary

Quick Start

Create a new project:

# Create a new Mercur project
npx @mercurjs/cli@canary create

# Create with a specific template
npx @mercurjs/cli@canary create my-mercur --template basic

Or add blocks to an existing project:

# Initialize your project
npx @mercurjs/cli@canary init

# Add a block from the registry
npx @mercurjs/cli@canary add product-review

# Search for available blocks
npx @mercurjs/cli@canary search --query product

Commands

`create`

Create a new Mercur project with the selected template.

npx @mercurjs/cli@canary create [name] [options]

Arguments:

Argument	Description
`name`	Name of your project (optional, will prompt if not provided)

Options:

Option	Description	Default
`-t, --template <template>`	Template to use: `basic` or `registry`	-
`-c, --cwd <path>`	Working directory	Current directory
`-y, --yes`	Skip confirmation prompt	`true`
`--no-deps`	Skip installing dependencies	`false`
`--skip-db`	Skip database configuration	`false`
`--db-connection-string <string>`	PostgreSQL connection string	-

Examples:

# Interactive project creation
npx @mercurjs/cli@canary create

# Create with a specific name and template
npx @mercurjs/cli@canary create my-marketplace --template basic

# Create without database setup
npx @mercurjs/cli@canary create my-mercur --skip-db

# Create with a specific database connection
npx @mercurjs/cli@canary create my-mercur --db-connection-string "postgresql://user:pass@localhost:5432/mydb"

`init`

Initialize your project and create a blocks.json configuration file.

npx @mercurjs/cli@canary init [options]

Options:

Option	Description	Default
`-y, --yes`	Skip confirmation prompt	`true`
`-d, --defaults`	Use default configuration	`false`
`-c, --cwd <path>`	Working directory	Current directory
`-s, --silent`	Mute output	`false`

Examples:

# Interactive initialization
npx @mercurjs/cli@canary init

# Non-interactive with defaults
npx @mercurjs/cli@canary init --defaults

# Initialize in a specific directory
npx @mercurjs/cli@canary init --cwd ./my-project

`add`

Add blocks to your project from the registry.

npx @mercurjs/cli@canary add <blocks...> [options]

Arguments:

Argument	Description
`blocks`	Names of blocks to add (space-separated)

Options:

Option	Description	Default
`-y, --yes`	Skip confirmation prompt	`false`
`-o, --overwrite`	Overwrite existing files	`false`
`-c, --cwd <path>`	Working directory	Current directory
`-s, --silent`	Mute output	`false`

Examples:

# Add a single block
npx @mercurjs/cli@canary add product-review

# Add multiple blocks
npx @mercurjs/cli@canary add product-review order-tracking wishlist

# Add with overwrite
npx @mercurjs/cli@canary add product-review --overwrite

# Add to a specific directory
npx @mercurjs/cli@canary add product-review --cwd ./my-project

`search`

Search blocks from registries by name or description.

npx @mercurjs/cli@canary search [options]

Options:

Option	Description	Default
`-q, --query <query>`	Search query string	-
`-r, --registry <registry>`	Registry to search from	`@mercurjs`
`-c, --cwd <path>`	Working directory	Current directory

Examples:

# Search for blocks with "product" in name or description
npx @mercurjs/cli@canary search --query product

# Search a custom registry
npx @mercurjs/cli@canary search --query review --registry @my-registry

`view`

View detailed information about specific blocks from the registry.

npx @mercurjs/cli@canary view <blocks...> [options]

Arguments:

Argument	Description
`blocks`	Names of blocks to view (space-separated)

Options:

Option	Description	Default
`-c, --cwd <path>`	Working directory	Current directory

Examples:

# View a block's details
npx @mercurjs/cli@canary view product-review

# View multiple blocks
npx @mercurjs/cli@canary view product-review order-tracking

`diff`

Check for updates by comparing local files against the registry.

npx @mercurjs/cli@canary diff <blocks...> [options]

Arguments:

Argument	Description
`blocks`	Names of blocks to diff (space-separated)

Options:

Option	Description	Default
`-c, --cwd <path>`	Working directory	Current directory

Examples:

# Check if a block has updates
npx @mercurjs/cli@canary diff product-review

# Check multiple blocks for updates
npx @mercurjs/cli@canary diff product-review order-tracking

`build`

Build the registry from a registry.json file.

npx @mercurjs/cli@canary build [registry] [options]

Arguments:

Argument	Description	Default
`registry`	Path to registry.json file	`./registry.json`

Options:

Option	Description	Default
`-o, --output <path>`	Destination directory for JSON files	`./r`
`-c, --cwd <path>`	Working directory	Current directory
`-v, --verbose`	Verbose output	`false`

Examples:

# Build with defaults
npx @mercurjs/cli@canary build

# Build with custom paths
npx @mercurjs/cli@canary build ./my-registry.json --output ./dist/registry

# Build with verbose output
npx @mercurjs/cli@canary build --verbose

`info`

Get information about your project and configuration.

npx @mercurjs/cli@canary info [options]

Options:

Option	Description	Default
`-c, --cwd <path>`	Working directory	Current directory

Examples:

# Get project info
npx @mercurjs/cli@canary info

# Get info for a specific directory
npx @mercurjs/cli@canary info --cwd ./my-project

Configuration

The CLI uses a blocks.json file for configuration. This file is created when you run init.

Example `blocks.json`

{
  "$schema": "https://raw.githubusercontent.com/mercurjs/mercur/new/packages/registry/schema/registry.json",
  "aliases": {
    "workflows": "packages/api/src/workflows",
    "api": "packages/api/src/api",
    "links": "packages/api/src/links",
    "modules": "packages/api/src/modules",
    "vendor": "apps/vendor/src/pages",
    "admin": "apps/admin/src/pages",
    "lib": "packages/api/src/lib"
  }
}

Configuration Options

Option	Type	Description
`$schema`	`string`	JSON schema URL for validation
`aliases.workflows`	`string`	Import alias for workflows directory
`aliases.api`	`string`	Import alias for API routes directory
`aliases.links`	`string`	Import alias for links directory
`aliases.modules`	`string`	Import alias for modules directory
`aliases.vendor`	`string`	Import alias for vendor panel pages
`aliases.admin`	`string`	Import alias for admin panel pages
`aliases.lib`	`string`	Import alias for lib directory
`registries`	`object`	Custom registry configurations

Custom Registries

You can add custom registries to your blocks.json:

{
  "aliases": {
    "workflows": "packages/api/src/workflows",
    "api": "packages/api/src/api",
    "links": "packages/api/src/links",
    "modules": "packages/api/src/modules",
    "vendor": "apps/vendor/src/pages",
    "admin": "apps/admin/src/pages",
    "lib": "packages/api/src/lib"
  },
  "registries": {
    "@my-registry": "https://my-registry.com/blocks/{name}.json",
    "@private": {
      "url": "https://private-registry.com/blocks/{name}.json",
      "headers": {
        "Authorization": "Bearer ${MY_AUTH_TOKEN}"
      }
    }
  }
}

Features

Project Scaffolding: Create new Mercur projects with templates
Automatic Dependency Resolution: When adding a block, the CLI automatically downloads any dependencies it requires
Import Transformation: Automatically transforms imports to use your configured path aliases
Package Manager Detection: Detects your package manager (npm, pnpm, yarn, bun) and installs dependencies automatically
TypeScript Support: Full TypeScript support
Database Setup: Automatic PostgreSQL database creation and migration
File Conflict Handling: Prompts for confirmation before overwriting existing files
Diff Preview: Shows colorized diff output when checking for updates
Custom Registries: Support for multiple registries with authentication

Examples

Creating a New Marketplace

# Create a new project
npx @mercurjs/cli@canary create my-marketplace

# Follow the prompts to:
# 1. Select a template (basic or registry)
# 2. Configure database connection
# 3. Install dependencies

Adding Blocks to an Existing Project

# Initialize the CLI in your project
npx @mercurjs/cli@canary init

# Search for available blocks
npx @mercurjs/cli@canary search --query product

# Add blocks
npx @mercurjs/cli@canary add product-review order-tracking

Checking for Updates

# See what changed in a block
npx @mercurjs/cli@canary diff product-review

# Update by overwriting
npx @mercurjs/cli@canary add product-review --overwrite

Building a Custom Registry

# Create a registry.json file with your blocks
# Then build the registry
npx @mercurjs/cli@canary build --verbose

# Output will be in ./registry directory

License

MIT

@mercurjs/cli

Package Exports

Readme

Mercur CLI

Prerequisites

Installation

Quick Start

Commands

create

init

add

search

view

diff

build

info

Configuration

Example blocks.json

Configuration Options

Custom Registries

Features

Examples

Creating a New Marketplace

Adding Blocks to an Existing Project

Checking for Updates

Building a Custom Registry

License

`create`

`init`

`add`

`search`

`view`

`diff`

`build`

`info`

Example `blocks.json`