Skip to content

Improve knife --help with topic-based command groups - #195

Open
Chef-Pradyumn wants to merge 3 commits into
chef:mainfrom
Chef-Pradyumn:main
Open

Improve knife --help with topic-based command groups#195
Chef-Pradyumn wants to merge 3 commits into
chef:mainfrom
Chef-Pradyumn:main

Conversation

@Chef-Pradyumn

@Chef-Pradyumn Chef-Pradyumn commented Aug 10, 2026

Copy link
Copy Markdown
Contributor

Summary
This PR improves the Knife help command experience by adding topic-based help navigation (access to the full command catalog is preserved under an '-all' flag.
The current default help output is long and difficult to scan quickly. The presence of plugin commands and other commands linked to very specific use-cases overwhelm the terminal and force users to scroll to reach the commands that they need help with. This change makes it easier for users to discover relevant commands fast, then drill into a focused command group when needed.

Changes

  • Added a topic-based help index in default --help
  • Added focused help by topic
  • Kept full help available through --help -all
  • Added clear topic guidance text at the bottom of topic outputs
  • Added unknown-topic handling with a valid topics list
  • Supported topics: all, infra, content, security, remote, cloud, repo, ops, plugins, search

Output
Below is the output for knife --help

Patents: https://www.chef.io/patents

Usage: knife sub-command (options)
    -s, --server-url URL             Chef Infra Server URL.
        --chef-zero-host HOST        Host to start Chef Infra Zero on.
        --chef-zero-port PORT        Port (or port range) to start Chef Infra Zero on. Port ranges like 1000,1010 or 8889-9999 will try all given ports until one works.
    -k, --key KEY                    Chef Infra Server API client key.
        --[no-]color                 Use colored output, defaults to enabled.
    -c, --config CONFIG              The configuration file to use.
        --config-option OPTION=VALUE Override a single configuration option.
        --defaults                   Accept default values for all questions.
    -d, --disable-editing            Do not open EDITOR, just accept the data as is.
    -e, --editor EDITOR              Set the editor to use for interactive commands.
    -E, --environment ENVIRONMENT    Set the Chef Infra Client environment (except for in searches, where this will be flagrantly ignored).
        --[no-]fips                  Enable FIPS mode.
    -F, --format FORMAT              Which format to use for output. (valid options: 'summary', 'text', 'json', 'yaml', or 'pp')
        --[no-]listen                Whether a local mode (-z) server binds to a port.
    -z, --local-mode                 Point knife commands at local repository instead of Chef Infra Server.
    -u, --user USER                  Chef Infra Server API client username.
        --print-after                Show the data after a destructive operation.
        --profile PROFILE            The credentials profile to select.
    -V, --verbose                    More verbose output. Use twice (-VV) for additional verbosity and three times (-VVV) for maximum verbosity.
    -v, --version                    Show knife version.
    -y, --yes                        Say yes to all prompts for confirmation.
    -h, --help                       Show this help message.

For help on specific knife commands, see the command groups below.
  knife --help -all      (full command list)
  knife --help -infra    (node, role, environment, tag)
  knife --help -content  (cookbook, data bag, recipe, supermarket, yaml)
  knife --help -security (acl, group, user, client, vault, ssl)
  knife --help -remote   (bootstrap, ssh, winrm, wsman, windows)
  knife --help -cloud    (ec2, google)
  knife --help -repo     (path-based, raw, serve)
  knife --help -ops      (config, configure, rehash, license, exec, status)
  knife --help -plugins  (installed plugin command families)
  knife --help -search   (search)

Below is the output for knife --help -infra for example:

Patents: https://www.chef.io/patents

Available infra subcommands: (for details, knife SUB-COMMAND --help)

** ENVIRONMENT COMMANDS **
knife environment compare [ENVIRONMENT..] (options)
knife environment create ENVIRONMENT (options)
knife environment delete ENVIRONMENT (options)
knife environment edit ENVIRONMENT (options)
knife environment from file FILE [FILE..] (options)
knife environment list (options)
knife environment show ENVIRONMENT (options)

** NODE COMMANDS **
knife node bulk delete REGEX (options)
knife node create NODE (options)
knife node delete [NODE [NODE]] (options)
knife node edit NODE (options)
knife node environment set NODE ENVIRONMENT
knife node from file FILE (options)
knife node list (options)
knife node policy set NODE POLICY_GROUP POLICY_NAME (options)
knife node run_list add [NODE] [ENTRY [ENTRY]] (options)
knife node run_list remove [NODE] [ENTRY [ENTRY]] (options)
knife node run_list set NODE ENTRIES (options)
knife node show NODE (options)

** ROLE COMMANDS **
knife role bulk delete REGEX (options)
knife role create ROLE (options)
knife role delete ROLE (options)
knife role edit ROLE (options)
knife role env_run_list add [ROLE] [ENVIRONMENT] [ENTRY [ENTRY]] (options)
knife role env_run_list clear [ROLE] [ENVIRONMENT] (options)
knife role env_run_list remove [ROLE] [ENVIRONMENT] [ENTRIES] (options)
knife role env_run_list replace [ROLE] [ENVIRONMENT] [OLD_ENTRY] [NEW_ENTRY] (options)
knife role env_run_list set [ROLE] [ENVIRONMENT] [ENTRIES] (options)
knife role from file FILE [FILE..] (options)
knife role list (options)
knife role run_list add [ROLE] [ENTRY [ENTRY]] (options)
knife role run_list clear [ROLE] (options)
knife role run_list remove [ROLE] [ENTRY] (options)
knife role run_list replace [ROLE] [OLD_ENTRY] [NEW_ENTRY] (options)
knife role run_list set [ROLE] [ENTRIES] (options)
knife role show ROLE (options)

** TAG COMMANDS **
knife tag create NODE TAG ...
knife tag delete NODE TAG ...
knife tag list NODE

For help on specific knife commands, see the command groups below.
knife --help -all      (full command list)
knife --help -infra    (node, role, environment, tag)
knife --help -content  (cookbook, data bag, recipe, supermarket, yaml)
knife --help -security (acl, group, user, client, vault, ssl)
knife --help -remote   (bootstrap, ssh, winrm, wsman, windows)
knife --help -cloud    (ec2, google)
knife --help -repo     (path-based, raw, serve)
knife --help -ops      (config, configure, rehash, license, exec, status)
knife --help -plugins  (installed plugin command families)
knife --help -search   (search)

Signed-off-by: Chef-Pradyumn <264104377+Chef-Pradyumn@users.noreply.github.com>
@Chef-Pradyumn
Chef-Pradyumn requested review from a team and jaymzh as code owners August 10, 2026 16:32
Signed-off-by: Chef-Pradyumn <264104377+Chef-Pradyumn@users.noreply.github.com>
Signed-off-by: Chef-Pradyumn <264104377+Chef-Pradyumn@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant