airflow-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jiajie Zhong <>
Subject Re: CLI: Use nested commands instead of flags
Date Thu, 20 Jun 2019 02:34:50 GMT
Thanks Ash bring this up.
I agree with Chris points

> in which case I think it would be very confusing to have <target> switch
> between singular and plural; both from a user perspective and from a coding
> perspective.

IMO, I think we should use plural in our cli, I think it just like RESTful api path
prefer plural, means we have lots of resource and we could pick one or more

Best Wish
— Jiajie

On Jun 20, 2019, at 00:01, Chris Palmer <<>>

I think it can make sense to use both singular and plural, if you structure
your commands in the right way. For example Kubernetes generally use the
structure of:

kubectl <action> <target>

where target can be singular or plural depending on what you want to take
action on.

This is opposed to GCP which use the general structure of:

gcloud <target> <action>

in which case I think it would be very confusing to have <target> switch
between singular and plural; both from a user perspective and from a coding

I think the Airlfow cli is much more in line with the second structure. It
would be weird to me if the Airflow cli had

airflow dags list  # plural
airflow dag trigger # singular

To that end I would suggest that Airflow sticks with either singular or
plural, but not both.


On Tue, Jun 11, 2019 at 3:52 PM Bas Harenslak <<>>

My 2c: I googled a bit and checked a few other CLIs. The internet is full
of people discussing this topic and there is no straight answer, so pick
one and stick with it.

Most CLIs seem to use both plural and singular, depending on whether
you’re making a request to single resource or multiple resources:

Kubernetes: both (e.g. kubectl get pod for single pod, kubectl get pods
for all)
Gcloud: plural (e.g. gcloud compute instances move … for moving a single
AWS: both
Docker: both

I think it kinda makes sense to use both forms, since in spoken word we
also talk about a “dag” (singular) when referring to one single DAG, and
talk about “dags” (plural) when referring to multiple DAGs.


On 11 Jun 2019, at 20:28, Kamil Breguła <<><mailto:<>>> wrote:

gcloud use a plurral form.

On Tue, Jun 11, 2019 at 8:08 PM Ash Berlin-Taylor <> wrote:

To bring up the point that William Pursell brought up in the vote thread:

Not sure if this is the right place to address minor issues, and
perhaps I'm late to the discussion.  It would be much more natural to
use singular expressions.  eg,

airflow dag list
airflow pool list
airflow pool add

Does anyone have any opinion about this. I'm fairly ambivalent. What do
other tools do here? (i.e. is there any prior art we can copy)


On 11 Feb 2019, at 08:48, Szymon Przedwojski <> wrote:

+1, I like the general idea of refactoring this and the new command
suggestions by Kamil look nice and coherent to me.

Szymon Przedwojski
Polidea | Software Engineer

M: +48 500 330 790

On 8 Feb 2019, at 11:50, Kamil Breguła <> wrote:

I think that it is worth to group some commands.

Currently, the user must choose from a large number of commands, which may
not be intuitive for the developer. Grouping several command will make it a
lot more enjoyable.

airflow resetdb => airflow db reset
airflow initdb => airflow db init

airflow list_dags => airflow dag list
airflow trigger_dag dag_id => airflow dag trigger dag_id
airflow unpause dag_id => airflow dag unpause dag_id
airflow list_dag_runs dag_id => airflow dag list_runs dag_id
airflow list_tasks dag_id => airflow dag list_tasks dag_id
airflow dag_state dag_id => airflow dag state dag_id
airflow backfill dag_id => airflow dag backfill dag_id

airflow render dag_id task_id execution_date => airflow ti render dag_id
task_id execution_date
airflow test dag_id task_id execution_date => airflow ti test dag_id
task_id execution_date
airflow task_state => airflow ti state
airflow run => airflow ti run

And other...

This way of building CLI UI is common in the industry. For example gcloud ( )

I think it's worth to prepare AIP to think about building the CLI
interface. We can introduce the proposed change for only some commands.It
is worth adding that another interface - REST, have AIP -

I personally support the introduction of changes, but we can not make
changes and think only about one case. First, let's prepare the whole
interface design, and the next step is to introduce changes.

Thank you very much for thinking about this issues.

On Fri, Feb 8, 2019 at 6:27 AM <>

The CLI treats `airflow connection` as a single command, with `--list`,
`--add`, etc. as flags. This means it's possible to pass options that can't
be used together: passing `--list` with `--conn_id` should be invalid. The
current implementation has to handle validation of mutually exclusive
options separately for each command. I think the code would be simpler and
easier to use if we used nested commands instead of flags: `airflow
connections list` and `airflow connections add` would be separate
subcommands that would take different arguments, and we wouldn't have to
check for invalid combinations of commands and arguments.

This might overlap with other CLI refactoring, like I'm not sure if that
conversation is still active, though.

Interested to get feedback about this--maybe there are advantages to using
flags instead of subcommands that I haven't thought of.


Kamil Breguła
Polidea <> | Software Engineer

M: +48 505 458 451 <+48505458451>
[image: Polidea] <>

We create human & business stories through technology.
Check out our projects! <>
[image: Github] <> [image: Facebook]
<> [image: Twitter]
<> [image: Linkedin]
<> [image: Instagram]
<> [image: Behance]

  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message