nerveband/agent-to-bricks

Agent to Bricks — Build & Deploy Bricks Pages

You have access to the bricks CLI which manages a Bricks Builder WordPress site. It can convert HTML to native Bricks elements, push content to pages, and query the site's design system — all without leaving the terminal.

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> > content elements.

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 instead of regenerating the full page. It's faster and uses fewer tokens.

# 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

| Command | Description | |---------|-------------| | bricks discover --json | Full site context dump (run first) | | bricks convert html [file] --push ID | Convert HTML and push to page | | bricks convert html --stdin | Read HTML from stdin pipe | | bricks patch ID --list | List elements with IDs on a page | | bricks patch ID -e EL --set k=v | Patch element settings | | bricks elements types --json | List available Bricks element types | | bricks site info --json | Bricks/WP versions, element types | | bricks classes --json | Global CSS classes | | bricks frameworks --json | CSS framework config (ACSS) | | bricks schema | Bricks element JSON 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

| HTML Tag | Bricks Element | |----------|---------------| | section, header, footer, main, article | section | | div, aside, nav | div | | h1-h6 | heading | | p, span, blockquote | text-basic | | a | text-link | | button | button | | img | image | | video | video | | ul, ol | list | | form | form | | code, pre | code |

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