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]| Option | Alias | Default | Description |
|---|---|---|---|
--yes | -y | false | Accept detected defaults and overwrite an existing config. |
--json | false | Write a JSON result instead of terminal output. | |
--cwd | -c | cwd | Target directory or workspace package. |
The command detects the framework, language, package manager, Redis, and tsconfig.json or jsconfig.json path aliases. It prompts for:
- Whether to keep, overwrite, or regenerate an existing config
- Blocks directory, defaulting to
src/blocksorblocks - Framework, when detection fails
- 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]| Option | Alias | Default | Description |
|---|---|---|---|
[block] | Registry key, such as rate-limiter or logger. | ||
--yes | -y | false | Skip prompts, install missing dependencies, and overwrite conflicts. |
--json | false | Write a JSON result. | |
--multi | -m | false | Select multiple blocks in one session. |
--recipe | Add every block in a published recipe, in its integration order. | ||
--cwd | -c | cwd | Target 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-apiThe 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
includeRedisis true and a Redis variant exists. With--yes, it selects memory when available, otherwise the first variant. - Checks
package.jsonfor missing or conflicting dependencies. Installation usespnpm addfor pnpm projects andnpm installfor every other detected package manager. - Rewrites imports for
aliases.blocksandimportRewriteStrategy. - Records installed files in the
installedarray.
--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]| Option | Default | Description |
|---|---|---|
--json | false | Write { success, environment, blocks } as JSON. |
--recipes | false | List published recipes instead of blocks. |
--cwd | cwd | Target 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]| Option | Default | Description |
|---|---|---|
--json | false | Write the full detection result as JSON. |
--cwd | cwd | Target directory or workspace package. |
| Field | Meaning |
|---|---|
framework | Detected backend framework, or none. |
language | typescript or javascript. |
packageManager | npm, pnpm, yarn, or bun. |
srcDir | Detected source directory path, such as the project's src/, app/, lib/, or root. |
importRewriteStrategy | rewrite (append .js) or remove (extensionless). |
hasRedis | Redis client found in dependencies. |
hasPrisma | Prisma found. |
hasDrizzle | Drizzle found. |
workspace | Workspace 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]| Option | Default | Description |
|---|---|---|
[block] | Required | Registry key to preview. |
--json | false | Write diff results as JSON. |
--cwd | cwd | Target 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]| Option | Default | Description |
|---|---|---|
--json | false | Write check results as JSON. |
--cwd | cwd | Target directory or workspace package. |
Checks include:
package.jsonandblockend.jsontsconfig.jsonpresence- Lockfile for npm, pnpm, yarn, or bun
- Framework detection
- Workspace detection (single project or monorepo manager and package count)
- Redis, Prisma, and Drizzle detection
environmentandpaths.blocksfields- 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]| Option | Default | Description |
|---|---|---|
--json | false | Write update status as JSON. |
--diff | true | Show line diffs for blocks with updates. |
--apply | false | Select blocks and apply updates. |
--cwd | cwd | Target 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]| Option | Default | Description |
|---|---|---|
--client | Prompt | claude, codex, cursor, vscode, or windsurf. |
--dry-run | false | Print the config without writing. |
--force | false | Skip the overwrite confirmation for an existing config. |
--yes | false | Skip 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/apiRun 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.