blueprints-cli

A tool for generating files and directories from reusable templates called blueprints. Commonly used to scaffold components, services, configurations, and other repeatable file structures.

Installation

npm install -g @codetools/blueprints-cli

Quick Start

# 1. Create a blueprint
bp new -g myBlueprint

# 2. Add template files to ~/.blueprints/myBlueprint/files/

# 3. Generate from the blueprint
bp generate myBlueprint MyInstance

Commands

| Command | Description | Options | | ------- | ----------- | ------- | | generate\|g <blueprint> <instance> | Generate files from a blueprint. Extra key=value args supply template data. | -d, --dest <dir>: Output directory.--dry-run: Preview without writing.--json: Machine-readable output. | | info\|i <blueprint> | Inspect a blueprint and list its required variables. | --json | | list\|ls [namespace] | List all available blueprints. | -l, --long: Show descriptions.--json | | new <blueprint> | Create a new blueprint template. | -g, --global: Create globally.-s, --source <path>: Seed from a directory.--json | | import <globalBlueprint> [localBlueprint] | Copy a global blueprint into the current project. | --json | | remove\|rm <blueprint> | Remove a blueprint. | -g, --global: Remove from global store.--json | | init [projectPath] | Initialize a .blueprints directory in a project. | --json | | ask\|a <blueprint> <instance> | Generate files using AI and blueprint prompts. | -d, --dest <dir>-m, --model <id> | | models\|md | List configured AI model ids, providers, and model names. | — |

The global --json flag is supported on all commands except ask and models. When set, output is emitted as structured JSON to stdout; errors are emitted as { "error": { "code", "message" } } to stderr with exit code 1.

Example

# Inspect a blueprint first
bp info statusReport --json

# Generate with template data
bp generate statusReport ProjectAlpha projectName="Project Alpha" status="On Track" date=2023-12-08

MCP Server (Agent Integration)

blueprints-cli ships an MCP server so AI agents (Claude Code, Claude Desktop, etc.) can call blueprint operations directly without shell execution.

Recommended — zero-install via npx:

{
  "mcpServers": {
    "blueprints": {
      "command": "npx",
      "args": ["-y", "-p", "@codetools/blueprints-cli", "bp-mcp"]
    }
  }
}

Working inside this repo? An .mcp.json is included at the project root — compatible clients connect automatically with no extra setup.

See Agent Integration for all setup options, available tools, and CLI JSON mode.

Documentation

• Blueprint Structure — directory layout, blueprint.json schema, template syntax, lifecycle hooks
• Template Variables — {{ var }} / __var__ patterns and auto-generated metadata
• AI Generation — bp ask, model configuration, prompt files
• Agent Integration — --json, --dry-run, bp info, MCP server
• Examples — full worked examples