Skip to content

hcassar93/meta-ads-cli

BranchesTags

Repository files navigation

Meta Ads CLI

A command-line interface for the Meta (Facebook) Ads API, enabling programmatic access to campaigns, ad sets, ads, and insights. Built with Node.js and TypeScript.

License: MIT

Features

  • 🔐 OAuth 2.0 Authentication - Secure authentication with long-lived tokens
  • 📊 Campaign Management - List and view campaigns, ad sets, and ads
  • 📈 Insights & Reporting - Access performance metrics and campaign insights
  • 👥 Multi-Profile Support - Manage multiple Meta Ads accounts
  • 🎨 Rich Output - Table formatting and JSON export options
  • 💾 Secure Storage - Encrypted credential storage with 0600 file permissions
  • 🔄 Multiple Ad Accounts - Support for managing multiple ad accounts per profile

Prerequisites

Before using this CLI, you need:

  1. Meta Developer Account with an app created
  2. App ID and App Secret from your Meta app
  3. Ad Account Access - You must have access to at least one Meta Ads account

Setup Guide

1. Create a Meta App

  1. Go to Meta for Developers
  2. Click My Apps > Create App
  3. Choose Business as the app type
  4. Fill in the app details and create the app

2. Configure Your App

  1. In your app dashboard, go to Settings > Basic
  2. Copy your App ID and App Secret
  3. Add Product: Select Facebook Login
  4. Under Facebook Login > Settings:
    • Add Valid OAuth Redirect URIs: http://localhost:3000/oauth/callback
    • Save changes

3. Get Access to Marketing API

  1. In your app, go to Add Products
  2. Click Set Up on Marketing API
  3. Request Standard Access if needed (for production use)

4. Get Your Ad Account ID

  1. Go to Meta Ads Manager
  2. Your Ad Account ID is visible in the URL: act_XXXXXXXXXX
  3. Copy this ID (including the act_ prefix)

Installation

Option 1: Install from npm (Recommended)

npm install -g meta-ads-cli

Option 2: Install from Source

git clone https://github.com/hcassar93/meta-ads-cli.git
cd meta-ads-cli
npm install
npm run build
npm link  # Install globally

Verify Installation

meta-ads-cli --version
meta-ads-cli --help

Quick Start

1. Initial Setup

Configure your credentials:

meta-ads-cli setup

You'll be prompted for:

  • Profile name - a local nickname for this saved config (examples: default, client1). This is just for your machine.
  • Meta App ID - from Meta Developer Dashboard → Settings → Basic.
  • Meta App Secret - from the same place (Settings → Basic).
  • Ad Account ID (optional) - from Ads Manager URL, format: act_XXXXXXXXXX.

If you're unsure about Profile name, keep default.

2. Authenticate

Run the OAuth flow to get access tokens:

meta-ads-cli auth

This will:

  1. Open your browser for Meta authentication
  2. Prompt you to authorize the application
  3. Store long-lived access tokens securely (~60 days)

3. Start Using Commands

List your ad accounts:

meta-ads-cli accounts

List campaigns:

meta-ads-cli campaigns -a act_123456789

Usage

Authentication Commands

Setup

meta-ads-cli setup

Configure API credentials for a new profile.

Authenticate

meta-ads-cli auth [-p <profile>]

Authenticate and obtain access tokens.

Logout

meta-ads-cli logout [-p <profile>]

Clear stored credentials.

View Configuration

meta-ads-cli config [-p <profile>]

Display current configuration.

Manage Profiles

# List all profiles
meta-ads-cli profiles --list

# Switch active profile
meta-ads-cli profiles --switch

Account Commands

List Ad Accounts

meta-ads-cli accounts [--json]

Shows all ad accounts you have access to.

Get Account Details

meta-ads-cli account <account-id> [--json]

Example:

meta-ads-cli account act_123456789

Campaign Commands

List Campaigns

meta-ads-cli campaigns [-a <account-id>] [-l <limit>] [--json]

Options:

  • -a, --account-id <id> - Ad Account ID (required if not set in profile)
  • -l, --limit <number> - Maximum campaigns to return (default: 50)
  • --json - Output as JSON

Example:

meta-ads-cli campaigns -a act_123456789 -l 10

View Campaign Details

meta-ads-cli campaign <campaign-id> [--insights] [--json]

Options:

  • --insights - Include performance insights (last 30 days)

Example:

meta-ads-cli campaign 120213377777777 --insights

List Ad Sets

meta-ads-cli adsets <campaign-id> [-l <limit>] [--json]

Example:

meta-ads-cli adsets 120213377777777

Configuration

Configuration Location

Credentials are stored in:

~/.meta-ads-cli/config.json

File permissions are automatically set to 0600 (owner read/write only).

Multi-Profile Support

Manage multiple Meta Ads accounts:

# Create additional profiles during setup
meta-ads-cli setup
# Enter a unique profile name when prompted

# List profiles
meta-ads-cli profiles --list

# Switch active profile
meta-ads-cli profiles --switch

# Use specific profile for a command
meta-ads-cli campaigns -p my-other-account -a act_123456789

Output Formats

Table Format (Default)

meta-ads-cli campaigns -a act_123456789

┌──────────────────┬────────────────────────────┬────────┬──────────────┬───────────────┬────────────┐
│ ID               │ Name                       │ Status │ Objective    │ Daily Budget  │ Start Time │
├──────────────────┼────────────────────────────┼────────┼──────────────┼───────────────┼────────────┤
│ 120213377777777  │ Summer Sale Campaign       │ ACTIVE │ CONVERSIONS  │ $50.00        │ 1/15/2024  │
└──────────────────┴────────────────────────────┴────────┴──────────────┴───────────────┴────────────┘

JSON Format

meta-ads-cli campaigns -a act_123456789 --json
[
  {
    "id": "120213377777777",
    "name": "Summer Sale Campaign",
    "status": "ACTIVE",
    "objective": "CONVERSIONS",
    "daily_budget": "5000",
    "start_time": "2024-01-15T08:00:00+0000"
  }
]

Troubleshooting

"Not authenticated" Error

Run the auth command:

meta-ads-cli auth

"No profile found" Error

Create a profile first:

meta-ads-cli setup

"Ad Account ID required" Error

Either:

  • Provide --account-id flag: meta-ads-cli campaigns -a act_123456789
  • Or set it during setup: meta-ads-cli setup and enter your Ad Account ID

Token Expired Error

Tokens are long-lived (~60 days) but do expire. Re-authenticate:

meta-ads-cli auth

Port 3000 Already in Use

The OAuth callback uses port 3000. Close conflicting applications or modify src/auth/oauth.ts to use a different port.

"Invalid OAuth access token" Error

Your access token may be invalid or expired. Try:

  1. Re-authenticating: meta-ads-cli auth
  2. Creating a new profile: meta-ads-cli setup

API Limits

  • Marketing API: Rate-limited per app and user
  • Test Mode: Limited to accounts you own or manage
  • Standard Access: Required for production use with broader access

Development

Build

npm run build

Development Mode

npm run dev -- <command>

# Examples
npm run dev -- setup
npm run dev -- campaigns -a act_123456789
npm run dev -- campaign 120213377777777 --insights

Project Structure

meta-ads-cli/
├── src/
│   ├── index.ts              # CLI entry point
│   ├── cli.ts                # Commander setup
│   ├── auth/                 # Authentication logic
│   │   ├── oauth.ts
│   │   └── setup.ts
│   ├── api/
│   │   └── meta-ads.ts       # Meta Ads API wrapper
│   ├── commands/             # CLI command implementations
│   │   ├── accounts.ts
│   │   └── campaigns.ts
│   └── utils/                # Utilities
│       └── config.ts
├── dist/                     # Compiled JavaScript
├── package.json
└── tsconfig.json

Resources

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please open an issue or submit a pull request on GitHub.

Author

Hayden Cassar

Note: This tool requires proper Meta app setup and API access. It is designed for developers and marketers with technical knowledge of APIs.

About

CLI tool for Meta Ads API on macOS with OAuth. Multi-profile management with campaigns and ad set insights.

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 1

v0.0.1 Latest
Feb 21, 2026

Packages

 
 
 

Contributors

Languages