Quickstart

Get Meta Ads Kit running and see your first daily briefing in 10 minutes.

Prerequisites

Before starting, make sure you have:

Node.js 14+ installed
A Facebook account with access to a Meta ad account
Permission to read ad insights (most ad account admins have this)

If you need detailed setup instructions, see the installation guide.

Step 1: Clone the repository

git clone https://github.com/themattberman/meta-ads-kit.git
cd meta-ads-kit

social-cli is the open-source engine that talks to the Meta Marketing API.

npm install -g @vishalgojha/social-cli

Verify it’s installed:

social --version

Step 3: Authenticate with Meta

social auth login

This opens your browser to authorize with Meta. Log in with your Facebook account and approve the permissions.

Step 4: Set your ad account

List your available ad accounts:

social marketing accounts

You’ll see output like:

ID: act_123456789, Name: My Brand
ID: act_987654321, Name: Client Account

Set the default ad account:

social marketing set-default-account act_YOUR_ACCOUNT_ID

Step 5: Configure benchmarks

cp ad-config.example.json ad-config.json

Edit ad-config.json with your benchmarks:

{
  "account": {
    "id": "act_YOUR_ACCOUNT_ID",
    "name": "Your Brand Name"
  },
  "benchmarks": {
    "target_cpa": 25.00,
    "target_roas": 3.0,
    "max_frequency": 3.5,
    "min_ctr": 1.0,
    "max_cpc": 2.50
  },
  "alerts": {
    "bleeder_ctr_threshold": 1.0,
    "bleeder_frequency_threshold": 3.5,
    "fatigue_ctr_drop_pct": 20,
    "spend_pace_alert_pct": 15
  }
}

Don’t know your benchmarks? Leave the defaults — the agent will learn them from your data.

Step 6: Run your first daily check

chmod +x run.sh
./run.sh daily-check

You’ll see the 5 Daily Questions with your actual ad data:

Question 1: Am I on track?

Spend Pacing (Today)
Daily Budget: $500.00
Spent So Far: $127.50 (as of 10:30 AM)
Pace: On track (25.5% of budget, 43% through day)

Question 2: What’s running?

Active Campaigns (3)
- Summer Sale 2026: ACTIVE, $200/day budget
- Retargeting - Cart: ACTIVE, $150/day budget  
- Brand Awareness: ACTIVE, $150/day budget

Question 3: How’s performance (last 7 days)?

Campaign Performance
1. Summer Sale 2026
   Spend: $1,400 | CTR: 2.3% | CPC: $0.87 | Conv: 47 | CPA: $29.79
2. Retargeting - Cart
   Spend: $1,050 | CTR: 1.8% | CPC: $1.12 | Conv: 32 | CPA: $32.81
3. Brand Awareness
   Spend: $1,050 | CTR: 1.1% | CPC: $0.65 | Conv: 12 | CPA: $87.50

Question 4: Who’s winning and losing?

Winners 🏆

1. Ad #238471234 - Hero Image A
   CTR: 3.2% | CPC: $0.72 | Freq: 1.8 | Spend: $287
   → Scale candidate (high CTR, low frequency)

2. Ad #238471567 - Testimonial Carousel
   CTR: 2.8% | CPC: $0.81 | Freq: 2.1 | Spend: $195
   → Strong performer

Bleeders 🩸

1. Ad #238472891 - Generic Product
   CTR: 0.7% | CPC: $1.89 | Freq: 4.2 | Spend: $312
   → Pause candidate (high frequency, low CTR)

2. Ad #238473102 - Lifestyle B
   CTR: 0.8% | CPC: $1.65 | Freq: 3.8 | Spend: $245
   → Review for pause

Question 5: Any fatigue?

Fatigue Signals 😴

Ad #238471234 - Hero Image A
- CTR declining: 3.8% → 3.2% (last 3 days)
- Frequency climbing: 1.8 → 2.3
- Status: Monitor (early fatigue signal)

Ad #238473102 - Lifestyle B
- CTR dropped 40% from peak
- Frequency at 3.8
- Status: Refresh needed

Next steps

Now that you’ve run your first daily check, you can:

Understand the 5 Questions

Learn what each question tells you and how to interpret the data

Explore Skills

Discover all 5 skills from monitoring to creative upload

Take Actions

Pause bleeders, scale winners, and optimize budgets

Automate It

Set up morning briefings with cron or OpenClaw

Running with OpenClaw

For a conversational experience, use OpenClaw:

npm install -g openclaw
cd meta-ads-kit
openclaw start

Then message the agent naturally:

You: "How are my ads doing?"
You: "Any bleeders I should pause?"
You: "Which ads should I scale?"
You: "Check for creative fatigue"

The agent runs the appropriate reports, analyzes results, and asks before taking any action.

Set up automated morning briefings: “Run my daily ads check every morning at 8am and send me the summary”

Get Started

Core Concepts

Skills

Configuration

Reports

Actions

Advanced

Prerequisites

Step 1: Clone the repository

Step 3: Authenticate with Meta

Step 4: Set your ad account

Step 5: Configure benchmarks

Step 6: Run your first daily check

Question 1: Am I on track?

Question 2: What’s running?

Question 3: How’s performance (last 7 days)?

Question 4: Who’s winning and losing?

Question 5: Any fatigue?

Next steps

Understand the 5 Questions

Explore Skills

Take Actions

Automate It

Running with OpenClaw

​Prerequisites

​Step 1: Clone the repository

​Step 2: Install social-cli

​Step 3: Authenticate with Meta

​Step 4: Set your ad account

​Step 5: Configure benchmarks

​Step 6: Run your first daily check

​Question 1: Am I on track?

​Question 2: What’s running?

​Question 3: How’s performance (last 7 days)?

​Question 4: Who’s winning and losing?

​Question 5: Any fatigue?

​Next steps

Understand the 5 Questions

Explore Skills

Take Actions

Automate It

​Running with OpenClaw

Prerequisites

Step 1: Clone the repository

Step 2: Install social-cli

Step 3: Authenticate with Meta

Step 4: Set your ad account

Step 5: Configure benchmarks

Step 6: Run your first daily check

Question 1: Am I on track?

Question 2: What’s running?

Question 3: How’s performance (last 7 days)?

Question 4: Who’s winning and losing?

Question 5: Any fatigue?

Next steps

Running with OpenClaw