Metadata-Version: 2.4
Name: direct-cli
Version: 0.1.2
Summary: Command-line interface for Yandex Direct API
Author: axisrow
License: MIT
Project-URL: Homepage, https://github.com/axisrow/direct-cli
Project-URL: Repository, https://github.com/axisrow/direct-cli
Keywords: yandex,direct,cli,api,advertising
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: tapi-yandex-direct>=2021.5.29
Requires-Dist: click>=8.0.0
Requires-Dist: python-dotenv>=0.19.0
Requires-Dist: tabulate>=0.8.0
Requires-Dist: colorama>=0.4.0
Requires-Dist: tqdm>=4.60.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov>=2.0; extra == "dev"
Requires-Dist: black>=22.0; extra == "dev"
Requires-Dist: flake8>=4.0; extra == "dev"

# Direct CLI

[English](#english) | [Русский](#русский)

---

## English

Command-line interface for the Yandex Direct API.

### Installation

```bash
pip install direct-cli
```

### Configuration

Create a `.env` file in your working directory:

```env
YANDEX_DIRECT_TOKEN=your_access_token
YANDEX_DIRECT_LOGIN=your_yandex_login
```

Or pass credentials directly per command:

```bash
direct-cli --token YOUR_TOKEN --login YOUR_LOGIN campaigns get
```

### Global Options

| Option | Description |
|--------|-------------|
| `--token` | API access token |
| `--login` | Yandex advertiser login |
| `--sandbox` | Use sandbox API |

### Usage

All commands follow the pattern: `direct-cli <resource> <action> [options]`

#### Campaigns

```bash
# Get campaigns
direct-cli campaigns get
direct-cli campaigns get --status ACTIVE
direct-cli campaigns get --ids 1,2,3 --format table
direct-cli campaigns get --fetch-all --format csv --output campaigns.csv

# Create (use --dry-run to preview the request)
direct-cli campaigns add --name "My Campaign" --start-date 2024-02-01 --type TEXT_CAMPAIGN --budget 1000
direct-cli campaigns add --name "My Campaign" --start-date 2024-02-01 --dry-run

# Update / lifecycle
direct-cli campaigns update --id 12345 --name "New Name"
direct-cli campaigns suspend --id 12345
direct-cli campaigns resume  --id 12345
direct-cli campaigns archive --id 12345
direct-cli campaigns unarchive --id 12345
direct-cli campaigns delete  --id 12345
```

#### Ad Groups

```bash
direct-cli adgroups get --campaign-ids 1,2,3 --limit 50
direct-cli adgroups add --name "Group 1" --campaign-id 12345 --dry-run
direct-cli adgroups update --id 67890 --name "New Name"
direct-cli adgroups delete --id 67890
```

#### Ads

```bash
direct-cli ads get --campaign-ids 1,2,3
direct-cli ads get --adgroup-ids 45678 --format table
direct-cli ads add --adgroup-id 12345 --type TEXT_AD --title "Title" --text "Ad text" --href "https://example.com" --dry-run
direct-cli ads update --id 99999 --status PAUSED
direct-cli ads delete --id 99999
```

#### Keywords

```bash
direct-cli keywords get --campaign-ids 1,2,3
direct-cli keywords add --adgroup-id 12345 --keyword "buy laptop" --bid 10.50 --dry-run
direct-cli keywords update --id 88888 --bid 15.00
direct-cli keywords delete --id 88888
```

#### Reports

```bash
# Get a report (saved to file)
direct-cli reports get \
  --type CAMPAIGN_PERFORMANCE_REPORT \
  --from 2024-01-01 --to 2024-01-31 \
  --name "January Report" \
  --fields "Date,CampaignId,Clicks,Cost" \
  --format csv --output report.csv

# List available report types
direct-cli reports list-types
```

Available report types: `CAMPAIGN_PERFORMANCE_REPORT`, `ADGROUP_PERFORMANCE_REPORT`, `AD_PERFORMANCE_REPORT`, `CRITERIA_PERFORMANCE_REPORT`, `CUSTOM_REPORT`, `REACH_AND_FREQUENCY_CAMPAIGN_REPORT`, `SEARCH_QUERY_PERFORMANCE_REPORT`

#### Other Resources

```bash
# Reference dictionaries
direct-cli dictionaries get --names Currencies,GeoRegions

# Client info
direct-cli clients get --fields ClientId,Login,Currency

# Changes feed
direct-cli changes get --campaign-ids 1,2,3

# Retargeting lists
direct-cli retargeting get --limit 10

# Ad extensions, sitelinks, vCards, images, creatives, feeds, bids, etc.
direct-cli adextensions get
direct-cli sitelinks get --ids 1,2,3
direct-cli bids get --campaign-ids 1,2,3
```

### Output Formats

All `get` commands support `--format`:

| Format | Description |
|--------|-------------|
| `json` | JSON (default) |
| `table` | Formatted table |
| `csv` | CSV |
| `tsv` | TSV |

```bash
direct-cli campaigns get --format table
direct-cli campaigns get --format csv --output campaigns.csv
```

### Pagination

```bash
direct-cli campaigns get --limit 10        # first 10 results
direct-cli campaigns get --fetch-all       # all pages
```

### ⚠️ Destructive Commands

The following commands make **irreversible changes** — use with caution:

| Command | Effect |
|---------|--------|
| `campaigns delete --id` | Permanently deletes a campaign and all its contents |
| `adgroups delete --id` | Permanently deletes an ad group |
| `ads delete --id` | Permanently deletes an ad |
| `keywords delete --id` | Permanently deletes a keyword |
| `audiencetargets delete --id` | Permanently deletes an audience target |

Commands that affect live ad delivery: `suspend`, `resume`, `archive`, `unarchive` (available on `campaigns`, `ads`, `keywords`).

Commands that affect bids and spending: `bids set`, `keywordbids set`, `bidmodifiers set`.

Use `--dry-run` on `add` / `update` commands to preview the API request before sending:

```bash
direct-cli campaigns add --name "Test" --start-date 2024-01-01 --dry-run
```

### Release Process

Build, validate and upload to PyPI:

```bash
pip install -e ".[dev]"
scripts/release_pypi.sh testpypi   # upload to TestPyPI
scripts/release_pypi.sh pypi       # upload to PyPI
scripts/release_pypi.sh all        # both
```

The script reads credentials from `.env`:

```dotenv
TWINE_USERNAME=__token__
TEST_PYPI_TOKEN=pypi-...
PYPI_TOKEN=pypi-...
```

#### PyPI Token Scoping

PyPI API tokens can be **account-wide** or **project-scoped**:

- **Project-scoped** tokens only allow uploads to the specific project they were created for. A token scoped to `telethon-cli` cannot upload `direct-cli` — you will get **403 Forbidden**.
- **Account-wide** tokens allow uploads to any project under your account.
- For the **first publication** of a new project, you **must** use an account-wide token (project-scoped tokens cannot be created until the project exists on PyPI).
- After the first successful upload, create a project-scoped token at https://pypi.org/manage/account/token/ and replace the account-wide token in `.env`.

Bump `version` in `pyproject.toml` before each release — PyPI rejects duplicate versions.

### License

MIT

---

## Русский

Интерфейс командной строки для Яндекс.Директ API.

### Установка

```bash
pip install direct-cli
```

### Настройка

Создайте файл `.env` в рабочей директории:

```env
YANDEX_DIRECT_TOKEN=ваш_токен
YANDEX_DIRECT_LOGIN=ваш_логин_на_яндексе
```

Или передавайте credentials напрямую в команду:

```bash
direct-cli --token ВАШ_ТОКЕН --login ВАШ_ЛОГИН campaigns get
```

### Глобальные опции

| Опция | Описание |
|-------|----------|
| `--token` | OAuth-токен доступа к API |
| `--login` | Логин рекламодателя на Яндексе |
| `--sandbox` | Использовать тестовое API (песочница) |

### Использование

Все команды следуют шаблону: `direct-cli <ресурс> <действие> [опции]`

#### Кампании

```bash
# Получить кампании
direct-cli campaigns get
direct-cli campaigns get --status ACTIVE
direct-cli campaigns get --ids 1,2,3 --format table
direct-cli campaigns get --fetch-all --format csv --output campaigns.csv

# Создать (--dry-run покажет запрос без отправки)
direct-cli campaigns add --name "Моя кампания" --start-date 2024-02-01 --type TEXT_CAMPAIGN --budget 1000
direct-cli campaigns add --name "Моя кампания" --start-date 2024-02-01 --dry-run

# Обновление и управление статусом
direct-cli campaigns update   --id 12345 --name "Новое название"
direct-cli campaigns suspend  --id 12345
direct-cli campaigns resume   --id 12345
direct-cli campaigns archive  --id 12345
direct-cli campaigns unarchive --id 12345
direct-cli campaigns delete   --id 12345
```

#### Группы объявлений

```bash
direct-cli adgroups get --campaign-ids 1,2,3 --limit 50
direct-cli adgroups add --name "Группа 1" --campaign-id 12345 --dry-run
direct-cli adgroups update --id 67890 --name "Новое название"
direct-cli adgroups delete --id 67890
```

#### Объявления

```bash
direct-cli ads get --campaign-ids 1,2,3
direct-cli ads get --adgroup-ids 45678 --format table
direct-cli ads add --adgroup-id 12345 --type TEXT_AD --title "Заголовок" --text "Текст объявления" --href "https://example.com" --dry-run
direct-cli ads update --id 99999 --status PAUSED
direct-cli ads delete --id 99999
```

#### Ключевые слова

```bash
direct-cli keywords get --campaign-ids 1,2,3
direct-cli keywords add --adgroup-id 12345 --keyword "купить ноутбук" --bid 10.50 --dry-run
direct-cli keywords update --id 88888 --bid 15.00
direct-cli keywords delete --id 88888
```

#### Отчёты

```bash
# Сформировать отчёт (сохраняется в файл)
direct-cli reports get \
  --type CAMPAIGN_PERFORMANCE_REPORT \
  --from 2024-01-01 --to 2024-01-31 \
  --name "Отчёт за январь" \
  --fields "Date,CampaignId,Clicks,Cost" \
  --format csv --output report.csv

# Список доступных типов отчётов
direct-cli reports list-types
```

Доступные типы: `CAMPAIGN_PERFORMANCE_REPORT`, `ADGROUP_PERFORMANCE_REPORT`, `AD_PERFORMANCE_REPORT`, `CRITERIA_PERFORMANCE_REPORT`, `CUSTOM_REPORT`, `REACH_AND_FREQUENCY_CAMPAIGN_REPORT`, `SEARCH_QUERY_PERFORMANCE_REPORT`

#### Другие ресурсы

```bash
# Справочники
direct-cli dictionaries get --names Currencies,GeoRegions

# Информация о клиенте
direct-cli clients get --fields ClientId,Login,Currency

# Лента изменений
direct-cli changes get --campaign-ids 1,2,3

# Списки ретаргетинга
direct-cli retargeting get --limit 10

# Расширения объявлений, быстрые ссылки, визитки, изображения, ставки и т.д.
direct-cli adextensions get
direct-cli sitelinks get --ids 1,2,3
direct-cli bids get --campaign-ids 1,2,3
```

### Форматы вывода

Все команды `get` поддерживают `--format`:

| Формат | Описание |
|--------|----------|
| `json` | JSON (по умолчанию) |
| `table` | Таблица |
| `csv` | CSV |
| `tsv` | TSV |

```bash
direct-cli campaigns get --format table
direct-cli campaigns get --format csv --output campaigns.csv
```

### Пагинация

```bash
direct-cli campaigns get --limit 10    # первые 10 результатов
direct-cli campaigns get --fetch-all   # все страницы
```

### ⚠️ Опасные команды

Следующие команды вносят **необратимые изменения** — используйте осторожно:

| Команда | Эффект |
|---------|--------|
| `campaigns delete --id` | Безвозвратно удаляет кампанию и весь её контент |
| `adgroups delete --id` | Безвозвратно удаляет группу объявлений |
| `ads delete --id` | Безвозвратно удаляет объявление |
| `keywords delete --id` | Безвозвратно удаляет ключевое слово |
| `audiencetargets delete --id` | Безвозвратно удаляет условие подбора аудитории |

Команды, влияющие на показ рекламы: `suspend`, `resume`, `archive`, `unarchive` (доступны для `campaigns`, `ads`, `keywords`).

Команды, влияющие на ставки и расходы: `bids set`, `keywordbids set`, `bidmodifiers set`.

Используйте `--dry-run` в командах `add` / `update`, чтобы увидеть тело запроса до отправки:

```bash
direct-cli campaigns add --name "Тест" --start-date 2024-01-01 --dry-run
```

### Публикация на PyPI

Сборка, проверка и загрузка на PyPI:

```bash
pip install -e ".[dev]"
scripts/release_pypi.sh testpypi   # загрузить на TestPyPI
scripts/release_pypi.sh pypi       # загрузить на PyPI
scripts/release_pypi.sh all        # оба
```

Скрипт читает credentials из `.env`:

```dotenv
TWINE_USERNAME=__token__
TEST_PYPI_TOKEN=pypi-...
PYPI_TOKEN=pypi-...
```

#### Области действия токенов PyPI

API-токены PyPI могут быть **account-wide** (на весь аккаунт) или **project-scoped** (на конкретный проект):

- **Project-scoped** токены работают только для конкретного проекта. Токен от `telethon-cli` не может загрузить `direct-cli` — будет **403 Forbidden**.
- **Account-wide** токены позволяют загружать в любой проект аккаунта.
- Для **первой публикации** нового проекта **необходим** account-wide токен (project-scoped нельзя создать, пока проект не зарегистрирован на PyPI).
- После первой успешной загрузки создайте project-scoped токен на https://pypi.org/manage/account/token/ и замените account-wide токен в `.env`.

Перед каждым релизом обновите `version` в `pyproject.toml` — PyPI отклоняет дубли версий.

### Лицензия

MIT
