Skip to main content
Get your AI ad manager running in 10 minutes.
1

Install social-cli

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
social-cli is built by @vishalgojha and handles Meta API authentication and data fetching for you.
2

Authenticate with Meta

Run the login command to connect your Facebook ad account:
social auth login
This opens your browser to authorize with Meta. You need:
  • A Facebook account with access to your ad account
  • Permission to read ad insights (most ad account admins have this)
The authentication flow stores your access token locally. No API keys are required in your .env file.

​
Advanced: Using a Meta App

If you have a Meta developer app with custom permissions:
social auth set-app --app-id YOUR_APP_ID --app-secret YOUR_APP_SECRET
social auth login --scopes ads_read,ads_management,read_insights
You only need ads_read and read_insights for monitoring. Add ads_management only if you want the agent to pause/resume ads or adjust budgets.
3

Set your ad account

List your available ad accounts:
social marketing accounts
You’ll see output like:
Account ID          Name
act_123456789       My Brand
act_987654321       Client Account
Set the default account you want to monitor:
social marketing set-default-account act_123456789
Alternatively, set it via environment variable:
export META_AD_ACCOUNT=act_123456789
The account ID always starts with act_. You can switch accounts anytime by running the set-default-account command again.
4

Configure benchmarks

Clone the repository and set up your configuration:
git clone https://github.com/themattberman/meta-ads-kit.git
cd meta-ads-kit
cp ad-config.example.json ad-config.json
Edit ad-config.json with your performance targets:
ad-config.json
{
  "account": {
    "id": "act_123456789",
    "name": "My Brand"
  },
  "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
  },
  "reporting": {
    "default_preset": "last_7d",
    "timezone": "America/New_York"
  }
}
Don’t know your benchmarks yet? Leave the defaults. The agent will learn from your actual performance data over time.

​
What the benchmarks mean

BenchmarkWhat it does
target_cpaCost per action target — flags campaigns above this
target_roasReturn on ad spend target (3.0 = 3revenueper3 revenue per 1 spent)
max_frequencyCreative fatigue threshold (3.5 = ad shown to same person 3.5 times on average)
min_ctrMinimum acceptable click-through rate as a percentage
max_cpcMaximum cost per click — alerts when exceeded
bleeder_ctr_thresholdCTR below this flags an ad as a “bleeder”
fatigue_ctr_drop_pctCTR decline percentage that signals creative fatigue
5

Test the installation

Make the run script executable and test it:
chmod +x run.sh
./run.sh daily-check
You should see the 5 Daily Questions with your actual ad data:
═══════════════════════════════════════
  META ADS — DAILY CHECK
  The 5 Questions That Matter
  Account: act_123456789
═══════════════════════════════════════

① SPEND: Am I on track?
---
Total Spend: $1,247.82
Active Campaigns: 3

② CAMPAIGNS: What's running?
---
Campaign Name              Status    Daily Budget
Spring Sale - Prospecting  ACTIVE    $500.00
Retargeting - Cart         ACTIVE    $200.00
...

③ PERFORMANCE: Last 7 days
...
If you see “No insights data”, make sure you have active campaigns that have been running for at least 24 hours.

​
Permissions needed

The Meta API scopes required depend on what you want to do:
PermissionRequired for
ads_readReading campaign data, insights
ads_managementPausing/resuming ads, budget changes
read_insightsPerformance metrics
ads_read + read_insights are enough for monitoring only. Add ads_management if you want the agent to take action on your behalf.

​
Troubleshooting

ProblemFix
social: command not foundRun npm install -g @vishalgojha/social-cli again. You may need to restart your terminal.
Authentication failsTry social auth login again. Check that the browser popup isn’t blocked.
”No ad accounts found”Make sure your Facebook user has ad account access. Check at business.facebook.com.
No data returnedCheck that campaigns have been running in the selected time period. Try --preset last_30d for a wider range.
Rate limitedMeta API has rate limits. Wait a few minutes and retry.

​
Check everything

Run the built-in diagnostics: 
social doctor
This checks your authentication, account access, and API connectivity.

​
Optional: Run with OpenClaw

For a conversational AI interface, install OpenClaw: 
npm install -g openclaw
cd meta-ads-kit
openclaw start
Now you can message the agent naturally:
  • “How are my ads doing?”
  • “Any bleeders?”
  • “Daily check”
See the quickstart guide for examples.

Build docs developers (and LLMs) love

Get started for freeTalk to us