CLI Reference

The Blockend CLI (blockend-cli) is the primary interface for initializing projects, discovering and installing backend blocks, and integrating with AI coding assistants via MCP.

Installation

No global installation required. Run commands directly with npx:

npx blockend-cli <command> [options]

`blockend-cli init`

Initialize a blockend.json configuration for your project.

npx blockend-cli init [options]

The init command scans your project, detects your framework and package manager, and generates a blockend.json file.

Options

Option	Alias	Default	Description
`--yes`	`-y`	`false`	Skip prompts and use auto-detected defaults
`--json`		`false`	Output machine-readable JSON instead of interactive text

Interactive Prompts

Existing config handling — keep, overwrite, or regenerate if blockend.json already exists
Framework selection — auto-detected or manually chosen from Express, Fastify, Next.js, Hono
Blocks directory — where block files will be installed (e.g. src/blocks)
Redis — enable Redis-backed variants if Redis is detected in the project
Import alias — derived from tsconfig.json paths automatically

Output

Creates blockend.json in the project root:

{
  "$schema": "https://blockend.noorulhassan.com/schema.json",
  "environment": "express",
  "language": "typescript",
  "packageManager": "pnpm",
  "importRewriteStrategy": "remove",
  "includeRedis": false,
  "aliases": {
    "blocks": "@/blocks"
  },
  "paths": {
    "blocks": "./src/blocks"
  },
  "installed": []
}

The installed array is populated automatically when you add blocks and tracks which blocks are installed, their versions, and content hashes for update detection.

`blockend-cli add <block>`

Download and install a backend block into your project.

npx blockend-cli add [block] [options]

If no block name is provided, an interactive selector shows all blocks compatible with your project's framework.

Options

Option	Alias	Default	Description
`[block]`			Block key name (e.g. `rate-limiter`, `logger`)
`--yes`	`-y`	`false`	Skip confirmations, auto-select first variant
`--json`		`false`	Output machine-readable JSON progress
`--multi`	`-m`	`false`	Select multiple blocks at once via multiselect

Multi-Select Mode

Use --multi to select and add multiple blocks in one session:

npx blockend-cli add --multi

This presents a multiselect prompt where you can:

Press Space to toggle block selection
Press Enter to confirm and install all selected blocks

Each block is processed sequentially with its own dependency install, conflict check, and file download.

How It Works

Finds blockend.json by walking up the directory tree
Fetches the registry manifest from raw.githubusercontent.com
Filters blocks compatible with your configured environment
Prompts variant selection (e.g. memory vs Redis store) when multiple exist
Installs missing npm dependencies automatically
Downloads source files and writes them to the configured blocks directory
Rewrites import paths according to your project's alias and strategy configuration

Variant Selection

Blocks with multiple storage backends present a variant picker:

? Select a storage variant:
❯ Memory
  Redis

If Redis is enabled in blockend.json and a Redis variant exists, it is auto-selected.

Framework Detection

The CLI checks whether a block supports your target framework using its frameworks field or adapter map. Incompatible blocks are hidden from the selector.

`blockend-cli list`

List available blocks for your project's framework.

npx blockend-cli list [options]

Options

Option	Default	Description
`--json`	`false`	Output machine-readable JSON array of block metadata

Output

Shows block names, descriptions, and available storage variants:

Available backend blocks for express:

  rate-limiter
    IP-based rate limiting middleware with pluggable storage strategies
    Storage Variants: memory, redis

  logger
    Framework-agnostic context logging engine
    Storage Variants: default

`blockend-cli detect`

Scan the current project directory and report detected configuration.

npx blockend-cli detect [options]

Options

Option	Default	Description
`--json`	`false`	Output full detected context as a JSON object

Detected Fields

Field	Description
`framework`	Detected backend framework
`language`	TypeScript or JavaScript
`packageManager`	Detected package manager (npm, pnpm, yarn)
`srcDir`	Whether a `src/` directory exists
`importRewriteStrategy`	NodeNext (`.js` append) or Bundler (extensionless)
`hasRedis`	Whether Redis is detected in dependencies
`hasPrisma`	Whether Prisma is detected
`hasDrizzle`	Whether Drizzle ORM is detected

`blockend-cli diff <block>`

Preview what files a block would generate without writing to disk.

npx blockend-cli diff <block> [options]

Options

Option	Default	Description
`[block]`		Block name to preview (required)
`--json`	`false`	Output diff results as JSON

Output

Shows each file's status (new, modified, unchanged) with line-level diffs for modified files:

  pino-logger — default variant

  + core.ts (new)
  ~ express.ts (modified)
    - import { pino } from 'pino';
    + import { pino } from 'pino';
    + export const logger = pino();

  1 new | 1 modified | 0 unchanged

`blockend-cli doctor`

Detect configuration and project issues that could affect Blockend.

npx blockend-cli doctor [options]

Options

Option	Default	Description
`--json`	`false`	Output health check results as JSON

Checks Performed

package.json exists
blockend.json exists and is valid
tsconfig.json exists (warning if missing)
Lockfile detection (npm, pnpm, yarn, bun)
Framework detection
blockend.json structure validation (environment, paths, blocks directory)

Exits with code 1 if any errors are found.

`blockend-cli update`

Compare installed blocks with registry versions and optionally apply updates.

npx blockend-cli update [options]

Options

Option	Default	Description
`--json`	`false`	Output update status as JSON
`--diff`	`true`	Show git-diff style file comparison for blocks with updates
`--apply`	`false`	Select blocks to update via multiselect and apply with rewriting

Version Tracking

The update command reads the installed array from blockend.json to know which blocks are installed and their versions. When you run blockend add, each block is recorded with:

name — block identifier
version — registry version at install time
installedAt — ISO timestamp
files — list of installed files
contentHash — hash of the rewritten file contents

Read-Only Mode (default)

Without --apply, the command compares versions and shows diffs:

  Updates available:

    ~ pino-logger 1.0.0 → 1.1.0

  Change details:

  ▸ pino-logger

  ~ core.ts (modified)
    3   import { pino } from 'pino';
    4 - export const logger = pino({ level: 'info' });
    4 + export const logger = pino({ level: 'debug' });

  ✖ 1 block(s) have updates. Run with --apply to update files.

Apply Mode

With --apply, a multiselect prompt lets you choose which blocks to update:

npx blockend-cli update --apply

This will:

Show a multiselect prompt (Space to select, Enter to confirm)
Confirm before overwriting files
Download new versions
Rewrite imports according to your project's settings (alias + strategy)
Update blockend.json tracking with new version and content hash

`blockend-cli mcp`

Start the MCP server or initialize MCP client configuration.

npx blockend-cli mcp [command] [options]

`blockend-cli mcp`

Start the MCP server using the Stdio transport. This allows AI coding assistants to interact with Blockend directly.

When the MCP server is running, AI clients can call these tools:

Tool	Description
`list_blocks`	List all available blocks with descriptions
`add_block`	Install a single block into a specified project
`add_blocks`	Install multiple blocks at once via interactive selection
`detect_project`	Analyze a project and return its configuration
`diff_block`	Preview what files a block would generate without writing to disk
`doctor`	Check project health and validate configuration
`update_check`	Check for available updates to installed blocks
`update_apply`	Apply updates to all installed blocks with import rewriting

`blockend-cli mcp init`

Generate MCP configuration files for supported AI clients.

npx blockend-cli mcp init [options]

Options

Option	Default	Description
`--client`		Target client: `claude`, `codex`, `cursor`, `vscode`, `windsurf`
`--force`	`false`	Overwrite existing configuration files
`--dry-run`	`false`	Preview changes without writing to disk
`--yes`	`false`	Skip prompts, default to Claude Code

Supported Clients

Client	Config File	Format
Claude Code	`.mcp.json`	JSON
Cursor	`.cursor/mcp.json`	JSON
VS Code	`.vscode/settings.json`	JSON
Codex CLI	`.codex/config.toml`	TOML
Windsurf	`.windsurf/mcp.json`	JSON

Using `blockend-cli` as a Package

Blockend CLI is also importable as a library:

import { addCommand } from "blockend-cli";
import { initCommand } from "blockend-cli";
import { listCommand } from "blockend-cli";
import { detectCommand } from "blockend-cli";
import { diffCommand } from "blockend-cli";
import { doctorCommand } from "blockend-cli";
import { updateCommand } from "blockend-cli";

Each command accepts options in the same format as the CLI flags.

Exit Codes

Code	Meaning
`0`	Success
`1`	General error (config missing, network failure, etc.)

Environment

Node.js: >= 20
Package Manager: npm, pnpm, or yarn
Language: TypeScript (JavaScript support is limited)

CLI Reference

On this page