Switch positional logical-date-or-run-id CLI argument to a flag?

[uranusjr]

Body

Raised during review of #46407.

We introduced logical_date_or_run_id back in 2.2 when we started enforcing the DR-TI relationship so people can select a TI with run_id instead of execution_date. The argument was implemented as a “smart” positional argument because we needed to maintain backward compatibility of the CLI. With 3.0, however, it is possible to get rid of the magic and require the user to pass in a named argument instead, so instead of

$ airflow tasks run <dag_id> <task_id> <logical_date_or_run_id>

the user must write

$ airflow tasks run <dag_id> <task_id> --run-id <run_id>

or

$ airflow tasks run <dag_id> <task_id> --logical-date <logical_date>

This feels like an improvement in a vacuum, but is it worthwhile as a breaking change?

Committer

• I acknowledge that I am a maintainer/committer of the Apache Airflow project.

[uranusjr]

Also should rename --exec-date on airflow dags trigger.

[amarlearning]

Hey @uranusjr, can we resolve this issue in separate MRs—one for renaming --exec-date on airflow dags trigger and the other for airflow tasks run? Both changes require significant effort, including updating docs, scripts, and tests, so splitting them will make implementation and review more manageable.

[uranusjr]

Of course, whatever works best.

[amarlearning]

Thanks! I'll start by implementing the --exec-date rename to --logical-date, and we can handle the airflow tasks run command change in a separate MR later.

[amarlearning]

Hi @uranusjr, As I'm relatively new to the Airflow community, I've been diving deep into the codebase to understand it better.

After carefully studying how the airflow tasks run command works in Airflow 3.0, I noticed it's part of a transition toward the Task SDK approach. While still used internally by some executors, it's no longer in the user-facing CLI.

I'm a bit concerned that changing the command syntax might introduce a breaking change during this transitional period, potentially affecting internal executor implementations. I've also noticed comments like TODO: TaskSDK: Compat, remove when KubeExecutor is fully moved over to TaskSDK which suggest this command pattern is temporary.

As someone eager to contribute meaningfully, I'm wondering if focusing on helping with the Task SDK transition might be more valuable for the project long term. I'd appreciate your guidance on whether this syntax change is still a priority given the architectural direction.

I'm happy to proceed with the original issue or redirect my efforts based on what would best serve the project.

[uranusjr]

Let me ask around. I’m not familiar with task sdk planning either.

[uranusjr]

With the 3.0rc close, however, I think it’s probably better to work on the CLI changes now anyway since 3.0 is the best time to do the changes if they are going to stick. If we don’t do them now, and it turns out we are still going to have them going forward, the transition will be a lot harder.