Was there any further update on this? > On 21 Jul 2026, at 19:37, Buğra Öztürk <[email protected]> wrote: > > Hey Bob, > > Thanks for creating the discussion! I think we should keep the parity. > Things that stay in people's minds for many years have a lasting impact, > even when it comes to naming. A major downside is that users would need to > migrate from `airflow dags trigger` to `airflowctl dags trigger`, and they > would also need to update the subcommand. On the other hand, this is the > right time before 1.0 to decide whether we want to make this change as a > community. > > If the preferred direction is the REST-style naming, we could add one more > item to the third outcome. Instead of enforcing hard limits, how about > adding aliases to preserve Airflow CLI parity? For example, we could > support both `airflowctl dagrun` and `airflowctl dagruns`. We could warn > users when they use the Airflow CLI naming, but not fail because they're > already familiar with it. This would make the transition more forgiving. We > would only accept these aliases to preserve Airflow CLI parity. As > suggested in the outcome, the new naming would follow the defined > convention. We should also define clear naming rules so we don't drift > further and have something to reference for future additions. This would make > the approach more future-proof. > > Best regards, > Bugra Ozturk > >> On Mon, Jul 20, 2026 at 11:09 AM Bob Du <[email protected]> wrote: >> >> Hi all, >> >> In https://github.com/apache/airflow/pull/67947#discussion_r3569126675 >> Ash suggested taking the naming question raised there to the dev list >> for a wider discussion. Starting that thread here, since it currently >> slows down the whole `tasks` command family — and since renames are >> only cheap while we are on 0.x. The sooner a rule is agreed, the less >> inconsistency friction accumulates for contributors and early adopters >> alike, and the smoother the eventual path to 1.0. >> >> **The question** >> >> airflowctl currently has no written rule for how user-facing command >> groups and names are chosen. Two principles are competing in practice, >> and I'd like us to pick one: >> >> - **Option A — REST resource alignment**: commands are named after the >> Public API resource they operate on, using the plural URL segment as >> the group (`POST /dags/{id}/dagRuns` → `dagruns trigger`). >> - **Option B — airflow CLI parity**: any command that replaces an >> `airflow` CLI remote command keeps its old group + name (`airflow >> tasks clear` → `airflowctl tasks clear`); commands with no old-CLI >> counterpart fit into the same old-CLI-style groups. >> >> The merged surface today mixes both: `dags trigger` follows B >> (deliberately moved out of the `dagrun` group after the 1.0.0rc2 vote >> feedback, although it calls `POST /dags/{id}/dagRuns`), while `dagrun >> get/list/delete` roughly follows A — with a singular group name that >> matches neither the URL segment (`/dagRuns`) nor any old-CLI group. >> Meanwhile `dagrun list` and the old CLI's `dags list-runs` name the >> same thing differently, and neither was chosen on purpose. >> >> **Why decide now** >> >> Seven open PRs adding task-level commands (#67947, #69320, #69366, >> #69397, #66852, #66213, #68776) each had to pick names independently: >> some would surface these commands as `tasks ...`, others as >> `taskinstances ...`. The diffs conflict with each other, and in #67947 >> the same code was renamed back and forth between reviews pulling in >> opposite directions ("match core CLI naming" vs "these are >> TaskInstance operations"). Three of these PRs are approved and >> mergeable but stalled. Every future command family will replay this >> argument until a rule is written down. >> >> From a user's perspective (I run Airflow in production and am >> evaluating airflowctl for remote task-instance operations — I filed >> #69947 for `tasks logs`): today you cannot predict whether the command >> you need will be called `tasks clear` or `taskinstances clear`. >> >> **The two options side by side** >> >> ``` >> operation | A: REST resources | B: airflow CLI >> parity >> >> ---------------------------+----------------------------+---------------------------------- >> trigger a dag run | dagruns trigger | dags trigger >> (today) >> list runs of a dag | dagruns list | dags >> list-runs (old CLI) >> get one dag run | dagruns get | dags state >> (today) >> delete a dag run | dagruns delete | needs a new >> name under `dags` >> list tasks of a dag | tasks list | tasks list >> all TI states of a run | taskinstances list | tasks >> states-for-dag-run >> clear task instances | taskinstances clear | tasks clear >> single TI state | taskinstances get | tasks state >> task instance logs (new) | taskinstances logs | tasks logs >> TI failed dependencies | taskinstances failed-deps | tasks failed-deps >> ``` >> >> **Why I would not formalize the middle path** >> >> There is a third possible outcome: codify what current practice has >> drifted into — migrated commands keep their old-CLI names (B), >> API-native commands follow REST (A). I want to argue explicitly >> against this hybrid, even though it looks like the path of least >> resistance, because I think it is the worst of the three for the long >> run: >> >> - It makes names unpredictable *by design*. To guess a command's name >> you first have to know whether it happened to exist in the >> pre-airflowctl CLI — that is knowledge about the tool's history, not >> about the task at hand. Existing users get partial familiarity; new >> users (eventually the majority) get no benefit at all, yet pay the >> full cost of two conventions. >> - It splits one resource across groups. Task-instance operations would >> land partly under `tasks` (the migrated clear/state) and partly under >> whatever the REST rule produces (e.g. a new logs command) — related >> commands stop being discoverable side by side in `--help`. >> - It never converges. As the old CLI is deprecated and new API >> capabilities keep arriving, the REST-named share of the surface keeps >> growing around a frozen old-CLI core. B's familiarity benefit decays >> to zero once the `airflow` CLI is gone, but the inconsistency it bakes >> in is permanent. There is no future release in which the command >> surface ever looks uniform again. >> - It doesn't even end the per-PR debates. "Did this exist in the old >> CLI?" is blurrier than it sounds (`dags list-runs` vs `dagrun list` is >> the same feature in two shapes), so contributors and reviewers still >> have to argue category membership for every new command family — which >> is exactly the friction we are trying to remove. >> - And it compounds the maintenance burden: docs, the `airflow ↔ >> airflowctl` mapping table, help texts and any lint/prek enforcement >> all have to encode two conventions plus an exception list, forever. >> >> Today's confusion is not the absence of the hybrid — it is the >> hybrid's output. Whichever of A or B people prefer, I believe one >> principle applied everywhere is worth more than either principle's >> specific merits. >> >> **Compatibility, if Option A wins** >> >> A implies renaming the commands that currently follow B (`dags >> trigger`, `dags state`), plus fixing `dagrun` → `dagruns`. I would >> lean against adding any compatibility shim for the old names: >> airflowctl is a new tool on 0.x — breaking changes are exactly what >> this window is for — and AIP-94 itself only requires *functional* >> parity plus a documented `airflow ↔ airflowctl` command mapping, not >> identical names. A clearly documented mapping table (which AIP-94's >> migration tooling plans anyway) is enough for users to migrate by, and >> it keeps the command surface clean and the long-term maintenance >> burden low. >> >> **Either way** >> >> Whichever option is chosen: write it into the contributing docs, >> enforce it with a prek check where possible, and rename the existing >> non-compliant commands while we are still on 0.x. >> >> I'm happy to turn the outcome into the docs PR plus the corresponding >> rename PRs. Curious what people think — especially Bugra and Ash, >> whose review positions in #67947 this is meant to unblock. >> >> Kind regards, >> Bob Du >> >> --------------------------------------------------------------------- >> To unsubscribe, e-mail: [email protected] >> For additional commands, e-mail: [email protected] >> >>
--------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
