meta-ads-cli 0.1.0__py3-none-any.whl

meta_ads/__init__.py

@@ -0,0 +1,3 @@
+"""meta-ads-cli: Create and manage Meta ad campaigns from your terminal."""
+
+__version__ = "0.1.0"

meta_ads/api.py

@@ -0,0 +1,202 @@
+"""Meta Graph API client for ad management."""
+
+import json
+import click
+import requests
+
+
+class MetaAPIError(Exception):
+    """Raised when the Meta API returns an error."""
+
+    def __init__(self, status_code, message, error_code=None):
+        self.status_code = status_code
+        self.error_code = error_code
+        super().__init__(message)
+
+
+class MetaAdsAPI:
+    """Lightweight wrapper around the Meta Marketing API."""
+
+    def __init__(self, access_token, ad_account_id, page_id, api_version="v21.0", dry_run=False):
+        self.access_token = access_token
+        self.ad_account_id = ad_account_id
+        self.act_id = f"act_{ad_account_id}"
+        self.page_id = page_id
+        self.api_version = api_version
+        self.base_url = f"https://graph.facebook.com/{api_version}"
+        self.dry_run = dry_run
+        self._dry_run_counter = 0
+
+    def _request(self, method, endpoint, **kwargs):
+        """Make an API request to the Meta Graph API."""
+        url = f"{self.base_url}/{endpoint}"
+        kwargs.setdefault("params", {})
+        kwargs["params"]["access_token"] = self.access_token
+
+        if self.dry_run:
+            self._dry_run_counter += 1
+            fake_id = f"dry_run_{self._dry_run_counter}"
+            click.echo(click.style(f"  [DRY RUN] {method} {endpoint}", fg="yellow"))
+            params = {k: v for k, v in kwargs.get("params", {}).items() if k != "access_token"}
+            if params:
+                preview = json.dumps(params, indent=2)
+                if len(preview) > 500:
+                    preview = preview[:500] + "..."
+                click.echo(click.style(f"  Params: {preview}", fg="yellow"))
+            if "files" in kwargs:
+                click.echo(click.style(f"  Files: {list(kwargs['files'].keys())}", fg="yellow"))
+            return {"id": fake_id}
+
+        resp = getattr(requests, method.lower())(url, **kwargs)
+
+        if resp.status_code != 200:
+            try:
+                error_data = resp.json().get("error", {})
+                message = error_data.get("message", resp.text)
+                error_code = error_data.get("code")
+            except Exception:
+                message = resp.text
+                error_code = None
+            raise MetaAPIError(resp.status_code, message, error_code)
+
+        return resp.json()
+
+    def upload_image(self, image_path):
+        """Upload an ad image to the ad account. Returns the image hash."""
+        with open(image_path, "rb") as f:
+            result = self._request(
+                "POST",
+                f"{self.act_id}/adimages",
+                files={"filename": (image_path.name, f, "image/png")},
+            )
+
+        if self.dry_run:
+            return "dry_run_hash"
+
+        images = result.get("images", {})
+        for key, val in images.items():
+            return val.get("hash")
+
+        raise MetaAPIError(0, f"Unexpected image upload response: {result}")
+
+    def create_campaign(self, name, objective="OUTCOME_TRAFFIC", status="PAUSED", special_ad_categories=None):
+        """Create an ad campaign. Returns the campaign ID."""
+        result = self._request(
+            "POST",
+            f"{self.act_id}/campaigns",
+            params={
+                "name": name,
+                "objective": objective,
+                "status": status,
+                "special_ad_categories": json.dumps(special_ad_categories or []),
+                "is_adset_budget_sharing_enabled": "false",
+            },
+        )
+        return result.get("id", "dry_run_id")
+
+    def create_ad_set(self, name, campaign_id, daily_budget, targeting, optimization_goal="LINK_CLICKS",
+                      billing_event="IMPRESSIONS", bid_strategy="LOWEST_COST_WITHOUT_CAP", status="PAUSED"):
+        """Create an ad set with targeting. Returns the ad set ID."""
+        # Build targeting spec from config
+        targeting_spec = {
+            "age_min": targeting.get("age_min", 18),
+            "age_max": targeting.get("age_max", 65),
+            "genders": targeting.get("genders", [0]),
+            "geo_locations": {
+                "countries": targeting.get("countries", ["US"]),
+            },
+        }
+
+        if targeting.get("interests"):
+            targeting_spec["flexible_spec"] = [
+                {"interests": targeting["interests"]}
+            ]
+
+        platforms = targeting.get("platforms", ["facebook", "instagram"])
+        targeting_spec["publisher_platforms"] = platforms
+
+        if "facebook" in platforms:
+            targeting_spec["facebook_positions"] = targeting.get(
+                "facebook_positions", ["feed"]
+            )
+        if "instagram" in platforms:
+            targeting_spec["instagram_positions"] = targeting.get(
+                "instagram_positions", ["stream", "story", "reels"]
+            )
+
+        result = self._request(
+            "POST",
+            f"{self.act_id}/adsets",
+            params={
+                "name": name,
+                "campaign_id": campaign_id,
+                "daily_budget": str(daily_budget),
+                "billing_event": billing_event,
+                "optimization_goal": optimization_goal,
+                "bid_strategy": bid_strategy,
+                "status": status,
+                "targeting": json.dumps(targeting_spec),
+            },
+        )
+        return result.get("id", "dry_run_id")
+
+    def create_ad_creative(self, name, image_hash, primary_text, headline, description, link, cta="LEARN_MORE"):
+        """Create an ad creative. Returns the creative ID."""
+        result = self._request(
+            "POST",
+            f"{self.act_id}/adcreatives",
+            params={
+                "name": name,
+                "object_story_spec": json.dumps({
+                    "link_data": {
+                        "image_hash": image_hash,
+                        "link": link,
+                        "message": primary_text,
+                        "name": headline,
+                        "description": description,
+                        "call_to_action": {
+                            "type": cta,
+                            "value": {"link": link},
+                        },
+                    },
+                    "page_id": self.page_id,
+                }),
+            },
+        )
+        return result.get("id", "dry_run_id")
+
+    def create_ad(self, name, ad_set_id, creative_id, status="PAUSED"):
+        """Create an ad linking a creative to an ad set. Returns the ad ID."""
+        result = self._request(
+            "POST",
+            f"{self.act_id}/ads",
+            params={
+                "name": name,
+                "adset_id": ad_set_id,
+                "creative": json.dumps({"creative_id": creative_id}),
+                "status": status,
+            },
+        )
+        return result.get("id", "dry_run_id")
+
+    def get_campaign(self, campaign_id, fields="name,status,objective"):
+        """Get campaign details."""
+        return self._request("GET", campaign_id, params={"fields": fields})
+
+    def get_ad_sets(self, campaign_id, fields="name,status,daily_budget"):
+        """Get ad sets for a campaign."""
+        result = self._request("GET", f"{campaign_id}/adsets", params={"fields": fields})
+        return result.get("data", [])
+
+    def get_ads(self, campaign_id, fields="name,status,effective_status"):
+        """Get ads for a campaign."""
+        result = self._request("GET", f"{campaign_id}/ads", params={"fields": fields})
+        return result.get("data", [])
+
+    def update_status(self, object_id, status):
+        """Update the status of a campaign, ad set, or ad."""
+        return self._request("POST", object_id, params={"status": status})
+
+    def delete_campaign(self, campaign_id):
+        """Delete a campaign (sets status to DELETED)."""
+        return self.update_status(campaign_id, "DELETED")

meta_ads/campaign.py

@@ -0,0 +1,112 @@
+"""Campaign orchestration: create, status, and management."""
+
+from pathlib import Path
+
+import click
+
+
+def create_full_campaign(api, config):
+    """Create a complete campaign from config: campaign, ad set, creatives, and ads.
+
+    Returns a dict with all created object IDs.
+    """
+    campaign_cfg = config["campaign"]
+    ad_set_cfg = config["ad_set"]
+    ads_cfg = config["ads"]
+    status = campaign_cfg.get("status", "PAUSED")
+
+    result = {
+        "campaign_id": None,
+        "ad_set_id": None,
+        "creatives": [],
+        "ads": [],
+    }
+
+    # Step 1: Upload images
+    click.echo(click.style("\n[1/4] Uploading images", fg="blue", bold=True))
+    image_hashes = {}
+    for ad in ads_cfg:
+        image_path = Path(ad["image"])
+        click.echo(f"  Uploading {image_path.name}...")
+        image_hashes[ad["name"]] = api.upload_image(image_path)
+        click.echo(click.style(f"  Done.", fg="green"))
+
+    # Step 2: Create campaign
+    click.echo(click.style("\n[2/4] Creating campaign", fg="blue", bold=True))
+    click.echo(f"  Name: {campaign_cfg['name']}")
+    campaign_id = api.create_campaign(
+        name=campaign_cfg["name"],
+        objective=campaign_cfg.get("objective", "OUTCOME_TRAFFIC"),
+        status=status,
+        special_ad_categories=campaign_cfg.get("special_ad_categories"),
+    )
+    result["campaign_id"] = campaign_id
+    click.echo(click.style(f"  Campaign ID: {campaign_id}", fg="green"))
+
+    # Step 3: Create ad set
+    click.echo(click.style("\n[3/4] Creating ad set", fg="blue", bold=True))
+    click.echo(f"  Name: {ad_set_cfg['name']}")
+    budget_dollars = int(ad_set_cfg['daily_budget']) / 100
+    click.echo(f"  Budget: ${budget_dollars:.2f}/day")
+    ad_set_id = api.create_ad_set(
+        name=ad_set_cfg["name"],
+        campaign_id=campaign_id,
+        daily_budget=ad_set_cfg["daily_budget"],
+        targeting=ad_set_cfg.get("targeting", {}),
+        optimization_goal=ad_set_cfg.get("optimization_goal", "LINK_CLICKS"),
+        billing_event=ad_set_cfg.get("billing_event", "IMPRESSIONS"),
+        bid_strategy=ad_set_cfg.get("bid_strategy", "LOWEST_COST_WITHOUT_CAP"),
+        status=status,
+    )
+    result["ad_set_id"] = ad_set_id
+    click.echo(click.style(f"  Ad Set ID: {ad_set_id}", fg="green"))
+
+    # Step 4: Create creatives and ads
+    click.echo(click.style("\n[4/4] Creating ads", fg="blue", bold=True))
+    for ad in ads_cfg:
+        click.echo(f"  Creating: {ad['name']}")
+
+        creative_id = api.create_ad_creative(
+            name=f"{ad['name']} - Creative",
+            image_hash=image_hashes[ad["name"]],
+            primary_text=ad["primary_text"].strip(),
+            headline=ad.get("headline", ""),
+            description=ad.get("description", ""),
+            link=ad["link"],
+            cta=ad.get("cta", "LEARN_MORE"),
+        )
+        result["creatives"].append(creative_id)
+
+        ad_id = api.create_ad(
+            name=ad["name"],
+            ad_set_id=ad_set_id,
+            creative_id=creative_id,
+            status=status,
+        )
+        result["ads"].append(ad_id)
+        click.echo(click.style(f"  Ad ID: {ad_id}", fg="green"))
+
+    return result
+
+
+def print_campaign_status(api, campaign_id):
+    """Fetch and display campaign status with ad sets and ads."""
+    campaign = api.get_campaign(campaign_id, fields="name,status,objective,daily_budget")
+    click.echo(click.style(f"\nCampaign: {campaign['name']}", bold=True))
+    click.echo(f"  ID: {campaign['id']}")
+    click.echo(f"  Status: {campaign['status']}")
+    click.echo(f"  Objective: {campaign.get('objective', 'N/A')}")
+
+    ad_sets = api.get_ad_sets(campaign_id, fields="name,status,daily_budget")
+    if ad_sets:
+        click.echo(click.style("\n  Ad Sets:", bold=True))
+        for ad_set in ad_sets:
+            budget = int(ad_set.get("daily_budget", 0)) / 100
+            click.echo(f"    {ad_set['name']}: {ad_set['status']} (${budget:.2f}/day)")
+
+    ads = api.get_ads(campaign_id, fields="name,status,effective_status")
+    if ads:
+        click.echo(click.style("\n  Ads:", bold=True))
+        for ad in ads:
+            effective = ad.get("effective_status", ad["status"])
+            click.echo(f"    {ad['name']}: {effective}")

meta_ads/cli.py

@@ -0,0 +1,192 @@
+"""CLI entry point for meta-ads."""
+
+import os
+import sys
+
+import click
+from dotenv import load_dotenv
+
+from meta_ads import __version__
+from meta_ads.api import MetaAdsAPI, MetaAPIError
+from meta_ads.campaign import create_full_campaign, print_campaign_status
+from meta_ads.config import load_config, validate_config, ConfigError
+
+
+def get_api(dry_run=False):
+    """Create a MetaAdsAPI instance from environment variables."""
+    access_token = os.getenv("META_ACCESS_TOKEN")
+    ad_account_id = os.getenv("META_AD_ACCOUNT_ID")
+    page_id = os.getenv("META_PAGE_ID")
+    api_version = os.getenv("META_API_VERSION", "v21.0")
+
+    missing = []
+    if not access_token:
+        missing.append("META_ACCESS_TOKEN")
+    if not ad_account_id:
+        missing.append("META_AD_ACCOUNT_ID")
+    if not page_id:
+        missing.append("META_PAGE_ID")
+
+    if missing:
+        click.echo(click.style("Missing required environment variables:", fg="red"))
+        for var in missing:
+            click.echo(click.style(f"  {var}", fg="red"))
+        click.echo("\nSet them in .env or export them in your shell.")
+        click.echo("See: https://github.com/attainmentlabs/meta-ads-cli#configuration")
+        sys.exit(1)
+
+    return MetaAdsAPI(
+        access_token=access_token,
+        ad_account_id=ad_account_id,
+        page_id=page_id,
+        api_version=api_version,
+        dry_run=dry_run,
+    )
+
+
+@click.group()
+@click.version_option(version=__version__, prog_name="meta-ads")
+def cli():
+    """Create and manage Meta ad campaigns from your terminal."""
+    load_dotenv()
+
+
+@cli.command()
+@click.option("--config", "config_path", default="campaign.yaml", help="Path to campaign YAML config.")
+@click.option("--dry-run", is_flag=True, help="Preview what would be created without making API calls.")
+@click.option("--yes", "-y", is_flag=True, help="Skip confirmation prompt.")
+def create(config_path, dry_run, yes):
+    """Create a full campaign from a YAML config file."""
+    try:
+        config = load_config(config_path)
+        validate_config(config)
+    except ConfigError as e:
+        click.echo(click.style(f"Config error:\n{e}", fg="red"))
+        sys.exit(1)
+
+    campaign_name = config["campaign"]["name"]
+    status = config["campaign"].get("status", "PAUSED")
+    budget = int(config["ad_set"]["daily_budget"]) / 100
+    num_ads = len(config["ads"])
+
+    click.echo(click.style("=" * 50, fg="blue"))
+    click.echo(click.style("meta-ads create", fg="blue", bold=True))
+    click.echo(click.style("=" * 50, fg="blue"))
+    click.echo(f"Campaign:  {campaign_name}")
+    click.echo(f"Budget:    ${budget:.2f}/day")
+    click.echo(f"Ads:       {num_ads}")
+    click.echo(f"Status:    {status}")
+    click.echo(f"Mode:      {'DRY RUN' if dry_run else 'LIVE'}")
+
+    if not dry_run and not yes:
+        click.echo()
+        if not click.confirm(click.style("This will create real campaigns. Continue?", fg="yellow")):
+            click.echo("Aborted.")
+            sys.exit(0)
+
+    api = get_api(dry_run=dry_run)
+
+    try:
+        result = create_full_campaign(api, config)
+    except MetaAPIError as e:
+        click.echo(click.style(f"\nAPI Error: {e}", fg="red"))
+        if e.error_code:
+            click.echo(click.style(f"Error code: {e.error_code}", fg="red"))
+        sys.exit(1)
+
+    # Summary
+    click.echo(click.style("\n" + "=" * 50, fg="green"))
+    click.echo(click.style("Done!", fg="green", bold=True))
+    click.echo(click.style("=" * 50, fg="green"))
+    click.echo(f"Campaign:  {result['campaign_id']} ({status})")
+    click.echo(f"Ad Set:    {result['ad_set_id']} ({status})")
+    click.echo(f"Creatives: {len(result['creatives'])}")
+    click.echo(f"Ads:       {len(result['ads'])}")
+
+    if not dry_run:
+        click.echo(f"\nView in Ads Manager:")
+        click.echo(f"  https://adsmanager.facebook.com/adsmanager/manage/campaigns?act={api.ad_account_id}")
+
+
+@cli.command()
+@click.argument("campaign_id")
+def status(campaign_id):
+    """Show the status of a campaign and its ads."""
+    api = get_api()
+    try:
+        print_campaign_status(api, campaign_id)
+    except MetaAPIError as e:
+        click.echo(click.style(f"API Error: {e}", fg="red"))
+        sys.exit(1)
+
+
+@cli.command()
+@click.argument("campaign_id")
+def pause(campaign_id):
+    """Pause a campaign."""
+    api = get_api()
+    try:
+        api.update_status(campaign_id, "PAUSED")
+        click.echo(click.style(f"Campaign {campaign_id} paused.", fg="green"))
+    except MetaAPIError as e:
+        click.echo(click.style(f"API Error: {e}", fg="red"))
+        sys.exit(1)
+
+
+@cli.command()
+@click.argument("campaign_id")
+@click.option("--yes", "-y", is_flag=True, help="Skip confirmation prompt.")
+def activate(campaign_id, yes):
+    """Activate a campaign. This will start spending your budget."""
+    if not yes:
+        if not click.confirm(click.style("This will start spending your ad budget. Continue?", fg="yellow")):
+            click.echo("Aborted.")
+            return
+
+    api = get_api()
+    try:
+        api.update_status(campaign_id, "ACTIVE")
+        click.echo(click.style(f"Campaign {campaign_id} activated.", fg="green"))
+    except MetaAPIError as e:
+        click.echo(click.style(f"API Error: {e}", fg="red"))
+        sys.exit(1)
+
+
+@cli.command()
+@click.argument("campaign_id")
+@click.option("--yes", "-y", is_flag=True, help="Skip confirmation prompt.")
+def delete(campaign_id, yes):
+    """Delete a campaign. This cannot be undone."""
+    if not yes:
+        if not click.confirm(click.style("This will permanently delete the campaign. Continue?", fg="red")):
+            click.echo("Aborted.")
+            return
+
+    api = get_api()
+    try:
+        api.delete_campaign(campaign_id)
+        click.echo(click.style(f"Campaign {campaign_id} deleted.", fg="green"))
+    except MetaAPIError as e:
+        click.echo(click.style(f"API Error: {e}", fg="red"))
+        sys.exit(1)
+
+
+@cli.command()
+@click.option("--config", "config_path", default="campaign.yaml", help="Path to campaign YAML config.")
+def validate(config_path):
+    """Validate a campaign YAML config without making API calls."""
+    try:
+        config = load_config(config_path)
+        validate_config(config)
+    except ConfigError as e:
+        click.echo(click.style(f"Validation failed:\n{e}", fg="red"))
+        sys.exit(1)
+
+    campaign_name = config["campaign"]["name"]
+    num_ads = len(config["ads"])
+    budget = int(config["ad_set"]["daily_budget"]) / 100
+
+    click.echo(click.style("Config is valid.", fg="green"))
+    click.echo(f"  Campaign: {campaign_name}")
+    click.echo(f"  Budget:   ${budget:.2f}/day")
+    click.echo(f"  Ads:      {num_ads}")

meta_ads/config.py

@@ -0,0 +1,137 @@
+"""Campaign config loading and validation."""
+
+from pathlib import Path
+
+import yaml
+
+
+VALID_OBJECTIVES = [
+    "OUTCOME_TRAFFIC",
+    "OUTCOME_AWARENESS",
+    "OUTCOME_ENGAGEMENT",
+    "OUTCOME_LEADS",
+    "OUTCOME_SALES",
+    "OUTCOME_APP_PROMOTION",
+]
+
+VALID_OPTIMIZATION_GOALS = [
+    "LINK_CLICKS",
+    "IMPRESSIONS",
+    "REACH",
+    "LANDING_PAGE_VIEWS",
+    "APP_INSTALLS",
+    "OFFSITE_CONVERSIONS",
+    "LEAD_GENERATION",
+]
+
+VALID_CTAS = [
+    "LEARN_MORE",
+    "SIGN_UP",
+    "DOWNLOAD",
+    "SHOP_NOW",
+    "BOOK_NOW",
+    "GET_OFFER",
+    "SUBSCRIBE",
+    "CONTACT_US",
+    "APPLY_NOW",
+    "WATCH_MORE",
+    "INSTALL_MOBILE_APP",
+]
+
+VALID_STATUSES = ["PAUSED", "ACTIVE"]
+
+
+class ConfigError(Exception):
+    """Raised when campaign config is invalid."""
+    pass
+
+
+def load_config(path):
+    """Load and validate a campaign YAML config file.
+
+    Returns the parsed config dict. Image paths are resolved
+    relative to the YAML file's directory.
+    """
+    config_path = Path(path)
+    if not config_path.exists():
+        raise ConfigError(f"Config file not found: {path}")
+
+    with open(config_path) as f:
+        config = yaml.safe_load(f)
+
+    if not config:
+        raise ConfigError("Config file is empty")
+
+    # Resolve image paths relative to the YAML file
+    config_dir = config_path.parent
+    for ad in config.get("ads", []):
+        if "image" in ad:
+            image_path = Path(ad["image"])
+            if not image_path.is_absolute():
+                ad["image"] = str(config_dir / image_path)
+
+    return config
+
+
+def validate_config(config):
+    """Validate a campaign config dict. Raises ConfigError on problems."""
+    errors = []
+
+    # Campaign section
+    campaign = config.get("campaign")
+    if not campaign:
+        errors.append("Missing 'campaign' section")
+    else:
+        if not campaign.get("name"):
+            errors.append("campaign.name is required")
+        objective = campaign.get("objective", "OUTCOME_TRAFFIC")
+        if objective not in VALID_OBJECTIVES:
+            errors.append(f"campaign.objective '{objective}' is not valid. Options: {', '.join(VALID_OBJECTIVES)}")
+        status = campaign.get("status", "PAUSED")
+        if status not in VALID_STATUSES:
+            errors.append(f"campaign.status must be PAUSED or ACTIVE")
+
+    # Ad set section
+    ad_set = config.get("ad_set")
+    if not ad_set:
+        errors.append("Missing 'ad_set' section")
+    else:
+        if not ad_set.get("name"):
+            errors.append("ad_set.name is required")
+        if not ad_set.get("daily_budget"):
+            errors.append("ad_set.daily_budget is required (in cents, e.g. 1000 = $10/day)")
+        opt_goal = ad_set.get("optimization_goal", "LINK_CLICKS")
+        if opt_goal not in VALID_OPTIMIZATION_GOALS:
+            errors.append(f"ad_set.optimization_goal '{opt_goal}' is not valid. Options: {', '.join(VALID_OPTIMIZATION_GOALS)}")
+
+        targeting = ad_set.get("targeting", {})
+        if not targeting.get("countries"):
+            errors.append("ad_set.targeting.countries is required (e.g. ['US', 'CA'])")
+
+    # Ads section
+    ads = config.get("ads")
+    if not ads:
+        errors.append("Missing 'ads' section (need at least one ad)")
+    else:
+        for i, ad in enumerate(ads):
+            prefix = f"ads[{i}]"
+            if not ad.get("name"):
+                errors.append(f"{prefix}.name is required")
+            if not ad.get("image"):
+                errors.append(f"{prefix}.image is required")
+            elif not Path(ad["image"]).exists():
+                errors.append(f"{prefix}.image not found: {ad['image']}")
+            if not ad.get("primary_text"):
+                errors.append(f"{prefix}.primary_text is required")
+            if not ad.get("headline"):
+                errors.append(f"{prefix}.headline is required")
+            if not ad.get("link"):
+                errors.append(f"{prefix}.link is required")
+            cta = ad.get("cta", "LEARN_MORE")
+            if cta not in VALID_CTAS:
+                errors.append(f"{prefix}.cta '{cta}' is not valid. Options: {', '.join(VALID_CTAS)}")
+
+    if errors:
+        raise ConfigError("\n".join(f"  - {e}" for e in errors))
+
+    return config

meta_ads_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,287 @@
+Metadata-Version: 2.4
+Name: meta-ads-cli
+Version: 0.1.0
+Summary: Create and manage Meta (Facebook/Instagram) ad campaigns from your terminal.
+Project-URL: Homepage, https://github.com/attainmentlabs/meta-ads-cli
+Project-URL: Issues, https://github.com/attainmentlabs/meta-ads-cli/issues
+Author-email: Attainment Labs <hello@attainmentlabs.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ads,advertising,cli,facebook,instagram,marketing,meta
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet
+Classifier: Topic :: Office/Business
+Requires-Python: >=3.9
+Requires-Dist: click>=8.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: requests>=2.28
+Description-Content-Type: text/markdown
+
+# meta-ads-cli
+
+Create and manage Meta (Facebook/Instagram) ad campaigns from your terminal.
+
+> Built by [Attainment Labs](https://attainmentlabs.com)
+
+## Why
+
+Meta Ads Manager is slow. Clicking through 15 screens to launch a campaign is a waste of time when you already know what you want to run.
+
+This tool lets you define a campaign in a YAML file and deploy it with one command.
+
+```
+meta-ads create --config campaign.yaml
+```
+
+One campaign. One ad set. Multiple ads. All created in seconds.
+
+## Install
+
+```bash
+pip install meta-ads-cli
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/attainmentlabs/meta-ads-cli.git
+cd meta-ads-cli
+pip install -e .
+```
+
+## Quick Start
+
+**1. Set up your credentials**
+
+```bash
+cp .env.example .env
+# Edit .env with your Meta access token, ad account ID, and page ID
+```
+
+**2. Create your campaign config**
+
+```bash
+cp campaign.example.yaml campaign.yaml
+# Edit campaign.yaml with your ad copy, images, targeting, and budget
+```
+
+**3. Validate your config**
+
+```bash
+meta-ads validate --config campaign.yaml
+```
+
+**4. Preview with dry run**
+
+```bash
+meta-ads create --config campaign.yaml --dry-run
+```
+
+**5. Deploy**
+
+```bash
+meta-ads create --config campaign.yaml
+```
+
+Your campaign is created as PAUSED by default. Review it in Ads Manager, then activate it when ready.
+
+## Configuration
+
+### Environment Variables
+
+Create a `.env` file in your project root (or export these in your shell):
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `META_ACCESS_TOKEN` | Yes | Your Meta API access token |
+| `META_AD_ACCOUNT_ID` | Yes | Your ad account ID (numbers only, no `act_` prefix) |
+| `META_PAGE_ID` | Yes | Your Facebook Page ID |
+| `META_API_VERSION` | No | API version (default: `v21.0`) |
+
+### Campaign Config (YAML)
+
+Your campaign is defined in a single YAML file. Here is the full schema:
+
+```yaml
+campaign:
+  name: "My Campaign"
+  objective: OUTCOME_TRAFFIC        # See objectives below
+  status: PAUSED                    # PAUSED or ACTIVE
+  special_ad_categories: []         # Leave empty unless required
+
+ad_set:
+  name: "My Ad Set"
+  daily_budget: 1000                # In cents. 1000 = $10/day
+  optimization_goal: LINK_CLICKS    # See optimization goals below
+  targeting:
+    age_min: 18
+    age_max: 65
+    genders: [0]                    # 0 = all, 1 = male, 2 = female
+    countries: ["US"]
+    interests:                      # Optional
+      - id: "6003139266461"
+        name: "Fitness and wellness"
+    platforms: ["facebook", "instagram"]
+    facebook_positions: ["feed"]
+    instagram_positions: ["stream", "story", "reels"]
+
+ads:
+  - name: "My Ad"
+    image: ./images/ad.png          # Path relative to YAML file
+    primary_text: "Your ad copy."
+    headline: "Your Headline"
+    description: "Short description"
+    cta: LEARN_MORE                 # See CTAs below
+    link: "https://example.com"
+```
+
+**Campaign Objectives:** `OUTCOME_TRAFFIC`, `OUTCOME_AWARENESS`, `OUTCOME_ENGAGEMENT`, `OUTCOME_LEADS`, `OUTCOME_SALES`, `OUTCOME_APP_PROMOTION`
+
+**Optimization Goals:** `LINK_CLICKS`, `IMPRESSIONS`, `REACH`, `LANDING_PAGE_VIEWS`, `APP_INSTALLS`, `OFFSITE_CONVERSIONS`, `LEAD_GENERATION`
+
+**CTA Options:** `LEARN_MORE`, `SIGN_UP`, `DOWNLOAD`, `SHOP_NOW`, `BOOK_NOW`, `GET_OFFER`, `SUBSCRIBE`, `CONTACT_US`, `APPLY_NOW`, `WATCH_MORE`
+
+## Commands
+
+### `meta-ads create`
+
+Create a full campaign from your YAML config.
+
+```bash
+# Preview first
+meta-ads create --dry-run
+
+# Deploy (will ask for confirmation)
+meta-ads create
+
+# Deploy without confirmation
+meta-ads create --yes
+
+# Use a custom config file
+meta-ads create --config path/to/campaign.yaml
+```
+
+### `meta-ads status <campaign-id>`
+
+Check the status of a campaign and all its ads.
+
+```bash
+meta-ads status 120243616427570285
+```
+
+### `meta-ads pause <campaign-id>`
+
+Pause a running campaign.
+
+```bash
+meta-ads pause 120243616427570285
+```
+
+### `meta-ads activate <campaign-id>`
+
+Activate a paused campaign. This starts spending your budget.
+
+```bash
+meta-ads activate 120243616427570285
+```
+
+### `meta-ads delete <campaign-id>`
+
+Permanently delete a campaign.
+
+```bash
+meta-ads delete 120243616427570285
+```
+
+### `meta-ads validate`
+
+Validate your YAML config without making any API calls.
+
+```bash
+meta-ads validate --config campaign.yaml
+```
+
+## Getting a Meta Access Token
+
+This is the part most people get stuck on. Here is the short version:
+
+1. Go to [Meta for Developers](https://developers.facebook.com/) and create an app (type: Business)
+2. Open the [Graph API Explorer](https://developers.facebook.com/tools/explorer/)
+3. Select your app, then request these permissions: `ads_management`, `pages_read_engagement`, `pages_show_list`
+4. Click "Generate Access Token" and authorize
+5. Copy the token to your `.env` file
+
+**Important:** Graph API Explorer tokens expire after about 2 hours. For production use, exchange it for a long-lived token:
+
+```bash
+curl "https://graph.facebook.com/v21.0/oauth/access_token?\
+grant_type=fb_exchange_token&\
+client_id=YOUR_APP_ID&\
+client_secret=YOUR_APP_SECRET&\
+fb_exchange_token=YOUR_SHORT_LIVED_TOKEN"
+```
+
+Long-lived tokens last about 60 days.
+
+## Finding Interest IDs
+
+Interest targeting requires Meta's internal IDs. Search for them using the API:
+
+```bash
+curl "https://graph.facebook.com/v21.0/search?\
+type=adinterest&\
+q=fitness&\
+access_token=YOUR_TOKEN"
+```
+
+This returns interest names and IDs you can use in your campaign YAML.
+
+## Examples
+
+See the [`examples/`](examples/) directory for ready-to-customize campaign configs:
+
+- **[ecommerce.yaml](examples/ecommerce.yaml)**: Product launch targeting skincare enthusiasts
+- **[app-install.yaml](examples/app-install.yaml)**: Mobile app install campaign for fitness users
+
+## How It Works
+
+This tool wraps the [Meta Marketing API](https://developers.facebook.com/docs/marketing-apis/) with `requests`. No heavy SDKs. The full chain:
+
+1. Uploads your ad images to your ad account
+2. Creates a campaign with your objective
+3. Creates an ad set with your budget and targeting
+4. Creates ad creatives linking your images and copy
+5. Creates ads linking creatives to the ad set
+
+Everything is created as `PAUSED` by default so you can review before spending.
+
+## Want the Full Playbook?
+
+We wrote a free guide covering Meta Ads automation end to end: OAuth setup walkthrough, audience segmentation strategy, budget allocation frameworks, creative testing, scaling rules, and common API errors with fixes.
+
+**[Get the Guide: The Engineer's Playbook for Meta Ads](https://attainmentlabs.com/meta-ads-playbook)**
+
+## Contributing
+
+PRs welcome. Keep it simple. This tool is intentionally lightweight.
+
+```bash
+git clone https://github.com/attainmentlabs/meta-ads-cli.git
+cd meta-ads-cli
+pip install -e .
+meta-ads --help
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

meta_ads_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+meta_ads/__init__.py,sha256=7V2HVw6gBETk2UhHzNB3Rb0okjUT8mtYAsapR-QLSiI,99
+meta_ads/api.py,sha256=yW19q4eee_i9t69n_IptpAR36u5h6F7GNXhgpfxJYHc,7833
+meta_ads/campaign.py,sha256=p-wmdNQBIRwzrmYZ2AR6eks3lA9xtfkp2LhM4HkrmWg,4225
+meta_ads/cli.py,sha256=mzXcfq9IkG5_r_Tfc-moAXLGGv8C7q6x9P6NWlYdKv4,6653
+meta_ads/config.py,sha256=loaX5iZoImCPa3zmfLf41wSeWGwzrQuGS9Qg37J4Smw,4205
+meta_ads_cli-0.1.0.dist-info/METADATA,sha256=xL0UEhhRzm_82rP9hyssl7XOTohekRZ316IVYCSF8_U,8021
+meta_ads_cli-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+meta_ads_cli-0.1.0.dist-info/entry_points.txt,sha256=Y9vImL5xWdansNNZbBti-UvAzGX1hwT8xTUnt1xFUMY,46
+meta_ads_cli-0.1.0.dist-info/licenses/LICENSE,sha256=Ye3Xeu5A3dvqnobTC0cIl4j_pYMgwArm613EtzaGqIA,1072
+meta_ads_cli-0.1.0.dist-info/RECORD,,

meta_ads_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

meta_ads_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+meta-ads = meta_ads.cli:cli

meta_ads_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Attainment Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.