Metadata-Version: 2.4
Name: asa-api-cli
Version: 0.2.0
Summary: Command-line interface for Apple Search Ads campaign management
Project-URL: Homepage, https://github.com/SamPetherbridge/asa-api-cli
Project-URL: Repository, https://github.com/SamPetherbridge/asa-api-cli
Project-URL: Issues, https://github.com/SamPetherbridge/asa-api-cli/issues
Author-email: Sam Petherbridge <hello@peth.me>
License-Expression: MIT
License-File: LICENSE
Keywords: advertising,apple,campaign-management,cli,search-ads
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.13
Requires-Dist: asa-api-client>=0.1.5
Requires-Dist: pydantic-ai>=0.1.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: rich>=13.9.0
Requires-Dist: typer>=0.13.0
Provides-Extra: dev
Requires-Dist: mypy>=1.13.0; extra == 'dev'
Requires-Dist: pre-commit>=4.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
Requires-Dist: pytest>=8.3.0; extra == 'dev'
Requires-Dist: ruff>=0.8.0; extra == 'dev'
Description-Content-Type: text/markdown

# ASA API CLI

[![PyPI version](https://img.shields.io/pypi/v/asa-api-cli.svg)](https://pypi.org/project/asa-api-cli/)
[![Python](https://img.shields.io/pypi/pyversions/asa-api-cli.svg)](https://pypi.org/project/asa-api-cli/)
[![License](https://img.shields.io/github/license/SamPetherbridge/asa-api-cli.svg)](https://github.com/SamPetherbridge/asa-api-cli/blob/main/LICENSE)
[![CI](https://github.com/SamPetherbridge/asa-api-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/SamPetherbridge/asa-api-cli/actions/workflows/ci.yml)

A command-line interface for managing Apple Search Ads campaigns.

Built on top of [asa-api-client](https://github.com/SamPetherbridge/asa-api-client).

## Installation

Using [uv](https://docs.astral.sh/uv/) (recommended):

```bash
uv tool install asa-api-cli
```

Using pip:

```bash
pip install asa-api-cli
```

Using pipx:

```bash
pipx install asa-api-cli
```

## Setup

Set up your Apple Search Ads API credentials:

```bash
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_ORG_ID="123456"
export ASA_PRIVATE_KEY_PATH="/path/to/private-key.pem"
```

Or use a `.env` file in your working directory.

Test your credentials:

```bash
asa auth test
```

## Commands

### Campaigns

```bash
# List all enabled campaigns
asa campaigns list

# List all campaigns (including paused)
asa campaigns list --all

# List with 7-day spend data
asa campaigns list --with-spend

# Get a specific campaign
asa campaigns get 123456789

# Output as JSON
asa campaigns list --json
```

### Ad Groups

```bash
# List ad groups in a campaign
asa ad-groups list 123456789
```

### Keywords

```bash
# List keywords in an ad group
asa keywords list 123456789 987654321
```

### Reports

```bash
# Campaign performance report
asa reports campaigns --start 2024-01-01 --end 2024-01-31

# Keyword report
asa reports keywords 123456789 --start 2024-01-01 --end 2024-01-31

# Export to CSV
asa reports campaigns --start 2024-01-01 --end 2024-01-31 --output report.csv
```

### Brand Campaigns

Create brand protection campaigns for your app:

```bash
# Interactive mode (recommended)
asa brand

# With arguments
asa brand "My App Name" -v "My App" -c US -c GB

# All standard countries
asa brand "My App Name" --country all

# Preview without creating
asa brand "My App Name" -c US --dry-run
```

### Campaign Expansion

Expand existing campaigns to new markets:

```bash
# Interactive mode
asa optimize expand

# With filters
asa optimize expand --type Generic --match EM

# Preview
asa optimize expand --dry-run
```

### Bid Optimization

Check and fix bid discrepancies:

```bash
# Check bids
asa optimize bid-check

# Auto-fix discrepancies
asa optimize bid-check --auto-fix

# With threshold
asa optimize bid-check --threshold 0.05
```

## Shell Completion

Install shell completion for your shell:

```bash
# Bash
asa --install-completion bash

# Zsh
asa --install-completion zsh

# Fish
asa --install-completion fish
```

## License

MIT License - Copyright (c) 2025 Peth Pty Ltd
