FYI @helderco I know this is on your radar already

Darn, seems there's a few issues I haven't created yet 😅

Yeah, all that and there's more.

Following:

• CLI: Improve display of core API in --help #6549

These are not just for dagger call, but all --help:

• Add line break between error and usage
• Style headings in BOLD UPPERCASE to help break sections visually
• Conventionalize on either <command> or COMMAND syntax in cmd.Use
• Figure out if arguments are better above or below functions/commands EDIT: confident it's the latter
• Put flags between commands and global flags
• Visual cue for required flags
• "Options" instead of "Flags"?¹
• Help topics for dagger call to keep --help lean while still providing more documentation EDIT: maybe best to just link to web

I could help on that one @helderco, wdyt ? Seems a not too hard issue with figurable context dumps (or I'm wrong ahahah) 🙏

(even subsets)

You're not wrong 🙂 Yeah, if you have cycles go ahead!

I've got the uppercase + newline done 🙏 (easy part)

For this part though, I'm not sure about what you mean in "top level commands". Because, with my tests, I only see the global flags on those 2 positions at the moment: on the root command (dagger help) and on any available subcommand (dagger functions --help), am I missing some other subcommands where this would be present ?

Also, on the root, we name "Global flags" as "Flags", whereas in the rest of the other commands it's "global flags"

1. What I understand about Global flags only on root command and top level commands:

We should have a condition on the usage template to show the section in those cases

2. Remove persistent flags from child commands after being parsed

On some of the commands, we should remove arguments that have been are already present in the user's command. Especially: TUI (--silent, --focus) and Modules (-m)

@grouville and I synced and I suggested to leave the global flags thing for later.

Re: terminology, global flags are "persistent flags" from a parent command. In the command that sets them, they're just "Flags". But if they're persisted to their children, then from the children they're "global". dagger call for example, defines --json and --output as persistent flags. You can see that in any dagger call FUNCTION --help, --json is a global flag, but in dagger call it's just flag.

I consider a "top-level" command, any command that is an immediate child of the root command (dagger call, dagger init, dagger run, etc).

I just think that showing global flags on children of top level commands just add clutter. I prefer adding these flags right after the root command. Otherwise, at minimum they should just be hidden. But if we actually remove them from top-level children (avoids clashing with user arguments in dagger call as well), it may require changing how flags are parsed, and it's in that scenario that it "may" be needed to use TraverseChildren.

This is all very fleeting thought like, so that's why I suggest leaving it for later. The main intent is to limit where they're shown, to de-clutter as much as possible.

Whilst working on #7143, I had the opportunity to stress test the CLI a bit. Brain dump:

dagger functions

After a user selects a function: dagger functions foo, the -—help is interpreted as another function and fails
E.g
./dagger -m github.com/levlaz/daggerverse/mariadb@v0.2.1 functions base --help

is it expected ? If not, the git CLI uses the -- terminology to specify that on their usage:

 git log [<options>] [<revision-range>] [[--] <path>...]

What is your opinion on using that -- to specify that after that section args are not interpretable ?

dagger config

This command is still partially hidden and raises the upcoming question on how to show / present subcommands. I realized that at the moment it is not (maybe intentionally?)

dagger query

This is the usage:

dagger query [flags] [<operation>]

with [<operation>], I understand that the operation is not mandatory. I could then try:

./dagger query         
✔ Module.initialize: Module! 1.6s
  ✔ exec go build -o /runtime . 0.9s

12:04:36 WRN failed to resolve image; falling back to leftover engine error="GET https://registry.dagger.io/v2/engine/manifests/latest: MANIFEST_UNKNOWN: manifest unknown"
Error: make request: returned error 422 Unprocessable Entity: {"errors":[{"message":"no operation provided","extensions":{"code":"GRAPHQL_VALIDATION_FAILED"}}],"data":null}

It is accepted but fails: no operation provided.

So, we accept having no operation on the CLI side, but its execution fails by default.
It might make more sense to change it as mandatory, and/or show the help as dagger gen ?

dagger run

This is the usage of dagger run:

dagger run [flags] <command>

When running ./dagger run, I have this error message:

./dagger run       
Error: requires at least 1 arg(s), only received 0

The behavior is correct, but across the CLI we have several behavior when a command is required and not specified:

1. Dagger query -> runs and fails with error message from execution
2. This command dagger run -> prints an error message
3. dagger install, which prints the --help output

dagger watch

its current usage does not seem correct per se:

dagger watch [flags] <command>

My understanding is that the <command> is mandatory, however, I managed to run the dagger watch command as a standalone.

It seems that it is currently not mandatory and should either be [<command>] or print an error / show help (preferred behavior) when not set ?

Whilst working on #7143, I had the opportunity to stress test the CLI a bit. Brain dump:

dagger functions

After a user selects a function: dagger functions foo, the -—help is interpreted as another function and fails E.g ./dagger -m github.com/levlaz/daggerverse/mariadb@v0.2.1 functions base --help

is it expected ? If not, the git CLI uses the -- terminology to specify that on their usage:

 git log [<options>] [<revision-range>] [[--] <path>...]

What is your opinion on using that -- to specify that after that section args are not interpretable ?

As long as dagger functions shows only functions and not their arguments, there's no conflict with --help and thus no need to --. It just requires an implementation fix.

Basically:

• dagger functions: Command path
• func1 func2 func3: Positional arguments to functions command
• --help: Flag for functions command

dagger config

This command is still partially hidden and raises the upcoming question on how to show / present subcommands. I realized that at the moment it is not (maybe intentionally?)

It's intentional because we needed to get the "views" feature in dagger.json out without having it be blocked on the design of the CLI ergonomics.

Don't worry about it for now, just keep what's hidden hidden.

dagger query

This is the usage:

dagger query [flags] [<operation>]

with [<operation>], I understand that the operation is not mandatory. I could then try:

./dagger query         
✔ Module.initialize: Module! 1.6s
  ✔ exec go build -o /runtime . 0.9s

12:04:36 WRN failed to resolve image; falling back to leftover engine error="GET https://registry.dagger.io/v2/engine/manifests/latest: MANIFEST_UNKNOWN: manifest unknown"
Error: make request: returned error 422 Unprocessable Entity: {"errors":[{"message":"no operation provided","extensions":{"code":"GRAPHQL_VALIDATION_FAILED"}}],"data":null}

It is accepted but fails: no operation provided.

So, we accept having no operation on the CLI side, but its execution fails by default. It might make more sense to change it as mandatory, and/or show the help as dagger gen ?

It's possible there's incorrent usage lines like that. If you find any, just fix the usage and validation if needed, to match the correct behavior. In this case yes: if it looks like it's required, then better make it required. There's a way to tell Cobra that this command is required to take 1 positional argument, for example. There's examples of this in ./cmd/dagger.

dagger run

This is the usage of dagger run:

dagger run [flags] <command>

When running ./dagger run, I have this error message:

./dagger run       
Error: requires at least 1 arg(s), only received 0

The behavior is correct, but across the CLI we have several behavior when a command is required and not specified:

To be technically accurate, there's a difference between a command and a positional argument. In this case it's the latter.

1. Dagger query -> runs and fails with error message from execution
2. This command dagger run -> prints an error message
3. dagger install, which prints the --help output

Some CLIs just print an error, others print an error with usage included. Cobra does the latter in some cases but we may have needed to disable, especially when manually handling output like we do with the TUI.

The best thing though is to help the user out, so I'd print the error with a short usage. You can see in Cobra there's a distinction between showing the usage and showing the full help. The help includes the usage, but you can show an error with the usage, without the full help.

I've already established that 1. needs fixing, but check what's the default for Cobra, is it 2. or 3? Is there any special handling on our side in either of those cases? I tend to prefer having less on our side to maintain. But after having this answered and it feels better to do more, than let's talk when we cross that bridge 🙂

dagger watch

its current usage does not seem correct per se:

dagger watch [flags] <command>

My understanding is that the <command> is mandatory, however, I managed to run the dagger watch command as a standalone.

It seems that it is currently not mandatory and should either be [<command>] or print an error / show help (preferred behavior) when not set ?

Yeah, that's not mandatory. I don't think it's actually used at all. Probably copy pasta 🙂

Update on improvements to --help:

• cli: remove special template on query subcommand #7124
• cli: style headings in BOLD UPPERCASE to help break sections visually #7126
• cli: repositioning flags below all commands #7134
• cli: conventionalize on <command> in cmd.Use #7143
• cli: rename flags to options #7170
• cli: Fix flag parsing when interspersed with arguments in dagger functions #7187
• cli: visual cue for required flags #7262
• cli: use "functions" and "arguments" instead of "commands" and "options" in dagger call --help #7286
• cli: indent examples in --help #7287
• CLI: simplify and clarify usage text #7277

EDIT: I moved the PR references above to the description, next to their list items.

I'm closing this epic. If there's more things, we'll address via individual issues.