docs/md_v2/core/c4a-script.md
C4A-Script is a powerful, human-readable domain-specific language (DSL) designed for web automation and interaction. Think of it as a simplified programming language that anyone can read and write, perfect for automating repetitive web tasks, testing user interfaces, or creating interactive demos.
Simple Syntax, Powerful Results
# Navigate and interact in plain English
GO https://example.com
WAIT `#search-box` 5
TYPE "Hello World"
CLICK `button[type="submit"]`
Visual Programming Support C4A-Script comes with a built-in Blockly visual editor, allowing you to create scripts by dragging and dropping blocks - no coding experience required!
Perfect for:
Let's create a simple script that searches for something on a website:
# My first C4A-Script
GO https://duckduckgo.com
# Wait for the search box to appear
WAIT `input[name="q"]` 10
# Type our search query
TYPE "Crawl4AI"
# Press Enter to search
PRESS Enter
# Wait for results
WAIT `.results` 5
That's it! In just a few lines, you've automated a complete search workflow.
Want to learn by doing? We've got you covered:
🚀 Live Demo - Try C4A-Script in your browser right now!
📁 Tutorial Examples - Complete examples with source code
The tutorial includes a Flask-based web interface with:
# Clone and navigate to the tutorial
cd docs/examples/c4a_script/tutorial/
# Install dependencies
pip install -r requirements.txt
# Launch the tutorial server
python server.py
# Open http://localhost:8000 in your browser
C4A-Script uses simple, English-like commands. Each command does one specific thing:
# Comments start with #
COMMAND parameter1 parameter2
# Most commands use CSS selectors in backticks
CLICK `#submit-button`
# Text content goes in quotes
TYPE "Hello, World!"
# Numbers are used directly
WAIT 3
C4A-Script uses CSS selectors to identify elements on the page:
# By ID
CLICK `#login-button`
# By class
CLICK `.submit-btn`
# By attribute
CLICK `button[type="submit"]`
# By accessible attributes
CLICK `button[aria-label="Search"][title="Search"]`
# Complex selectors
CLICK `.form-container input[name="email"]`
Store and reuse values with variables:
# Set a variable
SETVAR username = "[email protected]"
SETVAR password = "secret123"
# Use variables (prefix with $)
TYPE $username
PRESS Tab
TYPE $password
Move around the web like a user would:
| Command | Purpose | Example |
|---|---|---|
GO | Navigate to URL | GO https://example.com |
RELOAD | Refresh current page | RELOAD |
BACK | Go back in history | BACK |
FORWARD | Go forward in history | FORWARD |
Ensure elements are ready before interacting:
| Command | Purpose | Example |
|---|---|---|
WAIT | Wait for time/element/text | WAIT 3 or WAIT \#element` 10` |
Click, drag, and move like a human:
| Command | Purpose | Example |
|---|---|---|
CLICK | Click element or coordinates | CLICK \button`orCLICK 100 200` |
DOUBLE_CLICK | Double-click element | DOUBLE_CLICK \.item`` |
RIGHT_CLICK | Right-click element | RIGHT_CLICK \#menu`` |
SCROLL | Scroll in direction | SCROLL DOWN 500 |
DRAG | Drag from point to point | DRAG 100 100 500 300 |
Type text and press keys naturally:
| Command | Purpose | Example |
|---|---|---|
TYPE | Type text or variable | TYPE "Hello" or TYPE $username |
PRESS | Press special keys | PRESS Tab or PRESS Enter |
CLEAR | Clear input field | CLEAR \#search`` |
SET | Set input value directly | SET \#email` "[email protected]"` |
Add logic and repetition to your scripts:
| Command | Purpose | Example |
|---|---|---|
IF | Conditional execution | IF (EXISTS \#popup`) THEN CLICK `#close`` |
REPEAT | Loop commands | REPEAT (SCROLL DOWN 300, 5) |
Store data and execute custom code:
| Command | Purpose | Example |
|---|---|---|
SETVAR | Create variable | SETVAR email = "[email protected]" |
EVAL | Execute JavaScript | EVAL \console.log('Hello')`` |
# Complete login automation
GO https://myapp.com/login
# Wait for page to load
WAIT `#login-form` 5
# Fill credentials
CLICK `#email`
TYPE "[email protected]"
PRESS Tab
TYPE "mypassword"
# Submit form
CLICK `button[type="submit"]`
# Wait for dashboard
WAIT `.dashboard` 10
# Shopping automation with variables
SETVAR product = "laptop"
SETVAR budget = "1000"
GO https://shop.example.com
WAIT `#search-box` 3
# Search for product
TYPE $product
PRESS Enter
WAIT `.product-list` 5
# Filter by price
CLICK `.price-filter`
SET `#max-price` $budget
CLICK `.apply-filters`
# Select first result
WAIT `.product-item` 3
CLICK `.product-item:first-child`
# Smart form filling with error handling
GO https://forms.example.com
# Check if user is already logged in
IF (EXISTS `.user-menu`) THEN GO https://forms.example.com/new
IF (NOT EXISTS `.user-menu`) THEN CLICK `#login-link`
# Fill form
WAIT `#contact-form` 5
SET `#name` "John Doe"
SET `#email` "[email protected]"
SET `#message` "Hello from C4A-Script!"
# Handle popup if it appears
IF (EXISTS `.cookie-banner`) THEN CLICK `.accept-cookies`
# Submit
CLICK `#submit-button`
WAIT `.success-message` 10
C4A-Script includes a powerful visual programming interface built on Google Blockly. Perfect for:
Try the visual editor in our live demo or local tutorial.
The tutorial interface includes a recording feature that watches your browser interactions and automatically generates C4A-Script commands:
C4A-Script provides clear error messages and debugging information:
# Use comments for debugging
# This will wait up to 10 seconds for the element
WAIT `#slow-loading-element` 10
# Check if element exists before clicking
IF (EXISTS `#optional-button`) THEN CLICK `#optional-button`
# Use EVAL for custom debugging
EVAL `console.log("Current page title:", document.title)`
C4A-Script integrates seamlessly with Crawl4AI's web crawling capabilities:
from crawl4ai import AsyncWebCrawler, CrawlerRunConfig
# Use C4A-Script for interaction before crawling
script = """
GO https://example.com
CLICK `#load-more-content`
WAIT `.dynamic-content` 5
"""
config = CrawlerRunConfig(
js_code=script,
wait_for=".dynamic-content"
)
async with AsyncWebCrawler() as crawler:
result = await crawler.arun("https://example.com", config=config)
print(result.markdown)
# Bad: Clicking immediately
CLICK `#button`
# Good: Wait for element to appear
WAIT `#button` 5
CLICK `#button`
# Login to user account
GO https://myapp.com/login
WAIT `#login-form` 5
# Enter credentials
TYPE "[email protected]"
PRESS Tab
TYPE "password123"
# Submit and wait for redirect
CLICK `#submit-button`
WAIT `.dashboard` 10
# Handle different page states
IF (EXISTS `.cookie-banner`) THEN CLICK `.accept-cookies`
IF (EXISTS `.popup-modal`) THEN CLICK `.close-modal`
# Proceed with main workflow
CLICK `#main-action`
# Define once, use everywhere
SETVAR base_url = "https://myapp.com"
SETVAR test_email = "[email protected]"
GO $base_url/login
SET `#email` $test_email
Ready to dive deeper? Check out:
C4A-Script makes web automation accessible to everyone. Whether you're a developer automating tests, a designer creating interactive demos, or a business user streamlining repetitive tasks, C4A-Script has the tools you need.
Start automating today - your future self will thank you! 🚀