ASA API CLI
A command-line interface for managing Apple Ads campaigns on the Apple Ads Platform API v1.
Built on top of asa-api-client.
Installation
Using uv (recommended):
uv tool install asa-api-cli
# Include Excel workbook analysis support (pandas + xlsxwriter)
uv tool install "asa-api-cli[analyze]"
Using pip:
pip install asa-api-cli
# Or with Excel workbook analysis support
pip install "asa-api-cli[analyze]"
Using pipx:
pipx install asa-api-cli
Note (
asa-api-client>=1.0.1):asa-api-cliowns theasacommand (includingasa analyzeandasa v1-smoke). Starting inasa-api-client1.0.1, the client library's standalone console script was renamed toasa-clientso installing or upgradingasa-api-clientcannot overwriteasa.
Setup
Configure your Apple Ads Platform API v1 OAuth2 credentials via environment variables or a .env file:
export ASA_CLIENT_ID="SEARCHADS.your-client-id"
export ASA_TEAM_ID="SEARCHADS.your-team-id"
export ASA_KEY_ID="your-key-id"
export ASA_AD_ACCOUNT_ID="123456"
export ASA_PRIVATE_KEY_PATH="/path/to/private-key.pem"
If your API user only accesses a single ad account (or ASA_ORG_ID is set), asa will resolve the ad account automatically. For multi-account setups, discover accounts and override per command with --ad-account / -A:
# List accessible ad accounts and roles
asa auth accounts
# Test Platform API v1 authentication
asa auth test
# Override the active ad account for any command
asa --ad-account 123456 campaigns list
Commands
Campaigns, Ad Groups, Keywords & Ads
# List enabled campaigns (or --all, --with-spend, --json)
asa campaigns list
asa campaigns list --all --with-spend
asa campaigns get 123456789
asa campaigns set-budget 123456789 --daily 100.00 --currency USD
# Manage ad groups (flat ad group IDs in Platform API v1)
asa ad-groups list --campaign 123456789
asa ad-groups get 987654321
asa ad-groups set-bid 987654321 --bid 2.50
asa ad-groups set-bid 987654321 --target-cpa 8.00
# Manage keywords and negative keywords
asa keywords list --ad-group 987654321
asa keywords add "budget tracker" "expense app" --ad-group 987654321 --match EXACT --bid 2.00
asa keywords negatives list --campaign 123456789
# Manage ads and reusable creatives
asa ads list --ad-group 987654321
asa ads creatives --adam-id 654321987
asa ads create --campaign 123456789 --ad-group 987654321 --name "Holiday CPP" \
--type CUSTOM_PRODUCT_PAGE --product-page pp-uuid
Apps, Product Pages, Geo, Countries & Shared Budgets
# App Store lookup, metadata, and ad placement eligibility
asa apps search "habit tracker"
asa apps get 654321987
asa apps eligibilities 654321987
# Product pages (DPPs, CPPs, PPO variants) and localized metadata
asa product-pages list --adam-id 654321987
asa product-pages locales <page-id> --adam-id 654321987
asa product-pages app-locales 654321987
# Geo targeting, supported storefronts/languages, and shared budgets
asa geo search "New York" --country US
asa countries list
asa budget-orders list
Reports & Per-App Exports
# Reconcilable, read-only per-app JSON exports for separate apps over a fixed period
asa --ad-account 123456 reports export \
--app 654321987 --start 2026-01-01 --end 2026-01-07 --output app-654321987.json
asa --ad-account 123456 reports export \
--app 789123456 --start 2026-01-01 --end 2026-01-07 --output app-789123456.json
# Campaign, ad group, ad, keyword, and ORTZ search-term reports
asa reports campaigns --start 2026-01-01 --end 2026-01-31
asa reports campaigns --app 654321987 -s 2026-01-01 -e 2026-01-07 --daily -o daily.csv
asa reports ad-groups 123456789 --days 14
asa reports ads 123456789 --days 14
asa reports keywords 123456789 --days 30
asa reports search-terms 123456789 --days 14 --output search-terms.csv
asa reports export Contract
asa reports export produces a single structured JSON document per app without invoking any mutating API endpoints:
- App & account isolation: Scopes strictly to
--app <adamId>within the resolved ad account (--ad-account/ASA_AD_ACCOUNT_ID), recordingaccount(ad_account_id,org_id,currency,account_timezone),app(adam_id,app_name),period,collected_at, andversions. Repeat runs over the same--start/--enddates support downstream restatement diffing. - Stable entity keys & daily reconciliation: Emits both
dailyobservations andperiod_totalsacrosscampaigns,ad_groups,ads,keywords, andsearch_terms, keyed by stable entity IDs (and parent IDs + dimensions onsearch_terms) rather than mutable names. Renamed entities reconcile by ID with historical names recorded inobserved_names. - Independent API-total reconciliation & row validation: Every observation date (including dated
totalMetricsfallbacks) is validated against its effective fetch window (OutOfWindowDateError), and identified API rows lacking bothgranularMetricsandtotalMetricsfail explicitly (MissingMetricsError) while zero-row responses remain genuine empty exports. Alongsidereconciliation.daily_to_period_matches(internal mathematical consistency),reconciliation.api_totalsindependently compares API-suppliedtotalMetricsper entity and fetch window across additive counts and exactDecimallocal_spend(tolerance: "0"), preserving null semantics viaskipped_fieldsand reporting missing or non-comparable API totals as"not_checked"(matches: null) rather than an independent match. - Unambiguous attribution: Exposes
tap_*(tap_installs,tap_new_downloads,tap_redownloads,tap_install_cpi,tap_install_rate),view_*(view_installs,view_new_downloads,view_redownloads; CPI/rate remainnullas Apple Ads does not define view-only CPI), andtotal_*(total_installs,total_new_downloads,total_redownloads,total_avg_cpi,total_install_rate). Period ratios are calculated from summed period numerators and denominators (never by averaging daily ratios), valid zeroes are preserved, and missing values staynull. - Timezone policy:
campaigns,ad_groups,ads, andkeywordssupport--timezone ORTZ(default) or--timezone UTC.search_termsis fixed toORTZby Apple Ads Platform API v1 (and limited to the trailing 90 days); under--timezone UTC,search_termsis marked"status": "unavailable"(reason: "timezone_incompatible") by default rather than silently mixed with UTC daily data (pass--include-ortz-search-termsto opt into a separate ORTZ-tagged section). - Completeness & exit codes: Top-level
statusis"complete"or"empty"(complete: true, exit code0), or"partial"/"failed"(complete: false, exit code1with per-scope pagination and error records inerrors).--outputwrites atomically on every outcome so stale files from earlier runs are never mistaken for current results.
Read-Only Live Verification Procedure
To verify per-app export reconciliation against a live account using read-only endpoints only:
# 1. Confirm read-only Platform API v1 connectivity and inspect accessible accounts/apps
asa v1-smoke
asa auth accounts
asa apps search --own
# 2. Export two apps separately over an explicit completed 7-day range (ORTZ)
asa --ad-account "$ASA_AD_ACCOUNT_ID" reports export \
--app <APP_1_ADAM_ID> --start 2026-10-01 --end 2026-10-07 -o /tmp/app1.json
asa --ad-account "$ASA_AD_ACCOUNT_ID" reports export \
--app <APP_2_ADAM_ID> --start 2026-10-01 --end 2026-10-07 -o /tmp/app2.json
# 3. Verify completeness, zero cross-app campaign overlap, and daily-to-period reconciliation
jq '{status, complete, app, reconciliation: .reconciliation.daily_to_period_matches, errors}' /tmp/app1.json /tmp/app2.json
jq -s '(.[0].scope.campaign_ids - (.[0].scope.campaign_ids - .[1].scope.campaign_ids)) | length == 0' /tmp/app1.json /tmp/app2.json
Recommendations, Suggestions & Change History
# View, apply, or dismiss Apple Ads optimization recommendations
asa recommendations target-cpas
asa recommendations daily-budgets
asa recommendations apply <rec-id> --type target-cpa
asa recommendations dismiss <rec-id>
# Keyword, phrase, category, and Target CPA suggestions
asa suggestions keywords --adam-id 654321987 --country US
asa suggestions phrases --adam-id 654321987 --query-type SEARCH --phrase "budget planner"
asa suggestions categories --adam-id 654321987
asa suggestions target-cpa --adam-id 654321987 --country US
# Account change history and field-level audit details
asa change-history list --days 7
asa change-history details Campaign.444555666.txn_abc123
Impression Share & Search Popularity Insights
# Daily/weekly search term impression share (synchronous v1 Insights API)
asa impression-share analyze --country US --days 7
# Weekly search term popularity index (1-5)
asa impression-share popularity --country US --search "budget"
Optimization, Brand Campaigns, Translation & Workbook Analysis
# Optimization workflows
asa optimize bid-check --threshold 0.05
asa optimize bid-review --days 30
asa optimize cpa-impact
asa optimize expand --type Generic --match EM --dry-run
asa optimize negatives --days 30
# Brand protection campaigns & multi-language keyword translation
asa brand "My App Name" -c US -c GB --dry-run
asa translate detect
# Excel performance analysis workbook & Platform API v1 smoke test
asa analyze --period 30d --output asa-30d.xlsx
asa v1-smoke
Shell Completion
Install shell completion for your shell:
# Bash
asa --install-completion bash
# Zsh
asa --install-completion zsh
# Fish
asa --install-completion fish
License
MIT License - Copyright (c) 2025 Peth Pty Ltd
Metadata
Release files for asa-api-cli 0.5.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| asa_api_cli-0.5.1.tar.gz | 247.9 kB | With provenance | Details for asa_api_cli-0.5.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| asa_api_cli-0.5.1-py3-none-any.whl | Python 3 | none | any | Details for asa_api_cli-0.5.1-py3-none-any.whl |
Total release size: 374.3 kB
Release files / asa_api_cli-0.5.1.tar.gz
| Download URL | asa_api_cli-0.5.1.tar.gz |
|---|---|
| Size | 247.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0fbe836f281403d5a37ebf362fec15e492d99331bb58528b800bd058baf25f08
|
|
BLAKE2b-256 checksum How to use checksums |
7f8451517c49493de4262cb98be7eafdddcb0377672394f6f602e08c0840ae67
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logRelease files / asa_api_cli-0.5.1-py3-none-any.whl
| Download URL | asa_api_cli-0.5.1-py3-none-any.whl |
|---|---|
| Size | 126.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d427c81bbfe8c246b2a6002037f24976282950daaed67438941348ada900f54c
|
|
BLAKE2b-256 checksum How to use checksums |
aef7bed7bfdd1d6510e888f57f059408b21cfb1f4f2c7c1308ea192b2272e543
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logSecurity for asa-api-cli 0.5.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for asa_api_cli-0.5.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.