Metadata-Version: 2.4
Name: facebook-leads-cli
Version: 0.2.1
Summary: Facebook Lead Ads and Conversions API CLI
Requires-Python: >=3.10
Requires-Dist: facebook-business>=24.0.1
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: requests>=2.31.0
Description-Content-Type: text/markdown

# 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)

```bash
pip install facebook-leads-cli
```

### Option 2: Run directly from source

Requires [UV](https://docs.astral.sh/uv/) (fast Python package manager).

```bash
# 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

```bash
# 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`):

```bash
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

```bash
facebook-leads-cli whoami
```

Example output:
```
✓ Authentication successful!

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

### Check System Health

```bash
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

```bash
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

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

### Send Test Conversion

```bash
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](https://developers.facebook.com/tools/explorer/)
2. Select your app
3. Click "Generate Access Token"
4. Copy the token and set it as `FB_ACCESS_TOKEN`

## License

MIT