git clone https://github.com/Wayy-Research/flour-ads.git
cd flour-ads
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"

# List available platforms
flour-ads platforms

# Authenticate (uses env vars or stored credentials)
flour-ads auth login --platform google_ads --account-id 123-456-7890

# Deploy a campaign from YAML config
flour-ads campaign create \
  --platform google_ads \
  --account-id 123-456-7890 \
  --config examples/ringgold_campaign.yaml

# List campaigns
flour-ads campaign list --platform google_ads --account-id 123-456-7890

# Check performance
flour-ads campaign performance \
  --platform google_ads \
  --account-id 123-456-7890 \
  --campaign-id 12345678 \
  --range LAST_7_DAYS

# Pause/resume
flour-ads campaign pause --platform google_ads --account-id ID --campaign-id CID
flour-ads campaign resume --platform google_ads --account-id ID --campaign-id CID

# Update budget
flour-ads budget update \
  --platform google_ads \
  --campaign-id 12345678 \
  --account-id 123-456-7890 \
  --daily-budget 45.00

# Start the MCP server (stdio transport)
flour-ads serve

{
  "mcpServers": {
    "flour-ads": {
      "command": "flour-ads",
      "args": ["serve"]
    }
  }
}

name: "My Search Campaign"
platform: google_ads
campaign_type: SEARCH
status: PAUSED  # deploy paused, review, then enable

budget:
  daily_amount: 50.00

bidding:
  strategy: MAXIMIZE_CONVERSIONS

targeting:
  locations: ["10001", "10002", "10003"]
  languages: ["en"]
  networks:
    search: true
    display: false

ad_groups:
  - name: "Core Keywords"
    keywords:
      - text: "plumber NYC"
        match_type: PHRASE
    ads:
      - headlines:
          - "NYC Plumber — Fast Service"
          - "Licensed & Insured"
          - "Free Estimates Today"
        descriptions:
          - "Trusted plumber serving NYC. Same-day service. Call now."
          - "20+ years experience. No hourly rates. Upfront pricing."
        final_url: "https://example.com"

negative_keywords:
  - "DIY"
  - "jobs"
  - "hiring"

export GOOGLE_ADS_DEVELOPER_TOKEN="..."
export GOOGLE_ADS_CLIENT_ID="..."
export GOOGLE_ADS_CLIENT_SECRET="..."
export GOOGLE_ADS_REFRESH_TOKEN="..."
export GOOGLE_ADS_CUSTOMER_ID="1234567890"

from flour_ads.platforms.base import AdPlatform

class YourPlatformAdapter(AdPlatform):
    platform_id = "yourplatform"
    platform_name = "Your Platform"

    async def authenticate(self, account_id, credentials): ...
    async def create_campaign(self, account_id, config): ...
    async def pause_campaign(self, account_id, campaign_id): ...
    async def resume_campaign(self, account_id, campaign_id): ...
    async def get_performance(self, account_id, campaign_id, date_range): ...
    async def list_campaigns(self, account_id, status=None): ...
    async def update_budget(self, account_id, campaign_id, daily_budget): ...

[project.entry-points."flour_ads.platforms"]
yourplatform = "flour_ads.platforms.yourplatform.adapter:YourPlatformAdapter"

uv pip install -e ".[dev]"
pytest tests/ -v
black . && ruff check .
mypy src/