Segmentation

Move Audiences Between Salesforce Orgs with the sf CLI

Build and test audiences in a sandbox, then copy them to production with one command. Meet sf-plugin-cab, our open-source sf CLI plugin: what it copies, how the import stays safe, and how to run it in CI.

A white architectural model on a studio table in front of the identical full-size building outside the window – moving audiences between Salesforce orgs

You build and test your audiences in a sandbox. Then go-live comes, and someone rebuilds every one of them in production – click by click, filter by filter, hoping nothing gets lost on the way. With sf-plugin-cab, our open-source plugin for the Salesforce CLI, that is one command: it copies Campaign Audience Builder audiences from one org to another, shows you exactly what it will change first, and backs up the target before it touches anything.

The plugin is free, open source (Apache-2.0) and uses the org aliases your sf CLI already knows – no extra login, no extra tool.


When you need it

  • Go-live: copy the audiences you built and tested in a sandbox to production.
  • Keep orgs in step: bring a UAT org up to date with production, or the other way round.
  • Version control: export audience definitions to a JSON file, commit it, and import it from a pipeline.

What gets copied – and what stays

What Details
Copied Audience definitions (filters, sequence components, folder), plus the folders, Filter Library templates and outcome definitions they need. Audiences used by a Combination or Waterfall audience come along automatically.
Not copied Schedules, scheduled actions, final actions, run results and campaign members. These stay in each org.
Never changed in the target Existing folders, templates and outcome definitions. Target audiences that are not in the file are not deleted.

That split is deliberate: the plugin moves the logic of your audiences. What happens in each org – when an audience runs, which campaign it fills – stays under that org’s control.

Install in two commands

You need a current sf CLI (Node 22 or newer – run sf update), an alias for each org, Campaign Audience Builder installed in both orgs and, in the target org, create, edit and delete access to the CAB objects. The permission set CampaignAudienceBuilderUser provides that.

The sf CLI asks before installing a plugin that Salesforce did not sign. Allowlist it first to skip the prompt, then install:

sf plugins trust allowlist add --name @campaign-audience-builder/sf-plugin-cab
sf plugins install @campaign-audience-builder/sf-plugin-cab

To update later: sf plugins update.

Your first migration in three commands

# 1. See which audiences the source org has.
sf cab audience list -o uat

# 2. Preview what an import into production would change. This changes nothing.
sf cab audience migrate --source-org uat --target-org prod --all --dry-run

# 3. Copy the audiences. The plan is shown once more, and you confirm before anything is written.
sf cab audience migrate --source-org uat --target-org prod --all

The plan screen shows the target org, how many audiences will be created, updated and skipped, and any problems it found. Instead of --all, you can select audiences by name (--name) or by folder (--folder "Marketing/EMEA") – or leave the flag out and pick them from a list.

Prefer two steps, for example to review the file before go-live? export and import do the same job separately:

sf cab audience export -o uat --all --output-file golive.json
sf cab audience import -o prod --file golive.json --dry-run
sf cab audience import -o prod --file golive.json

Why the import is safe to run

Moving configuration into production is exactly the moment you don’t want surprises. The import is built around that:

  1. Plan first. Every import shows what it will create, update and skip before it changes anything. --dry-run stops right there.
  2. Backup before the first change. The import writes the target audiences it will update to a file such as cab-backup-prod-20261014-1412.json. Importing that file restores their previous definitions.
  3. One transaction per audience. If any part of an audience fails, that audience stays exactly as it was in the target.
  4. Links stay intact. Updates keep the target audience’s version and sequence components, so its schedules, run history and campaign members stay connected.
  5. Repeatable. Unchanged audiences are not written. If the connection drops mid-import, run the same command again – audiences already imported are skipped.
  6. Warnings where orgs differ. Filter values that look like record Ids trigger a warning, because an Id from the sandbox may point to nothing – or to the wrong record – in production.

Audiences in version control and CI

Because an export is a plain JSON file, audience definitions can live in Git next to the rest of your Salesforce metadata. In a pipeline, every question the import would ask is answered by a flag. If a required answer is missing, the command stops before changing anything and names the flag it needs:

sf cab audience import -o prod --file audiences/golive.json \
  --missing-folders create \
  --missing-templates create \
  --missing-outcomes create \
  --template-defaults clear \
  --yes --json

The exit code tells the pipeline what happened:

Exit code Meaning
0 All audiences were imported or are unchanged.
1 Nothing changed – an error or a “no” answer.
68 Some audiences were imported, some failed or were skipped.

Checklist before go-live

  • API names: audiences without an API name are skipped by the export. Set one in the source org first – it’s also how the import matches audiences in the target.
  • Schedules: they are not copied. Plan to set them up in production after the import.
  • Default templates: a template that is a default in the source would apply to every new audience in the target. The import asks before keeping it as a default; the default answer is no.
  • Locked templates: CAB only lets its own interface create a Locked template link. If the import can’t create one, the audience is imported without it and you get a warning – link the template again in the target.
  • Outcome definitions: a newly created outcome definition brings its definition, latest version and conditions. Cohorts, control groups and measurements stay in the source org.
  • Record Ids in filters: check every Id warning and replace sandbox Ids with production values.

Get started

The plugin, its full documentation and every flag (--help on each command) are on GitHub: sf-plugin-cab. The short version for admins is in our docs: Move audiences between orgs.

Found a bug or missing a flag? Open an issue in the repository – the plugin is open source, and contributions are welcome.

Campaign Audience Builder

Build audiences once, use them in every org

Build Campaign Audience Builder audiences once and move them between orgs with one command – previewed, backed up and safe to repeat.

  • Move audiences between orgs in one command
  • Segment across any standard or custom object
  • Reuse filters and keep audiences current
Audience in Campaign Audience Builder
Start for freeBook a demo

FAQ

Which audiences can the plugin move?

Every Campaign Audience Builder audience that has an API name. Select them with --all, by name with --name, by folder with --folder, or pick them from a list. If you select a Combination or Waterfall audience, the plugin also copies the audiences it uses.

Are schedules and campaign members copied too?

No. The plugin copies audience definitions plus the folders, Filter Library templates and outcome definitions they need. Schedules, scheduled actions, final actions, run results and campaign members stay in each org, so set up schedules in the target org after go-live.

What happens if an audience already exists in the target org?

Audiences match on API name, ignoring letter case. A match is updated, no match is created. Updates keep the target's version and sequence components, so schedules, run history and campaign members stay linked. Unchanged audiences are not written at all.

Can I undo an import?

Yes. Before its first change, the import writes a backup of the target audiences it will update. Importing that backup restores their previous definitions. Audiences the import created are not deleted; the restore output lists them.

Do I need a separate login for the plugin?

No. The plugin uses the org aliases your sf CLI already knows, for example one created with sf org login web --alias uat.

Is the plugin free?

Yes. sf-plugin-cab is open source under the Apache-2.0 license. The npm package is built from the public GitHub repository by GitHub Actions and includes npm provenance.