direct-cli 0.4.1__tar.gz → 0.4.3__tar.gz

{direct_cli-0.4.1 → direct_cli-0.4.3}/CHANGELOG.md

@@ -1,5 +1,263 @@
 # Changelog
 
+## 0.4.3
+
+**Features — batch `ads add` via `--from-file` / `--ads-json` (#562, #558 follow-up):**
+
+- `ads add` now accepts a batch of flag-form ad rows from a JSONL file
+  (`--from-file`) or an inline JSON array (`--ads-json`); each row is the same
+  flag set keyed by the kebab flag name without the leading dashes (e.g.
+  `{"type":"TEXT_AD","title":"...","text":"...","href":"...","adgroup-id":1}`).
+  `--adgroup-id` becomes the batch default and may be overridden per row. Single
+  typed-flag mode is unchanged.
+- The ~400-line flag→object logic of `ads add` was extracted into a reusable,
+  ctx-free `build_ad_object()` so the single-flag command and the batch
+  normalizer emit byte-identical ad objects (golden-tested across every
+  subtype).
+- New shared `direct_cli/commands/_batch.py` engine (JSONL/inline loading,
+  chunking, per-chunk send with partial-success reporting, dry-run preview,
+  `add`/`update`-aware result key). `keywords add` was migrated onto it with no
+  behavior change (its existing batch suite is the proof).
+- Chunk size `ADS_ADD_MAX_BATCH = 100` (conservative chunk, not the 1000-object
+  API ceiling — a partial failure rolls back at most 100 ads).
+
+**Features — batch `ads update` via `--from-file` / `--ads-json` (#563, #558 follow-up):**
+
+- `ads update` now accepts a batch of flag-form ad-update rows from a JSONL file
+  (`--from-file`) or an inline JSON array (`--ads-json`); each row is the same
+  flag set keyed by the kebab flag name without the leading dashes plus its own
+  `id` and `type` (e.g. `{"id":5,"type":"TEXT_AD","title":"New"}`). The
+  `--clear-image-hash` mechanic works per row as a JSON boolean. Single
+  typed-flag mode is unchanged.
+- The subtype-dispatch body of `ads update` (type validation, the
+  incompatible-flag / "does not convert between subtypes" guard, per-subtype
+  assembly, and the empty-subtype no-op guard) was extracted into a reusable,
+  ctx-free `build_ad_update_object()` so the single-flag command and the batch
+  normalizer emit byte-identical ad-update objects (golden-tested across every
+  subtype). Reuses the shared `_batch.py` engine with `method="update"` /
+  `result_key="UpdateResults"`.
+- `--id` and `--type` become per-row in batch mode (each row carries its own);
+  single-item mode still requires both. The per-row normalizer reproduces the
+  command's `--id`/`--type` required checks, the `--image-hash` /
+  `--clear-image-hash` mutex, and the same Click-type coercion as the single
+  path (a JSON float `id` is rejected, not truncated).
+
+**Features — batch `adgroups add` via `--from-file` / `--adgroups-json` (#564, #558 follow-up):**
+
+- `adgroups add` now accepts a batch of flag-form ad-group rows from a JSONL
+  file (`--from-file`) or an inline JSON array (`--adgroups-json`); each row is
+  the same flag set keyed by the kebab flag name without the leading dashes
+  (e.g. `{"name":"G","campaign-id":12,"region-ids":"225","type":"TEXT_AD_GROUP"}`).
+  `--campaign-id` becomes the batch default and may be overridden per row.
+  Single typed-flag mode is unchanged.
+- The flag→object logic of `adgroups add` (type validation, the
+  incompatible-flag guard, the negative-keyword compatibility check, region IDs,
+  and per-subtype assembly) was extracted into a reusable, ctx-free
+  `build_adgroup_object()` so the single-flag command and the batch normalizer
+  emit byte-identical ad-group objects (golden-tested across every subtype).
+  `--name` / `--campaign-id` / `--region-ids` become per-row in batch mode;
+  single-item mode still requires them (parity-gate `INTERNAL_VALIDATION`
+  entries). Per-row coercion runs every typed field through its single-flag
+  Click type (a JSON float `campaign-id` is rejected, not truncated).
+- The shared `_batch.send_batch` gained an optional `post` callable so
+  `adgroups` keeps its endpoint routing: a `UnifiedAdGroup` payload must use API
+  v501 (`_post_adgroups`). Because that routing keys off the whole body, a batch
+  may **not** mix `UNIFIED_AD_GROUP` with other ad-group types — the CLI refuses
+  the mix up front with a clear `UsageError` rather than send non-unified groups
+  to the v501 endpoint.
+
+**Features — batch `adgroups update` via `--from-file` / `--adgroups-json` (#565, #558 follow-up):**
+
+- `adgroups update` now accepts a batch of flag-form ad-group-update rows from a
+  JSONL file (`--from-file`) or an inline JSON array (`--adgroups-json`); each
+  row is the same flag set keyed by the kebab flag name without the leading
+  dashes plus its own `id` (e.g. `{"id":5,"name":"New"}`). The `--dynamic-feed`
+  routing works per row as a JSON boolean. Single typed-flag mode is unchanged.
+- The subtype-dispatch body of `adgroups update` (the mixed-subtype reject
+  guard, per-subtype assembly, the `--dynamic-feed` DynamicTextAdGroup ↔
+  DynamicTextFeedAdGroup routing, and the empty-payload no-op guard) was
+  extracted into a reusable, ctx-free `build_adgroup_update_object()` so the
+  single-flag command and the batch normalizer emit byte-identical objects
+  (golden-tested across every subtype). `--id` becomes per-row in batch mode;
+  single-item mode still requires it (parity-gate `INTERNAL_VALIDATION` entry).
+  Per-row coercion runs every typed field through its single-flag Click type (a
+  JSON float `id` is rejected, not truncated).
+- Reuses the shared `_batch.send_batch` with `method="update"` /
+  `result_key="UpdateResults"` and the `post=_post_adgroups` endpoint routing.
+  As with `adgroups add`, a batch may **not** mix `UNIFIED_AD_GROUP` with other
+  ad-group types (unified groups use API v501) — the CLI refuses the mix up
+  front with a clear `UsageError`.
+
+**Fixes — reject non-positive IDs before the request (#558):**
+
+- Mutating commands and lifecycle ops took their object-ID selector
+  (`--id` / `--adgroup-id` / `--campaign-id` / `--keyword-id` / `--client-id`)
+  as a bare `int`, which accepted `0` and negatives and forwarded them to the
+  API (opaque rejection). Every such selector now uses `click.IntRange(min=1)`
+  and rejects a non-positive id with a clear `UsageError` (exit 2) before any
+  request. Coverage is the full mutation surface, not a subset:
+  - every `delete` / `suspend` / `resume` / `archive` / `unarchive` /
+    `moderate` lifecycle command (via the shared `_lifecycle.py` factory);
+  - `ads add` / `ads update`, `adgroups add` / `adgroups update`,
+    `keywords add` / `keywords update`;
+  - `campaigns update`, `feeds update`, `strategies update`,
+    `retargeting update`, `negativekeywordsharedsets update`, `vcards add`;
+  - `smartadtargets add` / `update` / `set-bids`,
+    `audiencetargets add` / `set-bids`, `dynamicads add` / `set-bids`,
+    `dynamicfeedadtargets add` / `set-bids`;
+  - the bid setters `bids set` / `set-auto`, `keywordbids set` / `set-auto`
+    (the `campaign-id` / `adgroup-id` / `keyword-id` "exactly one of" trios),
+    `bidmodifiers add` / `set`;
+  - `agencyclients update --client-id`.
+
+  The ad-image lifecycle (`--hash`, a string) is unchanged. Secondary
+  reference-ID flags that point at *other* objects inside a write payload
+  (e.g. `--feed-id`, `--counter-id`, `--vcard-id`, `--region-id`,
+  `--retargeting-list-id`) are left as-is for now and tracked as follow-up.
+- Batch-size caps (the docs allow up to 1000 objects per add/update and 10000
+  ids per delete) are intentionally **not** added: the CLI builds a
+  single-item payload for every mutation, so there is no caller-controllable
+  array to overflow. Multi-item batch mode (`--from-file`) for ads/adgroups is
+  tracked as follow-up work.
+- De-staled the `KEYWORDS_ADD_MAX_BATCH` comment: it claimed the API caps a
+  `keywords.add` request at 10 (citing an outdated doc page that states no such
+  number). The real documented per-call limit is 1000; the value `10` is a
+  conservative chunk size for batch add, not the API ceiling — comment fixed,
+  value unchanged.
+
+**Fixes — explain Error 8300 on delete/moderate (#548):**
+
+- `raise_for_api_result_errors` now appends a hint when the API returns code
+  8300, mirroring the existing 8800 hint: the ad is likely not in `DRAFT`
+  status, and `Status=UNKNOWN` is an API fallback value (a status outside the
+  v5 enum), not a business status — such ads can only be archived/unarchived,
+  not deleted or sent to moderation. Covers `ads delete` / `ads moderate` and
+  any command routing through `format_output`. English-only, matching the 8800
+  hint (`output.py` does not import i18n).
+
+**Docs — audiencetargets get requires a filter (#554):**
+
+- Clarified that `audiencetargets get` cannot page the whole account: unlike
+  `retargeting get --fetch-all`, the live API hard-rejects an empty
+  `SelectionCriteria` (error 8000 with no criteria, 4001 with `{}`). The
+  required-filter guard now explains this and recommends the `campaigns get` →
+  batched `campaign_ids` sweep instead. No API behavior change; message only.
+
+**Fixes — preflight SelectionCriteria array limits on get (#555, P0):**
+
+- `keywordbids get` now rejects `--campaign-ids` >10, `--adgroup-ids` >1000,
+  `--keyword-ids` >10000; `dynamicads get` / `smartadtargets get` reject
+  `--campaign-ids` >2 — before the request, with a clear `UsageError` (exit 2)
+  naming the array and ceiling, instead of the opaque API `error_code=4001`.
+  These are runtime ceilings (the WSDL declares the arrays `unbounded`), pinned
+  next to each command with a doc/live-4001 citation, the same discipline as
+  `KEYWORDS_ADD_MAX_BATCH`. Verified live 2026-06-16. Other `get` arrays
+  (`AdGroupIds`/`Ids` on dynamic/smart, etc.) are intentionally **not** capped
+  because the live API accepts them.
+
+**Internal — dedup v4 Live output-option stack (#550):**
+
+- Replaced the byte-identical `--format`/`--output`/`--dry-run` trio across the
+  standard v4 Live and `balance` commands with a shared `v4_output_options`
+  decorator (the v4 analogue of `get_options`, epic #491). The CLI surface is
+  unchanged — same option order, names, `click.Choice(["json","table","csv",
+  "tsv"])` format, defaults, and help. `v4account enable-shared-account` /
+  `account-management` (reversed order, custom `--dry-run` help) and the
+  dry-run-only `v4finance transfer-money` / `pay-campaigns` /
+  `pay-campaigns-by-card` (no `--format`/`--output`) keep their divergent
+  stacks and are intentionally excluded.
+
+**Fixes — `ads update` can now clear AdImageHash (#552):**
+
+- Added `--clear-image-hash` to `ads update`. The flag sends
+  `AdImageHash: null` so an image can be removed from an existing ad — e.g.
+  unblocking a `TEXT_AD` whose image was restricted in moderation — without
+  recreating the ad. Supported for the three subtypes whose WSDL `AdImageHash`
+  is nillable: `TEXT_AD`, `DYNAMIC_TEXT_AD`, `MOBILE_APP_AD`. It is **rejected**
+  for `TEXT_IMAGE_AD` and `MOBILE_APP_IMAGE_AD`, which share the non-nillable
+  `ImageAdUpdateBase.AdImageHash` — the live API returns error 8000
+  (`AdImageHash cannot have the null value`) for those, verified directly.
+  `--image-hash` and `--clear-image-hash` are mutually exclusive.
+  Previously there was no way to reset the image: `--image-hash ""` was dropped
+  by a truthy check, and `--image-hash null` sent the literal string `"null"`.
+
+**Fixes — docs-URL drift regression (re-fixes #463):**
+
+- Restored the four WSDL `docs` URLs for `dynamicads`,
+  `dynamicfeedadtargets`, `smartadtargets` and `vcards` that the
+  `tapi-yandex-direct` 2026.5.29 vendor update silently reverted back to the
+  removed `…/dev/direct/doc/ru/<service>` HTML pages (which 404 since Yandex
+  dropped those pages in September 2025). The fix from #464 was overwritten by
+  the `rm -rf` + `cp -R` vendor sync; preflight
+  (`scripts/check_all_docs_urls.py`) caught it. URLs now point back at the live
+  `https://api.direct.yandex.com/v5/<service>?wsdl` endpoints — the only
+  authoritative source still served.
+- Fixed the same URLs at the source in the `axisrow/tapi-yandex-direct` fork so
+  the next vendor update no longer re-introduces the dead pages.
+- Added an offline regression guard
+  (`tests/test_audit_wire_shape.py::test_removed_doc_services_pin_wsdl_url`):
+  the four doc-removed services must keep WSDL `docs` URLs, failing in CI before
+  the network preflight ever runs.
+
+**Bug Fixes — reject empty-string CSV-ID flags in `adgroups` (#570):**
+
+- `adgroups add` and `adgroups update` now reject an explicitly-provided
+  empty/whitespace value for `--region-ids`, `--negative-keyword-shared-set-ids`
+  and `--feed-category-ids` (e.g. `--region-ids ""`, `--region-ids " "`,
+  `--region-ids ","`, or a batch row `{"region-ids":""}`) with a clear
+  `UsageError` instead of silently dropping the field. Previously `parse_ids("")`
+  returned `None` and the `if region_ids:` guards treated a provided-but-empty
+  value identically to an omitted option; for `RegionIds` (WSDL `minOccurs=1` on
+  add) that stripped a required field and sent an invalid body to the live API.
+- The fix is centralized in a new `_require_nonempty_ids_option` helper that
+  distinguishes `None` (option omitted) from an all-blank value, so single mode
+  and `--from-file` / `--adgroups-json` batch mode behave identically for both
+  add and update. A genuinely malformed value with real tokens
+  (e.g. `225,,226`) still reports the precise `Invalid ID` error, unchanged.
+
+## 0.4.2
+
+**BREAKING CHANGES - get requires SelectionCriteria (#498):**
+
+- `adgroups` / `ads` / `keywords` / `strategies` / `creatives` / `dynamicads` /
+  `smartadtargets` / `audiencetargets` `get` now refuse an empty
+  `SelectionCriteria` before the API call, raising a `UsageError` that asks for
+  at least one filter — instead of sending `{"SelectionCriteria": {}}` (which the
+  API rejects with the opaque error 4001 for ad-group/ad/keyword resources).
+  Extends the same guard already shipped for `bids` / `keywordbids` in 0.4.1
+  (#483). WSDL declares `GetRequest.SelectionCriteria` as `minOccurs=1` for all
+  eight resources.
+- `retargeting get` gains `--dry-run` and the shared read/pagination option
+  stack; its `SelectionCriteria` stays optional (WSDL `minOccurs=0`), so a
+  no-filter call is still valid and now omits the empty criteria from the
+  payload.
+- All eight commands and `retargeting get` build their request via the shared
+  `build_common_params` helper, completing the dedup epic #491 (B3c).
+
+**BREAKING CHANGES - auth precedence (#489):**
+
+- Base `YANDEX_DIRECT_TOKEN` / `YANDEX_DIRECT_LOGIN` credentials from the
+  environment or current-directory `.env` now win over the active OAuth profile
+  selected by `direct auth use` when `--profile` is not passed. Explicit
+  `--token`, `--login`, and `--profile` still take priority.
+- `direct auth status` reports the selected effective credentials, including
+  base env/`.env` and secret-manager fallbacks, instead of reporting only the
+  active OAuth profile.
+- `direct auth login` can now ask interactive users whether to save the OAuth
+  access token and resolved login into the current-directory `.env`; the default
+  answer is no.
+
+**Docs — live-write coverage limitation (#538):**
+
+- Documented why the SMART_CAMPAIGN / DYNAMIC_TEXT_CAMPAIGN / `adimages`
+  live-write lifecycle (`dynamicads`, `smartadtargets`, `adimages`) stays
+  recorded only as 3500/5004 error cassettes. Verified via direct API calls that
+  the available sandbox **agency** account has no client accounts under it
+  (`agencyclients.get` → empty), cannot create one (3001 "No rights to create
+  clients", access by request only), and that without a client login every
+  agency-scoped mutation returns 8000. Closed #538 as a documented account-tier
+  limitation; no CLI code change. See `tests/MANUAL_COVERAGE.md`.
+
 ## 0.4.1
 
 Russian-default CLI localization across all command modules (epic #466).

{direct_cli-0.4.1 → direct_cli-0.4.3}/CLAUDE.md

@@ -24,9 +24,9 @@ Click group-of-groups. Each Yandex Direct API resource = one file in `direct_cli
 
 **Request flow:** `cli.py` → `auth.py` (resolves token/login) → `api.py` (`create_client`) → `tapi_yandex_direct.YandexDirect` → Yandex API → `output.py` (format/print).
 
-**Credentials priority (CLI):** CLI flags (`--token`, `--login`) > active profile from `direct auth login` > env vars (`YANDEX_DIRECT_TOKEN`, `YANDEX_DIRECT_LOGIN`) > `.env` file > 1Password/Bitwarden refs. See `direct_cli/auth.py:600` (`get_credentials`) and README table for the full chain. `load_dotenv()` runs at `cli.py` import time.
+**Credentials priority (CLI):** explicit CLI flags (`--token`, `--login`, `--profile`) > base env/current working directory `.env` (`YANDEX_DIRECT_TOKEN`, `YANDEX_DIRECT_LOGIN`) > active profile from `direct auth login` / `direct auth use` > 1Password/Bitwarden refs. Explicit `--profile` is isolated and does not fall back to base `.env` login. See `direct_cli/auth.py` (`get_credentials`) and README table for the full chain.
 
-**Credentials priority (tests):** **inverted** — env vars > active profile > skip. Tests must not silently hit production when a developer has an active `direct auth` profile, so env vars take precedence over the profile (see `tests/test_v4_live_contracts.py::_credentials`).
+**Credentials priority (tests):** env vars/current working directory `.env` > active profile > skip. Tests must not silently hit production when a developer has an active `direct auth` profile, so env vars take precedence over the profile (see `tests/test_v4_live_contracts.py::_credentials`).
 
 **Shared utilities** (`utils.py`): `parse_ids`, `parse_json`, `build_selection_criteria`, `build_common_params`, `get_default_fields`, `COMMON_FIELDS` dict. All command modules import from here — don't duplicate.
 
@@ -106,7 +106,7 @@ Builds dist artifacts, runs twine checks, uploads to TestPyPI + PyPI. Does **not
 
 - **Unit** (`test_cli.py`, `test_comprehensive.py`) — no API calls, no token needed.
 - **Integration** (`test_integration.py`, `@pytest.mark.integration`) — require `.env` with `YANDEX_DIRECT_TOKEN` and `YANDEX_DIRECT_LOGIN`. Auto-skip if absent.
-- **Credential resolution in tests:** env vars first, then active `direct auth` profile, then skip. This is **inverted** vs. CLI (where the profile wins) on purpose: a developer machine with an active profile must not silently hit production on a plain `pytest`.
+- **Credential resolution in tests:** env vars/current working directory `.env` first, then active `direct auth` profile, then skip. This matches the safe CLI default for base env vs. active profile: a developer machine with an active profile must not silently hit production on a plain `pytest`.
 
 ## Dangerous Commands — Never Auto-Test
 

{direct_cli-0.4.1 → direct_cli-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: direct-cli
-Version: 0.4.1
+Version: 0.4.3
 Summary: Command-line interface for Yandex Direct API
 Author: axisrow
 License: MIT
@@ -106,6 +106,9 @@ Notes:
 - If the first non-interactive step includes `--client-secret`, the secret is remembered for the matching completion step.
 - If a profile already stores a confidential OAuth client, `direct auth login --code CODE --profile NAME` reuses the saved `client_id` and `client_secret`.
 - `direct auth login --oauth-token TOKEN` is a manual access-token import and does not auto-refresh.
+- After a successful interactive login, Direct CLI asks whether to save the
+  access token and login to the current working directory `.env`; non-interactive
+  login flows do not prompt.
 - Alias `auth_login` is not supported.
 
 Credential resolution priority:
@@ -113,22 +116,23 @@ Credential resolution priority:
 | Priority | Source | Example |
 |----------|--------|---------|
 | 1 | Explicit CLI options | `direct --token TOKEN --login LOGIN campaigns get` |
-| 2 | OAuth profile storage | `direct --profile agency1 campaigns get` |
-| 3 | Profile-specific env vars | `YANDEX_DIRECT_TOKEN_AGENCY1`, `YANDEX_DIRECT_LOGIN_AGENCY1` |
-| 4 | Base env vars or current working directory `.env` | `YANDEX_DIRECT_TOKEN`, `YANDEX_DIRECT_LOGIN` |
+| 2 | Explicit profile credentials | `direct --profile agency1 campaigns get` |
+| 3 | Base env vars or current working directory `.env` | `YANDEX_DIRECT_TOKEN`, `YANDEX_DIRECT_LOGIN` |
+| 4 | Active profile credentials | `direct auth use --profile agency1` |
 | 5 | 1Password references | `--op-token-ref`, `YANDEX_DIRECT_OP_TOKEN_REF` |
 | 6 | Bitwarden references | `--bw-token-ref`, `YANDEX_DIRECT_BW_TOKEN_REF` |
 
 Direct CLI automatically loads only the `.env` file from the current working
 directory, i.e. the directory where you run `direct`. It does not search for
-`.env` from the installed package or source-code location. If a profile is
-selected with `--profile` or `direct auth use --profile NAME`, Direct CLI does
-not fall back to base `YANDEX_DIRECT_LOGIN`; this prevents mixing a profile
-token with a login from the current working directory `.env`. For multi-account
-setups, prefer OAuth profiles or profile-specific env vars instead of base
-credentials.
+`.env` from the installed package or source-code location. Without an explicit
+`--profile`, base `YANDEX_DIRECT_TOKEN` / `YANDEX_DIRECT_LOGIN` from env or cwd
+`.env` win over the active OAuth profile. With explicit `--profile`, Direct CLI
+uses only that profile's OAuth/profile-env credentials and does not fall back to
+base `YANDEX_DIRECT_LOGIN`; this prevents mixing accounts. `direct auth status`
+without `--profile` reports the effective credential source; with `--profile` it
+reports that profile.
 
-> **Tests use the inverted order.** Live-API test suites (e.g. `tests/test_v4_live_contracts.py`) read `YANDEX_DIRECT_TOKEN` / `YANDEX_DIRECT_LOGIN` from the environment first, only then fall back to the active `direct auth` profile, and skip the test if neither is set. This is intentional: a developer machine with an active profile must not silently hit production on a plain `pytest` invocation. See `CLAUDE.md` for the contract.
+> **Tests follow the safe credential order.** Live-API test suites (e.g. `tests/test_v4_live_contracts.py`) read `YANDEX_DIRECT_TOKEN` / `YANDEX_DIRECT_LOGIN` from the environment first, only then fall back to the active `direct auth` profile, and skip the test if neither is set. This prevents a developer machine with an active profile from silently hitting production on a plain `pytest` invocation. See `CLAUDE.md` for the contract.
 
 Install with `pip install direct-cli`, then run commands with `direct`.
 Invoking the deprecated `direct-cli` entrypoint exits with
@@ -539,6 +543,7 @@ direct ads add --adgroup-id 12345 --type MOBILE_APP_IMAGE_AD --image-hash abcdef
 direct ads add --adgroup-id 12345 --type SMART_AD_BUILDER_AD --logo-extension-hash logoabcdefghijklmnop --dry-run
 direct ads update --id 99999 --type TEXT_AD --title "New Title" --text "New text" --href "https://example.com"
 direct ads update --id 99999 --type TEXT_AD --image-hash abcdefghijklmnopqrst
+direct ads update --id 99999 --type TEXT_AD --clear-image-hash  # remove the image (AdImageHash: null; TEXT_AD / DYNAMIC_TEXT_AD / MOBILE_APP_AD only)
 direct ads update --id 99999 --type TEXT_AD --title2 "New second headline" --vcard-id 222
 direct ads update --id 99999 --type TEXT_AD --callouts-add "111,222" --callouts-remove "333"
 direct ads update --id 99999 --type TEXT_AD --callouts-set "444,555"
@@ -557,7 +562,10 @@ direct ads delete --id 99999
 ```
 
 Available TEXT_AD typed flags for `ads add` / `ads update`: `--title`, `--text`,
-`--href`, `--image-hash`, `--title2`, `--display-url-path`, `--vcard-id`,
+`--href`, `--image-hash`, `--clear-image-hash` (update only — sets
+`AdImageHash: null`; TEXT_AD / DYNAMIC_TEXT_AD / MOBILE_APP_AD only, since
+TEXT_IMAGE_AD / MOBILE_APP_IMAGE_AD have a non-nillable `AdImageHash`),
+`--title2`, `--display-url-path`, `--vcard-id`,
 `--sitelink-set-id`, `--turbo-page-id`, `--final-url`,
 `--video-extension-creative-id`, `--price-extension-*`, `--business-id`,
 `--prefer-vcard-over-business`, and `--erir-ad-description`. For `ads add`,
@@ -704,6 +712,9 @@ direct bidmodifiers set --id 99 --value 130 --dry-run
 
 # Canonical multiword groups
 direct negativekeywordsharedsets update --id 123 --keywords "foo,bar"
+# audiencetargets get always needs a filter — the API rejects an empty
+# SelectionCriteria, so there is no whole-account paging. To sweep the account,
+# run `campaigns get` first, then page audiencetargets get in batches of campaign ids.
 direct audiencetargets get --campaign-ids 123 --fields Id,AdGroupId,RetargetingListId,State,ContextBid
 direct audiencetargets add --adgroup-id 100 --retargeting-list-id 200 --bid 12000000 --priority HIGH --dry-run
 direct audiencetargets set-bids --id 101 --context-bid 7000000 --priority LOW --dry-run
@@ -1065,27 +1076,32 @@ direct --profile agency1 campaigns get
 - Если первый non-interactive шаг включает `--client-secret`, secret запоминается для последующего completion step.
 - Если profile уже хранит confidential OAuth client, `direct auth login --code CODE --profile NAME` использует сохраненные `client_id` и `client_secret`.
 - `direct auth login --oauth-token TOKEN` импортирует access token вручную и не включает auto-refresh.
+- После успешного интерактивного входа Direct CLI спрашивает, сохранить ли
+  access token и login в `.env` текущей рабочей папки; non-interactive вход этот
+  вопрос не задаёт.
 
 Порядок выбора credentials:
 
 | Приоритет | Источник | Пример |
 |-----------|----------|--------|
 | 1 | Явные CLI-опции | `direct --token TOKEN --login LOGIN campaigns get` |
-| 2 | OAuth profile storage | `direct --profile agency1 campaigns get` |
-| 3 | Профильные env vars | `YANDEX_DIRECT_TOKEN_AGENCY1`, `YANDEX_DIRECT_LOGIN_AGENCY1` |
-| 4 | Базовые env vars или `.env` из папки запуска | `YANDEX_DIRECT_TOKEN`, `YANDEX_DIRECT_LOGIN` |
+| 2 | Явно выбранный profile | `direct --profile agency1 campaigns get` |
+| 3 | Базовые env vars или `.env` из папки запуска | `YANDEX_DIRECT_TOKEN`, `YANDEX_DIRECT_LOGIN` |
+| 4 | Активный profile | `direct auth use --profile agency1` |
 | 5 | 1Password references | `--op-token-ref`, `YANDEX_DIRECT_OP_TOKEN_REF` |
 | 6 | Bitwarden references | `--bw-token-ref`, `YANDEX_DIRECT_BW_TOKEN_REF` |
 
 Direct CLI автоматически читает только `.env` из текущей рабочей папки, то есть
 из папки, где запущена команда `direct`. Он не ищет `.env` от папки
-установленного пакета или исходного кода. Если профиль выбран через `--profile`
-или `direct auth use --profile NAME`, Direct CLI не подставляет base
-`YANDEX_DIRECT_LOGIN`; это защищает от смешивания токена из профиля с логином из
-`.env` текущей рабочей папки. Для нескольких аккаунтов используйте OAuth
-profiles или профильные env vars, а не базовые credentials.
+установленного пакета или исходного кода. Без явного `--profile` базовые
+`YANDEX_DIRECT_TOKEN` / `YANDEX_DIRECT_LOGIN` из окружения или cwd `.env`
+побеждают активный OAuth profile. С явным `--profile` Direct CLI использует
+только OAuth/profile-env credentials этого профиля и не подставляет base
+`YANDEX_DIRECT_LOGIN`; это защищает от смешивания аккаунтов. `direct auth status`
+без `--profile` показывает реально выбранный источник credentials, а с
+`--profile` показывает этот профиль.
 
-> **В тестах порядок инвертирован.** Live-API тесты (например `tests/test_v4_live_contracts.py`) сначала читают `YANDEX_DIRECT_TOKEN` / `YANDEX_DIRECT_LOGIN` из окружения, затем падают на активный профиль `direct auth`, и скипают тест если ни того ни другого нет. Это сделано специально: на машине разработчика с активным профилем обычный `pytest` не должен молча идти в боевой API. Контракт зафиксирован в `CLAUDE.md`.
+> **Тесты используют безопасный порядок credentials.** Live-API тесты (например `tests/test_v4_live_contracts.py`) сначала читают `YANDEX_DIRECT_TOKEN` / `YANDEX_DIRECT_LOGIN` из окружения, затем падают на активный профиль `direct auth`, и скипают тест если ни того ни другого нет. Это защищает от случайного обращения к production API на машине разработчика с активным profile. Контракт зафиксирован в `CLAUDE.md`.
 
 Установка остаётся через `pip install direct-cli`, а запуск команд теперь идет
 через `direct`. Вызов deprecated entrypoint `direct-cli` завершается ошибкой с
@@ -1362,6 +1378,7 @@ direct ads add --adgroup-id 12345 --type MOBILE_APP_IMAGE_AD --image-hash abcdef
 direct ads add --adgroup-id 12345 --type SMART_AD_BUILDER_AD --logo-extension-hash logoabcdefghijklmnop --dry-run
 direct ads update --id 99999 --type TEXT_AD --title "Новый заголовок" --text "Новый текст" --href "https://example.com"
 direct ads update --id 99999 --type TEXT_AD --image-hash abcdefghijklmnopqrst
+direct ads update --id 99999 --type TEXT_AD --clear-image-hash  # удалить изображение (AdImageHash: null; только TEXT_AD / DYNAMIC_TEXT_AD / MOBILE_APP_AD)
 direct ads update --id 99999 --type TEXT_AD --title2 "Новый второй заголовок" --vcard-id 222
 direct ads update --id 99999 --type TEXT_AD --callouts-add "111,222" --callouts-remove "333"
 direct ads update --id 99999 --type TEXT_AD --callouts-set "444,555"
@@ -1380,7 +1397,10 @@ direct ads delete --id 99999
 ```
 
 Доступные типизированные флаги TEXT_AD для `ads add` / `ads update`:
-`--title`, `--text`, `--href`, `--image-hash`, `--title2`, `--display-url-path`,
+`--title`, `--text`, `--href`, `--image-hash`, `--clear-image-hash`
+(только update — устанавливает `AdImageHash: null`; только TEXT_AD /
+DYNAMIC_TEXT_AD / MOBILE_APP_AD, так как у TEXT_IMAGE_AD / MOBILE_APP_IMAGE_AD
+поле `AdImageHash` не nillable), `--title2`, `--display-url-path`,
 `--vcard-id`, `--sitelink-set-id`, `--turbo-page-id`, `--final-url`,
 `--video-extension-creative-id`, `--price-extension-*`, `--business-id`,
 `--prefer-vcard-over-business` и `--erir-ad-description`. Для `ads add`
@@ -1529,6 +1549,9 @@ direct bidmodifiers set --id 99 --value 130 --dry-run
 
 # Канонические многословные группы
 direct negativekeywordsharedsets update --id 123 --keywords "foo,bar"
+# audiencetargets get всегда требует фильтр — API отклоняет пустой
+# SelectionCriteria, поэтому обхода всего аккаунта нет. Чтобы собрать аккаунт,
+# сначала выполните `campaigns get`, затем запрашивайте audiencetargets get батчами campaign id.
 direct audiencetargets get --campaign-ids 123 --fields Id,AdGroupId,RetargetingListId,State,ContextBid
 direct audiencetargets add --adgroup-id 100 --retargeting-list-id 200 --bid 12000000 --priority HIGH --dry-run
 direct audiencetargets set-bids --id 101 --context-bid 7000000 --priority LOW --dry-run

{direct_cli-0.4.1 → direct_cli-0.4.3}/README.md

@@ -63,6 +63,9 @@ Notes:
 - If the first non-interactive step includes `--client-secret`, the secret is remembered for the matching completion step.
 - If a profile already stores a confidential OAuth client, `direct auth login --code CODE --profile NAME` reuses the saved `client_id` and `client_secret`.
 - `direct auth login --oauth-token TOKEN` is a manual access-token import and does not auto-refresh.
+- After a successful interactive login, Direct CLI asks whether to save the
+  access token and login to the current working directory `.env`; non-interactive
+  login flows do not prompt.
 - Alias `auth_login` is not supported.
 
 Credential resolution priority:
@@ -70,22 +73,23 @@ Credential resolution priority:
 | Priority | Source | Example |
 |----------|--------|---------|
 | 1 | Explicit CLI options | `direct --token TOKEN --login LOGIN campaigns get` |
-| 2 | OAuth profile storage | `direct --profile agency1 campaigns get` |
-| 3 | Profile-specific env vars | `YANDEX_DIRECT_TOKEN_AGENCY1`, `YANDEX_DIRECT_LOGIN_AGENCY1` |
-| 4 | Base env vars or current working directory `.env` | `YANDEX_DIRECT_TOKEN`, `YANDEX_DIRECT_LOGIN` |
+| 2 | Explicit profile credentials | `direct --profile agency1 campaigns get` |
+| 3 | Base env vars or current working directory `.env` | `YANDEX_DIRECT_TOKEN`, `YANDEX_DIRECT_LOGIN` |
+| 4 | Active profile credentials | `direct auth use --profile agency1` |
 | 5 | 1Password references | `--op-token-ref`, `YANDEX_DIRECT_OP_TOKEN_REF` |
 | 6 | Bitwarden references | `--bw-token-ref`, `YANDEX_DIRECT_BW_TOKEN_REF` |
 
 Direct CLI automatically loads only the `.env` file from the current working
 directory, i.e. the directory where you run `direct`. It does not search for
-`.env` from the installed package or source-code location. If a profile is
-selected with `--profile` or `direct auth use --profile NAME`, Direct CLI does
-not fall back to base `YANDEX_DIRECT_LOGIN`; this prevents mixing a profile
-token with a login from the current working directory `.env`. For multi-account
-setups, prefer OAuth profiles or profile-specific env vars instead of base
-credentials.
+`.env` from the installed package or source-code location. Without an explicit
+`--profile`, base `YANDEX_DIRECT_TOKEN` / `YANDEX_DIRECT_LOGIN` from env or cwd
+`.env` win over the active OAuth profile. With explicit `--profile`, Direct CLI
+uses only that profile's OAuth/profile-env credentials and does not fall back to
+base `YANDEX_DIRECT_LOGIN`; this prevents mixing accounts. `direct auth status`
+without `--profile` reports the effective credential source; with `--profile` it
+reports that profile.
 
-> **Tests use the inverted order.** Live-API test suites (e.g. `tests/test_v4_live_contracts.py`) read `YANDEX_DIRECT_TOKEN` / `YANDEX_DIRECT_LOGIN` from the environment first, only then fall back to the active `direct auth` profile, and skip the test if neither is set. This is intentional: a developer machine with an active profile must not silently hit production on a plain `pytest` invocation. See `CLAUDE.md` for the contract.
+> **Tests follow the safe credential order.** Live-API test suites (e.g. `tests/test_v4_live_contracts.py`) read `YANDEX_DIRECT_TOKEN` / `YANDEX_DIRECT_LOGIN` from the environment first, only then fall back to the active `direct auth` profile, and skip the test if neither is set. This prevents a developer machine with an active profile from silently hitting production on a plain `pytest` invocation. See `CLAUDE.md` for the contract.
 
 Install with `pip install direct-cli`, then run commands with `direct`.
 Invoking the deprecated `direct-cli` entrypoint exits with
@@ -496,6 +500,7 @@ direct ads add --adgroup-id 12345 --type MOBILE_APP_IMAGE_AD --image-hash abcdef
 direct ads add --adgroup-id 12345 --type SMART_AD_BUILDER_AD --logo-extension-hash logoabcdefghijklmnop --dry-run
 direct ads update --id 99999 --type TEXT_AD --title "New Title" --text "New text" --href "https://example.com"
 direct ads update --id 99999 --type TEXT_AD --image-hash abcdefghijklmnopqrst
+direct ads update --id 99999 --type TEXT_AD --clear-image-hash  # remove the image (AdImageHash: null; TEXT_AD / DYNAMIC_TEXT_AD / MOBILE_APP_AD only)
 direct ads update --id 99999 --type TEXT_AD --title2 "New second headline" --vcard-id 222
 direct ads update --id 99999 --type TEXT_AD --callouts-add "111,222" --callouts-remove "333"
 direct ads update --id 99999 --type TEXT_AD --callouts-set "444,555"
@@ -514,7 +519,10 @@ direct ads delete --id 99999
 ```
 
 Available TEXT_AD typed flags for `ads add` / `ads update`: `--title`, `--text`,
-`--href`, `--image-hash`, `--title2`, `--display-url-path`, `--vcard-id`,
+`--href`, `--image-hash`, `--clear-image-hash` (update only — sets
+`AdImageHash: null`; TEXT_AD / DYNAMIC_TEXT_AD / MOBILE_APP_AD only, since
+TEXT_IMAGE_AD / MOBILE_APP_IMAGE_AD have a non-nillable `AdImageHash`),
+`--title2`, `--display-url-path`, `--vcard-id`,
 `--sitelink-set-id`, `--turbo-page-id`, `--final-url`,
 `--video-extension-creative-id`, `--price-extension-*`, `--business-id`,
 `--prefer-vcard-over-business`, and `--erir-ad-description`. For `ads add`,
@@ -661,6 +669,9 @@ direct bidmodifiers set --id 99 --value 130 --dry-run
 
 # Canonical multiword groups
 direct negativekeywordsharedsets update --id 123 --keywords "foo,bar"
+# audiencetargets get always needs a filter — the API rejects an empty
+# SelectionCriteria, so there is no whole-account paging. To sweep the account,
+# run `campaigns get` first, then page audiencetargets get in batches of campaign ids.
 direct audiencetargets get --campaign-ids 123 --fields Id,AdGroupId,RetargetingListId,State,ContextBid
 direct audiencetargets add --adgroup-id 100 --retargeting-list-id 200 --bid 12000000 --priority HIGH --dry-run
 direct audiencetargets set-bids --id 101 --context-bid 7000000 --priority LOW --dry-run
@@ -1022,27 +1033,32 @@ direct --profile agency1 campaigns get
 - Если первый non-interactive шаг включает `--client-secret`, secret запоминается для последующего completion step.
 - Если profile уже хранит confidential OAuth client, `direct auth login --code CODE --profile NAME` использует сохраненные `client_id` и `client_secret`.
 - `direct auth login --oauth-token TOKEN` импортирует access token вручную и не включает auto-refresh.
+- После успешного интерактивного входа Direct CLI спрашивает, сохранить ли
+  access token и login в `.env` текущей рабочей папки; non-interactive вход этот
+  вопрос не задаёт.
 
 Порядок выбора credentials:
 
 | Приоритет | Источник | Пример |
 |-----------|----------|--------|
 | 1 | Явные CLI-опции | `direct --token TOKEN --login LOGIN campaigns get` |
-| 2 | OAuth profile storage | `direct --profile agency1 campaigns get` |
-| 3 | Профильные env vars | `YANDEX_DIRECT_TOKEN_AGENCY1`, `YANDEX_DIRECT_LOGIN_AGENCY1` |
-| 4 | Базовые env vars или `.env` из папки запуска | `YANDEX_DIRECT_TOKEN`, `YANDEX_DIRECT_LOGIN` |
+| 2 | Явно выбранный profile | `direct --profile agency1 campaigns get` |
+| 3 | Базовые env vars или `.env` из папки запуска | `YANDEX_DIRECT_TOKEN`, `YANDEX_DIRECT_LOGIN` |
+| 4 | Активный profile | `direct auth use --profile agency1` |
 | 5 | 1Password references | `--op-token-ref`, `YANDEX_DIRECT_OP_TOKEN_REF` |
 | 6 | Bitwarden references | `--bw-token-ref`, `YANDEX_DIRECT_BW_TOKEN_REF` |
 
 Direct CLI автоматически читает только `.env` из текущей рабочей папки, то есть
 из папки, где запущена команда `direct`. Он не ищет `.env` от папки
-установленного пакета или исходного кода. Если профиль выбран через `--profile`
-или `direct auth use --profile NAME`, Direct CLI не подставляет base
-`YANDEX_DIRECT_LOGIN`; это защищает от смешивания токена из профиля с логином из
-`.env` текущей рабочей папки. Для нескольких аккаунтов используйте OAuth
-profiles или профильные env vars, а не базовые credentials.
+установленного пакета или исходного кода. Без явного `--profile` базовые
+`YANDEX_DIRECT_TOKEN` / `YANDEX_DIRECT_LOGIN` из окружения или cwd `.env`
+побеждают активный OAuth profile. С явным `--profile` Direct CLI использует
+только OAuth/profile-env credentials этого профиля и не подставляет base
+`YANDEX_DIRECT_LOGIN`; это защищает от смешивания аккаунтов. `direct auth status`
+без `--profile` показывает реально выбранный источник credentials, а с
+`--profile` показывает этот профиль.
 
-> **В тестах порядок инвертирован.** Live-API тесты (например `tests/test_v4_live_contracts.py`) сначала читают `YANDEX_DIRECT_TOKEN` / `YANDEX_DIRECT_LOGIN` из окружения, затем падают на активный профиль `direct auth`, и скипают тест если ни того ни другого нет. Это сделано специально: на машине разработчика с активным профилем обычный `pytest` не должен молча идти в боевой API. Контракт зафиксирован в `CLAUDE.md`.
+> **Тесты используют безопасный порядок credentials.** Live-API тесты (например `tests/test_v4_live_contracts.py`) сначала читают `YANDEX_DIRECT_TOKEN` / `YANDEX_DIRECT_LOGIN` из окружения, затем падают на активный профиль `direct auth`, и скипают тест если ни того ни другого нет. Это защищает от случайного обращения к production API на машине разработчика с активным profile. Контракт зафиксирован в `CLAUDE.md`.
 
 Установка остаётся через `pip install direct-cli`, а запуск команд теперь идет
 через `direct`. Вызов deprecated entrypoint `direct-cli` завершается ошибкой с
@@ -1319,6 +1335,7 @@ direct ads add --adgroup-id 12345 --type MOBILE_APP_IMAGE_AD --image-hash abcdef
 direct ads add --adgroup-id 12345 --type SMART_AD_BUILDER_AD --logo-extension-hash logoabcdefghijklmnop --dry-run
 direct ads update --id 99999 --type TEXT_AD --title "Новый заголовок" --text "Новый текст" --href "https://example.com"
 direct ads update --id 99999 --type TEXT_AD --image-hash abcdefghijklmnopqrst
+direct ads update --id 99999 --type TEXT_AD --clear-image-hash  # удалить изображение (AdImageHash: null; только TEXT_AD / DYNAMIC_TEXT_AD / MOBILE_APP_AD)
 direct ads update --id 99999 --type TEXT_AD --title2 "Новый второй заголовок" --vcard-id 222
 direct ads update --id 99999 --type TEXT_AD --callouts-add "111,222" --callouts-remove "333"
 direct ads update --id 99999 --type TEXT_AD --callouts-set "444,555"
@@ -1337,7 +1354,10 @@ direct ads delete --id 99999
 ```
 
 Доступные типизированные флаги TEXT_AD для `ads add` / `ads update`:
-`--title`, `--text`, `--href`, `--image-hash`, `--title2`, `--display-url-path`,
+`--title`, `--text`, `--href`, `--image-hash`, `--clear-image-hash`
+(только update — устанавливает `AdImageHash: null`; только TEXT_AD /
+DYNAMIC_TEXT_AD / MOBILE_APP_AD, так как у TEXT_IMAGE_AD / MOBILE_APP_IMAGE_AD
+поле `AdImageHash` не nillable), `--title2`, `--display-url-path`,
 `--vcard-id`, `--sitelink-set-id`, `--turbo-page-id`, `--final-url`,
 `--video-extension-creative-id`, `--price-extension-*`, `--business-id`,
 `--prefer-vcard-over-business` и `--erir-ad-description`. Для `ads add`
@@ -1486,6 +1506,9 @@ direct bidmodifiers set --id 99 --value 130 --dry-run
 
 # Канонические многословные группы
 direct negativekeywordsharedsets update --id 123 --keywords "foo,bar"
+# audiencetargets get всегда требует фильтр — API отклоняет пустой
+# SelectionCriteria, поэтому обхода всего аккаунта нет. Чтобы собрать аккаунт,
+# сначала выполните `campaigns get`, затем запрашивайте audiencetargets get батчами campaign id.
 direct audiencetargets get --campaign-ids 123 --fields Id,AdGroupId,RetargetingListId,State,ContextBid
 direct audiencetargets add --adgroup-id 100 --retargeting-list-id 200 --bid 12000000 --priority HIGH --dry-run
 direct audiencetargets set-bids --id 101 --context-bid 7000000 --priority LOW --dry-run