Google Ads CLI Plugin for OpenClaw

A comprehensive command-line interface for Google Ads that enables campaign management, optimization, and analytics through the Google Ads API v18.

Features

• Campaign Management: Create, update, pause, enable campaigns
• Ad Group Control: Manage ad groups within campaigns
• Keyword Management: Add, remove, and optimize keywords
• Ad Creation: Create responsive search ads with multiple headlines/descriptions
• Budget Control: Update daily budgets and monitor spend
• Performance Analytics: Get detailed metrics and generate reports
• Automated Optimization: Tools for campaign performance optimization
• Bulk Operations: Manage multiple campaigns and ad groups efficiently

Quick Start

1. Install dependencies:

   cd /root/.openclaw/workspace/skills/google-ads
   npm install

2. Set up credentials (see Setup Guide): Add to /root/.openclaw/.env:

   GOOGLE_ADS_CUSTOMER_ID=1234567890
   GOOGLE_ADS_DEVELOPER_TOKEN=your_developer_token
   GOOGLE_ADS_CLIENT_ID=your_oauth_client_id
   GOOGLE_ADS_CLIENT_SECRET=your_oauth_client_secret
   GOOGLE_ADS_REFRESH_TOKEN=your_refresh_token

3. Test the connection:

   ./google-ads.sh campaigns-list

Commands

Campaign Management

# List all campaigns with performance metrics
./google-ads.sh campaigns-list

# Create a new search campaign
./google-ads.sh campaign-create "Holiday Sale 2024" 100 MAXIMIZE_CLICKS

# Update campaign name
./google-ads.sh campaign-update 123456789 name:"New Campaign Name"

# Pause/enable campaigns
./google-ads.sh campaign-pause 123456789
./google-ads.sh campaign-enable 123456789

# Update daily budget
./google-ads.sh budget-update 123456789 150

Ad Group & Keyword Management

# List ad groups in a campaign
./google-ads.sh adgroups-list 123456789

# Create new ad group with $1.50 max CPC
./google-ads.sh adgroup-create 123456789 "Running Shoes" 1500000

# List keywords in ad group
./google-ads.sh keywords-list 987654321

# Add keywords with different match types
./google-ads.sh keyword-add 987654321 "running shoes" EXACT
./google-ads.sh keyword-add 987654321 "athletic footwear" PHRASE
./google-ads.sh keyword-add 987654321 "sports shoes" BROAD

# Remove underperforming keyword
./google-ads.sh keyword-remove 987654321 444555666

Ad Creation & Management

# List ads in ad group
./google-ads.sh ads-list 987654321

# Create responsive search ad
./google-ads.sh ad-create 987654321 \
  "https://shop.example.com/shoes" \
  "Best Running Shoes,Top Athletic Footwear,Premium Sports Shoes" \
  "Find your perfect running shoe,Quality footwear for athletes"

# Pause underperforming ad
./google-ads.sh ad-pause 987654321 111222333

Analytics & Reporting

# Get metrics for specific date range
./google-ads.sh metrics 2024-01-01 2024-01-31

# Get metrics for specific campaign
./google-ads.sh metrics 2024-01-01 2024-01-31 123456789

# Generate summary reports
./google-ads.sh report 7    # Last 7 days
./google-ads.sh report 30   # Last 30 days

Advanced Usage

Campaign Optimization Workflow

Performance Analysis:

# Get monthly performance summary
./google-ads.sh report 30 > monthly_performance.json

# Identify top performing campaigns
jq '.campaigns[] | select(.ctr > 3.0 and .conversions > 10) | {name, ctr, conversions, cost}' monthly_performance.json

# Find underperforming campaigns
jq '.campaigns[] | select(.ctr < 1.0 or (.cost > 100 and .conversions == 0)) | {name, ctr, conversions, cost}' monthly_performance.json

Budget Optimization:

# Increase budget for top performers
./google-ads.sh budget-update 123456789 200  # High converting campaign
./google-ads.sh budget-update 987654321 75   # Reduce budget for poor performer

# Pause campaigns with no conversions and high spend
./google-ads.sh campaign-pause 555666777

Keyword Expansion:

# Add related keywords to successful ad groups
./google-ads.sh keyword-add 987654321 "marathon shoes" EXACT
./google-ads.sh keyword-add 987654321 "trail running shoes" PHRASE
./google-ads.sh keyword-add 987654321 "professional running gear" BROAD

# Create new ad variations for expanded keywords
./google-ads.sh ad-create 987654321 "https://shop.example.com/trail-shoes" \
  "Trail Running Shoes,Off-Road Athletic Footwear,Adventure Running Gear" \
  "Conquer any terrain with our trail shoes,Built for outdoor adventures"

Automated Monitoring & Alerts

Daily Performance Check:

#!/bin/bash
# daily_ads_check.sh - Add to cron for daily monitoring

REPORT=$(./google-ads.sh report 1)
TOTAL_COST=$(echo $REPORT | jq -r '.total_cost')
TOTAL_CONVERSIONS=$(echo $REPORT | jq -r '.total_conversions')
AVG_CTR=$(echo $REPORT | jq -r '.average_ctr')

# Alert if spend is high but conversions are low
if (( $(echo "$TOTAL_COST > 500" | bc -l) )) && (( $(echo "$TOTAL_CONVERSIONS < 5" | bc -l) )); then
  echo "ALERT: High spend ($TOTAL_COST) with low conversions ($TOTAL_CONVERSIONS)"
fi

# Alert if CTR drops below threshold
if (( $(echo "$AVG_CTR < 2.0" | bc -l) )); then
  echo "ALERT: CTR dropped to $AVG_CTR% - consider ad optimization"
fi

Automated Budget Management:

#!/bin/bash
# auto_budget_optimizer.sh

# Get top performing campaigns (high CTR, good conversion rate)
HIGH_PERFORMERS=$(./google-ads.sh report 7 | jq -r '.campaigns[] | select(.ctr > 4.0 and .conversions > 5) | .id')

# Increase their budgets by 20%
for CAMPAIGN_ID in $HIGH_PERFORMERS; do
  CURRENT_BUDGET=$(./google-ads.sh campaigns-list | jq -r ".results[] | select(.campaign.id == \"$CAMPAIGN_ID\") | .campaign.campaign_budget")
  NEW_BUDGET=$(echo "$CURRENT_BUDGET * 1.2" | bc)
  ./google-ads.sh budget-update $CAMPAIGN_ID $NEW_BUDGET
  echo "Increased budget for campaign $CAMPAIGN_ID to $NEW_BUDGET"
done

Data Export & Integration

Export to CSV for Analysis:

# Campaign performance CSV
./google-ads.sh campaigns-list | jq -r '.results[] | [
  .campaign.name, 
  .campaign.status, 
  .metrics.impressions, 
  .metrics.clicks, 
  (.metrics.cost_micros | tonumber / 1000000), 
  .metrics.conversions,
  (.metrics.ctr | tonumber)
] | @csv' > campaigns_performance.csv

# Keyword performance CSV
./google-ads.sh keywords-list 123456789 | jq -r '.results[] | [
  .ad_group.name,
  .ad_group_criterion.keyword.text,
  .ad_group_criterion.keyword.match_type,
  .metrics.impressions,
  .metrics.clicks,
  (.metrics.cost_micros | tonumber / 1000000)
] | @csv' > keywords_performance.csv

Integration with External Tools:

# Send daily report to Slack webhook
./google-ads.sh report 1 | curl -X POST $SLACK_WEBHOOK_URL \
  -H "Content-Type: application/json" \
  -d '{"text": "Daily Google Ads Report", "attachments": [{"text": "'$(cat)'""}]}'

# Upload performance data to Google Sheets (via API)
./google-ads.sh metrics $(date -d '7 days ago' +%Y-%m-%d) $(date +%Y-%m-%d) > /tmp/ads_data.json
# Process and upload to sheets...

# Trigger optimization workflows
./google-ads.sh report 7 | python3 optimization_analyzer.py

Rate Limits & Best Practices

Google Ads API Rate Limits

• Standard Operations: 30,000 requests per minute
• Report Downloads: 50,000 requests per day
• Mutations: Varies by account (typically 5,000-50,000 per day)

Best Practices

• Batch Operations: Use bulk mutations when possible
• Efficient Queries: Request only needed fields in reports
• Caching: Cache frequently accessed data like campaign lists
• Error Handling: Implement retry logic for temporary failures
• Monitoring: Set up alerts for quota usage

Performance Optimization

# Use specific field selections for faster queries
./google-ads.sh campaigns-list | jq '.results[] | {name: .campaign.name, status: .campaign.status, cost: .metrics.cost_micros}'

# Batch keyword additions
echo "keyword1 EXACT
keyword2 PHRASE  
keyword3 BROAD" | while read keyword match_type; do
  ./google-ads.sh keyword-add 123456789 "$keyword" "$match_type"
done

Output Format

All commands return structured JSON for easy parsing and integration:

Campaign List Output:

{
  "results": [
    {
      "campaign": {
        "id": "123456789",
        "name": "Holiday Sale 2024",
        "status": "ENABLED",
        "advertising_channel_type": "SEARCH"
      },
      "metrics": {
        "impressions": "15420",
        "clicks": "832",
        "cost_micros": "4567890000",
        "ctr": "5.39",
        "conversions": "23"
      }
    }
  ]
}

Error Format:

{
  "error": "Google Ads API error: Invalid customer ID"
}

Troubleshooting

Common Issues

Authentication Errors:

• Verify all OAuth credentials are correct
• Ensure refresh token hasn't expired (regenerate if needed)
• Check that Customer ID format is correct (numbers only, no dashes)

API Access Issues:

• Confirm Google Ads account has API access enabled
• Verify developer token is approved for production use
• Check that billing is set up on the Google Ads account

Permission Errors:

• Ensure OAuth scope includes Google Ads API access
• Verify account has necessary permissions for the operations
• Check if account is properly linked to the Customer ID

Rate Limiting:

• Implement delays between bulk operations
• Use batch operations when available
• Monitor quota usage in Google Cloud Console

Debug Mode

Enable detailed logging for troubleshooting:

# Set debug environment variable
DEBUG=google-ads:* ./google-ads.sh campaigns-list

# Check API response details
./google-ads.sh campaigns-list 2>&1 | jq .

Setup Guide

For detailed credential setup instructions, see setup.md.

Deploy with PinchKit

Deploy this Google Ads CLI plugin to your PinchKit infrastructure:

1. Package the plugin:

   cd /root/.openclaw/workspace/skills/google-ads
   tar -czf google-ads-plugin.tar.gz .

2. Deploy via PinchKit CLI:

   pinchkit deploy --type openclaw-plugin --file google-ads-plugin.tar.gz --name google-ads-cli

3. Configure environment:

   pinchkit env set GOOGLE_ADS_CUSTOMER_ID "1234567890"
   pinchkit env set GOOGLE_ADS_DEVELOPER_TOKEN "your_developer_token"
   pinchkit env set GOOGLE_ADS_CLIENT_ID "your_client_id"
   pinchkit env set GOOGLE_ADS_CLIENT_SECRET "your_client_secret"
   pinchkit env set GOOGLE_ADS_REFRESH_TOKEN "your_refresh_token"

4. Test deployment:

   pinchkit exec google-ads-cli "./google-ads.sh campaigns-list"

5. Set up monitoring & scaling:

   pinchkit scale google-ads-cli --instances 3
   pinchkit monitor google-ads-cli --alerts high-cpu,high-memory
   pinchkit logs google-ads-cli --follow

The plugin will be available across your PinchKit cluster with automatic load balancing, monitoring, and scaling capabilities.

Contributing

1. Fork this repository
2. Create a feature branch
3. Add tests for new functionality
4. Update documentation
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

• Issues: Create an issue in this repository
• Documentation: See SKILL.md for OpenClaw integration details
• API Reference: Google Ads API Documentation