introduce debug commands (#4533)

adds the primary `debug` command to the cli as
a hidden command option.  Also includes the scaffold for
a `metadata-files` command that could be used to print
out the metadata files in the backup.

---

#### Does this PR need a docs update or release note?

- [x] ⛔ No

#### Type of change

- [x] 🌻 Feature

#### Test Plan

- [x] ⚡ Unit test

src/cli/debug/debug.go

@@ -0,0 +1,105 @@
+package debug
+
+import (
+	"context"
+
+	"github.com/spf13/cobra"
+
+	"github.com/alcionai/corso/src/cli/flags"
+	. "github.com/alcionai/corso/src/cli/print"
+	"github.com/alcionai/corso/src/cli/utils"
+	"github.com/alcionai/corso/src/pkg/selectors"
+)
+
+var subCommandFuncs = []func() *cobra.Command{
+	metadataFilesCmd,
+}
+
+var debugCommands = []func(cmd *cobra.Command) *cobra.Command{
+	addOneDriveCommands,
+	addSharePointCommands,
+	addGroupsCommands,
+	addExchangeCommands,
+}
+
+// AddCommands attaches all `corso debug * *` commands to the parent.
+func AddCommands(cmd *cobra.Command) {
+	debugC, _ := utils.AddCommand(cmd, debugCmd(), utils.MarkDebugCommand())
+
+	for _, sc := range subCommandFuncs {
+		subCommand := sc()
+		utils.AddCommand(debugC, subCommand, utils.MarkDebugCommand())
+
+		for _, addTo := range debugCommands {
+			addTo(subCommand)
+			flags.AddAllProviderFlags(subCommand)
+			flags.AddAllStorageFlags(subCommand)
+		}
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Commands
+// ---------------------------------------------------------------------------
+
+const debugCommand = "debug"
+
+// The debug category of commands.
+// `corso debug [<subcommand>] [<flag>...]`
+func debugCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:   debugCommand,
+		Short: "debugging & troubleshooting utilities",
+		Long:  `debug the data stored in corso.`,
+		RunE:  handledebugCmd,
+		Args:  cobra.NoArgs,
+	}
+}
+
+// Handler for flat calls to `corso debug`.
+// Produces the same output as `corso debug --help`.
+func handledebugCmd(cmd *cobra.Command, args []string) error {
+	return cmd.Help()
+}
+
+// The debug metadataFiles subcommand.
+// `corso debug metadata-files <service> [<flag>...]`
+var metadataFilesCommand = "metadata-files"
+
+func metadataFilesCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:   metadataFilesCommand,
+		Short: "display all the metadata file contents stored by the service",
+		RunE:  handleMetadataFilesCmd,
+		Args:  cobra.NoArgs,
+	}
+}
+
+// Handler for calls to `corso debug metadata-files`.
+// Produces the same output as `corso debug metadata-files --help`.
+func handleMetadataFilesCmd(cmd *cobra.Command, args []string) error {
+	return cmd.Help()
+}
+
+// ---------------------------------------------------------------------------
+// runners
+// ---------------------------------------------------------------------------
+
+func runMetadataFiles(
+	ctx context.Context,
+	cmd *cobra.Command,
+	args []string,
+	sel selectors.Selector,
+	debugID, serviceName string,
+) error {
+	r, _, err := utils.GetAccountAndConnect(ctx, cmd, sel.PathService())
+	if err != nil {
+		return Only(ctx, err)
+	}
+
+	defer utils.CloseRepo(ctx, r)
+
+	// TODO: read and print out all metadata files in the debug
+
+	return nil
+}

src/cli/debug/exchange.go

@@ -0,0 +1,71 @@
+package debug
+
+import (
+	"github.com/spf13/cobra"
+	"github.com/spf13/pflag"
+
+	"github.com/alcionai/corso/src/cli/flags"
+	"github.com/alcionai/corso/src/cli/utils"
+	"github.com/alcionai/corso/src/pkg/selectors"
+)
+
+// called by debug.go to map subcommands to provider-specific handling.
+func addExchangeCommands(cmd *cobra.Command) *cobra.Command {
+	var (
+		c  *cobra.Command
+		fs *pflag.FlagSet
+	)
+
+	switch cmd.Use {
+	case metadataFilesCommand:
+		c, fs = utils.AddCommand(cmd, exchangeMetadataFilesCmd(), utils.MarkDebugCommand())
+
+		c.Use = c.Use + " " + exchangeServiceCommandUseSuffix
+
+		// Flags addition ordering should follow the order we want them to appear in help and docs:
+		// More generic (ex: --user) and more frequently used flags take precedence.
+		fs.SortFlags = false
+
+		flags.AddBackupIDFlag(c, true)
+	}
+
+	return c
+}
+
+const (
+	exchangeServiceCommand          = "exchange"
+	exchangeServiceCommandUseSuffix = "--backup <backupId>"
+
+	//nolint:lll
+	exchangeServiceCommandDebugExamples = `# Display file contents for backup 1234abcd
+corso debug metadata-files exchange --backup 1234abcd-12ab-cd34-56de-1234abcd`
+)
+
+// `corso debug metadata-files exchange [<flag>...] <destination>`
+func exchangeMetadataFilesCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:     exchangeServiceCommand,
+		Short:   "Display exchange metadata file content",
+		RunE:    metadataFilesExchangeCmd,
+		Args:    cobra.NoArgs,
+		Example: exchangeServiceCommandDebugExamples,
+	}
+}
+
+func metadataFilesExchangeCmd(cmd *cobra.Command, args []string) error {
+	ctx := cmd.Context()
+
+	if utils.HasNoFlagsAndShownHelp(cmd) {
+		return nil
+	}
+
+	// opts := utils.MakeExchangeOpts(cmd)
+
+	if flags.RunModeFV == flags.RunModeFlagTest {
+		return nil
+	}
+
+	sel := selectors.NewExchangeBackup([]string{"unused-placeholder"})
+
+	return runMetadataFiles(ctx, cmd, args, sel.Selector, flags.BackupIDFV, "Exchange")
+}

src/cli/debug/exchange_test.go

@@ -0,0 +1,77 @@
+package debug
+
+import (
+	"testing"
+
+	"github.com/spf13/cobra"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/suite"
+
+	"github.com/alcionai/corso/src/cli/flags"
+	flagsTD "github.com/alcionai/corso/src/cli/flags/testdata"
+	cliTD "github.com/alcionai/corso/src/cli/testdata"
+	"github.com/alcionai/corso/src/internal/tester"
+)
+
+type ExchangeUnitSuite struct {
+	tester.Suite
+}
+
+func TestExchangeUnitSuite(t *testing.T) {
+	suite.Run(t, &ExchangeUnitSuite{Suite: tester.NewUnitSuite(t)})
+}
+
+func (suite *ExchangeUnitSuite) TestExchangeCommands() {
+	expectUse := exchangeServiceCommand + " " + exchangeServiceCommandUseSuffix
+
+	table := []struct {
+		name        string
+		use         string
+		expectUse   string
+		expectShort string
+		expectRunE  func(*cobra.Command, []string) error
+	}{
+		{
+			name:        "metdata-files exchange",
+			use:         metadataFilesCommand,
+			expectUse:   expectUse,
+			expectShort: exchangeMetadataFilesCmd().Short,
+			expectRunE:  metadataFilesExchangeCmd,
+		},
+	}
+	for _, test := range table {
+		suite.Run(test.name, func() {
+			t := suite.T()
+			parent := &cobra.Command{Use: metadataFilesCommand}
+
+			cmd := cliTD.SetUpCmdHasFlags(
+				t,
+				parent,
+				addExchangeCommands,
+				[]cliTD.UseCobraCommandFn{
+					flags.AddAllProviderFlags,
+					flags.AddAllStorageFlags,
+				},
+				flagsTD.WithFlags(
+					exchangeServiceCommand,
+					[]string{
+						"--" + flags.RunModeFN, flags.RunModeFlagTest,
+						"--" + flags.BackupFN, flagsTD.BackupInput,
+					},
+					flagsTD.PreparedProviderFlags(),
+					flagsTD.PreparedStorageFlags()))
+
+			cliTD.CheckCmdChild(
+				t,
+				parent,
+				3,
+				test.expectUse,
+				test.expectShort,
+				test.expectRunE)
+
+			assert.Equal(t, flagsTD.BackupInput, flags.BackupIDFV)
+			flagsTD.AssertProviderFlags(t, cmd)
+			flagsTD.AssertStorageFlags(t, cmd)
+		})
+	}
+}

src/cli/debug/groups.go

@@ -0,0 +1,72 @@
+package debug
+
+import (
+	"github.com/spf13/cobra"
+	"github.com/spf13/pflag"
+
+	"github.com/alcionai/corso/src/cli/flags"
+	"github.com/alcionai/corso/src/cli/utils"
+	"github.com/alcionai/corso/src/pkg/selectors"
+)
+
+// called by debug.go to map subcommands to provider-specific handling.
+func addGroupsCommands(cmd *cobra.Command) *cobra.Command {
+	var (
+		c  *cobra.Command
+		fs *pflag.FlagSet
+	)
+
+	switch cmd.Use {
+	case metadataFilesCommand:
+		c, fs = utils.AddCommand(cmd, groupsMetadataFilesCmd(), utils.MarkDebugCommand())
+
+		c.Use = c.Use + " " + groupsServiceCommandUseSuffix
+
+		// Flags addition ordering should follow the order we want them to appear in help and docs:
+		// More generic (ex: --user) and more frequently used flags take precedence.
+		fs.SortFlags = false
+
+		flags.AddBackupIDFlag(c, true)
+	}
+
+	return c
+}
+
+// TODO: correct examples
+const (
+	groupsServiceCommand          = "groups"
+	groupsServiceCommandUseSuffix = "--backup <backupId>"
+
+	//nolint:lll
+	groupsServiceCommandDebugExamples = `# Display file contents for backup 1234abcd
+	corso debug metadata-files groups --backup 1234abcd-12ab-cd34-56de-1234abcd`
+)
+
+// `corso debug metadata-files groups [<flag>...] <destination>`
+func groupsMetadataFilesCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:     groupsServiceCommand,
+		Short:   "Display groups metadata file content",
+		RunE:    metadataFilesGroupsCmd,
+		Args:    cobra.NoArgs,
+		Example: groupsServiceCommandDebugExamples,
+	}
+}
+
+func metadataFilesGroupsCmd(cmd *cobra.Command, args []string) error {
+	ctx := cmd.Context()
+
+	if utils.HasNoFlagsAndShownHelp(cmd) {
+		return nil
+	}
+
+	// opts := utils.MakeGroupsOpts(cmd)
+
+	if flags.RunModeFV == flags.RunModeFlagTest {
+		return nil
+	}
+
+	sel := selectors.NewGroupsBackup([]string{"unused-placeholder"})
+
+	return runMetadataFiles(ctx, cmd, args, sel.Selector, flags.BackupIDFV, "Groups")
+}

src/cli/debug/groups_test.go

@@ -0,0 +1,76 @@
+package debug
+
+import (
+	"testing"
+
+	"github.com/spf13/cobra"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/suite"
+
+	"github.com/alcionai/corso/src/cli/flags"
+	flagsTD "github.com/alcionai/corso/src/cli/flags/testdata"
+	cliTD "github.com/alcionai/corso/src/cli/testdata"
+	"github.com/alcionai/corso/src/internal/tester"
+)
+
+type GroupsUnitSuite struct {
+	tester.Suite
+}
+
+func TestGroupsUnitSuite(t *testing.T) {
+	suite.Run(t, &GroupsUnitSuite{Suite: tester.NewUnitSuite(t)})
+}
+
+func (suite *GroupsUnitSuite) TestAddGroupsCommands() {
+	expectUse := groupsServiceCommand + " " + groupsServiceCommandUseSuffix
+
+	table := []struct {
+		name        string
+		use         string
+		expectUse   string
+		expectShort string
+		expectRunE  func(*cobra.Command, []string) error
+	}{
+		{
+			name:        "metdata-files groups",
+			use:         metadataFilesCommand,
+			expectUse:   expectUse,
+			expectShort: groupsMetadataFilesCmd().Short,
+			expectRunE:  metadataFilesGroupsCmd,
+		},
+	}
+	for _, test := range table {
+		suite.Run(test.name, func() {
+			t := suite.T()
+			parent := &cobra.Command{Use: metadataFilesCommand}
+
+			cmd := cliTD.SetUpCmdHasFlags(
+				t,
+				parent,
+				addGroupsCommands,
+				[]cliTD.UseCobraCommandFn{
+					flags.AddAllProviderFlags,
+					flags.AddAllStorageFlags,
+				},
+				flagsTD.WithFlags(
+					groupsServiceCommand,
+					[]string{
+						"--" + flags.RunModeFN, flags.RunModeFlagTest,
+						"--" + flags.BackupFN, flagsTD.BackupInput,
+					},
+					flagsTD.PreparedProviderFlags(),
+					flagsTD.PreparedStorageFlags()))
+
+			cliTD.CheckCmdChild(
+				t,
+				parent,
+				3,
+				test.expectUse,
+				test.expectShort,
+				test.expectRunE)
+
+			assert.Equal(t, flagsTD.BackupInput, flags.BackupIDFV)
+			flagsTD.AssertStorageFlags(t, cmd)
+		})
+	}
+}

src/cli/debug/onedrive.go

@@ -0,0 +1,71 @@
+package debug
+
+import (
+	"github.com/spf13/cobra"
+	"github.com/spf13/pflag"
+
+	"github.com/alcionai/corso/src/cli/flags"
+	"github.com/alcionai/corso/src/cli/utils"
+	"github.com/alcionai/corso/src/pkg/selectors"
+)
+
+// called by debug.go to map subcommands to provider-specific handling.
+func addOneDriveCommands(cmd *cobra.Command) *cobra.Command {
+	var (
+		c  *cobra.Command
+		fs *pflag.FlagSet
+	)
+
+	switch cmd.Use {
+	case metadataFilesCommand:
+		c, fs = utils.AddCommand(cmd, oneDriveMetadataFilesCmd(), utils.MarkDebugCommand())
+
+		c.Use = c.Use + " " + oneDriveServiceCommandUseSuffix
+
+		// Flags addition ordering should follow the order we want them to appear in help and docs:
+		// More generic (ex: --user) and more frequently used flags take precedence.
+		fs.SortFlags = false
+
+		flags.AddBackupIDFlag(c, true)
+	}
+
+	return c
+}
+
+const (
+	oneDriveServiceCommand          = "onedrive"
+	oneDriveServiceCommandUseSuffix = "--backup <backupId>"
+
+	//nolint:lll
+	oneDriveServiceCommandDebugExamples = `# Display file contents for backup 1234abcd
+	corso debug metadata-files onedrive --backup 1234abcd-12ab-cd34-56de-1234abcd`
+)
+
+// `corso debug metadata-files onedrive [<flag>...] <destination>`
+func oneDriveMetadataFilesCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:     oneDriveServiceCommand,
+		Short:   "Display onedrive metadata file content",
+		RunE:    metadataFilesOneDriveCmd,
+		Args:    cobra.NoArgs,
+		Example: oneDriveServiceCommandDebugExamples,
+	}
+}
+
+func metadataFilesOneDriveCmd(cmd *cobra.Command, args []string) error {
+	ctx := cmd.Context()
+
+	if utils.HasNoFlagsAndShownHelp(cmd) {
+		return nil
+	}
+
+	// opts := utils.MakeOneDriveOpts(cmd)
+
+	if flags.RunModeFV == flags.RunModeFlagTest {
+		return nil
+	}
+
+	sel := selectors.NewOneDriveBackup([]string{"unused-placeholder"})
+
+	return runMetadataFiles(ctx, cmd, args, sel.Selector, flags.BackupIDFV, "OneDrive")
+}

src/cli/debug/onedrive_test.go

@@ -0,0 +1,76 @@
+package debug
+
+import (
+	"testing"
+
+	"github.com/spf13/cobra"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/suite"
+
+	"github.com/alcionai/corso/src/cli/flags"
+	flagsTD "github.com/alcionai/corso/src/cli/flags/testdata"
+	cliTD "github.com/alcionai/corso/src/cli/testdata"
+	"github.com/alcionai/corso/src/internal/tester"
+)
+
+type OneDriveUnitSuite struct {
+	tester.Suite
+}
+
+func TestOneDriveUnitSuite(t *testing.T) {
+	suite.Run(t, &OneDriveUnitSuite{Suite: tester.NewUnitSuite(t)})
+}
+
+func (suite *OneDriveUnitSuite) TestAddOneDriveCommands() {
+	expectUse := oneDriveServiceCommand + " " + oneDriveServiceCommandUseSuffix
+
+	table := []struct {
+		name        string
+		use         string
+		expectUse   string
+		expectShort string
+		expectRunE  func(*cobra.Command, []string) error
+	}{
+		{
+			name:        "metadata-files onedrive",
+			use:         metadataFilesCommand,
+			expectUse:   expectUse,
+			expectShort: oneDriveMetadataFilesCmd().Short,
+			expectRunE:  metadataFilesOneDriveCmd,
+		},
+	}
+	for _, test := range table {
+		suite.Run(test.name, func() {
+			t := suite.T()
+			parent := &cobra.Command{Use: metadataFilesCommand}
+
+			cmd := cliTD.SetUpCmdHasFlags(
+				t,
+				parent,
+				addOneDriveCommands,
+				[]cliTD.UseCobraCommandFn{
+					flags.AddAllProviderFlags,
+					flags.AddAllStorageFlags,
+				},
+				flagsTD.WithFlags(
+					oneDriveServiceCommand,
+					[]string{
+						"--" + flags.RunModeFN, flags.RunModeFlagTest,
+						"--" + flags.BackupFN, flagsTD.BackupInput,
+					},
+					flagsTD.PreparedProviderFlags(),
+					flagsTD.PreparedStorageFlags()))
+
+			cliTD.CheckCmdChild(
+				t,
+				parent,
+				3,
+				test.expectUse,
+				test.expectShort,
+				test.expectRunE)
+
+			assert.Equal(t, flagsTD.BackupInput, flags.BackupIDFV)
+			flagsTD.AssertStorageFlags(t, cmd)
+		})
+	}
+}

src/cli/debug/sharepoint.go

@@ -0,0 +1,71 @@
+package debug
+
+import (
+	"github.com/spf13/cobra"
+	"github.com/spf13/pflag"
+
+	"github.com/alcionai/corso/src/cli/flags"
+	"github.com/alcionai/corso/src/cli/utils"
+	"github.com/alcionai/corso/src/pkg/selectors"
+)
+
+// called by debug.go to map subcommands to provider-specific handling.
+func addSharePointCommands(cmd *cobra.Command) *cobra.Command {
+	var (
+		c  *cobra.Command
+		fs *pflag.FlagSet
+	)
+
+	switch cmd.Use {
+	case metadataFilesCommand:
+		c, fs = utils.AddCommand(cmd, sharePointMetadataFilesCmd(), utils.MarkDebugCommand())
+
+		c.Use = c.Use + " " + sharePointServiceCommandUseSuffix
+
+		// Flags addition ordering should follow the order we want them to appear in help and docs:
+		// More generic (ex: --user) and more frequently used flags take precedence.
+		fs.SortFlags = false
+
+		flags.AddBackupIDFlag(c, true)
+	}
+
+	return c
+}
+
+const (
+	sharePointServiceCommand          = "sharepoint"
+	sharePointServiceCommandUseSuffix = "--backup <backupId>"
+
+	//nolint:lll
+	sharePointServiceCommandDebugExamples = `# Display file contents for backup 1234abcd
+	corso debug metadata-files sharepoint --backup 1234abcd-12ab-cd34-56de-1234abcd`
+)
+
+// `corso debug metadata-files sharepoint [<flag>...] <destination>`
+func sharePointMetadataFilesCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:     sharePointServiceCommand,
+		Short:   "Display sharepoint metadata file content",
+		RunE:    metadataFilesSharePointCmd,
+		Args:    cobra.NoArgs,
+		Example: sharePointServiceCommandDebugExamples,
+	}
+}
+
+func metadataFilesSharePointCmd(cmd *cobra.Command, args []string) error {
+	ctx := cmd.Context()
+
+	if utils.HasNoFlagsAndShownHelp(cmd) {
+		return nil
+	}
+
+	// opts := utils.MakeSharePointOpts(cmd)
+
+	if flags.RunModeFV == flags.RunModeFlagTest {
+		return nil
+	}
+
+	sel := selectors.NewSharePointBackup([]string{"unused-placeholder"})
+
+	return runMetadataFiles(ctx, cmd, args, sel.Selector, flags.BackupIDFV, "SharePoint")
+}

src/cli/debug/sharepoint_test.go

@@ -0,0 +1,76 @@
+package debug
+
+import (
+	"testing"
+
+	"github.com/spf13/cobra"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/suite"
+
+	"github.com/alcionai/corso/src/cli/flags"
+	flagsTD "github.com/alcionai/corso/src/cli/flags/testdata"
+	cliTD "github.com/alcionai/corso/src/cli/testdata"
+	"github.com/alcionai/corso/src/internal/tester"
+)
+
+type SharePointUnitSuite struct {
+	tester.Suite
+}
+
+func TestSharePointUnitSuite(t *testing.T) {
+	suite.Run(t, &SharePointUnitSuite{Suite: tester.NewUnitSuite(t)})
+}
+
+func (suite *SharePointUnitSuite) TestAddSharePointCommands() {
+	expectUse := sharePointServiceCommand + " " + sharePointServiceCommandUseSuffix
+
+	table := []struct {
+		name        string
+		use         string
+		expectUse   string
+		expectShort string
+		expectRunE  func(*cobra.Command, []string) error
+	}{
+		{
+			name:        "metdata-files sharepoint",
+			use:         metadataFilesCommand,
+			expectUse:   expectUse,
+			expectShort: sharePointMetadataFilesCmd().Short,
+			expectRunE:  metadataFilesSharePointCmd,
+		},
+	}
+	for _, test := range table {
+		suite.Run(test.name, func() {
+			t := suite.T()
+			parent := &cobra.Command{Use: metadataFilesCommand}
+
+			cmd := cliTD.SetUpCmdHasFlags(
+				t,
+				parent,
+				addSharePointCommands,
+				[]cliTD.UseCobraCommandFn{
+					flags.AddAllProviderFlags,
+					flags.AddAllStorageFlags,
+				},
+				flagsTD.WithFlags(
+					sharePointServiceCommand,
+					[]string{
+						"--" + flags.RunModeFN, flags.RunModeFlagTest,
+						"--" + flags.BackupFN, flagsTD.BackupInput,
+					},
+					flagsTD.PreparedProviderFlags(),
+					flagsTD.PreparedStorageFlags()))
+
+			cliTD.CheckCmdChild(
+				t,
+				parent,
+				3,
+				test.expectUse,
+				test.expectShort,
+				test.expectRunE)
+
+			assert.Equal(t, flagsTD.BackupInput, flags.BackupIDFV)
+			flagsTD.AssertStorageFlags(t, cmd)
+		})
+	}
+}

src/cli/flags/repo.go

@@ -69,7 +69,8 @@ func AddAWSCredsFlags(cmd *cobra.Command) {
 // M365 flags
 func AddCorsoPassphaseFlags(cmd *cobra.Command) {
 	fs := cmd.Flags()
-	fs.StringVar(&PassphraseFV,
+	fs.StringVar(
+		&PassphraseFV,
 		PassphraseFN,
 		"",
 		"Passphrase to protect encrypted repository contents")
@@ -78,7 +79,8 @@ func AddCorsoPassphaseFlags(cmd *cobra.Command) {
 // M365 flags
 func AddUpdatePassphraseFlags(cmd *cobra.Command, require bool) {
 	fs := cmd.Flags()
-	fs.StringVar(&NewPhasephraseFV,
+	fs.StringVar(
+		&NewPhasephraseFV,
 		NewPassphraseFN,
 		"",
 		"update Corso passphrase for repo")

src/cli/utils/debug.go

@@ -0,0 +1,3 @@
+package utils
+
+// TODO(keepers): something

src/cli/utils/utils.go

@@ -149,6 +149,7 @@ type cmdCfg struct {
 	hidden     bool
 	preRelease bool
 	preview    bool
+	debug      bool
 }
 
 type cmdOpt func(*cmdCfg)
@@ -178,6 +179,13 @@ func MarkPreviewCommand() cmdOpt {
 	}
 }
 
+func MarkDebugCommand() cmdOpt {
+	return func(cc *cmdCfg) {
+		cc.hidden = true
+		cc.debug = true
+	}
+}
+
 // AddCommand adds a clone of the subCommand to the parent,
 // and returns both the clone and its pflags.
 func AddCommand(parent, c *cobra.Command, opts ...cmdOpt) (*cobra.Command, *pflag.FlagSet) {
@@ -187,22 +195,25 @@ func AddCommand(parent, c *cobra.Command, opts ...cmdOpt) (*cobra.Command, *pfla
 	parent.AddCommand(c)
 	c.Hidden = cc.hidden
 
-	if cc.preRelease {
+	var deprecatedMsgOverride string
+
+	switch true {
+	case cc.preRelease:
+		deprecatedMsgOverride = "THIS IS A PRE-RELEASE COMMAND THAT MAY NOT FUNCTION PROPERLY, OR AT ALL"
+	case cc.preview:
+		deprecatedMsgOverride = "THIS IS A FEATURE PREVIEW THAT MAY NOT FUNCTION PROPERLY AND MAY BREAK ACROSS RELEASES"
+	case cc.debug:
+		deprecatedMsgOverride = "THIS IS A DEBUGGING COMMAND - IT IS NOT PART OF STANDARD CORSO OPERATION"
+	}
+
+	if len(deprecatedMsgOverride) > 0 {
 		// There is a default deprecated message that always shows so we do some terminal magic to overwrite it
 		c.Deprecated = "\n\033[1F\033[K" +
 			"==================================================================================================\n" +
-			"\tWARNING!!! THIS IS A PRE-RELEASE COMMAND THAT MAY NOT FUNCTION PROPERLY, OR AT ALL\n" +
+			"\tWARNING!!! " + deprecatedMsgOverride + "\n" +
 			"==================================================================================================\n"
 	}
 
-	if cc.preview {
-		// There is a default deprecated message that always shows so we do some terminal magic to overwrite it
-		c.Deprecated = "\n\033[1F\033[K" +
-			"=============================================================================================================\n" +
-			"\tWARNING!!! THIS IS A FEATURE PREVIEW THAT MAY NOT FUNCTION PROPERLY AND MAY BREAK ACROSS RELEASES\n" +
-			"=============================================================================================================\n"
-	}
-
 	c.Flags().SortFlags = false
 
 	return c, c.Flags()