CLI: simplify and clarify usage text

[shykes]

No description provided.

[grouville]

Related to:

• cli: conventionalize on <command> in cmd.Use #7143

[helderco]

@shykes, I rebased. Only not merging because waiting for reply to #7277 (comment).

[gerhard]

@helderco you may want to rebase this again.

These are the most important change that this PR has not picked up yet:

• Migrate to new ci runners #7082
• Add testdev job with v2-dind runners #7296

[shykes]

@shykes, I rebased. Only not merging because waiting for reply to #7277 (comment).

Thanks, sorry I had missed your rebase earlier.

[helderco]

[arguments] and <function> are appended to the usage line dynamically based on the existence of arguments or further functions, respectively. So this will produce the following:

dagger call [options] [FUNCTION [FUNCTION...]] [arguments] <function>

[options] only show on call (doesn't include global flags), so leaving as is creates this usage while you keep adding functions (assuming there's constructor arguments):

dagger call [options] [arguments] <function>
dagger call cli <function>
dagger call cli file [arguments] <function>
dagger call cli file name

Notice also that we conventionalized usage syntax here:

• cli: conventionalize on <command> in cmd.Use #7143

[helderco]

The strings.ReplaceAll here is no longer needed. It was a clever hack to allow markdown with ´--output´ for example.

[helderco]

This error has been replaced with:

• cli: list available functions when chain ends in an object #7421

Basically any chain that ends in an object that has itself functions, lists them under "Available Functions".

[shykes]

This was meant to be a quick win... Does it even make sense for me to update this, with other improvements in flight?

[helderco]

This was meant to be a quick win... Does it even make sense for me to update this, with other improvements in flight?

I think so. Let’s see:

• cli: don't show inherited flags in function commands #7419
  • Inherited flags added a lot of noise and have been hidden for function commands (not dagger call --help)
• cli: list available functions when chain ends in an object #7421
  • Resolves the FIXME comment
  • Reduces some of the need for --help and completely replaces dagger function
  • Had to cut on the long description already because sync is no longer implicit in core types
• CLI: calling 'export' just prints 'true' #7131
  • Not done yet, but will remove the rest of that long description

Since we'll want to conventionalize on export --path PATH rather than -o PATH, I think it's ok to clear the whole Long description now so people don't get used to it. The value "Call a function, or a pipeline of functions, and print the result" is short enough to be in Short, without having Long too.

The update on the --output flag's description is an improvement too.

As for the examples, they're hardly helpful as they are. It would be more helpful to have a stable URL to add to the end of --help to learn more, but I say remove the examples now, and add that URL in a follow up when it’s available.