Agent to Bricks — Build & Deploy Bricks Pages

You have access to the

bricks

Quick Start Workflow

When the user asks you to build or update a Bricks page, follow these steps:

Step 1: Discover the site's design system

bricks discover --json

This returns the site's colors, fonts, spacing variables, CSS framework classes, available element types, and pages. Pay attention to:

• CSS variables (

  --primary

  ,

  --space-m

  ) — use these in your HTML
• Global classes (ACSS utilities) — add these as CSS classes
• Breakpoints — the site's responsive breakpoint widths

Step 2: Generate HTML using the site's design tokens

Write clean, semantic HTML that uses the site's CSS variables and class names. Structure your HTML with

<section>

<div>

Step 3: Convert and push to the site

# Convert HTML and push directly to a page
bricks convert html --push PAGE_ID --stdin <<'HTML'
<section>...</section>
HTML

# Or from a file
bricks convert html page.html --push PAGE_ID

# Preview without pushing (dry run)
bricks convert html --push PAGE_ID --dry-run --stdin <<'HTML'
<section>...</section>
HTML

# Snapshot before pushing (for rollback)
bricks convert html --push PAGE_ID --snapshot --stdin <<'HTML'
<section>...</section>
HTML

Step 4: Verify

# Use the REST API to check page elements (the CLI handles auth from config)
curl -s -H "X-ATB-Key: $(grep api_key ~/.agent-to-bricks/config.yaml | awk '{print $2}')" \
  "$(grep url ~/.agent-to-bricks/config.yaml | awk '{print $2}')/wp-json/agent-bricks/v1/pages/PAGE_ID/elements"

# Or just use --dry-run before pushing to preview the conversion
bricks convert html --push PAGE_ID --dry-run --stdin <<'HTML'
<section>...</section>
HTML

Patching Existing Elements (Preferred for Updates)

When you need to modify an existing page (change classes, text, styles), use

bricks patch

# Step 1: List elements to find IDs
bricks patch PAGE_ID --list
bricks patch PAGE_ID --list --json    # structured output

# Step 2: Patch specific settings by element ID
bricks patch PAGE_ID -e ELEMENT_ID --set '_cssClasses=new-class another'
bricks patch PAGE_ID -e ELEMENT_ID --set 'text=Updated Heading'
bricks patch PAGE_ID -e ELEMENT_ID --set '_display=flex' --set '_gap=var(--space-m)'

# Patch with JSON values (for nested settings like background, typography)
bricks patch PAGE_ID -e ELEMENT_ID --set '_background={"color":{"raw":"var(--primary)"}}'
bricks patch PAGE_ID -e ELEMENT_ID --set '_typography={"font-size":"var(--h2)","font-weight":"700"}'

# Remove a setting
bricks patch PAGE_ID -e ELEMENT_ID --rm '_padding'

# Multi-element patch via JSON stdin
echo '{"patches":[
  {"id":"abc123","settings":{"_cssClasses":"hero-dark"}},
  {"id":"def456","settings":{"text":"New text"}}
]}' | bricks patch PAGE_ID --stdin

# Preview without applying
bricks patch PAGE_ID -e ELEMENT_ID --set 'text=Preview' --dry-run

When to use patch vs convert:

• Patch: changing classes, text, styles, settings on existing elements
• Convert: creating new sections/pages from HTML

Available Commands

bricks discover --json

bricks convert html [file] --push ID

bricks convert html --stdin

bricks patch ID --list

bricks patch ID -e EL --set k=v

bricks elements types --json

bricks site info --json

bricks classes --json

bricks frameworks --json

bricks schema

Key Principles

1. Always call

   bricks discover --json

   first to learn the design system
2. Prefer

   bricks patch

   for updates — don't regenerate what you can patch
3. Use the site's CSS variables — not hardcoded values
4. Use ACSS global classes when available
5. Use

   --snapshot

   when pushing to important pages
6. Use

   --json

   on any command for structured output
7. Pipe HTML from stdin with

   --stdin

   for seamless workflow
8. Structure HTML as: section → div (container) → content elements

Element Mapping

Error Recovery

• 409 conflict: re-fetch elements and retry
• 401/403: check API key with

  bricks doctor

• Bad results: use

  --dry-run

  to inspect before pushing
• Undo:

  bricks elements PAGE_ID rollback SNAP_ID