Goal commands
Commands for creating and managing conversion goals.
add_goal
Creates a new conversion goal by passing goal properties as associative arguments. This is the CLI equivalent of the "Add goal" action in the Burst dashboard.
Usage:
wp burst add_goal --<property>=<value> [--<property>=<value> ...]
At least one property must be provided.
Arguments:
| Argument | Type | Required | Description |
|---|---|---|---|
--title | string | Recommended | Human-readable goal name shown in the dashboard |
--type | string | Recommended | Goal trigger type (see goal types below) |
--url | string | Conditional | Target URL. Required for page_visit and scroll_depth types |
--event_name | string | Conditional | Custom event name. Required for event type |
Goal types
| Type | Description | Required extra argument |
|---|---|---|
page_visit | Fires when a visitor lands on a specific page | --url |
scroll_depth | Fires when a visitor scrolls to a percentage of a specific page | --url |
event | Fires when a custom JavaScript event is triggered | --event_name |
outbound_link | Fires when a visitor clicks a link to an external domain | — |
file_download | Fires when a visitor clicks a file download link | — |
Active goal limit
The free version allows a fixed number of simultaneously active goals. When that limit is reached, add_goal does not create the goal and the underlying save fails — existing goals must be deactivated or deleted before a new one can be added. Only goals with the active status count toward the limit, so deactivating a goal frees a slot while preserving its historical statistics.
Pro - CreatorAvailable in the Creator tier
A valid Pro license lifts the active goal limit, allowing an unlimited number of active goals. See Goal conversion tracking.
Examples
Page visit goal:
wp burst add_goal --title="Thank you page" --type="page_visit" --url="/thank-you/"
Scroll depth goal:
wp burst add_goal --title="Blog scroll 50%" --type="scroll_depth" --url="/blog/"
Custom event goal:
wp burst add_goal --title="Video played" --type="event" --event_name="video_play"
Outbound link goal:
wp burst add_goal --title="External link clicks" --type="outbound_link"
Output on success:
Success: Goal added
Adding goals in a deployment script
Use wp burst add_goal to provision a standard set of goals on a fresh install as part of a setup script:
Show code
#!/usr/bin/env bash
set -e
wp burst add_goal --title="Purchase complete" --type="page_visit" --url="/checkout/order-received/"
wp burst add_goal --title="Contact form submitted" --type="page_visit" --url="/contact/thank-you/"
wp burst add_goal --title="Outbound links" --type="outbound_link"
echo "Goals provisioned."
Troubleshooting
Goal created but not appearing in the dashboard
Goals are stored immediately and should appear on the next dashboard load. If the goal is missing, confirm that --type matches one of the accepted values exactly. An unrecognised type may silently create a goal with no trigger.
Goal not added on the free version If the goal is not created, the site may have reached the free active goal limit. Deactivate or delete an existing active goal to free a slot, or activate a Pro license for unlimited active goals. Deactivating a goal keeps its recorded statistics while removing it from the active count.