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

Install globally (recommended):

npm install -g @mercurjs/cli

Any package manager works:

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

Or install locally as a dev dependency:

npm install -D @mercurjs/cli

Quick Start

Create a new project:

# Create a new Mercur project
mercurjs create

# Create with a specific template
mercurjs create my-mercur --template basic

Or add blocks to an existing project:

# Initialize your project
mercurjs init

# Add a block from the registry
mercurjs add product-review

# Search for available blocks
mercurjs search --query product

Commands

`create`

Create a new Mercur project with the selected template.

mercurjs 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
mercurjs create

# Create with a specific name and template
mercurjs create my-marketplace --template basic

# Create without database setup
mercurjs create my-mercur --skip-db

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

`init`

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

mercurjs 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
mercurjs init

# Non-interactive with defaults
mercurjs init --defaults

# Initialize in a specific directory
mercurjs init --cwd ./my-project

`add`

Add blocks to your project from the registry.

mercurjs 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
mercurjs add product-review

# Add multiple blocks
mercurjs add product-review order-tracking wishlist

# Add with overwrite
mercurjs add product-review --overwrite

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

`search`

Search blocks from registries by name or description.

mercurjs 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
mercurjs search --query product

# Search a custom registry
mercurjs search --query review --registry @my-registry

`view`

View detailed information about specific blocks from the registry.

mercurjs 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
mercurjs view product-review

# View multiple blocks
mercurjs view product-review order-tracking

`diff`

Check for updates by comparing local files against the registry.

mercurjs 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
mercurjs diff product-review

# Check multiple blocks for updates
mercurjs diff product-review order-tracking

`build`

Build the registry from a registry.json file.

mercurjs 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
mercurjs build

# Build with custom paths
mercurjs build ./my-registry.json --output ./dist/registry

# Build with verbose output
mercurjs build --verbose

`info`

Get information about your project and configuration.

mercurjs info [options]

Options:

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

Examples:

# Get project info
mercurjs info

# Get info for a specific directory
mercurjs 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
mercurjs 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
mercurjs init

# Search for available blocks
mercurjs search --query product

# Add blocks
mercurjs add product-review order-tracking

Checking for Updates

# See what changed in a block
mercurjs diff product-review

# Update by overwriting
mercurjs add product-review --overwrite

Building a Custom Registry

# Create a registry.json file with your blocks
# Then build the registry
mercurjs 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`