Shell Completions - Githubissues

I've just caught up on the last community standup and was interested to hear the direction for completions, and wanted to share how I'm solving this today.

First off, I love the idea of the automagic self-describing directives based completions today (dotnet-suggest), however as was mentioned this is slow (although very workable when AOTing). I abandoned this approach in the end mostly because:

implementation was very buggy, to the point it wouldn't work in many scenarios
shell support was lacking
Fish allows for a better experience than just "here is are the valid tokens you can use here", it can show them in a grid with descriptions, which again wasn't supported with the dotnet-suggest approach.

So what I do for my internal tool (can't share the code sorry) is have a separate file that has the grammar of the command line in, and using a tool (complgen) to produce the per-shell scripts. I have the outputs of these then embedded my tool, so I can say jaz completions fish (the tool is named jaz) and it will output the fish shell snipped. This plays well with eco-system tools like homebrew (example).

Here is what my usage grammar looks like:

jaz [<OPTION>]... [<HELP>];
jaz <COMMAND> [<HELP>];

<COMMAND> ::= info               "About jaz"
            | clear              "Remove credentials from your profile" [<CREDENTIALS-PROFILE-OPTION>]
            | doctor             "Perform checkup to diagnose any issues"
            | logout             "Logout of SSO sessions"
            | whoami             "Get the caller ID of the current session" [<PROFILE-OPTION>] [<SHOW-ROLE-ARN-OPTION>]
            | update-metadata    "Update the environment metadata"
            | list-profiles      "List session profiles"
            | generate-profiles  "Generate SSO profiles"
            ;

<OPTION> ::= --sso-session  "The AWS SSO session to use" <SSO-SESSION>
           | --account-id   "The AWS account ID to use" <ACCOUNT-ID>
           | --role         "The AWS role to use" <ROLE>
           | --region       "The AWS region to use" <REGION>
           | <PROFILE-OPTION>
           | --version      "Show version information"
           ;

<SHOW-ROLE-ARN-OPTION> ::= --show-role-arn "Show the role ARN";

<PROFILE-OPTION> ::= --profile "The AWS profile to use" <PROFILE>;
<CREDENTIALS-PROFILE-OPTION> ::= --profile "The AWS profile to use" <CREDENTIALS-PROFILE>;

<PROFILE> ::= {{{ jaz list-profiles --include-all }}};
<CREDENTIALS-PROFILE> ::= {{{ jaz list-profiles }}};

<HELP> ::= (-h | --help)  "Show help and usage information";

You can see this supports calling back into itself for completions (see <CREDENTIALS-PROFILE>), this is awesome because I get nice completions across all shells, and it's fast because it's static, but I get the dynamic behaviours when I want them.

I'm not suggesting that this exact tool/grammar be selected as the approach, but as a general pattern I think this is really powerful yet simple for developers.

dotnet / command-line-api

Shell Completions #2425