asa-cli

The missing command-line interface for Apple Search Ads. Manage campaigns, ad groups, keywords, and reporting — built for AI agents and humans.

Features

• Multiple profiles — manage many Apple Search Ads accounts
• AI-agent friendly — JSON output by default when piped, --help --json for machine-readable discovery
• Full CRUD for campaigns, ad groups, and keywords
• Performance reports (campaigns, ad groups, keywords)
• Environment variable overrides for CI/CD

Install

npm install -g @onmyway133/asa-cli

Or with Bun:

bun install -g @onmyway133/asa-cli

Authentication

Interactive setup

asa auth login

You'll be prompted for:

• Client ID — from Apple Search Ads API settings (SEARCHADS.xxxxxxxx-…)
• Team ID — your team/account identifier
• Key ID — the key identifier
• Org ID — your organization ID (from app.searchads.apple.com > Settings > API)
• Private key — path to .p8 file or paste PEM content

Credentials are stored in ~/.asa/credentials.json (mode 600).

Environment variables (CI / AI agents)

export ASA_CLIENT_ID=SEARCHADS.00000000-0000-0000-0000-000000000000
export ASA_TEAM_ID=ABCDE12345
export ASA_KEY_ID=ABCDE12345
export ASA_ORG_ID=123456789
export ASA_PRIVATE_KEY_PATH=~/keys/AuthKey.p8
# or inline PEM:
export ASA_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n..."

Multiple Profiles

# Add a second account
asa auth login --name client-a

# Switch active profile
asa auth use client-a

# Or use per-command
asa campaigns list --profile client-a

# See all profiles
asa auth list

# Remove a profile
asa auth logout client-a

Commands

Campaigns

asa campaigns list
asa campaigns list --output json
asa campaigns get 12345678
asa campaigns create --name "My App - Brand" --adam-id 1234567890 --budget 1000 --currency USD --countries US,GB
asa campaigns update 12345678 --status PAUSED
asa campaigns update 12345678 --budget 2000 --currency USD
asa campaigns delete 12345678

Ad Groups

asa adgroups list --campaign 12345678
asa adgroups get --campaign 12345678 87654321
asa adgroups create --campaign 12345678 --name "Exact Match" --cpa-goal 2.50 --currency USD
asa adgroups pause --campaign 12345678 87654321

Keywords

asa keywords list --campaign 12345678 --adgroup 87654321
asa keywords add --campaign 12345678 --adgroup 87654321 --text "photo editor" --match EXACT
asa keywords add --campaign 12345678 --adgroup 87654321 --text "image editing" --match BROAD --bid 1.50 --currency USD
asa keywords pause --campaign 12345678 --adgroup 87654321 11112222

Reports

asa reports campaigns --start 2024-01-01 --end 2024-01-31
asa reports campaigns --start 2024-01-01 --end 2024-01-31 --granularity WEEKLY
asa reports adgroups --campaign 12345678 --start 2024-01-01 --end 2024-01-31
asa reports keywords --campaign 12345678 --adgroup 87654321 --start 2024-01-01 --end 2024-01-31

Apps

asa apps list

Output Formats

| Context | Default | |---------|---------| | Terminal (TTY) | table — colored ASCII tables | | Pipe / script | json — machine-readable JSON |

Force a format with --output json or --output table.

AI Agent Usage

# Get machine-readable command tree (for LLM tool use / system prompts)
asa --help --json

# All commands output JSON when piped
asa campaigns list | jq '.[].name'

# Combine env auth + JSON output for fully automated flows
ASA_CLIENT_ID=... ASA_TEAM_ID=... ASA_KEY_ID=... ASA_ORG_ID=... ASA_PRIVATE_KEY_PATH=... \
  asa reports campaigns --start 2024-01-01 --end 2024-01-31 --output json

Development

bun run dev <command>   # run without building
bun test               # run tests
bun run typecheck      # TypeScript type check
bun run build          # compile to dist/index.js

License

MIT