v0.3.0 — Full Apple Search Ads v5 surface + AI negatives

Built on asa-api-client 0.2.1 (full Apple Search Ads API v5 coverage). This release adds AI-assisted optimization and surfaces the complete reachable v5 resource set as CLI commands.

✨ New features

AI-powered optimization

• asa optimize negatives — pull search-term reports across campaigns, classify relevance with an AI model (Anthropic or Gemini via PydanticAI), and optionally apply suggestions as campaign-level negative keywords. Supports filtering, CSV export, and --dry-run.

New v5 lookup & reference commands

• asa apps search — find advertisable apps and their adamId
• asa geo search — find geo locations for targeting
• asa countries list — supported countries and ad languages

Creative & catalog commands

• asa ads list/get/create/update/delete — view and manage ads (creatives) within ad groups
• asa product-pages list/get/locales — custom product pages (CPP) and their per-locale details

Account & billing commands

• asa budget-orders list/get — view budget orders
• asa auth orgs — list organizations your credentials can access

🐛 Fixes

• asa --version now derives both the CLI and asa-api-client versions from package metadata, so it stays accurate without manual updates.
• Adapted report metric fields to the v5 API (installs→tap_installs, conversion_rate→tap_install_rate, avg_cpa→total_avg_cpi).

⬆️ Dependencies

• Adopted asa-api-client 0.2.1 (from 0.1.6).
• Upgraded pydantic-ai to 1.99 and refreshed transitive dependencies (aiohttp, cryptography, urllib3, requests, authlib, pyjwt, idna, and others).

Notes

• Ad creation validates the creative-type/product-page pairing client-side; CREATIVE_SET is not yet supported (asset selection). Use --dry-run to preview create payloads.
• The generic Custom Reports endpoint is intentionally not surfaced — Apple disabled GET /custom-reports (403) in March 2026 in favour of Insights; the impression-share POST/poll flow remains available via asa impression-share.

Full changelog: v0.2.0...v0.3.0

v0.2.0

What's New

✨ CLI Standards Overhaul

• Added global --quiet/-q, --verbose/-v, --json, --no-input, and --no-color flags
• All diagnostic output now routes to stderr; data output to stdout (pipe-friendly)
• TTY detection: spinners, progress bars, and prompts automatically disabled when piped
• Named exit codes: 0 (success), 1 (runtime error), 2 (usage/validation error)
• Next-command hints after campaign pause/enable/set-budget and keyword add operations

✨ New Commands

• Campaign expansion (asa optimize expand) — clone campaigns across new countries
• CPA goal optimization (asa optimize cpa-goal) — analyze and set CPA goals
• SKAG creation (asa ad-groups skag) — single keyword ad groups with interactive workflows
• Keyword translation (asa translate keywords) — AI-powered keyword translation across languages

✨ Impression Share Enhancements

• Added asa impression-share correlate for bid-to-impression analysis
• Added asa optimize bid-review for bid strength optimization
• Multi-country support and app grouping in analysis output

♻️ Breaking Changes

• Keyword commands: campaign_id and ad_group_id changed from positional args to --campaign and --ad-group/-g flags
• --version no longer has -v shorthand (now used for --verbose)

🐛 Bug Fixes

• Fixed impression-share bid update using correct bulk API endpoint
• Fixed keyword matching in bid-review interactive mode
• Deprecated ASA_PRIVATE_KEY env var in favour of ASA_PRIVATE_KEY_PATH

⬆️ Dependencies

• Upgraded asa-api-client to >=0.1.5 for improved retry and CustomReport support
• Bumped cryptography 46.0.3→46.0.5 (security fix)
• Bumped filelock 3.20.0→3.21.1 (security fix)
• Bumped virtualenv 20.35.4→20.36.1

v0.1.0 - Initial Release

Initial Release

Command-line interface for Apple Search Ads campaign management.

Features

• Campaign Management: List, create, update, and delete campaigns
• Ad Group Management: Full CRUD operations for ad groups
• Keyword Management: Manage targeting and negative keywords
• Reports: Generate campaign, ad group, keyword, and search term reports
• Optimization Tools:
  • asa optimize bid-check - Find bid discrepancies between ad groups and keywords
  • asa optimize expand - Expand successful campaigns to new countries
• Brand Campaigns: Create brand campaigns across multiple countries with asa brand

Installation

# Using uv (recommended)
uv tool install asa-api-cli

# Using pip
pip install asa-api-cli

# Using pipx
pipx install asa-api-cli

Requirements

• Python 3.13+
• Apple Search Ads API credentials

Dependencies

• asa-api-client - Core API client library
• Typer - CLI framework
• Rich - Terminal formatting