facebook-leads-cli 0.2.5

Facebook Lead Ads and Conversions API CLI

fb-cli

A Python CLI tool for Facebook Lead Ads and Conversions API. Fetch leads, manage forms, and send conversion events.

Installation

Option 1: Install from PyPI (recommended)

pip install facebook-leads-cli

After installation, run with:

fb-cli --help

Note: The package name (facebook-leads-cli) differs from the command (fb-cli). This is intentional — the package name is descriptive for discoverability, while the command is short for convenience.

Option 2: Run directly from source

Requires UV (fast Python package manager).

# Install UV (if not already installed)
brew install uv

# Clone and sync dependencies
git clone https://github.com/thaddeus-git/fb-cli.git
cd fb-cli
uv sync

Quick Start

# Run tests
uv run python -m unittest discover tests/

# Run CLI (when installed via pip)
fb-cli --help

# Run CLI (when running from source)
uv run python -m src.fb --help

Configuration

Set environment variables (copy from .env.example):

export FB_ACCESS_TOKEN="your_access_token"
export FB_PIXEL_ID="your_pixel_id"
export FB_PAGE_ID="your_page_id"
export FB_PAGE_ACCESS_TOKEN="your_page_access_token"  # Recommended for lead retrieval

Commands

Authentication & Status

Command	Description
fb-cli whoami	Verify token, show connected account info
fb-cli status	System health check (API connectivity)

Lead Gen API

Command	Description
fb-cli forms list	List all lead forms on page
fb-cli forms show <form_id>	Show form details
fb-cli leads fetch --days=7	Fetch leads from all forms
fb-cli leads list --form=<id>	List leads from specific form

Conversions API

Command	Description
fb-cli conversions test	Send a test event to verify setup
fb-cli conversions send --file=data.json	Send conversion events from file

Examples

Verify Authentication

fb-cli whoami

Example output:

✓ Authentication successful!

Page: My Business Page (ID: 107534675430395)
Pixel ID: 1758183674728645

Check System Health

fb-cli status

Example output:

Checking Facebook API connectivity...

✓ Authentication: OK
  Page: My Business Page
✓ Lead Gen API: OK
  Forms found: 10
✓ Conversions API: Configured
  Pixel ID: 1758183674728645

✓ System health check complete

Fetch Recent Leads

fb-cli leads fetch --days=7

Example output:

Fetching leads from the past 7 days (limit: 1000 per form)...

✓ Fetched 42 lead(s)

ID                   Created              Form
-----------------------------------------------------------------
9876543210987654     2026-02-25T10:30:00  Contact Form
8765432109876543     2026-02-24T15:45:00  Newsletter Signup

Export Leads as JSON

fb-cli leads fetch --days=7 --json > leads.json

Send Test Conversion

fb-cli conversions test

Example output:

Sending test conversion event...

✓ Test event sent successfully!
Response: {'events_received': 1, 'event_ids': ['test_12345']}

Environment Variables

Variable	Required	Description
FB_ACCESS_TOKEN	Yes	Facebook API access token
FB_PIXEL_ID	Yes*	Pixel ID for Conversions API
FB_PAGE_ID	Yes*	Page ID for Lead Gen API
FB_PAGE_ACCESS_TOKEN	Recommended	Page token for lead retrieval
FB_APP_ID	Optional	App ID for additional API calls
FB_TEST_EVENT_CODE	Optional	Test event code for debugging

*At least one of FB_PIXEL_ID or FB_PAGE_ID must be set.

Getting Your Access Token

1. Go to Facebook Graph API Explorer
2. Select your app
3. Click "Generate Access Token"
4. Copy the token and set it as FB_ACCESS_TOKEN

License

MIT