Enjoying Blockend?

Give us a star on GitHub

Star on GitHub
blockend

Blockend

CLI reference

Commands and options for initializing Blockend, adding blocks, and checking updates.

The package is blockend-cli; the executable is blockend. You do not need a global install:

pnpm dlx blockend-cli <command>

The npm equivalent is npx blockend-cli <command>. After installation, the blockend binary also works.

init

Create blockend.json in the project root.

pnpm dlx blockend-cli init [options]
OptionAliasDefaultDescription
--yes-yfalseAccept detected defaults and overwrite an existing config.
--jsonfalseWrite a JSON result instead of terminal output.
--cwd-ccwdTarget directory or workspace package.

The command detects the framework, language, package manager, Redis, and tsconfig.json or jsconfig.json path aliases. It prompts for:

  1. Whether to keep, overwrite, or regenerate an existing config
  2. Blocks directory, defaulting to src/blocks or blocks
  3. Framework, when detection fails
  4. Redis variants, when Redis is detected

Generated config:

{
  "$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 is added by add, not by init. With --yes, an existing blockend.json is overwritten without a prompt.

add

Write a block into the project.

pnpm dlx blockend-cli add [block] [options]
OptionAliasDefaultDescription
[block]Registry key, such as rate-limiter or logger.
--yes-yfalseSkip prompts, install missing dependencies, and overwrite conflicts.
--jsonfalseWrite a JSON result.
--multi-mfalseSelect multiple blocks in one session.
--recipeAdd every block in a published recipe, in its integration order.
--cwd-ccwdTarget directory or workspace package.

Without a block name, the CLI shows a selector. With --multi, it shows a multiselect. Space toggles a block and Enter confirms.

Adding a recipe

A recipe is a published, ordered stack of blocks. One command installs the whole set:

pnpm dlx blockend-cli add --recipe authenticated-api

The CLI installs the recipe's required blocks in the recipe's integration order. If the recipe lists optional blocks and you are not using --yes or --json, it asks which to include. Each block is installed with its normal variant selection, dependency installation, and import rewriting, so the result matches adding the blocks one by one. Blocks that do not support the configured framework are skipped and reported.

--recipe and --multi cannot be combined, and a recipe cannot be passed with a positional block name.

Behavior:

  • Requires a TypeScript project. JavaScript projects are rejected.
  • Filters blocks by the configured framework.
  • Asks for a storage variant when more than one exists.
  • In interactive mode, selects Redis automatically when includeRedis is true and a Redis variant exists. With --yes, it selects memory when available, otherwise the first variant.
  • Checks package.json for missing or conflicting dependencies. Installation uses pnpm add for pnpm projects and npm install for every other detected package manager.
  • Rewrites imports for aliases.blocks and importRewriteStrategy.
  • Records installed files in the installed array.

--yes does not supply a block name. add --yes without a block is an error.

list

List blocks available for the configured framework, or list published recipes.

pnpm dlx blockend-cli list [options]
OptionDefaultDescription
--jsonfalseWrite { success, environment, blocks } as JSON.
--recipesfalseList published recipes instead of blocks.
--cwdcwdTarget directory or workspace package.

--recipes writes { success, recipes } in JSON mode and does not require blockend.json. The block listing requires blockend.json and network access to GitHub.

detect

Report detected project settings.

pnpm dlx blockend-cli detect [options]
OptionDefaultDescription
--jsonfalseWrite the full detection result as JSON.
--cwdcwdTarget directory or workspace package.
FieldMeaning
frameworkDetected backend framework, or none.
languagetypescript or javascript.
packageManagernpm, pnpm, yarn, or bun.
srcDirDetected source directory path, such as the project's src/, app/, lib/, or root.
importRewriteStrategyrewrite (append .js) or remove (extensionless).
hasRedisRedis client found in dependencies.
hasPrismaPrisma found.
hasDrizzleDrizzle found.
workspaceWorkspace manager, root, and packages, when inside a monorepo.

detect does not require blockend.json.

diff

Preview files a block would write, without changing the project.

pnpm dlx blockend-cli diff <block> [options]
OptionDefaultDescription
[block]RequiredRegistry key to preview.
--jsonfalseWrite diff results as JSON.
--cwdcwdTarget directory or workspace package.

The output marks each file as new, modified, or unchanged. Modified files include a line diff.

doctor

Check the project and blockend.json for problems.

pnpm dlx blockend-cli doctor [options]
OptionDefaultDescription
--jsonfalseWrite check results as JSON.
--cwdcwdTarget directory or workspace package.

Checks include:

  • package.json and blockend.json
  • tsconfig.json presence
  • Lockfile for npm, pnpm, yarn, or bun
  • Framework detection
  • Workspace detection (single project or monorepo manager and package count)
  • Redis, Prisma, and Drizzle detection
  • environment and paths.blocks fields
  • Whether the blocks directory exists

In text mode, doctor exits with code 1 when it finds errors. In JSON mode it returns success: false with warnings and errors arrays.

update

Compare installed blocks with registry versions.

pnpm dlx blockend-cli update [options]
OptionDefaultDescription
--jsonfalseWrite update status as JSON.
--difftrueShow line diffs for blocks with updates.
--applyfalseSelect blocks and apply updates.
--cwdcwdTarget directory or workspace package.

Updates use the installed entries in blockend.json: block name, version, install time, files, and content hash. --apply asks which blocks to update, confirms before overwriting, downloads the new files, rewrites imports, and updates the installed metadata. In JSON mode it applies every available update without prompting.

mcp

Start the MCP server or write a client config.

pnpm dlx blockend-cli mcp
pnpm dlx blockend-cli mcp init [options]
OptionDefaultDescription
--clientPromptclaude, codex, cursor, vscode, or windsurf.
--dry-runfalsePrint the config without writing.
--forcefalseSkip the overwrite confirmation for an existing config.
--yesfalseSkip prompts and default to Claude Code.

The MCP server exposes list_blocks, detect_project, add_block, add_blocks, diff_block, doctor, update_check, and update_apply. See MCP server.

Monorepos

The CLI detects pnpm workspaces, npm/yarn workspaces, Lerna, and Nx layouts and enumerates their packages. Each package keeps its own blockend.json, and a block installs into the package that config belongs to.

Run commands from inside a package, or target one from the workspace root with -c, --cwd (the path is resolved from your current directory):

cd apps/api
pnpm dlx blockend-cli add rate-limiter

# or, from the workspace root:
pnpm dlx blockend-cli add rate-limiter -c apps/api

Run init at the workspace root and the CLI asks which package to target. A workspace that has a single package targets it automatically. If the chosen package has no blockend.json, run init in it first. When the root has several packages and is used non-interactively (for example with --json), the CLI lists the packages and the --cwd command to run instead of choosing one for you.

Requirements

  • Node.js 20 or newer
  • TypeScript project for add
  • A supported framework: Express, Fastify, Next.js App Router, or Hono
  • Network access to GitHub for registry commands
  • A package manager: npm, pnpm, yarn, or bun is detected

Framework-specific blocks appear only for matching frameworks. Universal blocks such as env-config and password-hash work with every framework.

On this page