Getting Started

Prerequisites

• Node.js 18+
• A WordPress theme or plugin where you want to install blocks

Initialize your project

Run init in the root of your theme or plugin:

npx blockstudio init

The CLI walks you through an interactive setup:

1. Block directory: where blocks should be installed (default: blockstudio)
2. 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:

1. Fetches the registry
2. Finds the block
3. Resolves any dependencies (e.g. tabs depends on tab-item)
4. Downloads all files
5. 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.

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 fuzzy match across 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

All commands support --yes to skip interactive prompts. In non-TTY environments (piped output, CI runners), the CLI automatically falls back to non-interactive mode.

npx blockstudio init --yes --directory blockstudio
npx blockstudio add ui/tabs --yes
npx blockstudio remove tabs --yes