Open-source operator tool
Apple Ads CLI by Attainment
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
Apple Ads work breaks when account state is unclear.
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
Find the real account state
Inventory campaigns, ad groups, and keywords before an operator or agent recommends a change.
02
Make output composable
Use stable JSON so the same response can support terminal review, scripts, and agent workflows.
03
Separate preview from action
Keep proposed bid changes inspectable until a human explicitly approves a narrow live write.
What the CLI does
Safe primitives for Apple Ads operators and agents.
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.
Campaign, ad group, and keyword inventory
List campaigns, ad groups, and keywords with the exact IDs needed for reporting and controlled follow-up actions.
Keyword reporting
Read Apple Search Ads keyword performance with date controls, latest-complete reporting, and nonzero filters.
Stable JSON output
Use a consistent success, error, pagination, and partial-read contract in scripts, agents, and operator workflows.
Read-only API hatch
Call relative ASA API GET paths when a high-level command is missing. Raw POST, PUT, PATCH, and DELETE are not exposed.
Dry-run bid updates
Preview the exact keyword bid change first. A live update requires an explicit --apply flag and verified readback.
Credential-safe diagnostics
Check configuration and connectivity without printing full credentials. Local profile IDs are masked by default.
Safety model
Read broadly. Write narrowly. Verify the result.
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 GitHubDry run by default
Keyword bid commands return a reviewable preview unless --apply is explicitly passed.
Verified readback
After a live update, the CLI reads the value back and exits nonzero on a mismatch.
Fail-closed pagination
Incomplete inventory returns partial_read unless --allow-partial is explicitly accepted.
Credential-safe output
Diagnostics report credential presence, not secret values. Profile IDs stay masked by default.
Agent and script workflows
One JSON contract for success, errors, and pagination.
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.
- Top-level ok field on success and failure
- Explicit partial and truncated inventory state
- Structured error codes for invalid arguments
- Masked identifiers and credential-safe diagnostics
Paginated inventory response
{
"ok": true,
"partial": false,
"pagination": {
"total_results": 1001,
"returned": 1001,
"page_count": 2,
"truncated": false
},
"rows": []
}Install from GitHub
Install the command. Run doctor. Inspect before acting.
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 FAQ
What is Apple Ads CLI by Attainment?
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.
Is this an official Apple product?
No. This project is not affiliated with, endorsed by, or sponsored by Apple Inc. It is an independent open-source project by Attainment.
Can the CLI change live keyword bids?
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.
Which Python version does apple-ads-cli require?
Apple Ads CLI requires Python 3.13 or newer because its upstream asa-api-client dependency requires Python 3.13 or newer.
Need an approval-safe ads workflow?
Attainment helps teams turn fragile ad account tasks into clear, reviewable operating workflows with the right controls around every live action.