CLI tool for programmatic ad campaign management across multiple platforms. Built for AI agents and automation pipelines — all output is structured JSON to stdout, human-readable logs go to stderr.
| Platform | Status | Auth Method |
|---|---|---|
| Google Ads | Available | OAuth2 + Developer Token |
| YouTube Ads | Available | Same as Google Ads (VIDEO channel) |
| Meta Ads (Instagram) | Available | System User Access Token |
| Reddit Ads | Planned (Phase 2) | OAuth2 |
| TikTok Ads | Planned (Phase 2) | Access Token |
| Pinterest Ads | Planned (Phase 2) | OAuth2 |
- Node.js >= 20.0.0
- pnpm (recommended) or npm
- API credentials for the platforms you want to use (see
.env.example)
# Clone the repository
git clone <repo-url>
cd auto-ads
# Install dependencies
pnpm install
# Copy and fill in credentials
cp .env.example .env
# Edit .env with your platform credentials
# Verify setup
pnpm typecheck
pnpm testThe CLI follows the pattern: ads-manager <platform> <action> [options]
pnpm dev google auth-test
pnpm dev youtube auth-test
pnpm dev meta auth-testpnpm dev google list-campaigns
pnpm dev meta list-campaignspnpm dev google create-campaign --from-file=templates/google-campaign.json
pnpm dev youtube create-campaign --from-file=templates/youtube-campaign.json
pnpm dev meta create-campaign --from-file=templates/meta-campaign.jsonpnpm dev google pause --campaign-id=123456
pnpm dev google enable --campaign-id=123456pnpm dev google get-performance --days=7
pnpm dev google get-performance --campaign-id=123456 --days=30All commands output structured JSON to stdout:
{
"success": true,
"platform": "google",
"action": "list-campaigns",
"data": [...]
}Campaign configs are JSON files in templates/. Each platform has its own schema validated with Zod at runtime. See the example templates:
templates/google-campaign.json— Search campaign with ad groups, keywords, and responsive search adstemplates/youtube-campaign.json— Video campaign (in-stream / bumper)templates/meta-campaign.json— Instagram-first campaign with targeting
pnpm dev # Run CLI in development mode (via tsx)
pnpm test # Run all tests
pnpm test:watch # Run tests in watch mode
pnpm typecheck # TypeScript type checking
pnpm lint # Check formatting (Prettier)
pnpm lint:fix # Auto-fix formatting
pnpm build # Compile to dist/src/
├── cli.ts # Commander.js entry point
├── config.ts # Env var validation (Zod schemas per platform)
├── platforms/
│ ├── platform.ts # PlatformClient interface (shared contract)
│ ├── registry.ts # Platform factory (name → client instance)
│ ├── google/ # Google Ads (google-ads-api SDK)
│ │ ├── client.ts # GoogleAdsClient
│ │ ├── campaigns.ts # Campaign creation orchestration
│ │ ├── adgroups.ts # Ad group creation
│ │ ├── keywords.ts # Keyword targeting
│ │ ├── ads.ts # Responsive Search Ad creation
│ │ └── reporting.ts # GAQL performance queries
│ ├── youtube/ # YouTube Ads (thin Google wrapper, VIDEO channel)
│ │ └── client.ts # YouTubeAdsClient
│ └── meta/ # Meta Ads (facebook-nodejs-business-sdk)
│ └── client.ts # MetaAdsClient
├── types/
│ ├── common.ts # CLIResponse / CLIError types
│ ├── google.ts # Google campaign Zod schema
│ ├── youtube.ts # YouTube campaign Zod schema
│ └── meta.ts # Meta campaign Zod schema
└── utils/
├── errors.ts # PlatformError class
├── http.ts # Shared HTTP client (rate limiting, retry, token refresh)
└── logger.ts # Structured JSON logging (stdout/stderr)
Every platform implements the PlatformClient interface:
interface PlatformClient {
readonly platform: string;
authTest(): Promise<AuthTestResult>;
listCampaigns(): Promise<Campaign[]>;
createCampaign(config: CampaignConfig): Promise<CampaignResult>;
pauseCampaign(id: string): Promise<void>;
enableCampaign(id: string): Promise<void>;
getPerformance(params: PerformanceQuery): Promise<PerformanceData>;
}Build the project and run the compiled output:
pnpm build
node dist/cli.js google auth-testDocker and Railway deployment support coming in a future release.
MIT