oclif / oclif/core

Allow to define summary for flag options.

Open
#756 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

--help output unlikely waiting for interest
Dominant language
TypeScript
Stars
316
Forks
98
Avg merge
12h 32m
Merged PRs (30d)
2

Description

Is your feature request related to a problem? Please describe.
If you have a command with a flag that accepts a set of options like this:
https://github.com/salesforcecli/plugin-deploy-retrieve/blob/cf94d9b10d1256e9cad96f75df3452094b9d4865/src/commands/project/deploy/start.ts#L121

you get those in zsh/powershell completion but plugin-autocomplete can't show any summary/description about them:

Screenshot 2023-08-04 at 14 33 58

Describe the solution you'd like
Allow to define a summary for each flag option so that plugin-autocomplete can set it in completion functions (natively supported):
Screenshot 2023-08-04 at 14 47 48

Describe alternatives you've considered
make flag.options an object containing one 1 object per option

'test-level': testLevelFlag({
      description: messages.getMessage('flags.test-level.description'),
      summary: messages.getMessage('flags.test-level.summary'),
      options: {
        TestLevel.NoTestRun: {
          summary: 'No tests are run'
        }
      },
      helpGroup: testFlags,
    }),

Additional context
We could also update the help logic so that it renders these summaries, in sf we just add all of them in the flag summary:
https://github.com/salesforcecli/plugin-deploy-retrieve/blob/cf94d9b10d1256e9cad96f75df3452094b9d4865/messages/deploy.metadata.md#flagstest-leveldescription

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the flag option example in src/commands/project/deploy/start.ts and trace how flag options are consumed by plugin-autocomplete for zsh and PowerShell completion. Compare the proposed options object shape with the existing flag and help logic; done means each option can provide a summary that appears in completion functions, with help rendering considered separately.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
cli
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.