Uploaded image for project: 'Puppet'
  1. Puppet
  2. PUP-6507

Puppet help: Hide bad subcommands, and sort remainder by usefulness

    XMLWordPrintable

    Details

    • Type: Improvement
    • Status: Closed
    • Priority: Normal
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: PUP 6.0.0
    • Component/s: None
    • Labels:
      None
    • Template:
    • Team:
      Coremunity
    • Sprint:
      Platform Core KANBAN
    • Release Notes:
      Not Needed

      Description

      The CLI leads meeting recently discussed the current slate of built-in Puppet subcommands (all thirty of them), and came to the conclusion that some of them are useless and/or harmful.

      Deprecating and removing subcommands is a larger task, and improving the interfaces of useful-but-problematic ones is an even bigger one. But we identified two things we can do today to vastly improve the user experience. Namely:

      • puppet help's list of subcommands should omit the useless or confusing ones completely. This won't break the workflow of anyone who's actually using them, but will keep new users from hitting their heads on exposed nails or stepping into the insulation.
      • The list of remaining subcommands should be sorted into categories according to their usefulness, so users who haven't memorized everything can more easily stay on the rails.

      The useless commands

      The CLI leads team has broadly agreed that the following subcommands aren't good news. This list mostly focuses on the "indirector faces," but also includes some other stuff.

      • puppet file
      • puppet report
      • puppet resource_type
      • puppet status
      • puppet inspect
      • puppet plugin
      • puppet doc
      • puppet catalog
      • puppet ca
      • puppet certificate_request
      • puppet certificate_revocation_list
      • puppet key

      Categories of remaining commands

      Useful on a daily basis for most users

      • puppet agent
      • puppet apply
      • puppet cert
      • puppet resource
      • puppet module

      Occasionally useful, or frequently useful for a smaller subset of users

      • puppet config
      • puppet describe
      • puppet device
      • puppet epp
      • puppet facts
      • puppet filebucket
      • puppet help
      • puppet lookup
      • puppet man
      • puppet node
      • puppet parser

      Rarely useful

      • puppet certificate
      • puppet master

      Plugin-provided

      (We should have a section for PE-only or third-party subcommands.)

      ***Updated*****

      Here is a list of subcommands in puppet#master:

      Useful Subcommands Status
      apply keep
      agent keep
      config keep
      help keep
      lookup keep
      module keep
      resource keep
      Less Used Status What For?
      catalog keep download catalog
      device keep run puppet on devices
      epp keep interact with puppet's templating parser/render
      facts keep generate puppet facts
      filebucket keep interact with filebucket
      generate keep environment isolation
      parser keep validate catalogs
      script keep runs puppet code without a catalog
      Could Be Useful With Work Status What For?
      node ??? retrieve node classification
      plugin ??? force pluginsync
      report ??? upload report
      status ??? check server status
      Needs Work/Replacing Status What For?
      ca delete replace with `puppetserver ca`
      cert hide split into puppetserver ca and agent cli
      certificate delete  
      certificate_request delete  
      certificate_request_list delete  
      key delete  
      Documentation Related Status What For?
      describe keep list and describe types & providers
      doc keep generate reference documentation
      man hide another way to view help, duplicated by `man puppet.conf`

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              kris.bosland Kris Bosland
              Reporter:
              nick.fagerlund Nicholas Fagerlund
              Votes:
              0 Vote for this issue
              Watchers:
              6 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved:

                  Zendesk Support