Skip to main content

Getting Started

This guide walks you through setting up growthctl and managing your first campaign.

Prerequisites​

  • Python 3.10 or higher
  • A Meta (Facebook) Business account with Marketing API access

Installation​

We recommend using uv to install growthctl:

uv tool install growthctl

Alternatively, you can use pipx:

pipx install growthctl

Or with standard pip:

pip install growthctl

Development Setup​

If you want to contribute or modify the code, see our Contributing Guide.

Configuration​

Meta Provider Setup​

To connect to Meta's Marketing API, set the following environment variable:

export META_ACCESS_TOKEN="your-access-token"

You can get an access token from the Meta Business Suite.

Mock Mode​

If no credentials are set, growthctl runs in mock mode - perfect for testing and learning:

# No credentials = mock mode
growthctl plan campaign.yaml

Your First Campaign​

1. Create a Campaign File​

Create a file called campaign.yaml:

version: "1.0"
campaigns:
  - id: my-first-campaign
    name: My First Campaign
    objective: OUTCOME_TRAFFIC
    status: PAUSED
    ad_sets:
      - id: test-audience
        name: Test Audience
        status: PAUSED
        budget_daily: 1000
        targeting:
          locations: ["US"]
          age_min: 18
          age_max: 65

2. Preview Changes​

Run plan to see what would change:

growthctl plan campaign.yaml

Output:

╭─ Running Plan for campaign.yaml ─╮
+ Create Campaign: My First Campaign (ID: my-first-campaign)
  + Create AdSet: Test Audience

3. Apply Changes​

When ready, apply to your ad account:

growthctl apply campaign.yaml

You'll be prompted for confirmation before any changes are made to your live account.

Importing Existing Campaigns​

Already have campaigns running? Import them to YAML:

growthctl import "Summer Sale" --output summer-sale.yaml

This creates a YAML file from your existing campaign that you can then version control and manage with growthctl.

Next Steps​