facebook-leads-cli 0.2.2

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

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)
facebook-leads-cli --help

# Run CLI (when running from source)
uv run python src/fb.py --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
facebook-leads-cli whoami	Verify token, show connected account info
facebook-leads-cli status	System health check (API connectivity)

Lead Gen API

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

Conversions API

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

Examples

Verify Authentication

facebook-leads-cli whoami

Example output:

✓ Authentication successful!

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

Check System Health

facebook-leads-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

facebook-leads-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

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

Send Test Conversion

facebook-leads-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