cli: public commands API

internals/cli/cli.go

@@ -80,9 +80,9 @@ var commands []*cmdInfo
 // debugCommands holds information about all debug commands.
 var debugCommands []*cmdInfo
 
-// addCommand replaces parser.addCommand() in a way that is compatible with
+// AddCommand replaces parser.addCommand() in a way that is compatible with
 // re-constructing a pristine parser.
-func addCommand(name, shortHelp, longHelp string, builder func() flags.Commander, optDescs map[string]string, argDescs []argDesc) *cmdInfo {
+func AddCommand(name, shortHelp, longHelp string, builder func() flags.Commander, optDescs map[string]string, argDescs []argDesc) *cmdInfo {
 	info := &cmdInfo{
 		name:      name,
 		shortHelp: shortHelp,

internals/cli/cmd_add.go

@@ -67,5 +67,5 @@ func (cmd *cmdAdd) Execute(args []string) error {
 }
 
 func init() {
-	addCommand("add", shortAddHelp, longAddHelp, func() flags.Commander { return &cmdAdd{} }, addDescs, nil)
+	AddCommand("add", shortAddHelp, longAddHelp, func() flags.Commander { return &cmdAdd{} }, addDescs, nil)
 }

internals/cli/cmd_autostart.go

@@ -31,7 +31,7 @@ type cmdAutoStart struct {
 }
 
 func init() {
-	addCommand("autostart", shortAutoStartHelp, longAutoStartHelp, func() flags.Commander { return &cmdAutoStart{} }, waitDescs, nil)
+	AddCommand("autostart", shortAutoStartHelp, longAutoStartHelp, func() flags.Commander { return &cmdAutoStart{} }, waitDescs, nil)
 }
 
 func (cmd cmdAutoStart) Execute(args []string) error {

internals/cli/cmd_changes.go

@@ -48,9 +48,9 @@ type cmdTasks struct {
 }
 
 func init() {
-	addCommand("changes", shortChangesHelp, longChangesHelp,
+	AddCommand("changes", shortChangesHelp, longChangesHelp,
 		func() flags.Commander { return &cmdChanges{} }, timeDescs, nil)
-	addCommand("tasks", shortTasksHelp, longTasksHelp,
+	AddCommand("tasks", shortTasksHelp, longTasksHelp,
 		func() flags.Commander { return &cmdTasks{} },
 		merge(changeIDMixinOptDesc, timeDescs),
 		changeIDMixinArgDesc)

internals/cli/cmd_checks.go

@@ -79,5 +79,5 @@ func (cmd *cmdChecks) Execute(args []string) error {
 }
 
 func init() {
-	addCommand("checks", shortChecksHelp, longChecksHelp, func() flags.Commander { return &cmdChecks{} }, checksDescs, nil)
+	AddCommand("checks", shortChecksHelp, longChecksHelp, func() flags.Commander { return &cmdChecks{} }, checksDescs, nil)
 }

internals/cli/cmd_enter.go

@@ -58,7 +58,7 @@ func init() {
 	for k, v := range sharedRunEnterOptsHelp {
 		optsHelp[k] = v
 	}
-	cmdInfo := addCommand("enter", shortEnterHelp, longEnterHelp, func() flags.Commander { return &cmdEnter{} }, optsHelp, nil)
+	cmdInfo := AddCommand("enter", shortEnterHelp, longEnterHelp, func() flags.Commander { return &cmdEnter{} }, optsHelp, nil)
 	cmdInfo.extra = func(cmd *flags.Command) {
 		cmd.PassAfterNonOption = true
 	}

internals/cli/cmd_exec.go

@@ -264,7 +264,7 @@ func execControlHandler(process *client.ExecProcess, terminal bool, stop <-chan
 }
 
 func init() {
-	info := addCommand("exec", shortExecHelp, longExecHelp, func() flags.Commander { return &cmdExec{} }, execDescs, nil)
+	info := AddCommand("exec", shortExecHelp, longExecHelp, func() flags.Commander { return &cmdExec{} }, execDescs, nil)
 	info.extra = func(cmd *flags.Command) {
 		cmd.PassAfterNonOption = true
 	}

internals/cli/cmd_help.go

@@ -79,7 +79,7 @@ type cmdHelp struct {
 }
 
 func init() {
-	addCommand("help", shortHelpHelp, longHelpHelp, func() flags.Commander { return &cmdHelp{} },
+	AddCommand("help", shortHelpHelp, longHelpHelp, func() flags.Commander { return &cmdHelp{} },
 		map[string]string{
 			"all": "Show a short summary of all commands",
 			"man": "Generate the manpage",
@@ -158,14 +158,14 @@ func (cmd cmdHelp) Execute(args []string) error {
 	return &flags.Error{Type: flags.ErrCommandRequired}
 }
 
-type helpCategory struct {
+type HelpCategory struct {
 	Label       string
 	Description string
 	Commands    []string
 }
 
 // helpCategories helps us by grouping commands
-var helpCategories = []helpCategory{{
+var helpCategories = []HelpCategory{{
 	Label:       "Run",
 	Description: "run pebble",
 	Commands:    []string{"run", "help", "version"},
@@ -191,6 +191,11 @@ var helpCategories = []helpCategory{{
 	Commands:    []string{"warnings", "okay"},
 }}
 
+// AddHelpCategory appends an existing help category to the Pebble help manual.
+func AddHelpCategory(category HelpCategory) {
+	helpCategories = append(helpCategories, category)
+}
+
 var (
 	longPebbleDescription = strings.TrimSpace(`
 Pebble lets you control services and perform management actions on

internals/cli/cmd_help_test.go

@@ -109,3 +109,20 @@ func (s *PebbleSuite) TestCommandWithHelpOption(c *C) {
 	c.Check(s.Stdout(), Matches, "(?s)Usage.*pebble help.*The help command.*help command options.*")
 	c.Check(s.Stderr(), Equals, "")
 }
+
+func (s *PebbleSuite) TestAddHelpCategory(c *C) {
+	restore := fakeArgs("pebble")
+	defer restore()
+
+	cli.AddHelpCategory(cli.HelpCategory{
+		Label:       "Test category",
+		Description: "Test description",
+		Commands:    []string{"run", "logs"},
+	})
+
+	err := cli.RunMain()
+	c.Assert(err, Equals, nil)
+
+	c.Check(s.Stdout(), Matches, "(?s).*Test category: run, logs\n.*")
+	c.Check(s.Stderr(), Equals, "")
+}

internals/cli/cmd_logs.go

@@ -121,5 +121,5 @@ func notifyContext(parent context.Context, signals ...os.Signal) context.Context
 }
 
 func init() {
-	addCommand("logs", shortLogsHelp, longLogsHelp, func() flags.Commander { return &cmdLogs{} }, logsDescs, nil)
+	AddCommand("logs", shortLogsHelp, longLogsHelp, func() flags.Commander { return &cmdLogs{} }, logsDescs, nil)
 }

internals/cli/cmd_ls.go

@@ -103,5 +103,5 @@ func parseGlob(path string) (parsedPath, parsedPattern string, err error) {
 }
 
 func init() {
-	addCommand("ls", shortLsHelp, longLsHelp, func() flags.Commander { return &cmdLs{} }, merge(lsDescs, timeDescs), nil)
+	AddCommand("ls", shortLsHelp, longLsHelp, func() flags.Commander { return &cmdLs{} }, merge(lsDescs, timeDescs), nil)
 }

internals/cli/cmd_mkdir.go

@@ -79,5 +79,5 @@ func (cmd *cmdMkdir) Execute(args []string) error {
 }
 
 func init() {
-	addCommand("mkdir", shortMkdirHelp, longMkdirHelp, func() flags.Commander { return &cmdMkdir{} }, mkdirDescs, nil)
+	AddCommand("mkdir", shortMkdirHelp, longMkdirHelp, func() flags.Commander { return &cmdMkdir{} }, mkdirDescs, nil)
 }

internals/cli/cmd_plan.go

@@ -43,5 +43,5 @@ func (cmd *cmdPlan) Execute(args []string) error {
 }
 
 func init() {
-	addCommand("plan", shortPlanHelp, longPlanHelp, func() flags.Commander { return &cmdPlan{} }, nil, nil)
+	AddCommand("plan", shortPlanHelp, longPlanHelp, func() flags.Commander { return &cmdPlan{} }, nil, nil)
 }

internals/cli/cmd_replan.go

@@ -32,7 +32,7 @@ type cmdReplan struct {
 }
 
 func init() {
-	addCommand("replan", shortReplanHelp, longReplanHelp, func() flags.Commander { return &cmdReplan{} }, waitDescs, nil)
+	AddCommand("replan", shortReplanHelp, longReplanHelp, func() flags.Commander { return &cmdReplan{} }, waitDescs, nil)
 }
 
 func (cmd cmdReplan) Execute(args []string) error {

internals/cli/cmd_restart.go

@@ -33,7 +33,7 @@ type cmdRestart struct {
 }
 
 func init() {
-	addCommand("restart", shortRestartHelp, longRestartHelp, func() flags.Commander { return &cmdRestart{} }, waitDescs, nil)
+	AddCommand("restart", shortRestartHelp, longRestartHelp, func() flags.Commander { return &cmdRestart{} }, waitDescs, nil)
 }
 
 func (cmd cmdRestart) Execute(args []string) error {

internals/cli/cmd_rm.go

@@ -51,5 +51,5 @@ func (cmd *cmdRm) Execute(args []string) error {
 }
 
 func init() {
-	addCommand("rm", shortRmHelp, longRmHelp, func() flags.Commander { return &cmdRm{} }, rmDescs, nil)
+	AddCommand("rm", shortRmHelp, longRmHelp, func() flags.Commander { return &cmdRm{} }, rmDescs, nil)
 }

internals/cli/cmd_run.go

@@ -65,7 +65,7 @@ type cmdRun struct {
 }
 
 func init() {
-	addCommand("run", shortRunHelp, longRunHelp, func() flags.Commander { return &cmdRun{} },
+	AddCommand("run", shortRunHelp, longRunHelp, func() flags.Commander { return &cmdRun{} },
 		sharedRunEnterOptsHelp, nil)
 }
 

internals/cli/cmd_services.go

@@ -73,7 +73,7 @@ func (cmd *cmdServices) Execute(args []string) error {
 }
 
 func init() {
-	addCommand("services", shortServicesHelp, longServicesHelp,
+	AddCommand("services", shortServicesHelp, longServicesHelp,
 		func() flags.Commander { return &cmdServices{} },
 		timeDescs, nil)
 }

internals/cli/cmd_signal.go

@@ -58,5 +58,5 @@ func (cmd *cmdSignal) Execute(args []string) error {
 }
 
 func init() {
-	addCommand("signal", shortSignalHelp, longSignalHelp, func() flags.Commander { return &cmdSignal{} }, nil, nil)
+	AddCommand("signal", shortSignalHelp, longSignalHelp, func() flags.Commander { return &cmdSignal{} }, nil, nil)
 }

internals/cli/cmd_start.go

@@ -34,7 +34,7 @@ type cmdStart struct {
 }
 
 func init() {
-	addCommand("start", shortStartHelp, longStartHelp, func() flags.Commander { return &cmdStart{} }, waitDescs, nil)
+	AddCommand("start", shortStartHelp, longStartHelp, func() flags.Commander { return &cmdStart{} }, waitDescs, nil)
 }
 
 func (cmd cmdStart) Execute(args []string) error {

internals/cli/cmd_stop.go

@@ -34,7 +34,7 @@ type cmdStop struct {
 }
 
 func init() {
-	addCommand("stop", shortStopHelp, longStopHelp, func() flags.Commander { return &cmdStop{} }, waitDescs, nil)
+	AddCommand("stop", shortStopHelp, longStopHelp, func() flags.Commander { return &cmdStop{} }, waitDescs, nil)
 }
 
 func (cmd cmdStop) Execute(args []string) error {

internals/cli/cmd_version.go

@@ -38,7 +38,7 @@ var versionDescs = map[string]string{
 }
 
 func init() {
-	addCommand("version", shortVersionHelp, longVersionHelp, func() flags.Commander { return &cmdVersion{} }, versionDescs, nil)
+	AddCommand("version", shortVersionHelp, longVersionHelp, func() flags.Commander { return &cmdVersion{} }, versionDescs, nil)
 }
 
 func (cmd cmdVersion) Execute(args []string) error {

internals/cli/cmd_warnings.go

@@ -61,11 +61,11 @@ sufficient time has passed.
 `
 
 func init() {
-	addCommand("warnings", shortWarningsHelp, longWarningsHelp, func() flags.Commander { return &cmdWarnings{} }, merge(timeDescs, unicodeDescs, map[string]string{
+	AddCommand("warnings", shortWarningsHelp, longWarningsHelp, func() flags.Commander { return &cmdWarnings{} }, merge(timeDescs, unicodeDescs, map[string]string{
 		"all":     "Show all warnings",
 		"verbose": "Show more information",
 	}), nil)
-	addCommand("okay", shortOkayHelp, longOkayHelp, func() flags.Commander { return &cmdOkay{} }, nil, nil)
+	AddCommand("okay", shortOkayHelp, longOkayHelp, func() flags.Commander { return &cmdOkay{} }, nil, nil)
 }
 
 func (cmd *cmdWarnings) Execute(args []string) error {