BlocksWeb CLI

A command-line interface for managing BlocksWeb CMS workspaces, pages, and collections.

Features

• 🔐 Browser Authentication: One-time authentication via browser or API key
• 📄 Page Management: Create, update, delete, and list pages
• 📦 Collection Management: Manage data collections and schemas
• 🏢 Workspace Info: View workspace details and usage statistics
• 🎨 Interactive Mode: Guided prompts for complex operations
• 📱 JSON Support: Full JSON input/output support for automation

Installation

# Use with npx (recommended - no installation required)
npx @blocksweb/cli --help

# Or install globally
npm install -g @blocksweb/cli

# Or install in your project
npm install @blocksweb/cli

Quick Start

1. Set Environment Variable: Add your API key to your project

   export BLOCKSWEB_API_KEY="your-api-key-here"

2. List Pages: See all pages in your workspace

   npx @blocksweb/cli pages list

3. Create a Page: Add a new page to your site

   npx @blocksweb/cli create page "Homepage"

4. View Workspace: Check your workspace information

   npx @blocksweb/cli workspace info

Authentication

The CLI supports two authentication methods:

Environment Variable (Recommended)

export BLOCKSWEB_API_KEY="your-api-key-here"
npx @blocksweb/cli auth status

This uses your project's API key directly from the environment.

Check Authentication Status

npx @blocksweb/cli auth status

Logout

npx @blocksweb/cli auth logout

Commands

Pages

List Pages

# List all pages
blocksweb pages list

# Search pages
blocksweb pages list --search "about"

# JSON output
blocksweb pages list --json

Create Page

# Basic page creation
blocksweb create page "About Us"

# With custom slug and status
blocksweb create page "About Us" --slug about --status published

# With JSON content
blocksweb create page "Homepage" --content '{"title": "Welcome", "sections": []}'

# Interactive mode
blocksweb create page "Contact" --interactive

Update Page

# Update page by name, slug, or ID
blocksweb update page homepage --name "Home Page"

# Update status
blocksweb update page homepage --status published

# Update content
blocksweb update page homepage --content '{"title": "New Title"}'

# Interactive mode
blocksweb update page homepage --interactive

Delete Page

# Delete with confirmation
blocksweb pages delete homepage

# Force delete without confirmation
blocksweb pages delete homepage --force

Show Page Details

# Human-readable format
blocksweb pages show homepage

# JSON format
blocksweb pages show homepage --json

Collections

List Collections

# List all collections
blocksweb collections list

# Search collections
blocksweb collections list --search "products"

# JSON output
blocksweb collections list --json

Create Collection

# Basic collection
blocksweb collections create "Products"

# With schema
blocksweb collections create "Products" --schema '{"fields": [{"name": "title", "type": "text"}]}'

# Interactive mode
blocksweb collections create "Products" --interactive

Update Collection

# Update collection name
blocksweb collections update products --name "Product Catalog"

# Update schema
blocksweb collections update products --schema '{"fields": [{"name": "title", "type": "text"}, {"name": "price", "type": "number"}]}'

# Interactive mode
blocksweb collections update products --interactive

Delete Collection

# Delete with confirmation
blocksweb collections delete products

# Force delete
blocksweb collections delete products --force

Workspace

Show Workspace Info

# Human-readable format
blocksweb workspace info

# JSON format
blocksweb workspace info --json

List Workspace Collections

# List collections in workspace
blocksweb workspace collections

# JSON format
blocksweb workspace collections --json

MCP Server Integration

The CLI can automatically configure the BlocksWeb MCP (Model Context Protocol) server for Claude Code, enabling you to interact with your BlocksWeb CMS directly through natural language commands in Claude Code.

Install MCP Server

# Navigate to your project directory
cd /path/to/your/project

# Install MCP server (creates project-level configuration)
blocksweb mcp install

# Alternative command
blocksweb mcp setup

This command will:

1. Create .claude/config.json in your project directory (project-level configuration)
2. Create .claude/config.example.json for team members to copy
3. Create .claude/README.md with setup instructions
4. Automatically update .gitignore to exclude config.json (keeps your API key safe)
5. Configure the MCP server to use @blocksweb/mcp-server@latest for automatic updates
6. Use your API key from CLI settings or environment variable

Check MCP Status

# Check if MCP server is configured
blocksweb mcp status

Remove MCP Server

# Remove MCP server configuration
blocksweb mcp remove

# Alternative command
blocksweb mcp uninstall

Note: After installing or removing the MCP server, you need to restart Claude Code for the changes to take effect.

What is MCP?

MCP (Model Context Protocol) allows Claude Code to interact with BlocksWeb CMS directly. Once configured, you can:

• Create and manage pages through natural language commands
• Query and update collections
• Manage workspace settings
• All from within your Claude Code conversation

Team Collaboration

The project-level configuration enables better team collaboration:

1. Share the setup: Commit .claude/config.example.json and .claude/README.md to git
2. Keep secrets safe: .claude/config.json is automatically added to .gitignore
3. Easy onboarding: Team members copy config.example.json to config.json and add their API key
4. Per-project setup: Each project can have its own MCP configuration

Examples

Create a Blog Post Page

blocksweb create page "My First Blog Post" \\
  --slug "my-first-blog-post" \\
  --status draft \\
  --content '{
    "title": "My First Blog Post",
    "content": "This is the content of my first blog post",
    "author": "John Doe",
    "publishedAt": "2023-01-01"
  }'

Update Page to Published

blocksweb update page "my-first-blog-post" --status published

Create a Product Collection

blocksweb collections create "Products" --schema '{
  "fields": [
    {"name": "title", "type": "text", "required": true},
    {"name": "description", "type": "textarea", "required": false},
    {"name": "price", "type": "number", "required": true},
    {"name": "image", "type": "image", "required": false}
  ]
}'

Batch Operations with JSON

# Get all pages as JSON and process with jq
blocksweb pages list --json | jq '.[] | select(.status == "draft") | .name'

# Create multiple pages from a JSON file
cat pages.json | jq -r '.[] | "blocksweb create page \\"\\(.name)\\" --slug \\(.slug) --status \\(.status)"' | sh

Setting up Claude Code Integration

# Step 1: Authenticate with BlocksWeb
blocksweb auth set-key your-api-key-here

# Step 2: Install MCP server for Claude Code
blocksweb mcp install

# Step 3: Restart Claude Code

# Now you can interact with BlocksWeb directly in Claude Code!
# Example: "Create a new page called About Us with a hero section"

Configuration

The CLI stores configuration in ~/.blocksweb/ directory:

• Authentication tokens
• API keys
• Workspace preferences

API Integration

The CLI directly communicates with the BlocksWeb API at https://cloud.blocksweb.nl/api. All operations are performed via RESTful API calls with proper authentication headers.

Error Handling

The CLI provides detailed error messages and suggestions:

• Authentication errors guide you to re-authenticate
• Network errors show connection status
• API errors display server response messages
• Validation errors highlight specific issues

Development

# Clone the repository
git clone https://github.com/blocksweb/cli.git

# Install dependencies
npm install

# Build
npm run build

# Run locally
npm run start -- --help

Support

• Documentation: https://docs.blocksweb.com
• Issues: https://github.com/blocksweb/cli/issues
• Support: [email protected]

License

MIT License - see LICENSE file for details.