search

neos / neos-development-collection

The unified repository containing the Neos core packages, used for Neos development.
https://www.neos.io/
GNU General Public License v3.0
260 stars 218 forks source link

DISCUSSION: Improve our existing CLI commands in Flow/Neos #5128

Open crydotsnake opened 3 weeks ago

crydotsnake commented 3 weeks ago

Is there an existing issue for this topic?

Description

Hi,

I have been working with commands for the console for a while now and have found it interesting!

Therefore, I would like to take on the topic of improving our existing CLI commands if necessary.

In the last few weeks, I have been thinking about what new commands could be introduced. But so far I haven't come up with anything useful. But we already have a whole range of CLI commands. So I would like to concentrate on improving our existing ones.

But of course, you can also contribute your feedback for new commands if you have something in mind!

I look forward to your feedback!

Open issues

Open Pull requests

Possible Solution

No response

robertlemke commented 3 weeks ago

Assuming you want to open a general discussion about Flow CLI commands, here's my take:

I would like to see the introduction of global flags which can be used in any command. For starters, it would be great if you could do just append --help to any command in order to display the help message (instead of doing ./flow help foo:bar).

Another type of flag I'd love to have is --quiet and --verbose. By default, we could omit any output from the command sent by $this->output->outputLine() or so, when --quiet is used. But to make really sense, we need to introduce some kind of new output() method which is meant for errors (not exceptions), which would be displayed even when --quiet was specified. Likewise, an outputVerbose() method would only result in output if --verbose is specified.

Other than that, I don't like the pattern foo:bar anymore, which we use for commands. If I'd start today, I'd go for the scheme Go uses (for example, Cobra - https://cobra.dev/#concepts). We could introduce the new scheme and still support the old one for a couple of years.

That's what I'd love most regarding commands at the moment.

kitsunet commented 3 weeks ago

I really like the pattern of help <command> to get help for a specific command, I think this could work for us too?

kitsunet commented 3 weeks ago

Another thing I would personally really want to do long term is use symfony/console parsing of arguments, so it would be great to not add anything that contradicts that if possible.

robertlemke commented 3 weeks ago

I really like the pattern of help <command> to get help for a specific command, I think this could work for us too?

But that's just what we have now, or what do you mean?

./flow help <command> ./flow help user:show

I think that this is quite inconvenient, because I often start writing a command like so:

./flow user:create --name=Robert --favorite-drink=coffee

and then wonder which other flags exist. So I have to go all the way back between flow and user:create and insert a help, then submit the command and then remove the help again. It's way easy to just append --help at the very end.

And without going into detail, there are quite a few technical and aesthetic issues I have with symfony/console argument handling, so let's rather have a deeper look into that, once we want to tackle that task.

kitsunet commented 3 weeks ago

Right, I forget we do have that. It seems to be a pattern many tools follow though, so it's at least well known? But I am fine if we shift to global --help I can follow your argument.

crydotsnake commented 3 weeks ago

Hello @robertlemke & @kitsunet

Thanks for your feedback!

I would like to see the introduction of global flags which can be used in any command. For starters, it would be great if you could do just append --help to any command in order to display the help message (instead of doing ./flow help foo:bar).

I totally see your point. I also work with other CLI tools and there its the same schema/behavior that you have a --help flag. I already experiement a bit with the --help flag but i still have to spend a bit more time and check if i still have/can improve something codewise:

https://github.com/neos/neos-development-collection/assets/39345336/915b3726-15bc-477a-aa53-d61682f04836

Right now i'm a bit unsure about this.

Would it make sense to have one PR that contains the changes with the --help flag and the new pattern for applying commands like here: https://cobra.dev/#concepts ? Or would that go beyond the scope and it would be better to implement this separately?

robertlemke commented 3 weeks ago

Personally, I'd keep the pull requests as small and focused as possible – create one which introduces the --help flag sounds like a good idea to me.

But I guess we shouldn't change the old behavior (yet) that if you specify no arguments or miss arguments (./flow user:create), Flow will turn into interactive mode and ask for the arguments.

One topic I completely forgot which also need improvement: In my opinion, Flow should throw an error and exit with a code != 0 if you specify an argument which does not exist. Imagine you have a --dry-run option and mistype the command like so: ./flow universe:destroy --dryrun. This will destroy the universe, and it shouldn't.

crydotsnake commented 3 weeks ago

Personally, I'd keep the pull requests as small and focused as possible – create one which introduces the --help flag sounds like a good idea to me.

👍🏽

I was just about to create a DRAFT PR for it, but then I realized that there is no 8.4 branch in the flow-development-collection yet 🤦🏽 I could created it against the 8.3 branch and change the target branch later but i will wait then until the 8.4 branch is there !

But I guess we shouldn't change the old behavior (yet) that if you specify no arguments or miss arguments (./flow user:create), Flow will turn into interactive mode and ask for the arguments.

Totally agree