How do I install the Apple Ads CLI skill?

Run npx skillmds@latest add bin-huang/apple-ads-cli in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

What does the Apple Ads CLI skill do?

Apple Search Ads data analysis and reporting via apple-ads-cli. Use when the user wants to check Apple Search Ads performance, pull campaign/ad group/keyword stats, explore account structure, inspect ads and keywords, analyze budget orders, or check app eligibility. Triggers: "Apple Ads", "Apple Search Ads", "App Store ads", "apple ad performance", "apple campaign stats", "apple ad spend", "apple keyword report", "apple ads budget", "app eligibility", "search ads". It is listed under Marketing & Growth on SkillMD.

Is Apple Ads CLI safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Apple Ads CLI?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Apple Ads CLI free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Apple Ads CLI?

bin-huang (@bin-huang) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Apple Ads CLI by bin-huang — Agent Skill

Name: Apple Ads CLI
Author: bin-huang

Apple Ads CLI Skill

You have access to apple-ads-cli, a read-only CLI for the Apple Search Ads Campaign Management API (v5). Use it to query campaigns, ad groups, ads, keywords, budget orders, pull performance reports, and check app eligibility on the App Store.

Quick start

# Check if the CLI is available
apple-ads-cli --help

# Get authenticated user info
apple-ads-cli me

# Get access control list (find your orgId)
apple-ads-cli acl

If the CLI is not installed, install it:

npm install -g apple-ads-cli

Authentication

The CLI requires an OAuth2 access token and an organization ID. Credentials are resolved in this order:

--credentials <path> flag (per-command)
Environment variables: APPLE_ADS_ACCESS_TOKEN + APPLE_ADS_ORG_ID
Auto-detected file: ~/.config/apple-ads-cli/credentials.json

The credentials JSON file must contain access_token and org_id fields. The access token is obtained by signing a JWT with your private key (ES256) and exchanging it at Apple's OAuth endpoint. Tokens expire after 1 hour.

Before running any command, verify credentials are configured by running apple-ads-cli me. If it fails with a credentials error, ask the user to set up authentication.

Entity hierarchy

Organization (orgId)
 +-- Campaign
 |    +-- Ad Group
 |         +-- Ad
 |         +-- Targeting Keyword
 |         +-- Negative Keyword
 |    +-- Campaign-level Negative Keyword
 +-- Budget Order
 +-- App (by Adam ID)

Organization IDs are numeric identifiers shown in the Apple Search Ads UI. The acl command returns all organizations the user has access to.

Monetary values

The Apple Search Ads API returns monetary values as objects with amount (string) and currency (string) fields, e.g. {"amount": "12.34", "currency": "USD"}. The amount is in the major currency unit -- no conversion needed.

Output format

All commands output pretty-printed JSON by default. Use --format compact for single-line JSON (useful for piping).

All listing commands support --limit <n> (default 20) and --offset <n> (default 0) for pagination. Single-entity commands (me, acl, campaign, budget-order, app, app-eligibility) do not support pagination.

Commands reference

Account discovery

# Access control list -- find your orgId and permissions
apple-ads-cli acl

# Authenticated user details (userId, parentOrgId)
apple-ads-cli me

Apps

# Search for iOS apps to promote
apple-ads-cli search-apps "fitness"
apple-ads-cli search-apps "my app name" --return-own-apps --limit 10 --offset 0

# Check if an app is eligible for promotion
apple-ads-cli app-eligibility 123456789

# Get app details by Adam ID
apple-ads-cli app 123456789

search-apps options:

--return-own-apps -- only return apps owned by the organization
--limit <n> -- number of results (default 20)
--offset <n> -- pagination offset (default 0)

Campaigns

# List all campaigns
apple-ads-cli campaigns
apple-ads-cli campaigns --limit 50 --offset 0

# Get a specific campaign by ID
apple-ads-cli campaign 123456

campaigns options:

--limit <n> -- number of results (default 20)
--offset <n> -- pagination offset (default 0)

Budget orders

# List all budget orders
apple-ads-cli budget-orders
apple-ads-cli budget-orders --limit 50 --offset 0

# Get a specific budget order by ID
apple-ads-cli budget-order 789012

budget-orders options:

--limit <n> -- number of results (default 20)
--offset <n> -- pagination offset (default 0)

Ad groups

# List ad groups for a campaign
apple-ads-cli adgroups 123456
apple-ads-cli adgroups 123456 --limit 50 --offset 0

Options:

--limit <n> -- number of results (default 20)
--offset <n> -- pagination offset (default 0)

# List ads for an ad group (requires both campaign ID and ad group ID)
apple-ads-cli ads 123456 789012
apple-ads-cli ads 123456 789012 --limit 50

Options:

--limit <n> -- number of results (default 20)
--offset <n> -- pagination offset (default 0)

Keywords

# List targeting keywords for an ad group (requires campaign ID and ad group ID)
apple-ads-cli keywords 123456 789012
apple-ads-cli keywords 123456 789012 --limit 50

# List negative keywords for an ad group
apple-ads-cli negative-keywords 123456 789012
apple-ads-cli negative-keywords 123456 789012 --limit 50

# List campaign-level negative keywords
apple-ads-cli campaign-negative-keywords 123456
apple-ads-cli campaign-negative-keywords 123456 --limit 50

All keyword listing commands support:

--limit <n> -- number of results (default 20)
--offset <n> -- pagination offset (default 0)

Reports

Report commands use POST requests to the Apple Search Ads reporting API. All report commands require --start-date and --end-date.

# Campaign-level performance report
apple-ads-cli report 123456 \
  --start-date 2026-03-01 \
  --end-date 2026-03-15

# With granularity and grouping
apple-ads-cli report 123456 \
  --start-date 2026-03-01 \
  --end-date 2026-03-15 \
  --granularity DAILY \
  --group-by countryOrRegion,deviceClass

# Include records with zero metrics
apple-ads-cli report 123456 \
  --start-date 2026-03-01 \
  --end-date 2026-03-15 \
  --return-records-with-no-metrics

# Ad group-level report
apple-ads-cli report-adgroups 123456 \
  --start-date 2026-03-01 \
  --end-date 2026-03-15

# Keyword-level report
apple-ads-cli report-keywords 123456 \
  --start-date 2026-03-01 \
  --end-date 2026-03-15 \
  --granularity WEEKLY

report (campaign-level)

Options:

--start-date <date> -- start date, YYYY-MM-DD (required)
--end-date <date> -- end date, YYYY-MM-DD (required)
--granularity <gran> -- HOURLY, DAILY, WEEKLY, MONTHLY (default DAILY)
--group-by <fields> -- group by fields, comma-separated (e.g. countryOrRegion, deviceClass, ageRange, gender)
--return-records-with-no-metrics -- include records with no metrics

report-adgroups (ad group-level)

Options:

--start-date <date> -- start date, YYYY-MM-DD (required)
--end-date <date> -- end date, YYYY-MM-DD (required)
--granularity <gran> -- HOURLY, DAILY, WEEKLY, MONTHLY (default DAILY)

report-keywords (keyword-level)

Options:

--start-date <date> -- start date, YYYY-MM-DD (required)
--end-date <date> -- end date, YYYY-MM-DD (required)
--granularity <gran> -- HOURLY, DAILY, WEEKLY, MONTHLY (default DAILY)

Note: --group-by and --return-records-with-no-metrics are only available on the report command (campaign-level), not on report-adgroups or report-keywords.

All reports use UTC timezone (hardcoded by the CLI; the Apple API supports other timezones like ORTZ), return row totals and grand totals, and have an internal pagination limit of 1000 rows. If a report has more than 1000 matching rows, results will be truncated.

Workflow guidance

When the user asks for a quick overview

Run apple-ads-cli acl to find the organization and verify access
Run apple-ads-cli campaigns to list all campaigns
Use apple-ads-cli report <campaign-id> --start-date <date> --end-date <date> for a performance snapshot

When the user asks for deep analysis

Start with report at campaign level to identify overall performance
Use report-adgroups to break down by ad group within a campaign
Use report-keywords to identify top and bottom performing keywords
Add --group-by countryOrRegion or --group-by deviceClass for geographic or device segmentation
Add --group-by ageRange,gender for demographic breakdown
Use --granularity DAILY with --group-by to spot trends over time

When the user asks about keyword performance

Use report-keywords to get keyword-level metrics for a campaign
Use keywords <campaign-id> <adgroup-id> to see keyword details (bid amounts, match type, status)
Use negative-keywords and campaign-negative-keywords to review exclusions

When the user asks about app eligibility

Use search-apps to find the app and get its Adam ID
Use app-eligibility <adam-id> to check if it can run ads
Use app <adam-id> for detailed app information

When the user asks about budget

Use budget-orders to list all budget orders
Use budget-order <id> for details on a specific budget order
Use campaigns and campaign <id> to check campaign-level budget settings

Error handling

Authentication errors -- ask the user to verify their access token (expires after 1 hour) and org_id
Missing credentials -- the CLI checks for access_token and org_id in the credentials file; both are required
Empty results -- check the date range, campaign status, and whether the organization has active campaigns
Invalid granularity -- must be one of HOURLY, DAILY, WEEKLY, MONTHLY
Report errors -- verify the campaign ID exists and the date range is valid (start before end)

Apple Ads CLI

File contents

Apple Ads CLI Skill

Quick start

Authentication

Entity hierarchy

Monetary values

Output format

Commands reference

Account discovery

Apps

Campaigns

Budget orders

Ad groups

Ads

Keywords

Reports

report (campaign-level)

report-adgroups (ad group-level)

report-keywords (keyword-level)

Workflow guidance

When the user asks for a quick overview

When the user asks for deep analysis

When the user asks about keyword performance

When the user asks about app eligibility

When the user asks about budget

Error handling

API documentation references

Frequently asked questions

Apple Ads CLI

File contents

Apple Ads CLI Skill

Quick start

Authentication

Entity hierarchy

Monetary values

Output format

Commands reference

Account discovery

Apps

Campaigns

Budget orders

Ad groups

Ads

Keywords

Reports

report (campaign-level)

report-adgroups (ad group-level)

report-keywords (keyword-level)

Workflow guidance

When the user asks for a quick overview

When the user asks for deep analysis

When the user asks about keyword performance

When the user asks about app eligibility

When the user asks about budget

Error handling

API documentation references

Related skills

Frequently asked questions

How do I install the Apple Ads CLI skill?

What does the Apple Ads CLI skill do?

Is Apple Ads CLI safe to use?

Which AI agents work with Apple Ads CLI?

Is Apple Ads CLI free to use?

Who published Apple Ads CLI?