Open-source operator tool
Know exactly what is live before you change it.
A composable Apple Search Ads CLI for operators, developers, and AI agents that need safe Apple Ads campaign inventory, keyword reporting, stable JSON, and approval-ready bid management through the ASA API.
This project is not affiliated with, endorsed by, or sponsored by Apple Inc.
# Check config without exposing secrets
$ apple-ads --json doctor
# Inspect live campaign inventory
$ apple-ads --json campaigns list
{
"ok": true,
"partial": false,
"rows": [...]
}
# Preview before any live bid change
$ apple-ads --json keywords set-bid ...
Output
Stable JSON
Writes
Dry run first
Raw API
GET only
The operator problem
Safe account work starts with exact inventory, exact IDs, complete reporting, and a reviewable change plan. A browser view alone is hard to compose into scripts or approval workflows.
01
Inventory campaigns, ad groups, and keywords before an operator or agent recommends a change.
02
Use stable JSON so the same response can support terminal review, scripts, and agent workflows.
03
Keep proposed bid changes inspectable until a human explicitly approves a narrow live write.
What the CLI does
Apple Ads CLI keeps strategy outside the binary. It exposes focused commands for account discovery, App Store Ads keyword reporting, diagnostics, and controlled keyword bid changes.
List campaigns, ad groups, and keywords with the exact IDs needed for reporting and controlled follow-up actions.
Read Apple Search Ads keyword performance with date controls, latest-complete reporting, and nonzero filters.
Use a consistent success, error, pagination, and partial-read contract in scripts, agents, and operator workflows.
Call relative ASA API GET paths when a high-level command is missing. Raw POST, PUT, PATCH, and DELETE are not exposed.
Preview the exact keyword bid change first. A live update requires an explicit --apply flag and verified readback.
Check configuration and connectivity without printing full credentials. Local profile IDs are masked by default.
Safety model
The CLI is built for careful Apple Ads bid management. Inventory is explicit, partial reads fail closed by default, and a proposed keyword bid remains a preview until --apply is present.
Read the safety model on GitHubKeyword bid commands return a reviewable preview unless --apply is explicitly passed.
After a live update, the CLI reads the value back and exits nonzero on a mismatch.
Incomplete inventory returns partial_read unless --allow-partial is explicitly accepted.
Diagnostics report credential presence, not secret values. Profile IDs stay masked by default.
Agent and script workflows
Add --json to make CLI responses predictable for scripts and AI agents. Inventory output includes pagination state, and errors keep a stable top-level shape.
Paginated inventory response
{
"ok": true,
"partial": false,
"pagination": {
"total_results": 1001,
"returned": 1001,
"page_count": 2,
"truncated": false
},
"rows": []
}Install from GitHub
The package is apple-ads-cli and the installed command is apple-ads. Python 3.13 or newer is required because the upstream asa-api-client requires Python 3.13 or newer.
Install with pipx
pipx install git+https://github.com/attainmentlabs/apple-ads-cli.git apple-ads --json doctor
Install with uv
uv tool install git+https://github.com/attainmentlabs/apple-ads-cli.git apple-ads --json doctor
Apple Ads CLI is an open-source command-line tool for Apple Ads and Apple Search Ads workflows. It provides campaign inventory, keyword reporting, stable JSON, read-only raw requests, credential-safe diagnostics, and dry-run-first keyword bid updates.
No. This project is not affiliated with, endorsed by, or sponsored by Apple Inc. It is an independent open-source project by Attainment.
Yes, but the default is a dry run. A live keyword bid update requires the explicit --apply flag. After an applied update, the CLI reads the live value back and exits nonzero if the value does not match.
Apple Ads CLI requires Python 3.13 or newer because its upstream asa-api-client dependency requires Python 3.13 or newer.
Attainment helps teams turn fragile ad account tasks into clear, reviewable operating workflows with the right controls around every live action.