Getting Started
Prerequisites
- Node.js 18+
- A WordPress theme or plugin where you want to install blocks
The blockstudio package on npm is at version 0.0.1. That release is a
placeholder: it only has an add command, which prints Adding block: <name> and exits without fetching anything, and it rejects init, list,
search, remove, --yes and --dry-run as unknown. The commands on these
pages describe the registry CLI in the Blockstudio repository
(packages/registry).
Initialize your project
Run init in the root of your theme or plugin:
npx blockstudio init
The CLI walks you through an interactive setup:
- Block directory: where blocks should be installed (default:
blockstudio) - Registries: add one or more registry URLs by name
This creates a blocks.json file:
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "blockstudio",
"registries": {
"ui": "https://blocks.example.com/registry.json"
}
}
You can also skip the interactive prompts:
npx blockstudio init --yes
This creates a blocks.json with defaults. You can edit it manually
afterwards.
Add a block
npx blockstudio add ui/tabs
The format is namespace/block, where namespace matches a key in your
registries config.
The CLI:
- Fetches the registry
- Finds the block
- Resolves any dependencies (e.g.
tabsdepends ontab-item) - Downloads all files
- Writes them to your block directory
If the block exists in only one registry, you can skip the namespace:
npx blockstudio add tabs
If it exists in multiple registries, the CLI prompts you to choose in a
terminal. Without a terminal, it stops with an error that lists the matching
registries, and --yes picks the first one in blocks.json order.
Add multiple blocks
npx blockstudio add ui/tabs ui/hero ui/accordion
All blocks are installed in a single run.
Preview before installing
npx blockstudio add ui/tabs --dry-run
This shows what would be installed without writing any files.
Browse available blocks
npx blockstudio list
npx blockstudio list ui
npx blockstudio search hero
list shows all blocks from all registries (or a specific one). search
does a case-insensitive substring match against block names, titles, and
descriptions.
Remove a block
npx blockstudio remove tabs
This deletes the block folder. In interactive mode, you’re prompted to
confirm. Pass --yes to skip the prompt.
CI and automation
init, add, and remove accept --yes to skip interactive prompts.
list and search never prompt and reject --yes as an unknown option.
When stdin is not a terminal (CI runners, piped input), the CLI falls back to
non-interactive mode: init overwrites an existing blocks.json, add
stops with an error when a block folder already exists or a block name is
ambiguous, and remove deletes without asking.
npx blockstudio init --yes --directory blockstudio
npx blockstudio add ui/tabs --yes
npx blockstudio remove tabs --yes