crawl4ai/docs/md_v2/api/c4a-script-reference.md

C4A-Script API Reference

Complete reference for all C4A-Script commands, syntax, and advanced features.

Command Categories

🧭 Navigation Commands

Navigate between pages and manage browser history.

GO <url>

Navigate to a specific URL.

Syntax:

GO <url>

Parameters:

• url - Target URL (string)

Examples:

GO https://example.com
GO https://api.example.com/login
GO /relative/path

Notes:

• Supports both absolute and relative URLs
• Automatically handles protocol detection
• Waits for page load to complete

---

RELOAD

Refresh the current page.

Syntax:

RELOAD

Examples:

RELOAD

Notes:

• Equivalent to pressing F5 or clicking browser refresh
• Waits for page reload to complete
• Preserves current URL

---

BACK

Navigate back in browser history.

Syntax:

BACK

Examples:

BACK

Notes:

• Equivalent to clicking browser back button
• Does nothing if no previous page exists
• Waits for navigation to complete

---

FORWARD

Navigate forward in browser history.

Syntax:

FORWARD

Examples:

FORWARD

Notes:

• Equivalent to clicking browser forward button
• Does nothing if no next page exists
• Waits for navigation to complete

⏱️ Wait Commands

Control timing and synchronization with page elements.

WAIT <time>

Wait for a specified number of seconds.

Syntax:

WAIT <seconds>

Parameters:

• seconds - Number of seconds to wait (number)

Examples:

WAIT 3
WAIT 1.5
WAIT 10

Notes:

• Accepts decimal values
• Useful for giving dynamic content time to load
• Non-blocking for other browser operations

---

WAIT <selector> <timeout>

Wait for an element to appear on the page.

Syntax:

WAIT `<selector>` <timeout>

Parameters:

• selector - CSS selector for the element (string in backticks)
• timeout - Maximum seconds to wait (number)

Examples:

WAIT `#content` 10
WAIT `.loading-spinner` 5
WAIT `button[type="submit"]` 15
WAIT `.results .item:first-child` 8

Notes:

• Fails if element doesn't appear within timeout
• More reliable than fixed time waits
• Supports complex CSS selectors

---

WAIT "<text>" <timeout>

Wait for specific text to appear anywhere on the page.

Syntax:

WAIT "<text>" <timeout>

Parameters:

• text - Text content to wait for (string in quotes)
• timeout - Maximum seconds to wait (number)

Examples:

WAIT "Loading complete" 10
WAIT "Welcome back" 5
WAIT "Search results" 15

Notes:

• Case-sensitive text matching
• Searches entire page content
• Useful for dynamic status messages

🖱️ Mouse Commands

Simulate mouse interactions and movements.

CLICK <selector>

Click on an element specified by CSS selector.

Syntax:

CLICK `<selector>`

Parameters:

• selector - CSS selector for the element (string in backticks)

Examples:

CLICK `#submit-button`
CLICK `.menu-item:first-child`
CLICK `button[data-action="save"]`
CLICK `a[href="/dashboard"]`

Notes:

• Waits for element to be clickable
• Scrolls element into view if necessary
• Handles overlapping elements intelligently

---

CLICK <x> <y>

Click at specific coordinates on the page.

Syntax:

CLICK <x> <y>

Parameters:

• x - X coordinate in pixels (number)
• y - Y coordinate in pixels (number)

Examples:

CLICK 100 200
CLICK 500 300
CLICK 0 0

Notes:

• Coordinates are relative to viewport
• Useful when element selectors are unreliable
• Consider responsive design implications

---

DOUBLE_CLICK <selector>

Double-click on an element.

Syntax:

DOUBLE_CLICK `<selector>`

Parameters:

• selector - CSS selector for the element (string in backticks)

Examples:

DOUBLE_CLICK `.file-icon`
DOUBLE_CLICK `#editable-cell`
DOUBLE_CLICK `.expandable-item`

Notes:

• Triggers dblclick event
• Common for opening files or editing inline content
• Timing between clicks is automatically handled

---

RIGHT_CLICK <selector>

Right-click on an element to open context menu.

Syntax:

RIGHT_CLICK `<selector>`

Parameters:

• selector - CSS selector for the element (string in backticks)

Examples:

RIGHT_CLICK `#context-target`
RIGHT_CLICK `.menu-trigger`
RIGHT_CLICK `img.thumbnail`

Notes:

• Opens browser/application context menu
• Useful for testing context menu interactions
• May be blocked by some applications

---

SCROLL <direction> <amount>

Scroll the page in a specified direction.

Syntax:

SCROLL <direction> <amount>

Parameters:

• direction - Direction to scroll: UP, DOWN, LEFT, RIGHT
• amount - Number of pixels to scroll (number)

Examples:

SCROLL DOWN 500
SCROLL UP 200
SCROLL LEFT 100
SCROLL RIGHT 300

Notes:

• Smooth scrolling animation
• Useful for infinite scroll pages
• Amount can be larger than viewport

---

MOVE <x> <y>

Move mouse cursor to specific coordinates.

Syntax:

MOVE <x> <y>

Parameters:

• x - X coordinate in pixels (number)
• y - Y coordinate in pixels (number)

Examples:

MOVE 200 100
MOVE 500 400

Notes:

• Triggers hover effects
• Useful for testing mouseover interactions
• Does not click, only moves cursor

---

DRAG <x1> <y1> <x2> <y2>

Drag from one point to another.

Syntax:

DRAG <x1> <y1> <x2> <y2>

Parameters:

• x1, y1 - Starting coordinates (numbers)
• x2, y2 - Ending coordinates (numbers)

Examples:

DRAG 100 100 500 300
DRAG 0 200 400 200

Notes:

• Simulates click, drag, and release
• Useful for sliders, resizing, reordering
• Smooth drag animation

⌨️ Keyboard Commands

Simulate keyboard input and key presses.

TYPE "<text>"

Type text into the currently focused element.

Syntax:

TYPE "<text>"

Parameters:

• text - Text to type (string in quotes)

Examples:

TYPE "Hello, World!"
TYPE "user@example.com"
TYPE "Password123!"

Notes:

• Requires an input element to be focused
• Types character by character with realistic timing
• Supports special characters and Unicode

---

TYPE $<variable>

Type the value of a variable.

Syntax:

TYPE $<variable>

Parameters:

• variable - Variable name (without quotes)

Examples:

SETVAR email = "user@example.com"
TYPE $email

Notes:

• Variable must be defined with SETVAR first
• Variable values are strings
• Useful for reusable credentials or data

---

PRESS <key>

Press and release a special key.

Syntax:

PRESS <key>

Parameters:

• key - Key name (see supported keys below)

Supported Keys:

• Tab, Enter, Escape, Space
• ArrowUp, ArrowDown, ArrowLeft, ArrowRight
• Delete, Backspace
• Home, End, PageUp, PageDown

Examples:

PRESS Tab
PRESS Enter
PRESS Escape
PRESS ArrowDown

Notes:

• Simulates actual key press and release
• Useful for form navigation and shortcuts
• Case-sensitive key names

---

KEY_DOWN <key>

Hold down a modifier key.

Syntax:

KEY_DOWN <key>

Parameters:

• key - Modifier key: Shift, Control, Alt, Meta

Examples:

KEY_DOWN Shift
KEY_DOWN Control

Notes:

• Must be paired with KEY_UP
• Useful for key combinations
• Meta key is Cmd on Mac, Windows key on PC

---

KEY_UP <key>

Release a modifier key.

Syntax:

KEY_UP <key>

Parameters:

• key - Modifier key: Shift, Control, Alt, Meta

Examples:

KEY_UP Shift
KEY_UP Control

Notes:

• Must be paired with KEY_DOWN
• Releases the specified modifier key
• Good practice to always release held keys

---

CLEAR <selector>

Clear the content of an input field.

Syntax:

CLEAR `<selector>`

Parameters:

• selector - CSS selector for input element (string in backticks)

Examples:

CLEAR `#search-box`
CLEAR `input[name="email"]`
CLEAR `.form-input:first-child`

Notes:

• Works with input, textarea elements
• Faster than selecting all and deleting
• Triggers appropriate change events

---

SET <selector> "<value>"

Set the value of an input field directly.

Syntax:

SET `<selector>` "<value>"

Parameters:

• selector - CSS selector for input element (string in backticks)
• value - Value to set (string in quotes)

Examples:

SET `#email` "user@example.com"
SET `#age` "25"
SET `textarea#message` "Hello, this is a test message."

Notes:

• Directly sets value without typing animation
• Faster than TYPE for long text
• Triggers change and input events

🔀 Control Flow Commands

Add conditional logic and loops to your scripts.

IF (EXISTS <selector>) THEN <command>

Execute command if element exists.

Syntax:

IF (EXISTS `<selector>`) THEN <command>

Parameters:

• selector - CSS selector to check (string in backticks)
• command - Command to execute if condition is true

Examples:

IF (EXISTS `.cookie-banner`) THEN CLICK `.accept-cookies`
IF (EXISTS `#popup-modal`) THEN CLICK `.close-button`
IF (EXISTS `.error-message`) THEN RELOAD

Notes:

• Checks for element existence at time of execution
• Does not wait for element to appear
• Can be combined with ELSE

---

IF (EXISTS <selector>) THEN <command> ELSE <command>

Execute command based on element existence.

Syntax:

IF (EXISTS `<selector>`) THEN <command> ELSE <command>

Parameters:

• selector - CSS selector to check (string in backticks)
• First command - Execute if condition is true
• Second command - Execute if condition is false

Examples:

IF (EXISTS `.user-menu`) THEN CLICK `.logout` ELSE CLICK `.login`
IF (EXISTS `.loading`) THEN WAIT 5 ELSE CLICK `#continue`

Notes:

• Exactly one command will be executed
• Useful for handling different page states
• Commands must be on same line

---

IF (NOT EXISTS <selector>) THEN <command>

Execute command if element does not exist.

Syntax:

IF (NOT EXISTS `<selector>`) THEN <command>

Parameters:

• selector - CSS selector to check (string in backticks)
• command - Command to execute if element doesn't exist

Examples:

IF (NOT EXISTS `.logged-in`) THEN GO /login
IF (NOT EXISTS `.results`) THEN CLICK `#search-button`

Notes:

• Inverse of EXISTS condition
• Useful for error handling
• Can check for missing required elements

---

IF (<javascript>) THEN <command>

Execute command based on JavaScript condition.

Syntax:

IF (`<javascript>`) THEN <command>

Parameters:

• javascript - JavaScript expression that returns boolean (string in backticks)
• command - Command to execute if condition is true

Examples:

IF (`window.innerWidth < 768`) THEN CLICK `.mobile-menu`
IF (`document.readyState === "complete"`) THEN CLICK `#start`
IF (`localStorage.getItem("user")`) THEN GO /dashboard

Notes:

• JavaScript executes in browser context
• Must return boolean value
• Access to all browser APIs and globals

---

REPEAT (<command>, <count>)

Repeat a command a specific number of times.

Syntax:

REPEAT (<command>, <count>)

Parameters:

• command - Command to repeat
• count - Number of times to repeat (number)

Examples:

REPEAT (SCROLL DOWN 300, 5)
REPEAT (PRESS Tab, 3)
REPEAT (CLICK `.load-more`, 10)

Notes:

• Executes command exactly count times
• Useful for pagination, scrolling, navigation
• No delay between repetitions (add WAIT if needed)

---

REPEAT (<command>, <condition>)

Repeat a command while condition is true.

Syntax:

REPEAT (<command>, `<condition>`)

Parameters:

• command - Command to repeat
• condition - JavaScript condition to check (string in backticks)

Examples:

REPEAT (SCROLL DOWN 500, `document.querySelector(".load-more")`)
REPEAT (PRESS ArrowDown, `window.scrollY < document.body.scrollHeight`)

Notes:

• Condition checked before each iteration
• JavaScript condition must return boolean
• Be careful to avoid infinite loops

💾 Variables and Data

Store and manipulate data within scripts.

SETVAR <name> = "<value>"

Create or update a variable.

Syntax:

SETVAR <name> = "<value>"

Parameters:

• name - Variable name (alphanumeric, underscore)
• value - Variable value (string in quotes)

Examples:

SETVAR username = "john@example.com"
SETVAR password = "secret123"
SETVAR base_url = "https://api.example.com"
SETVAR counter = "0"

Notes:

• Variables are global within script scope
• Values are always strings
• Can be used with TYPE command using $variable syntax

---

EVAL <javascript>

Execute arbitrary JavaScript code.

Syntax:

EVAL `<javascript>`

Parameters:

• javascript - JavaScript code to execute (string in backticks)

Examples:

EVAL `console.log("Script started")`
EVAL `window.scrollTo(0, 0)`
EVAL `localStorage.setItem("test", "value")`
EVAL `document.title = "Automated Test"`

Notes:

• Full access to browser JavaScript APIs
• Useful for custom logic and debugging
• Return values are not captured
• Be careful with security implications

📝 Comments and Documentation

# <comment>

Add comments to scripts for documentation.

Syntax:

# <comment text>

Examples:

# This script logs into the application
# Step 1: Navigate to login page
GO /login

# Step 2: Fill credentials
TYPE "user@example.com"

Notes:

• Comments are ignored during execution
• Useful for documentation and debugging
• Can appear anywhere in script
• Supports multi-line documentation blocks

🔧 Procedures (Advanced)

Define reusable command sequences.

PROC <name> ... ENDPROC

Define a reusable procedure.

Syntax:

PROC <name>
  <commands>
ENDPROC

Parameters:

• name - Procedure name (alphanumeric, underscore)
• commands - Commands to include in procedure

Examples:

PROC login
  CLICK `#email`
  TYPE $email
  CLICK `#password`
  TYPE $password
  CLICK `#submit`
ENDPROC

PROC handle_popups
  IF (EXISTS `.cookie-banner`) THEN CLICK `.accept`
  IF (EXISTS `.newsletter-modal`) THEN CLICK `.close`
ENDPROC

Notes:

• Procedures must be defined before use
• Support nested command structures
• Variables are shared with main script scope

---

<procedure_name>

Call a defined procedure.

Syntax:

<procedure_name>

Examples:

# Define procedure first
PROC setup
  GO /login
  WAIT `#form` 5
ENDPROC

# Call procedure
setup
login

Notes:

• Procedure must be defined before calling
• Can be called multiple times
• No parameters supported (use variables instead)

Error Handling Best Practices

1. Always Use Waits

# Bad - element might not be ready
CLICK `#button`

# Good - wait for element first
WAIT `#button` 5
CLICK `#button`

2. Handle Optional Elements

# Check before interacting
IF (EXISTS `.popup`) THEN CLICK `.close`
IF (EXISTS `.cookie-banner`) THEN CLICK `.accept`

# Then proceed with main flow
CLICK `#main-action`

3. Use Descriptive Variables

# Set up reusable data
SETVAR admin_email = "admin@company.com"
SETVAR test_password = "TestPass123!"
SETVAR staging_url = "https://staging.example.com"

# Use throughout script
GO $staging_url
TYPE $admin_email

4. Add Debugging Information

# Log progress
EVAL `console.log("Starting login process")`
GO /login

# Verify page state
IF (`document.title.includes("Login")`) THEN EVAL `console.log("On login page")`

# Continue with login
TYPE $username

Common Patterns

Login Flow

# Complete login automation
SETVAR email = "user@example.com"
SETVAR password = "mypassword"

GO /login
WAIT `#login-form` 5

# Handle optional cookie banner
IF (EXISTS `.cookie-banner`) THEN CLICK `.accept-cookies`

# Fill and submit form
CLICK `#email`
TYPE $email
PRESS Tab
TYPE $password
CLICK `button[type="submit"]`

# Wait for redirect
WAIT `.dashboard` 10

Infinite Scroll

# Load all content with infinite scroll
GO /products

# Scroll and load more content
REPEAT (SCROLL DOWN 500, `document.querySelector(".load-more")`)

# Alternative: Fixed number of scrolls
REPEAT (SCROLL DOWN 800, 10)
WAIT 2

Form Validation

# Handle form with validation
SET `#email` "invalid-email"
CLICK `#submit`

# Check for validation error
IF (EXISTS `.error-email`) THEN SET `#email` "valid@example.com"

# Retry submission
CLICK `#submit`
WAIT `.success-message` 5

Multi-step Process

# Complex multi-step workflow
PROC navigate_to_step
  CLICK `.next-button`
  WAIT `.step-content` 5
ENDPROC

# Step 1
WAIT `.step-1` 5
SET `#name` "John Doe"
navigate_to_step

# Step 2
SET `#email` "john@example.com"
navigate_to_step

# Step 3
CLICK `#submit-final`
WAIT `.confirmation` 10

Integration with Crawl4AI

Use C4A-Script with Crawl4AI for dynamic content interaction:

from crawl4ai import AsyncWebCrawler, CrawlerRunConfig

# Define interaction script
script = """
# Handle dynamic content loading
WAIT `.content` 5
IF (EXISTS `.load-more-button`) THEN CLICK `.load-more-button`
WAIT `.additional-content` 5

# Accept cookies if needed
IF (EXISTS `.cookie-banner`) THEN CLICK `.accept-all`
"""

config = CrawlerRunConfig(
    c4a_script=script,
    wait_for=".content",
    screenshot=True
)

async with AsyncWebCrawler() as crawler:
    result = await crawler.arun("https://example.com", config=config)
    print(result.markdown)

This reference covers all available C4A-Script commands and patterns. For interactive learning, try the tutorial or live demo.