De-clutter `dagger call --help`

[shykes]

Problem

dagger call [ARGS] --help plays a crucial role, and must be kept as lean as possible. At the moment there is clutter that could be removed.

Solution

De-clutter the output of dagger call [ARGS] --help.

• Talk about "functions" and "arguments", rather than "function commands" and "flags"
  • cli: use "functions" and "arguments" instead of "commands" and "options" in dagger call --help #7286
• Don't show inherited flags when a function is selected
  • cli: don't show inherited flags in function commands #7419
• Don't show functions that the CLI can't run
  • cli: don’t show functions that can’t be called #7418
• Keep long description short by linking to the web for more information
  • CLI: simplify and clarify usage text #7277

Additional

Improvements to make --help easier to read:

• Style headings in BOLD UPPERCASE to help break sections visually
  • cli: style headings in BOLD UPPERCASE to help break sections visually #7126
• Put flags between commands and global flags
  • cli: repositioning flags below all commands #7134
• Visual cue for required flags
  • cli: visual cue for required flags #7262
• Examples aren't indented
  • cli: indent examples in --help #7287

Improve consistency:

• "Options" instead of "Flags"
  • cli: rename flags to options #7170
• Conventionalize usage syntax for consistency
  • cli: conventionalize on <command> in cmd.Use #7143
• dagger query has a different help template
  • cli: remove special template on query subcommand #7124
• dagger functions <function> --help doesn't work
  • cli: Fix flag parsing when interspersed with arguments in dagger functions #7187

[shykes]

FYI @helderco I know this is on your radar already

[helderco]

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

Yeah, all that and there's more.

[helderco]

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

Note

Moved the above list to the description.

Footnotes

1. I went back and forth on this one. I like Options more, but Flags is Cobra's default and overriding it means making sure no [flags] is also used, in favor of [options], so I want back and reverted to Flags. ↩

[grouville]

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)

[helderco]

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

[grouville]

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)

[helderco]

@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.