Metadata-Version: 2.4
Name: meta-ads
Version: 1.1.0
Summary: CLI for interacting with the Meta Marketing API
License-Expression: LicenseRef-Proprietary
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1
Requires-Dist: facebook-business>=20.0
Requires-Dist: python-dotenv>=1.0
Requires-Dist: rich>=13.0
Dynamic: license-file

# meta-ads

Official CLI for the Meta Marketing API. Manage campaigns, ad sets, ads, creatives, catalogs, datasets, and insights from your terminal.

## Installation

```bash
pip install meta-ads
```

## Quick Start

```bash
# Set up authentication
export ACCESS_TOKEN=your_access_token
export AD_ACCOUNT_ID=act_123456

# List campaigns
meta ads campaign list

# Get ad performance insights
meta ads insights get --date-preset last_7d

# Create a campaign
meta ads campaign create --name "Sales Campaign" --objective OUTCOME_SALES --daily-budget 5000

# Output as JSON
meta ads campaign list --output json
```

## Commands

| Command | Description |
|---------|-------------|
| `meta auth` | Manage authentication |
| `meta ads adaccount` | Manage ad accounts (list, get, current) |
| `meta ads campaign` | Manage campaigns (list, get, create, update, delete) |
| `meta ads adset` | Manage ad sets (list, get, create, update, delete) |
| `meta ads ad` | Manage ads (list, get, create, update, delete) |
| `meta ads creative` | Manage creatives (list, get, create, update, delete) |
| `meta ads catalog` | Manage product catalogs (list, get, create, update, delete) |
| `meta ads page` | List business pages (list, get) |
| `meta ads product-set` | Manage product sets (list, get, create, update, delete) |
| `meta ads product-item` | Manage product items (list, get, create, update, delete) |
| `meta ads product-feed` | Manage product feeds (list, get, create, update, delete) |
| `meta ads dataset` | Manage datasets/pixels (list, get, create, connect, disconnect, assign-user) |
| `meta ads guidance` | Get ad recommendations and guidance (list) |
| `meta ads insights` | Query ad performance (get) |
| `meta ads study` | Manage ad studies / experiments (list) |

## Options

```
-o, --output       Output format: table, json, plain     [default: table]
--no-color         Disable colored output
--no-input         Disable interactive prompts
--debug            Enable debug output
--ad-account-id    Meta Ad Account ID                     [env: AD_ACCOUNT_ID]
--business-id      Meta Business ID                       [env: BUSINESS_ID]
```

The campaign, ad set, and ad `list`/`get`/`create` commands also accept
`--fields name,other,...` to fetch any Marketing API fields beyond the defaults
(names are passed straight to the API):

```bash
meta ads adset get 123456 --fields name,targeting,promoted_object,bid_strategy
```

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `ACCESS_TOKEN` | Yes | Meta access token |
| `AD_ACCOUNT_ID` | Yes | Ad account ID (e.g. `act_123456`) |
| `BUSINESS_ID` | No | Business ID (auto-resolved from ad account if omitted) |

## Requirements

- Python 3.12+

## License

Copyright (c) Meta Platforms, Inc. and affiliates. All rights reserved.
