Summary

Define an explicit canonical naming convention for direct-cli transport commands.

direct-cli currently exposes both canonical commands and historical aliases. The repository needs one source of truth for which names are canonical, which names are compatibility aliases, and which names must be used in docs, examples, tests, and downstream integrations.

This is a breaking change for documentation, examples, and any code that currently treats legacy aliases as canonical.

Goals

• define canonical naming rules for direct-cli command groups and subcommands
• distinguish canonical command names from compatibility aliases
• require canonical names in docs, examples, smoke tests, and coverage matrices
• keep legacy aliases only where compatibility is intentionally preserved
• document one canonical example for every canonical command
• make transport naming an explicit direct-cli concern rather than leaking it into downstream repos

Required outcomes

• direct-cli has a documented canonical <group> and <command> naming convention
• docs and examples use canonical names, not legacy aliases
• compatibility aliases are tracked explicitly and tested as aliases rather than presented as first-class names
• help output, docs, and coverage metadata agree on canonical command names
• any command assumed by downstream wrappers but not actually exposed by the installed CLI surface is documented as a transport gap

Canonical naming rules

1. Canonical command shape

All transport commands follow:

• direct <group> <command> [flags]

2. Group naming

Rules:

• lowercase ASCII only
• no underscores
• multiword groups are concatenated

Examples:

• agencyclients
• keywordbids
• negativekeywordsharedsets
• smartadtargets

3. Command naming

Rules:

• lowercase only
• use kebab-case for multiword actions
• prefer explicit full names over short historical aliases

Examples:

• set-auto
• set-bids
• list-types
• list-names
• get-geo-regions
• has-search-volume
• check-campaigns
• check-dictionaries

Canonical vs legacy alias policy

The following names should be treated as canonical in docs, examples, and coverage tables:

• get instead of list
• check-campaigns instead of checkcamp
• check-dictionaries instead of checkdict
• has-search-volume instead of has-volume
• negativekeywordsharedsets instead of negativekeywords
• smartadtargets instead of smarttargets
• dynamicads instead of dynamictargets

Legacy aliases may remain for compatibility, but they must be:

• documented in a compatibility table
• tested as aliases
• excluded from the main canonical examples section
• excluded from canonical coverage and parity summaries

Per-command examples

Add one minimal happy-path example for every canonical command.

Rules:

• examples use canonical names only
• examples use placeholders like <TOKEN>, <ID>, <JSON>, <LOGIN>
• examples should prefer --format json when structured output matters
• examples should be grouped by canonical command group

Representative examples:

direct --token <TOKEN> campaigns get --format json
direct --token <TOKEN> keywordbids set-auto --json '<JSON>'
direct --token <TOKEN> changes check-campaigns --campaign-ids <ID>
direct --token <TOKEN> dictionaries get-geo-regions --ids <ID> --format json
direct --token <TOKEN> negativekeywordsharedsets update --id <ID> --keywords "foo,bar"

Documentation and test updates

• update README and command reference sections to use canonical names
• add a canonical vs alias table for all retained compatibility names
• update CLI coverage metadata and smoke tests so canonical names are the only first-class entries
• add checks that examples do not regress back to legacy aliases
• document transport gaps where downstream wrappers assume commands that are not consistently exposed by the CLI help surface

Known transport gap to track

Current downstream wrappers assume dynamicads update / dynamictargets update, but the installed CLI help surface does not expose update for those groups. That mismatch should be resolved or explicitly documented before any downstream repo treats those commands as canonical transport operations.

Cross-repo note

Downstream MCP naming and API-first public contract migration are tracked separately in axisrow/yandex-direct-mcp-plugin#66. That issue should consume direct-cli as a transport implementation detail and must not define transport naming policy.

Acceptance criteria

• canonical transport names are documented in direct-cli
• legacy aliases are explicitly labeled as compatibility aliases
• canonical docs and examples do not use legacy alias names
• canonical command matrices, smoke tests, and help-oriented tests agree on canonical names
• transport gaps are documented where CLI exposure and downstream assumptions diverge