Package Exports

adpilot
adpilot/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (adpilot) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

adpilot

A powerful CLI for the Meta/Facebook Marketing API. Manage campaigns, ad sets, ads, creatives, audiences, budgets, and performance insights -- all from your terminal. Built for both human use and machine (LLM pipeline) consumption with first-class JSON output and stdin piping.

Features

Full Campaign Lifecycle -- Create, update, pause, resume, archive, copy, and delete campaigns, ad sets, ads, and creatives
Performance Insights -- Pull metrics at any level with date ranges, breakdowns, and CSV export
AI Ad Copy Pipeline -- Generate LLM prompts for ad copy, parse responses into deployable templates, feed performance back for iteration
Template Deploy System -- Define entire campaign stacks in JSON and deploy with a single command
Variant Generation -- Auto-generate combinatorial ad variants across headlines, bodies, CTAs, countries, and age groups
Test Cycle Orchestration -- End-to-end test cycles: deploy, evaluate, kill losers, scale winners
Performance Monitoring -- Threshold-based auto-pause, winner/loser detection with composite scoring
Budget Allocation -- Dynamic cross-project budget allocation by demand score, performance, or equal split
Audience Discovery -- Analyze campaign breakdowns to discover top-performing segments and auto-create targeted ad sets
Targeting Builder -- Interactive wizard and API search for interests, locations, demographics, and audience size estimates
A/B Split Testing -- Create and monitor ad studies with statistical confidence tracking
Automated Rules -- Create metric-based rules to auto-pause, scale, or notify on performance thresholds
Lead Management -- List forms, download leads to CSV, create new lead gen forms
Saved Reports -- Save, run, and compare report templates across time periods with async support
Batch API -- Execute up to 50 API calls in a single HTTP request
Webhook Subscriptions -- Subscribe to ad account change notifications
Multi-Account Profiles -- Switch between multiple ad accounts and tokens instantly
OAuth 2.0 Flow -- Built-in OAuth with long-lived token exchange and refresh
Shell Completions -- Auto-install for Bash, Zsh, and Fish

Installation

npm (global)

npm install -g adpilot

From source

git clone https://github.com/connorodea/adpilot.git
cd adpilot
npm install
npm run build
npm link

Development

npm run dev -- campaigns list    # Run via ts-node

Quick Start

# 1. Authenticate
adpilot auth login

# 2. Set your ad account
adpilot config set adAccountId act_123456789

# 3. List campaigns
adpilot campaigns list

# 4. Pull last 7 days of insights
adpilot insights account --date-preset last_7d

# 5. Export campaign insights to CSV
adpilot insights campaign 123456789 --csv report.csv

Getting a Facebook Access Token

Go to Meta Business Suite > Settings > Users > System Users
Generate a token with ads_management, ads_read, and read_insights permissions
Or use the built-in OAuth flow: adpilot auth oauth --app-id YOUR_APP_ID --app-secret YOUR_SECRET
For testing, use the Graph API Explorer

Command Reference

Every command supports --help for full option details. Most list/get commands support --json, --fields, and --account-id flags.

Core

`auth` -- Authentication & profiles

Subcommand	Description
`auth login`	Set access token (interactive or `--token`)
`auth logout`	Clear stored token
`auth status`	Check authentication status
`auth token`	Display current token
`auth oauth`	OAuth 2.0 flow for long-lived tokens
`auth refresh`	Refresh current token
`auth inspect`	Inspect token metadata (scopes, expiry)
`auth profiles list`	List all saved profiles
`auth profiles add`	Add a named profile (`--name`, `--token`, `--account-id`)
`auth profiles switch <name>`	Switch active profile
`auth profiles remove <name>`	Delete a profile
`auth profiles current`	Show active profile

# OAuth flow with automatic long-lived token
adpilot auth oauth --app-id 123 --app-secret abc

# Multi-account setup
adpilot auth profiles add --name client-a --token EAA... --account-id act_111
adpilot auth profiles add --name client-b --token EAA... --account-id act_222
adpilot auth profiles switch client-a

`config` -- Configuration

Subcommand	Description
`config show`	Display current configuration
`config set <key> <value>`	Set a config value
`config reset`	Reset all to defaults
`config path`	Show config file location

Keys: adAccountId, apiVersion, defaultOutputFormat (table/json), pageSize

`account` -- Account info

Subcommand	Description
`account info`	View ad account details (status, currency, spend)
`account list`	List all ad accounts for the current user

Campaign Management

`campaigns` -- Campaign CRUD (aliases: `campaign`, `camp`)

Subcommand	Description
`campaigns list`	List campaigns (filter by `--status`)
`campaigns get <id>`	Get campaign details
`campaigns create`	Create campaign (`-n`, `-o`, `--daily-budget`)
`campaigns update <id>`	Update name, status, budget, bid strategy
`campaigns pause <id>`	Pause a campaign
`campaigns resume <id>`	Activate a campaign
`campaigns archive <id>`	Archive a campaign
`campaigns delete <id>`	Delete a campaign
`campaigns copy <id>`	Duplicate a campaign (`--deep` for full copy)

adpilot campaigns create -n "Summer Sale" -o OUTCOME_SALES --daily-budget 5000
adpilot campaigns copy 123456 --deep --rename-prefix "Copy -"

Objectives: OUTCOME_AWARENESS, OUTCOME_ENGAGEMENT, OUTCOME_LEADS, OUTCOME_SALES, OUTCOME_TRAFFIC, OUTCOME_APP_PROMOTION

`adsets` -- Ad set CRUD (aliases: `adset`)

Subcommand	Description
`adsets list`	List ad sets (`--campaign-id` to filter)
`adsets get <id>`	Get ad set details
`adsets create`	Create ad set (targeting, billing, optimization)
`adsets update <id>`	Update fields
`adsets pause <id>`	Pause
`adsets resume <id>`	Activate
`adsets delete <id>`	Delete
`adsets set-schedule <id>`	Set dayparting schedule (`--days`, `--start-minute`, `--end-minute`)
`adsets get-schedule <id>`	View current schedule

adpilot adsets create -n "US 18-35" \
  --campaign-id 123 \
  --billing-event IMPRESSIONS \
  --optimization-goal LINK_CLICKS \
  --daily-budget 2000 \
  --targeting '{"geo_locations":{"countries":["US"]},"age_min":18,"age_max":35}'

# Weekday-only delivery (dayparting)
adpilot adsets set-schedule 456 --days 1,2,3,4,5 --start-minute 540 --end-minute 1200

`ads` -- Ad CRUD (aliases: `ad`)

Subcommand	Description
`ads list`	List ads (`--campaign-id`, `--adset-id` filters)
`ads get <id>`	Get ad details
`ads create`	Create ad with creative spec
`ads update <id>`	Update name, status, creative
`ads pause <id>`	Pause
`ads resume <id>`	Activate
`ads delete <id>`	Delete
`ads preview <id>`	Generate ad preview HTML

`creatives` -- Creative management (aliases: `creative`)

Subcommand	Description
`creatives list`	List ad creatives
`creatives get <id>`	Get creative details
`creatives create`	Create from object story spec, image hash, etc.
`creatives create-dynamic`	Create dynamic creative with asset feed spec
`creatives create-carousel`	Create carousel creative with multiple cards
`creatives update <id>`	Update name/status
`creatives delete <id>`	Delete
`creatives preview <id>`	Preview a creative

# Dynamic creative with multiple variants
adpilot creatives create-dynamic -n "Test Creative" \
  --page-id 123 \
  --images hash1,hash2 \
  --titles "Buy Now|Shop Today" \
  --bodies "Great deals|Limited time" \
  --link-url https://example.com

# Carousel creative
adpilot creatives create-carousel -n "Products" \
  --page-id 123 \
  --cards-file cards.json \
  --message "Check out our lineup"

`images` -- Image management (aliases: `image`, `img`)

Subcommand	Description
`images upload <file>`	Upload image, returns hash
`images list`	List images in account

`videos` -- Video management (aliases: `video`, `vid`)

Subcommand	Description
`videos upload <file>`	Upload video file
`videos list`	List videos in account
`videos get <id>`	Get video details
`videos delete <id>`	Delete a video

Insights & Reporting

`insights` -- Performance insights (alias: `report`)

Subcommand	Description
`insights account`	Account-level insights
`insights campaign <id>`	Campaign-level insights
`insights adset <id>`	Ad set-level insights
`insights ad <id>`	Ad-level insights

All subcommands support --date-preset, --since/--until, --breakdowns, --csv <file>, and --json.

# Date range with breakdowns
adpilot insights account --since 2025-01-01 --until 2025-01-31 --breakdowns age,gender

# Export to CSV
adpilot insights campaign 123 --date-preset last_30d --csv campaign-report.csv

Date presets: today, yesterday, this_month, last_month, last_7d, last_14d, last_30d, last_90d, maximum

Breakdowns: age, gender, country, region, dma, impression_device, platform_position, publisher_platform, device_platform

`reports` -- Saved reports & comparison

Subcommand	Description
`reports save`	Save an insight query as a named template
`reports list`	List saved report templates
`reports run <name>`	Execute a saved report
`reports delete <name>`	Delete a saved report
`reports compare`	Compare metrics across two time periods
`reports async`	Request a large async insights report
`reports async-status <id>`	Check async report status
`reports async-download <id>`	Download completed async report
`reports async-wait <id>`	Poll and auto-download when complete

# Save a report template
adpilot reports save --name weekly-perf --level campaign \
  --fields impressions,clicks,spend,ctr,cpc --date-preset last_7d

# Run it anytime
adpilot reports run weekly-perf --csv weekly.csv

# Compare two time periods
adpilot reports compare --level account \
  --period1 2025-01-01,2025-01-31 \
  --period2 2025-02-01,2025-02-28

# Large async report
adpilot reports async --level ad --fields impressions,clicks,spend --date-preset last_90d
adpilot reports async-wait <report_run_id> --csv large-report.csv

AI Pipeline

`ai` -- AI-assisted ad copy

Subcommand	Description
`ai generate-copy`	Generate an LLM prompt for ad copy variants
`ai parse-copy`	Parse LLM-generated JSON into a deployable template
`ai feedback`	Generate performance feedback for LLM iteration

# Step 1: Generate prompt for your LLM
adpilot ai generate-copy --product "Widget Pro" \
  --description "A better widget" --tone casual --variants 5

# Step 2: Paste LLM response into a file, then parse it
adpilot ai parse-copy --input llm-response.json \
  --product "Widget Pro" --url https://example.com --output template.json

# Step 3: Deploy the template
adpilot deploy run -t template.json

# Step 4: After data collects, generate feedback for next iteration
adpilot ai feedback --campaign 123456 --date-preset last_7d --output feedback.md

`generate` -- Variant generation

Subcommand	Description
`generate variants`	Generate combinatorial ad variants from headlines, bodies, CTAs
`generate from-template`	Multiply a base template across a variable matrix

# Auto-generate variants
adpilot generate variants \
  --name "Widget Pro" --url https://example.com \
  --headlines "Buy Now,Shop Today,Get Yours" \
  --bodies "Great deals await|Limited time offer" \
  --ctas SHOP_NOW,LEARN_MORE \
  --countries US,GB --age-groups 18-30,31-45 \
  --deploy

# Template matrix expansion
adpilot generate from-template \
  --template base.json \
  --matrix '{"country":["US","UK","CA"],"cta":["SHOP_NOW","LEARN_MORE"]}' \
  --output ./variants/ --deploy-all

`deploy` -- Template deployment

Subcommand	Description
`deploy run`	Deploy a template JSON to Meta Ads
`deploy validate`	Validate a template without deploying

adpilot deploy run -t campaign.json --dry-run       # Preview what would be created
adpilot deploy run -t campaign.json                   # Deploy for real
adpilot deploy run -t campaign.json --var headline="New Text" --var budget=5000
adpilot deploy validate -t campaign.json              # Validate only

`cycle` -- Test cycle orchestrator

Subcommand	Description
`cycle run`	Full test cycle: deploy template, link to project, evaluate, act
`cycle status <campaignId>`	Quick health check of a running campaign
`cycle report <campaignId>`	Detailed report with winners, losers, and recommendations

# Full pipeline: deploy + link + monitor
adpilot cycle run -t campaign.json --project my-product \
  --min-ctr 0.5 --max-cpa 50 --evaluate

# Post-run analysis
adpilot cycle report 123456 --date-preset last_7d

`validate` -- Market validation

Subcommand	Description
`validate market <projectId>`	Generate a market validation report with verdict

Produces a structured report with STRONG/MODERATE/WEAK/INSUFFICIENT DATA verdict and actionable next steps.

adpilot validate market my-product --date-preset maximum --output report.md

Project Management

`projects` -- IP/product registry (aliases: `project`, `ip`)

Subcommand	Description
`projects list`	List all registered projects
`projects create`	Register a new product/IP for testing
`projects get <id>`	Show project details and linked campaigns
`projects update <id>`	Update project fields
`projects delete <id>`	Remove from registry
`projects link <projectId> <campaignId>`	Associate a campaign with a project
`projects unlink <projectId> <campaignId>`	Remove association
`projects report <projectId>`	Aggregated insights across all linked campaigns
`projects dashboard`	Cross-project performance dashboard with demand scoring

adpilot projects create -n "Widget Pro" -u https://example.com -b 100000
adpilot projects link widget-pro 123456789
adpilot projects dashboard --sort demand_score

`monitor` -- Performance monitoring (alias: `mon`)

Subcommand	Description
`monitor run`	Evaluate campaigns against thresholds, auto-pause underperformers
`monitor winners`	Detect top-performing ads, optionally scale budgets
`monitor losers`	Detect worst-performing ads, optionally pause
`monitor status`	Quick health overview of active campaigns

# Auto-kill underperformers
adpilot monitor run --min-ctr 0.5 --max-cpa 50 --max-cpc 5 --dry-run
adpilot monitor run --project my-product   # Scope to a project

# Scale winners by 1.5x
adpilot monitor winners --top 5 --scale-budget 1.5

# Pause bottom performers
adpilot monitor losers --bottom 5 --pause

`budget` -- Budget allocation & scheduling

Subcommand	Description
`budget allocate`	Dynamically allocate budget across projects by strategy
`budget status`	Show budget utilization and pacing across projects
`budget schedule`	Set a scheduled budget change for a campaign
`budget schedule-list`	List all budget schedules
`budget schedule-apply`	Apply/revert pending budget schedules
`budget schedule-delete <id>`	Delete a schedule

# Allocate $500/day across all projects by demand score
adpilot budget allocate --total-budget 50000 --strategy demand_score --dry-run

# Schedule a budget increase for a sale
adpilot budget schedule --campaign-id 123 --budget 10000 \
  --start-date 2025-03-01 --end-date 2025-03-07 --original-budget 5000

Strategies: equal, performance (by CTR), demand_score (clicks/spend ratio)

Targeting & Audiences

`targeting` -- Targeting builder & search

Subcommand	Description
`targeting build`	Interactive wizard to build targeting JSON
`targeting search <query>`	Search interests, locations, demographics
`targeting estimate <json>`	Get audience size estimate for a targeting spec

adpilot targeting build                                    # Interactive wizard
adpilot targeting search "fitness" --type adinterest       # Search interests
adpilot targeting estimate '{"geo_locations":{"countries":["US"]},"age_min":25}'

Search types: adinterest, adinterestsuggestion, adTargetingCategory, adgeolocation, adeducationschool, adworkemployer, adworkposition, adlocale

`audiences` -- Custom audiences (alias: `audience`)

Subcommand	Description
`audiences list`	List custom audiences
`audiences get <id>`	Get audience details
`audiences create`	Create a custom audience
`audiences create-lookalike`	Create a lookalike audience from a source
`audiences delete <id>`	Delete an audience

adpilot audiences create -n "Website Visitors" --subtype WEBSITE
adpilot audiences create-lookalike --source-audience 123 --countries US,GB --ratio 0.02

`discover` -- Audience discovery engine

Subcommand	Description
`discover audiences <campaignId>`	Analyze breakdowns to find best segments, optionally auto-create ad sets
`discover interests <campaignId>`	Suggest interest targeting based on performance

# Find top-performing audience segments
adpilot discover audiences 123456 --breakdowns age,gender,country --top 10

# Auto-create ad sets for top segments
adpilot discover audiences 123456 --create-adsets --daily-budget 1500

# Discover related interests
adpilot discover interests 123456

Automation

`rules` -- Automated ad rules (alias: `rule`)

Subcommand	Description
`rules list`	List ad rules
`rules get <id>`	Get rule details
`rules create`	Create a rule (metric, operator, threshold, action)
`rules quick-create`	Create from presets: `pause-high-cpa`, `pause-low-ctr`, `scale-winners`, `notify-spend`
`rules pause <id>`	Disable a rule
`rules resume <id>`	Enable a rule
`rules delete <id>`	Delete a rule

# Quick preset rules
adpilot rules quick-create --type pause-high-cpa --apply-to 123,456 --apply-to-type CAMPAIGN
adpilot rules quick-create --type scale-winners --apply-to 789 --apply-to-type ADSET --threshold 2.0

# Custom rule
adpilot rules create --name "Pause low CTR" \
  --apply-to 123 --apply-to-type AD \
  --metric ctr --operator LESS_THAN --value 0.3 \
  --action PAUSE --schedule DAILY

`bulk` -- Bulk operations

Subcommand	Description
`bulk pause`	Pause multiple objects by ID
`bulk resume`	Resume multiple objects
`bulk delete`	Delete multiple objects
`bulk update`	Update fields on multiple objects

adpilot bulk pause --type campaign --ids 111,222,333
adpilot bulk update --type adset --ids 111,222 --set daily_budget=5000
echo -e "111\n222\n333" | adpilot bulk pause --type ad --stdin

`batch` -- Batch API requests

Subcommand	Description
`batch run`	Execute batch requests from a JSON file
`batch from-ids`	Build and execute batch from object IDs

Sends up to 50 API calls in a single HTTP request (auto-chunks larger sets).

# From a file
adpilot batch run --requests batch.json

# Quick batch from IDs
adpilot batch from-ids --type campaign --ids 111,222,333 --action get --fields id,name,status
adpilot batch from-ids --type ad --ids 111,222 --action pause

Advanced

`labels` -- Ad labels (alias: `label`)

Subcommand	Description
`labels list`	List labels
`labels create`	Create a label
`labels delete <id>`	Delete a label
`labels assign <labelId>`	Assign label to an object (`--to`, `--type`)
`labels remove <labelId>`	Remove label from an object (`--from`)

`leads` -- Lead gen forms & downloads

Subcommand	Description
`leads forms`	List lead forms for a page (`--page-id`)
`leads form-get <formId>`	Get form details
`leads download <formId>`	Download leads (supports `--csv`)
`leads create-form`	Create a new lead form
`leads delete <formId>`	Delete a form

adpilot leads forms --page-id 123456
adpilot leads download 789 --csv leads.csv

`splits` -- A/B split testing (alias: `split`)

Subcommand	Description
`splits create`	Create an ad study
`splits list`	List ad studies
`splits get <id>`	Get study details
`splits results <id>`	Get results and winner
`splits delete <id>`	Delete a study
`splits quick-ab`	Quick A/B setup from two ad sets

# Quick A/B test
adpilot splits quick-ab --name "Landing Page Test" \
  --adset-a 111 --adset-b 222 --split 50,50 --duration 7

# Check results
adpilot splits results 123456

`webhooks` -- Webhook subscriptions (alias: `webhook`)

Subcommand	Description
`webhooks subscribe`	Subscribe to change notifications
`webhooks list`	List subscriptions
`webhooks delete`	Delete a subscription
`webhooks test`	Send a test verification to your callback URL

adpilot webhooks subscribe --callback-url https://example.com/webhook \
  --verify-token my-secret --fields spend,status

adpilot webhooks test --callback-url https://example.com/webhook \
  --verify-token my-secret

`logs` -- API call logs

Subcommand	Description
`logs show`	Display API call logs (`--date`, `--status`, `--limit`)
`logs clear`	Delete log files (`--before <date>` or `--all`)

`completions` -- Shell completions

Subcommand	Description
`completions bash`	Output Bash completion script
`completions zsh`	Output Zsh completion script
`completions fish`	Output Fish completion script
`completions install`	Auto-detect shell and install

Template System

adpilot uses JSON template files to define complete campaign stacks (campaign + ad sets + ads + creatives) that can be deployed in a single command.

Template structure

{
  "name": "My Test Campaign",
  "description": "Optional description",
  "variables": {
    "headline": { "description": "Ad headline", "default": "Buy Now" },
    "budget": { "description": "Daily budget in cents", "default": "1500" }
  },
  "campaign": {
    "name": "{{headline}} Campaign",
    "objective": "OUTCOME_TRAFFIC",
    "status": "PAUSED",
    "special_ad_categories": []
  },
  "adsets": [
    {
      "name": "US Broad",
      "billing_event": "IMPRESSIONS",
      "optimization_goal": "LINK_CLICKS",
      "daily_budget": "{{budget}}",
      "targeting": {
        "geo_locations": { "countries": ["US"] }
      },
      "status": "PAUSED"
    }
  ],
  "ads": [
    {
      "name": "Ad Variant 1",
      "adset_index": 0,
      "creative": {
        "name": "Creative V1",
        "title": "{{headline}}",
        "body": "Check out our product!",
        "link_url": "https://example.com",
        "call_to_action_type": "LEARN_MORE"
      },
      "status": "PAUSED"
    }
  ]
}

Template variables

Templates support {{variable}} placeholders that are resolved at deploy time:

adpilot deploy run -t template.json --var headline="Shop Now" --var budget=3000

Workflow

# Validate first
adpilot deploy validate -t template.json

# Preview the deploy plan
adpilot deploy run -t template.json --dry-run

# Deploy for real
adpilot deploy run -t template.json

AI Ad Testing Pipeline

adpilot supports a full end-to-end AI-driven ad testing pipeline:

1. REGISTER       adpilot projects create -n "Widget Pro" -u https://example.com
       |
2. GENERATE        adpilot ai generate-copy --product "Widget Pro" --description "..." --variants 5
       |            (copy prompt to LLM, save response as variants.json)
       |
3. PARSE           adpilot ai parse-copy --input variants.json --product "Widget Pro" --url https://...
       |            (outputs a deployable template)
       |
4. DEPLOY          adpilot deploy run -t template.json
       |            (creates campaign, ad sets, creatives, and ads)
       |
5. LINK            adpilot projects link widget-pro <campaign_id>
       |
6. MONITOR         adpilot monitor status --project widget-pro
       |            adpilot monitor run --project widget-pro --dry-run
       |
7. EVALUATE        adpilot monitor winners --top 5 --scale-budget 1.5
       |            adpilot monitor losers --bottom 5 --pause
       |
8. FEEDBACK        adpilot ai feedback --campaign <id> --output feedback.md
       |            (feed report back into LLM for next iteration)
       |
9. VALIDATE        adpilot validate market widget-pro
                   (go/no-go verdict: STRONG, MODERATE, WEAK, INSUFFICIENT DATA)

Or use cycle run to orchestrate steps 4-7 in a single command:

adpilot cycle run -t template.json --project widget-pro --evaluate --min-ctr 0.5 --max-cpa 50

Environment Variables

Variable	Description
`ADPILOT_TOKEN`	Access token (overrides config)
`FACEBOOK_ACCESS_TOKEN`	Access token (fallback)

Tokens are resolved in this order: active profile > config file > ADPILOT_TOKEN > FACEBOOK_ACCESS_TOKEN.

Configuration

Configuration is stored in ~/.config/adpilot/ (or ~/.adpilot/) via the conf library.

Key	Default	Description
`adAccountId`	(none)	Your ad account ID (`act_XXXXX`)
`apiVersion`	`v25.0`	Meta Graph API version
`defaultOutputFormat`	`table`	Default output: `table` or `json`
`pageSize`	`25`	Default results per page
`accessToken`	(none)	Stored access token
`appId`	(none)	Facebook App ID (for OAuth)
`appSecret`	(none)	Facebook App Secret (for OAuth)
`tokenExpiresAt`	(none)	Token expiry timestamp

adpilot config show                          # View current config
adpilot config set adAccountId act_123456    # Set account
adpilot config set apiVersion v24.0          # Change API version
adpilot config path                          # Show config file path

Shell Completions

# Auto-detect and install
adpilot completions install

# Or manually:
# Bash
adpilot completions bash >> ~/.bashrc && source ~/.bashrc

# Zsh
adpilot completions zsh > ~/.zsh/completions/_adpilot
# Add to .zshrc: fpath=(~/.zsh/completions $fpath) && autoload -Uz compinit && compinit

# Fish
adpilot completions fish > ~/.config/fish/completions/adpilot.fish

API Version

Defaults to v25.0. Change with:

adpilot config set apiVersion v24.0

Global Options

Available on most commands:

Flag	Description
`--json`	Output as JSON instead of table
`--fields <fields>`	Comma-separated fields to return
`--account-id <id>`	Override the configured ad account
`--limit <n>`	Max results per page
`-v, --version`	Show version
`--help`	Show help for any command

Contributing

git clone https://github.com/connorodea/adpilot.git
cd adpilot
npm install
npm run build
npm test           # Run 93+ tests
npm run lint       # Type-check

Module system: CommonJS (not ESM). Chalk v4, ora v5, inquirer v8, node-fetch v2 are pinned for CJS compatibility.
Commands: Add new command files in src/commands/, register in src/index.ts.
Tests: Jest with ts-jest, located in tests/.

License

MIT

adpilot

Package Exports

Readme

adpilot

Features

Installation

npm (global)

From source

Development

Quick Start

Getting a Facebook Access Token

Command Reference

Core

auth -- Authentication & profiles

config -- Configuration

account -- Account info

Campaign Management

campaigns -- Campaign CRUD (aliases: campaign, camp)

adsets -- Ad set CRUD (aliases: adset)

ads -- Ad CRUD (aliases: ad)

creatives -- Creative management (aliases: creative)

images -- Image management (aliases: image, img)

videos -- Video management (aliases: video, vid)

Insights & Reporting

insights -- Performance insights (alias: report)

reports -- Saved reports & comparison

AI Pipeline

ai -- AI-assisted ad copy

generate -- Variant generation

deploy -- Template deployment

cycle -- Test cycle orchestrator

validate -- Market validation

Project Management

projects -- IP/product registry (aliases: project, ip)

monitor -- Performance monitoring (alias: mon)

budget -- Budget allocation & scheduling

Targeting & Audiences

targeting -- Targeting builder & search

audiences -- Custom audiences (alias: audience)

discover -- Audience discovery engine

Automation

rules -- Automated ad rules (alias: rule)

bulk -- Bulk operations

batch -- Batch API requests

Advanced

labels -- Ad labels (alias: label)

leads -- Lead gen forms & downloads

splits -- A/B split testing (alias: split)

webhooks -- Webhook subscriptions (alias: webhook)

logs -- API call logs

completions -- Shell completions

Template System

Template structure

Template variables

Workflow

AI Ad Testing Pipeline

Environment Variables

Configuration

Shell Completions

API Version

Global Options

Contributing

License

`auth` -- Authentication & profiles

`config` -- Configuration

`account` -- Account info

`campaigns` -- Campaign CRUD (aliases: `campaign`, `camp`)

`adsets` -- Ad set CRUD (aliases: `adset`)

`ads` -- Ad CRUD (aliases: `ad`)

`creatives` -- Creative management (aliases: `creative`)

`images` -- Image management (aliases: `image`, `img`)

`videos` -- Video management (aliases: `video`, `vid`)

`insights` -- Performance insights (alias: `report`)

`reports` -- Saved reports & comparison

`ai` -- AI-assisted ad copy

`generate` -- Variant generation

`deploy` -- Template deployment

`cycle` -- Test cycle orchestrator

`validate` -- Market validation

`projects` -- IP/product registry (aliases: `project`, `ip`)

`monitor` -- Performance monitoring (alias: `mon`)

`budget` -- Budget allocation & scheduling

`targeting` -- Targeting builder & search

`audiences` -- Custom audiences (alias: `audience`)

`discover` -- Audience discovery engine

`rules` -- Automated ad rules (alias: `rule`)

`bulk` -- Bulk operations

`batch` -- Batch API requests

`labels` -- Ad labels (alias: `label`)

`leads` -- Lead gen forms & downloads

`splits` -- A/B split testing (alias: `split`)

`webhooks` -- Webhook subscriptions (alias: `webhook`)

`logs` -- API call logs

`completions` -- Shell completions