PowerShell / PowerShell/DSC

dsc.exe options discoverability improvements

Open
#654 2 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Issue-Documentation
Dominant language
Rust
Stars
523
Forks
75
Avg merge
3d 16h
Merged PRs (30d)
24

Description

Summary of the new feature / enhancement

As a user of dsc commands, I want to be able to know all of the options available to me without having to recursively run help on the parent commands.

For instance, to use dsc config set, I have to inquire about the options for it and dsc config and dsc.

PS> dsc config set -h
Set the current configuration

Usage: dsc.exe config set [OPTIONS]

Options:
  -i, --input <INPUT>                  The input document as JSON or YAML to pass to the configuration or resource
  -f, --file <FILE>                    The path to a file used as input to the configuration or resource. Use '-' for the file to read from STDIN.
  -o, --output-format <OUTPUT_FORMAT>  The output format to use [possible values: json, pretty-json, yaml]
  -w, --what-if                        Run as a what-if operation instead of executing the configuration or resource
  -h, --help                           Print help

then

PS> dsc config -h
Apply a configuration document

Usage: dsc.exe config [OPTIONS] <COMMAND>

Commands:
  get     Retrieve the current configuration
  set     Set the current configuration
  test    Test the current configuration
  export  Export the current configuration
  help    Print this message or the help of the given subcommand(s)

Options:
  -p, --parameters <PARAMETERS>
          Parameters to pass to the configuration as JSON or YAML
  -f, --parameters-file <PARAMETERS_FILE>
          Parameters to pass to the configuration as a JSON or YAML file
  -r, --system-root <SYSTEM_ROOT>
          Specify the operating system root path if not targeting the current running OS
  -h, --help
          Print help

and

PS> dsc -h
Apply configuration or invoke specific DSC resources

Usage: dsc.exe [OPTIONS] <COMMAND>

Commands:
  completer  Generate a shell completion script
  config     Apply a configuration document
  resource   Invoke a specific DSC resource
  schema     Get the JSON schema for a DSC type
  help       Print this message or the help of the given subcommand(s)

Options:
  -l, --trace-level <TRACE_LEVEL>
          Trace level to use [possible values: error, warn, info, debug, trace]
  -t, --trace-format <TRACE_FORMAT>
          Trace format to use [possible values: default, plaintext, json]
  -p, --progress-format <PROGRESS_FORMAT>
          Progress format to use [possible values: default, json]
  -h, --help
          Print help
  -V, --version
          Print version
Proposed technical implementation details (optional)

At a minimum, I would be nice for help to at least mention that the parent commands have their own options. And it would subtly inform you about the requirement for those options to be placed between the parent and child commands. Maybe like:

PS> dsc config set -h
Set the current configuration

Usage: dsc.exe [dsc.exe OPTIONS] config [config OPTIONS] set [OPTIONS]

Options:
  -i, --input <INPUT>                  The input document as JSON or YAML to pass to the configuration or resource
  -f, --file <FILE>                    The path to a file used as input to the configuration or resource. Use '-' for the file to read from STDIN.
  -o, --output-format <OUTPUT_FORMAT>  The output format to use [possible values: json, pretty-json, yaml]
  -w, --what-if                        Run as a what-if operation instead of executing the configuration or resource
  -h, --help                           Print help

For config command options, run `dsc.exe config --help`.
For dsc.exe options, run `dsc.exe --help`.

But to prevent needing to run those other commands, the "For ..., run ..." would need to be replaced with blocks of the options. This might be considered too much output, so it could be contained to the 2-3 top options with a "run for more" line. My example output already removes some of the options (like help) that don't need to be repeated/inherited.

PS> dsc config set -h
Set the current configuration

Usage: dsc.exe [dsc.exe OPTIONS] config [config OPTIONS] set [OPTIONS]

Options:
  -i, --input <INPUT>                  The input document as JSON or YAML to pass to the configuration or resource
  -f, --file <FILE>                    The path to a file used as input to the configuration or resource. Use '-' for the file to read from STDIN.
  -o, --output-format <OUTPUT_FORMAT>  The output format to use [possible values: json, pretty-json, yaml]
  -w, --what-if                        Run as a what-if operation instead of executing the configuration or resource
  -h, --help                           Print help

config Options:
  -p, --parameters <PARAMETERS>
          Parameters to pass to the configuration as JSON or YAML
  -f, --parameters-file <PARAMETERS_FILE>
          Parameters to pass to the configuration as a JSON or YAML file
  -r, --system-root <SYSTEM_ROOT>
          Specify the operating system root path if not targeting the current running OS

dsc.exe Options:
  -l, --trace-level <TRACE_LEVEL>
          Trace level to use [possible values: error, warn, info, debug, trace]
  -t, --trace-format <TRACE_FORMAT>
          Trace format to use [possible values: default, plaintext, json]
  -p, --progress-format <PROGRESS_FORMAT>
          Progress format to use [possible values: default, json]

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 by comparing the help output for dsc -h, dsc config -h, and dsc config set -h shown in the issue. Define the desired inherited-options presentation and command placement, then verify that nested help exposes the relevant parent options without unnecessary repetition.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
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.