From edb542c653ce4f0949482172f661f9b524f75b7a Mon Sep 17 00:00:00 2001 From: decentral1se Date: Wed, 10 Jul 2024 11:37:06 +0200 Subject: [PATCH] docs: terse manually managed usage text --- cli/app/app.go | 2 +- cli/app/backup.go | 17 +++++++++++---- cli/app/check.go | 7 +++---- cli/app/cmd.go | 20 ++++++++---------- cli/app/config.go | 3 ++- cli/app/cp.go | 10 ++++----- cli/app/deploy.go | 18 +++++++--------- cli/app/list.go | 12 +++++------ cli/app/logs.go | 9 ++++---- cli/app/new.go | 10 +++++---- cli/app/ps.go | 11 +++++----- cli/app/remove.go | 12 +++++------ cli/app/restart.go | 18 +++++++--------- cli/app/restore.go | 9 ++++---- cli/app/rollback.go | 19 +++++++---------- cli/app/run.go | 5 +++-- cli/app/secret.go | 32 +++++++++++++--------------- cli/app/services.go | 3 ++- cli/app/undeploy.go | 10 ++++----- cli/app/upgrade.go | 13 ++++-------- cli/app/volume.go | 26 ++++++++++++----------- cli/catalogue/catalogue.go | 14 ++++++------- cli/cli.go | 33 +++++++---------------------- cli/recipe/diff.go | 11 +++++----- cli/recipe/fetch.go | 2 +- cli/recipe/lint.go | 9 ++++---- cli/recipe/list.go | 8 ++++--- cli/recipe/new.go | 10 ++++----- cli/recipe/recipe.go | 5 ++--- cli/recipe/release.go | 16 +++++++------- cli/recipe/reset.go | 11 +++++----- cli/recipe/sync.go | 15 ++++++------- cli/recipe/upgrade.go | 26 ++++++++++------------- cli/recipe/version.go | 9 ++++---- cli/server/add.go | 21 +++++++------------ cli/server/list.go | 8 ++++--- cli/server/prune.go | 11 +++++----- cli/server/remove.go | 18 ++++++++-------- cli/server/server.go | 1 + cli/updater/updater.go | 43 +++++++++++++++++--------------------- 40 files changed, 256 insertions(+), 281 deletions(-) diff --git a/cli/app/app.go b/cli/app/app.go index 93af1a17..adb75734 100644 --- a/cli/app/app.go +++ b/cli/app/app.go @@ -8,7 +8,7 @@ var AppCommand = cli.Command{ Name: "app", Aliases: []string{"a"}, Usage: "Manage apps", - ArgsUsage: "", + UsageText: "abra app [command] [options] [arguments]", HideHelpCommand: true, Commands: []*cli.Command{ &appBackupCommand, diff --git a/cli/app/backup.go b/cli/app/backup.go index 8d12d389..25def0ea 100644 --- a/cli/app/backup.go +++ b/cli/app/backup.go @@ -46,6 +46,8 @@ var appBackupListCommand = cli.Command{ Before: internal.SubCommandBefore, Usage: "List all backups", EnableShellCompletion: true, + HideHelpCommand: true, + UsageText: "abra app backup list [options] ", ShellComplete: autocomplete.AppNameComplete, Action: func(ctx context.Context, cmd *cli.Command) error { app := internal.ValidateApp(cmd) @@ -92,6 +94,8 @@ var appBackupDownloadCommand = cli.Command{ }, Before: internal.SubCommandBefore, Usage: "Download a backup", + UsageText: "abra app backup download [options] ", + HideHelpCommand: true, EnableShellCompletion: true, ShellComplete: autocomplete.AppNameComplete, Action: func(ctx context.Context, cmd *cli.Command) error { @@ -162,6 +166,8 @@ var appBackupCreateCommand = cli.Command{ }, Before: internal.SubCommandBefore, Usage: "Create a new backup", + HideHelpCommand: true, + UsageText: "abra app backup create [options] ", EnableShellCompletion: true, ShellComplete: autocomplete.AppNameComplete, Action: func(ctx context.Context, cmd *cli.Command) error { @@ -220,6 +226,8 @@ var appBackupSnapshotsCommand = cli.Command{ }, Before: internal.SubCommandBefore, Usage: "List backup snapshots", + UsageText: "abra app backup snapshots [options] ", + HideHelpCommand: true, EnableShellCompletion: true, ShellComplete: autocomplete.AppNameComplete, Action: func(ctx context.Context, cmd *cli.Command) error { @@ -270,10 +278,11 @@ var appBackupSnapshotsCommand = cli.Command{ } var appBackupCommand = cli.Command{ - Name: "backup", - Aliases: []string{"b"}, - Usage: "Manage app backups", - ArgsUsage: "", + Name: "backup", + Aliases: []string{"b"}, + Usage: "Manage app backups", + UsageText: "abra app backup [command] [options] [arguments]", + HideHelpCommand: true, Commands: []*cli.Command{ &appBackupListCommand, &appBackupSnapshotsCommand, diff --git a/cli/app/check.go b/cli/app/check.go index af62cc63..cdf42f10 100644 --- a/cli/app/check.go +++ b/cli/app/check.go @@ -15,9 +15,7 @@ var appCheckCommand = cli.Command{ Name: "check", Aliases: []string{"chk"}, Usage: "Ensure an app is well configured", - Description: ` -This command compares env vars in both the app ".env" and recipe ".env.sample" -file. + Description: `Compare env vars in both the app ".env" and recipe ".env.sample" file. The goal is to ensure that recipe ".env.sample" env vars are defined in your app ".env" file. Only env var definitions in the ".env.sample" which are @@ -27,7 +25,8 @@ these env vars, then "check" will complain. Recipe maintainers may or may not provide defaults for env vars within their recipes regardless of commenting or not (e.g. through the use of ${FOO:} syntax). "check" does not confirm or deny this for you.`, - ArgsUsage: "", + UsageText: "abra app check [options] ", + HideHelpCommand: true, Flags: []cli.Flag{ internal.ChaosFlag, internal.OfflineFlag, diff --git a/cli/app/cmd.go b/cli/app/cmd.go index 53138c61..e627cc4b 100644 --- a/cli/app/cmd.go +++ b/cli/app/cmd.go @@ -28,14 +28,11 @@ var appCmdCommand = cli.Command{ These commands are bash functions, defined in the abra.sh of the recipe itself. They can be run within the context of a service (e.g. app) or locally on your work station by passing "--local". Arguments can be passed into these functions -using the "-- " syntax. +using the "-- " syntax. -**WARNING**: options must be passed directly after the sub-command "cmd". - -EXAMPLE: - - abra app cmd --local example.com app create_user -- me@example.com`, - ArgsUsage: " [] [-- ]", +**WARNING**: [options] must be passed directly after the "cmd" sub-command.`, + UsageText: "abra app cmd [options] [] [-- ]", + HideHelpCommand: true, Flags: []cli.Flag{ internal.LocalCmdFlag, internal.RemoteUserFlag, @@ -199,10 +196,11 @@ func cmdNameComplete(appName string) { } var appCmdListCommand = cli.Command{ - Name: "list", - Aliases: []string{"ls"}, - Usage: "List all available commands", - ArgsUsage: "", + Name: "list", + Aliases: []string{"ls"}, + Usage: "List all available commands", + UsageText: "abra app cmd ls [options] ", + HideHelpCommand: true, Flags: []cli.Flag{ internal.OfflineFlag, internal.ChaosFlag, diff --git a/cli/app/config.go b/cli/app/config.go index dfce75db..ba87ceda 100644 --- a/cli/app/config.go +++ b/cli/app/config.go @@ -18,7 +18,8 @@ var appConfigCommand = cli.Command{ Name: "config", Aliases: []string{"cfg"}, Usage: "Edit app config", - ArgsUsage: "", + HideHelpCommand: true, + UsageText: "abra app config [options] ", Before: internal.SubCommandBefore, EnableShellCompletion: true, ShellComplete: autocomplete.AppNameComplete, diff --git a/cli/app/cp.go b/cli/app/cp.go index 84bd1cb9..5daddb90 100644 --- a/cli/app/cp.go +++ b/cli/app/cp.go @@ -26,16 +26,16 @@ import ( ) var appCpCommand = cli.Command{ - Name: "cp", - Aliases: []string{"c"}, - ArgsUsage: " ", + Name: "cp", + Aliases: []string{"c"}, + HideHelpCommand: true, + UsageText: "abra app cp [options] ", Flags: []cli.Flag{ internal.NoInputFlag, }, Before: internal.SubCommandBefore, Usage: "Copy files to/from a deployed app service", - Description: ` -Copy files to and from any app service file system. + Description: `Copy files to and from any app service file system. If you want to copy a myfile.txt to the root of the app service: diff --git a/cli/app/deploy.go b/cli/app/deploy.go index 32fefc93..e569f59e 100644 --- a/cli/app/deploy.go +++ b/cli/app/deploy.go @@ -19,10 +19,12 @@ import ( ) var appDeployCommand = cli.Command{ - Name: "deploy", - Aliases: []string{"d"}, - Usage: "Deploy an app", - ArgsUsage: " []", + Name: "deploy", + Aliases: []string{"d"}, + Usage: "Deploy an app", + ArgsUsage: " []", + HideHelpCommand: true, + UsageText: "abra app deploy [options] []", Flags: []cli.Flag{ internal.NoInputFlag, internal.ForceFlag, @@ -37,13 +39,7 @@ var appDeployCommand = cli.Command{ This command supports chaos operations. Use "--chaos" to deploy your recipe checkout as-is. Recipe commit hashes are also supported values for "[]". Please note, "upgrade"/"rollback" do not support chaos -operations. - -EXAMPLE: - - abra app deploy foo.example.com - abra app deploy foo.example.com 1.2.3+3.2.1 - abra app deploy foo.example.com 1e83340e`, +operations.`, EnableShellCompletion: true, ShellComplete: autocomplete.AppNameComplete, Action: func(ctx context.Context, cmd *cli.Command) error { diff --git a/cli/app/list.go b/cli/app/list.go index 4b3929f3..0e29cb9d 100644 --- a/cli/app/list.go +++ b/cli/app/list.go @@ -71,12 +71,12 @@ type serverStatus struct { } var appListCommand = cli.Command{ - Name: "list", - Aliases: []string{"ls"}, - Usage: "List all managed apps", - Description: ` -Read the local file system listing of apps and servers (e.g. ~/.abra/) to -generate a report of all your apps. + Name: "list", + Aliases: []string{"ls"}, + Usage: "List all managed apps", + HideHelpCommand: true, + UsageText: "abra app list [options]", + Description: `Generate a report of all managed apps. By passing the "--status/-S" flag, you can query all your servers for the actual live deployment status. Depending on how many servers you manage, this diff --git a/cli/app/logs.go b/cli/app/logs.go index 5c221200..8a26fa86 100644 --- a/cli/app/logs.go +++ b/cli/app/logs.go @@ -23,10 +23,11 @@ import ( ) var appLogsCommand = cli.Command{ - Name: "logs", - Aliases: []string{"l"}, - ArgsUsage: " []", - Usage: "Tail app logs", + Name: "logs", + Aliases: []string{"l"}, + Usage: "Tail app logs", + HideHelpCommand: true, + UsageText: "abra app logs [options] []", Flags: []cli.Flag{ internal.StdErrOnlyFlag, internal.SinceLogsFlag, diff --git a/cli/app/new.go b/cli/app/new.go index 62875a85..f5efaf81 100644 --- a/cli/app/new.go +++ b/cli/app/new.go @@ -19,9 +19,10 @@ import ( "github.com/urfave/cli/v3" ) -var appNewDescription = ` -Creates a new app from a default recipe. This new app configuration is stored -in your $ABRA_DIR directory under the appropriate server. +var appNewDescription = `Creates a new app from a default recipe. + +This new app configuration is stored in your $ABRA_DIR directory under the +appropriate server. This command does not deploy your app for you. You will need to run "abra app deploy " to do so. @@ -53,7 +54,8 @@ var appNewCommand = cli.Command{ internal.ChaosFlag, }, Before: internal.SubCommandBefore, - ArgsUsage: "[] []", + HideHelpCommand: true, + UsageText: "abra app new [options] [] []", EnableShellCompletion: true, ShellComplete: func(ctx context.Context, cmd *cli.Command) { args := cmd.Args() diff --git a/cli/app/ps.go b/cli/app/ps.go index 971a5d7e..da1bb7c7 100644 --- a/cli/app/ps.go +++ b/cli/app/ps.go @@ -21,11 +21,12 @@ import ( ) var appPsCommand = cli.Command{ - Name: "ps", - Aliases: []string{"p"}, - Usage: "Check app status", - ArgsUsage: "", - Description: "Show status of a deployed app.", + Name: "ps", + Aliases: []string{"p"}, + Usage: "Check app status", + HideHelpCommand: true, + UsageText: "abra app ps [options] ", + Description: "Show status of a deployed app.", Flags: []cli.Flag{ internal.MachineReadableFlag, }, diff --git a/cli/app/remove.go b/cli/app/remove.go index 3f1ca724..3a52c765 100644 --- a/cli/app/remove.go +++ b/cli/app/remove.go @@ -16,12 +16,12 @@ import ( ) var appRemoveCommand = cli.Command{ - Name: "remove", - Aliases: []string{"rm"}, - ArgsUsage: "", - Usage: "Remove all app data, locally and remotely", - Description: ` -This command removes everything related to an app which is already undeployed. + Name: "remove", + Aliases: []string{"rm"}, + HideHelpCommand: true, + UsageText: "abra app remove [options] ", + Usage: "Remove all app data, locally and remotely", + Description: `Remove everything related to an app which is already undeployed. By default, it will prompt for confirmation before proceeding. All secrets, volumes and the local app env file will be deleted. diff --git a/cli/app/restart.go b/cli/app/restart.go index 250bef62..7ce64e3d 100644 --- a/cli/app/restart.go +++ b/cli/app/restart.go @@ -16,25 +16,21 @@ import ( ) var appRestartCommand = cli.Command{ - Name: "restart", - Aliases: []string{"re"}, - Usage: "Restart an app", - ArgsUsage: " []", + Name: "restart", + Aliases: []string{"re"}, + Usage: "Restart an app", + HideHelpCommand: true, + UsageText: "abra app restart [options] []", Flags: []cli.Flag{ internal.OfflineFlag, internal.AllServicesFlag, }, Before: internal.SubCommandBefore, - Description: ` -This command restarts services within a deployed app. + Description: `This command restarts services within a deployed app. Run "abra app ps " to see a list of service names. -Pass "--all-services/-a" to restart all services. - -EXAMPLE: - - abra app restart example.com app`, +Pass "--all-services/-a" to restart all services.`, EnableShellCompletion: true, ShellComplete: autocomplete.AppNameComplete, Action: func(ctx context.Context, cmd *cli.Command) error { diff --git a/cli/app/restore.go b/cli/app/restore.go index 4b5c9a98..ce68c6dc 100644 --- a/cli/app/restore.go +++ b/cli/app/restore.go @@ -20,10 +20,11 @@ var targetPathFlag = &cli.StringFlag{ } var appRestoreCommand = cli.Command{ - Name: "restore", - Aliases: []string{"rs"}, - Usage: "Restore an app backup", - ArgsUsage: " ", + Name: "restore", + Aliases: []string{"rs"}, + Usage: "Restore an app backup", + HideHelpCommand: true, + UsageText: "abra app restore [options] ", Flags: []cli.Flag{ internal.OfflineFlag, targetPathFlag, diff --git a/cli/app/rollback.go b/cli/app/rollback.go index e6d6a982..9bbe711d 100644 --- a/cli/app/rollback.go +++ b/cli/app/rollback.go @@ -19,10 +19,11 @@ import ( ) var appRollbackCommand = cli.Command{ - Name: "rollback", - Aliases: []string{"rl"}, - Usage: "Roll an app back to a previous version", - ArgsUsage: " []", + Name: "rollback", + Aliases: []string{"rl"}, + Usage: "Roll an app back to a previous version", + HideHelpCommand: true, + UsageText: "abra app rollback [options] []", Flags: []cli.Flag{ internal.NoInputFlag, internal.ForceFlag, @@ -31,19 +32,13 @@ var appRollbackCommand = cli.Command{ internal.OfflineFlag, }, Before: internal.SubCommandBefore, - Description: ` -This command rolls an app back to a previous version. + Description: `This command rolls an app back to a previous version. Unlike "deploy", chaos operations are not supported here. Only recipe versions are supported values for "[]". A rollback can be destructive, please ensure you have a copy of your app data -beforehand. - -EXAMPLE: - - abra app rollback foo.example.com - abra app rollback foo.example.com 1.2.3+3.2.1`, +beforehand.`, EnableShellCompletion: true, ShellComplete: autocomplete.AppNameComplete, Action: func(ctx context.Context, cmd *cli.Command) error { diff --git a/cli/app/run.go b/cli/app/run.go index 742c978e..195f97a1 100644 --- a/cli/app/run.go +++ b/cli/app/run.go @@ -40,8 +40,9 @@ var appRunCommand = cli.Command{ userFlag, }, Before: internal.SubCommandBefore, - ArgsUsage: " ...", - Usage: "Run a command in a service container", + UsageText: "abra app run [options] ", + Usage: "Run a command in an app service", + HideHelpCommand: true, EnableShellCompletion: true, ShellComplete: autocomplete.AppNameComplete, Action: func(ctx context.Context, cmd *cli.Command) error { diff --git a/cli/app/secret.go b/cli/app/secret.go index 0e628fa8..205cb044 100644 --- a/cli/app/secret.go +++ b/cli/app/secret.go @@ -41,10 +41,11 @@ var ( ) var appSecretGenerateCommand = cli.Command{ - Name: "generate", - Aliases: []string{"g"}, - Usage: "Generate secrets", - ArgsUsage: " ", + Name: "generate", + Aliases: []string{"g"}, + Usage: "Generate secrets", + UsageText: "abra app secret generate [options] ", + HideHelpCommand: true, Flags: []cli.Flag{ allSecretsFlag, internal.PassFlag, @@ -145,21 +146,15 @@ var appSecretInsertCommand = cli.Command{ internal.TrimFlag, }, Before: internal.SubCommandBefore, - ArgsUsage: " ", + UsageText: "abra app secret insert [options] ", + HideHelpCommand: true, EnableShellCompletion: true, ShellComplete: autocomplete.AppNameComplete, - Description: ` -This command inserts a secret into an app environment. + Description: `This command inserts a secret into an app environment. This can be useful when you want to manually generate secrets for an app environment. Typically, you can let Abra generate them for you on app creation -(see "abra app new --secrets" for more). - -Example: - - abra app secret insert myapp db_pass v1 mySecretPassword - -`, +(see "abra app new --secrets" for more).`, Action: func(ctx context.Context, cmd *cli.Command) error { app := internal.ValidateApp(cmd) @@ -383,10 +378,11 @@ var appSecretLsCommand = cli.Command{ } var appSecretCommand = cli.Command{ - Name: "secret", - Aliases: []string{"s"}, - Usage: "Manage app secrets", - ArgsUsage: "", + Name: "secret", + Aliases: []string{"s"}, + Usage: "Manage app secrets", + HideHelpCommand: true, + UsageText: "abra app secret [command] [options] [arguments]", Commands: []*cli.Command{ &appSecretGenerateCommand, &appSecretInsertCommand, diff --git a/cli/app/services.go b/cli/app/services.go index 50307e5f..bc84140b 100644 --- a/cli/app/services.go +++ b/cli/app/services.go @@ -20,7 +20,8 @@ var appServicesCommand = cli.Command{ Name: "services", Aliases: []string{"sr"}, Usage: "Display all services of an app", - ArgsUsage: "", + HideHelpCommand: true, + UsageText: "abra app services [options] ", Before: internal.SubCommandBefore, EnableShellCompletion: true, ShellComplete: autocomplete.AppNameComplete, diff --git a/cli/app/undeploy.go b/cli/app/undeploy.go index 03fcdcff..01a14160 100644 --- a/cli/app/undeploy.go +++ b/cli/app/undeploy.go @@ -62,9 +62,10 @@ func pruneApp(cl *dockerClient.Client, app appPkg.App) error { } var appUndeployCommand = cli.Command{ - Name: "undeploy", - Aliases: []string{"un"}, - ArgsUsage: "", + Name: "undeploy", + Aliases: []string{"un"}, + UsageText: "abra app undeploy [options] ", + HideHelpCommand: true, Flags: []cli.Flag{ internal.NoInputFlag, pruneFlag, @@ -73,8 +74,7 @@ var appUndeployCommand = cli.Command{ Usage: "Undeploy an app", EnableShellCompletion: true, ShellComplete: autocomplete.AppNameComplete, - Description: ` -This does not destroy any of the application data. + Description: `This does not destroy any of the application data. However, you should remain vigilant, as your swarm installation will consider any previously attached volumes as eligible for pruning once undeployed. diff --git a/cli/app/upgrade.go b/cli/app/upgrade.go index ee23868a..786bb903 100644 --- a/cli/app/upgrade.go +++ b/cli/app/upgrade.go @@ -21,7 +21,7 @@ var appUpgradeCommand = cli.Command{ Name: "upgrade", Aliases: []string{"up"}, Usage: "Upgrade an app", - ArgsUsage: " []", + UsageText: "abra app upgrade [options] []", Flags: []cli.Flag{ internal.NoInputFlag, internal.ForceFlag, @@ -31,20 +31,15 @@ var appUpgradeCommand = cli.Command{ internal.ReleaseNotesFlag, }, Before: internal.SubCommandBefore, - Description: ` -Upgrade an app. + Description: `Upgrade an app. Unlike "deploy", chaos operations are not supported here. Only recipe versions are supported values for "[]". An upgrade can be destructive, please ensure you have a copy of your app data -beforehand. - -EXAMPLE: - - abra app upgrade foo.example.com - abra app upgrade foo.example.com 1.2.3+3.2.1`, +beforehand.`, EnableShellCompletion: true, + HideHelpCommand: true, ShellComplete: autocomplete.AppNameComplete, Action: func(ctx context.Context, cmd *cli.Command) error { app := internal.ValidateApp(cmd) diff --git a/cli/app/volume.go b/cli/app/volume.go index ef83ec57..8357ad9a 100644 --- a/cli/app/volume.go +++ b/cli/app/volume.go @@ -16,12 +16,13 @@ import ( var appVolumeListCommand = cli.Command{ Name: "list", Aliases: []string{"ls"}, - ArgsUsage: "", + UsageText: "abra app volume list [options] ", Flags: []cli.Flag{ internal.NoInputFlag, }, Before: internal.SubCommandBefore, Usage: "List volumes associated with an app", + HideHelpCommand: true, EnableShellCompletion: true, ShellComplete: autocomplete.AppNameComplete, Action: func(ctx context.Context, cmd *cli.Command) error { @@ -64,20 +65,20 @@ var appVolumeListCommand = cli.Command{ var appVolumeRemoveCommand = cli.Command{ Name: "remove", Usage: "Remove volume(s) associated with an app", - Description: ` -This command supports removing volumes associated with an app. The app in -question must be undeployed before you try to remove volumes. See "abra app -undeploy " for more. + Description: `Memove volumes associated with an app. + +The app in question must be undeployed before you try to remove volumes. See +"abra app undeploy " for more. The command is interactive and will show a multiple select input which allows you to make a seclection. Use the "?" key to see more help on navigating this interface. Passing "--force/-f" will select all volumes for removal. Be careful.`, - ArgsUsage: "", - Aliases: []string{"rm"}, + HideHelpCommand: true, + UsageText: "abra app volume remove [options] ", + Aliases: []string{"rm"}, Flags: []cli.Flag{ - internal.DebugFlag, internal.NoInputFlag, internal.ForceFlag, }, @@ -146,10 +147,11 @@ Passing "--force/-f" will select all volumes for removal. Be careful.`, } var appVolumeCommand = cli.Command{ - Name: "volume", - Aliases: []string{"vl"}, - Usage: "Manage app volumes", - ArgsUsage: "", + Name: "volume", + Aliases: []string{"vl"}, + Usage: "Manage app volumes", + UsageText: "abra app volume [command] [options] [arguments]", + HideHelpCommand: true, Commands: []*cli.Command{ &appVolumeListCommand, &appVolumeRemoveCommand, diff --git a/cli/catalogue/catalogue.go b/cli/catalogue/catalogue.go index b247a8aa..e17fcb38 100644 --- a/cli/catalogue/catalogue.go +++ b/cli/catalogue/catalogue.go @@ -24,6 +24,7 @@ var catalogueGenerateCommand = cli.Command{ Aliases: []string{"g"}, Usage: "Generate the recipe catalogue", HideHelpCommand: true, + UsageText: "abra catalogue generate [options] []", Flags: []cli.Flag{ internal.NoInputFlag, internal.PublishFlag, @@ -33,8 +34,7 @@ var catalogueGenerateCommand = cli.Command{ internal.OfflineFlag, }, Before: internal.SubCommandBefore, - Description: ` -Generate a new copy of the recipe catalogue. + Description: `Generate a new copy of the recipe catalogue. It is possible to generate new metadata for a single recipe by passing . The existing local catalogue will be updated, not overwritten. @@ -46,7 +46,6 @@ If you have a Hub account you can have Abra log you in to avoid this. Pass Push your new release to git.coopcloud.tech with "-p/--publish". This requires that you have permission to git push to these repositories and have your SSH keys configured on your account.`, - ArgsUsage: "[]", EnableShellCompletion: true, ShellComplete: autocomplete.RecipeNameComplete, Action: func(ctx context.Context, cmd *cli.Command) error { @@ -207,10 +206,11 @@ keys configured on your account.`, // CatalogueCommand defines the `abra catalogue` command and sub-commands. var CatalogueCommand = cli.Command{ - Name: "catalogue", - Usage: "Manage the recipe catalogue", - Aliases: []string{"c"}, - ArgsUsage: "", + Name: "catalogue", + Usage: "Manage the recipe catalogue", + Aliases: []string{"c"}, + HideHelpCommand: true, + UsageText: "abra catalogue [command] [options] [arguments]", Commands: []*cli.Command{ &catalogueGenerateCommand, }, diff --git a/cli/cli.go b/cli/cli.go index 8ddc4746..ab8b8d0b 100644 --- a/cli/cli.go +++ b/cli/cli.go @@ -27,14 +27,9 @@ var AutoCompleteCommand = cli.Command{ Name: "autocomplete", Aliases: []string{"ac"}, Usage: "Configure shell autocompletion", - Description: ` -Set up shell auto-completion. + Description: `Set up shell auto-completion. -Supported shells are: bash, fish, fizsh & zsh. - -EXAMPLE: - - abra autocomplete bash`, +Supported shells are: bash, fish, fizsh & zsh.`, ArgsUsage: "", Action: func(ctx context.Context, cmd *cli.Command) error { shellType := cmd.Args().First() @@ -111,17 +106,11 @@ var UpgradeCommand = cli.Command{ Name: "upgrade", Aliases: []string{"u"}, Usage: "Upgrade abra", - Description: ` -Upgrade abra in-place with the latest stable or release candidate. + Description: `Upgrade abra in-place with the latest stable or release candidate. Use "-r/--rc" to install the latest release candidate. Please bear in mind that it may contain absolutely catastrophic deal-breaker bugs. Thank you very much -for the testing efforts 💗 - -EXAMPLE: - - abra upgrade - abra upgrade --rc`, +for the testing efforts 💗`, Flags: []cli.Flag{internal.RCFlag}, Action: func(ctx context.Context, cmd *cli.Command) error { mainURL := "https://install.abra.coopcloud.tech" @@ -144,16 +133,10 @@ EXAMPLE: func newAbraApp(version, commit string) *cli.Command { app := &cli.Command{ - Name: "abra", - Usage: `the Co-op Cloud command-line utility belt 🎩🐇 - ____ ____ _ _ - / ___|___ ___ _ __ / ___| | ___ _ _ __| | - | | / _ \ _____ / _ \| '_ \ | | | |/ _ \| | | |/ _' | - | |__| (_) |_____| (_) | |_) | | |___| | (_) | |_| | (_| | - \____\___/ \___/| .__/ \____|_|\___/ \__,_|\__,_| - |_| -`, - Version: fmt.Sprintf("%s-%s", version, commit[:7]), + Name: "abra", + Usage: "The Co-op Cloud command-line utility belt 🎩🐇", + UsageText: "abra [command] [options] [arguments]", + Version: fmt.Sprintf("%s-%s", version, commit[:7]), Flags: []cli.Flag{ internal.DebugFlag, }, diff --git a/cli/recipe/diff.go b/cli/recipe/diff.go index 936d27ef..4a5b94fc 100644 --- a/cli/recipe/diff.go +++ b/cli/recipe/diff.go @@ -11,11 +11,12 @@ import ( ) var recipeDiffCommand = cli.Command{ - Name: "diff", - Usage: "Show unstaged changes in recipe config", - Description: "This command requires /usr/bin/git.", - Aliases: []string{"d"}, - ArgsUsage: "", + Name: "diff", + Usage: "Show unstaged changes in recipe config", + Description: "This command requires /usr/bin/git.", + HideHelpCommand: true, + Aliases: []string{"d"}, + UsageText: "abra recipe diff [options] ", Flags: []cli.Flag{ internal.NoInputFlag, }, diff --git a/cli/recipe/fetch.go b/cli/recipe/fetch.go index 6a104ff4..6da69f58 100644 --- a/cli/recipe/fetch.go +++ b/cli/recipe/fetch.go @@ -15,7 +15,7 @@ var recipeFetchCommand = cli.Command{ Name: "fetch", Usage: "Fetch recipe(s)", Aliases: []string{"f"}, - ArgsUsage: "[]", + UsageText: "abra recipe fetch [options] []", Description: "Retrieves all recipes if no argument is passed", Flags: []cli.Flag{ internal.NoInputFlag, diff --git a/cli/recipe/lint.go b/cli/recipe/lint.go index be55a278..b0a667b8 100644 --- a/cli/recipe/lint.go +++ b/cli/recipe/lint.go @@ -13,10 +13,11 @@ import ( ) var recipeLintCommand = cli.Command{ - Name: "lint", - Usage: "Lint a recipe", - Aliases: []string{"l"}, - ArgsUsage: "", + Name: "lint", + Usage: "Lint a recipe", + Aliases: []string{"l"}, + UsageText: "abra recipe lint [options] ", + HideHelpCommand: true, Flags: []cli.Flag{ internal.OnlyErrorFlag, internal.OfflineFlag, diff --git a/cli/recipe/list.go b/cli/recipe/list.go index f69594e1..0a45a9be 100644 --- a/cli/recipe/list.go +++ b/cli/recipe/list.go @@ -24,9 +24,11 @@ var patternFlag = &cli.StringFlag{ } var recipeListCommand = cli.Command{ - Name: "list", - Usage: "List available recipes", - Aliases: []string{"ls"}, + Name: "list", + Usage: "List recipes", + HideHelpCommand: true, + UsageText: "abra recipe list [options]", + Aliases: []string{"ls"}, Flags: []cli.Flag{ internal.MachineReadableFlag, patternFlag, diff --git a/cli/recipe/new.go b/cli/recipe/new.go index c80f2eec..96a5b24f 100644 --- a/cli/recipe/new.go +++ b/cli/recipe/new.go @@ -40,11 +40,11 @@ var recipeNewCommand = cli.Command{ internal.GitNameFlag, internal.GitEmailFlag, }, - Before: internal.SubCommandBefore, - Usage: "Create a new recipe", - ArgsUsage: "", - Description: ` -Create a new recipe. + Before: internal.SubCommandBefore, + Usage: "Create a new recipe", + UsageText: "abra recipe new [options] ", + HideHelpCommand: true, + Description: `Create a new recipe. Abra uses the built-in example repository which is available here: diff --git a/cli/recipe/recipe.go b/cli/recipe/recipe.go index 77bc6872..1926719a 100644 --- a/cli/recipe/recipe.go +++ b/cli/recipe/recipe.go @@ -9,9 +9,8 @@ var RecipeCommand = cli.Command{ Name: "recipe", Aliases: []string{"r"}, Usage: "Manage recipes", - ArgsUsage: "", - Description: ` -A recipe is a blueprint for an app. It is a bunch of config files which + UsageText: "abra recipe [command] [options] [arguments]", + Description: `A recipe is a blueprint for an app. It is a bunch of config files which describe how to deploy and maintain an app. Recipes are maintained by the Co-op Cloud community and you can use Abra to read them, deploy them and create apps for you. diff --git a/cli/recipe/release.go b/cli/recipe/release.go index 88135748..ea770124 100644 --- a/cli/recipe/release.go +++ b/cli/recipe/release.go @@ -23,13 +23,15 @@ import ( ) var recipeReleaseCommand = cli.Command{ - Name: "release", - Aliases: []string{"rl"}, - Usage: "Release a new recipe version", - ArgsUsage: " []", - Description: ` -Create a new version of a recipe. These versions are then published on the -Co-op Cloud recipe catalogue. These versions take the following form: + Name: "release", + Aliases: []string{"rl"}, + Usage: "Release a new recipe version", + HideHelpCommand: true, + UsageText: "abra recipe release [options] []", + Description: `Create a new version of a recipe. + +These versions are then published on the Co-op Cloud recipe catalogue. These +versions take the following form: a.b.c+x.y.z diff --git a/cli/recipe/reset.go b/cli/recipe/reset.go index 32c4c786..e302f361 100644 --- a/cli/recipe/reset.go +++ b/cli/recipe/reset.go @@ -12,11 +12,12 @@ import ( ) var recipeResetCommand = cli.Command{ - Name: "reset", - Usage: "Remove all unstaged changes from recipe config", - Description: "WARNING: this will delete your changes. Be Careful.", - Aliases: []string{"rs"}, - ArgsUsage: "", + Name: "reset", + Usage: "Remove all unstaged changes from recipe config", + Description: "WARNING: this will delete your changes. Be Careful.", + HideHelpCommand: true, + Aliases: []string{"rs"}, + UsageText: "abra recipe reset [options] ", Flags: []cli.Flag{ internal.NoInputFlag, }, diff --git a/cli/recipe/sync.go b/cli/recipe/sync.go index f0c3617f..b52386db 100644 --- a/cli/recipe/sync.go +++ b/cli/recipe/sync.go @@ -17,10 +17,11 @@ import ( ) var recipeSyncCommand = cli.Command{ - Name: "sync", - Aliases: []string{"s"}, - Usage: "Sync recipe version label", - ArgsUsage: " []", + Name: "sync", + Aliases: []string{"s"}, + Usage: "Sync recipe version label", + HideHelpCommand: true, + UsageText: "abra recipe lint [options] []", Flags: []cli.Flag{ internal.NoInputFlag, internal.DryFlag, @@ -29,9 +30,9 @@ var recipeSyncCommand = cli.Command{ internal.PatchFlag, }, Before: internal.SubCommandBefore, - Description: ` -Generate labels for the main recipe service (i.e. by convention, the service -named "app") which corresponds to the following format: + Description: `Generate labels for the main recipe service. + +By convention, the service named "app" using the following format: coop-cloud.${STACK_NAME}.version= diff --git a/cli/recipe/upgrade.go b/cli/recipe/upgrade.go index 6e1d5324..c94f32bf 100644 --- a/cli/recipe/upgrade.go +++ b/cli/recipe/upgrade.go @@ -28,8 +28,8 @@ type imgPin struct { version tagcmp.Tag } -// anUpgrade represents a single service upgrade (as within a recipe), and the list of tags that it can be upgraded to, -// for serialization purposes. +// anUpgrade represents a single service upgrade (as within a recipe), and the +// list of tags that it can be upgraded to, for serialization purposes. type anUpgrade struct { Service string `json:"service"` Image string `json:"image"` @@ -38,13 +38,13 @@ type anUpgrade struct { } var recipeUpgradeCommand = cli.Command{ - Name: "upgrade", - Aliases: []string{"u"}, - Usage: "Upgrade recipe image tags", - Description: ` -Parse all image tags within the given configuration and prompt with -more recent tags to upgrade to. It will update the relevant compose file tags -on the local file system. + Name: "upgrade", + Aliases: []string{"u"}, + Usage: "Upgrade recipe image tags", + HideHelpCommand: true, + Description: `Upgrade a given configuration. + +It will update the relevant compose file tags on the local file system. Some image tags cannot be parsed because they do not follow some sort of semver-like convention. In this case, all possible tags will be listed and it @@ -54,12 +54,8 @@ The command is interactive and will show a select input which allows you to make a seclection. Use the "?" key to see more help on navigating this interface. -You may invoke this command in "wizard" mode and be prompted for input. - -EXAMPLE: - - abra recipe upgrade`, - ArgsUsage: "", +You may invoke this command in "wizard" mode and be prompted for input.`, + UsageText: "abra recipe upgrade [options] []", Flags: []cli.Flag{ internal.NoInputFlag, internal.PatchFlag, diff --git a/cli/recipe/version.go b/cli/recipe/version.go index 0c887f11..20b9f170 100644 --- a/cli/recipe/version.go +++ b/cli/recipe/version.go @@ -25,10 +25,11 @@ func sortServiceByName(versions [][]string) func(i, j int) bool { } var recipeVersionCommand = cli.Command{ - Name: "versions", - Aliases: []string{"v"}, - Usage: "List recipe versions", - ArgsUsage: "", + Name: "versions", + Aliases: []string{"v"}, + Usage: "List recipe versions", + UsageText: "abra recipe version [options] ", + HideHelpCommand: true, Flags: []cli.Flag{ internal.OfflineFlag, internal.NoInputFlag, diff --git a/cli/server/add.go b/cli/server/add.go index 6f42d4df..2ed5803a 100644 --- a/cli/server/add.go +++ b/cli/server/add.go @@ -94,15 +94,16 @@ func createServerDir(name string) (bool, error) { } var serverAddCommand = cli.Command{ - Name: "add", - Aliases: []string{"a"}, - Usage: "Add a new server to your configuration", - Description: ` -Add a new server to your configuration so that it can be managed by Abra. + Name: "add", + Aliases: []string{"a"}, + Usage: "Add a new server", + UsageText: "abra server add [options] ", + HideHelpCommand: true, + Description: `Add a new server to your configuration so that it can be managed by Abra. Abra relies on the standard SSH command-line and ~/.ssh/config for client connection details. You must configure an entry per-host in your ~/.ssh/config -for each server. For example: +for each server: Host example.com example Hostname example.com @@ -110,10 +111,6 @@ for each server. For example: Port 12345 IdentityFile ~/.ssh/example@somewhere -You can then add a server like so: - - abra server add example.com - If "--local" is passed, then Abra assumes that the current local server is intended as the target server. This is useful when you want to have your entire Co-op Cloud config located on the server itself, and not on your local @@ -121,9 +118,7 @@ developer machine. The domain is then set to "default". You can also pass "--no-domain-checks/-D" flag to use any arbitrary name instead of a real domain. The host will be resolved with the "Hostname" entry -of your ~/.ssh/config. Checks for a valid online domain will be skipped: - - abra server add -D example`, +of your ~/.ssh/config. Checks for a valid online domain will be skipped.`, Flags: []cli.Flag{ internal.NoInputFlag, internal.NoDomainChecksFlag, diff --git a/cli/server/list.go b/cli/server/list.go index fa8dedda..8f2c0454 100644 --- a/cli/server/list.go +++ b/cli/server/list.go @@ -14,9 +14,11 @@ import ( ) var serverListCommand = cli.Command{ - Name: "list", - Aliases: []string{"ls"}, - Usage: "List managed servers", + Name: "list", + Aliases: []string{"ls"}, + Usage: "List managed servers", + UsageText: "abra server list [options]", + HideHelpCommand: true, Flags: []cli.Flag{ internal.DebugFlag, internal.MachineReadableFlag, diff --git a/cli/server/prune.go b/cli/server/prune.go index 3fd0da33..b581cbde 100644 --- a/cli/server/prune.go +++ b/cli/server/prune.go @@ -31,11 +31,12 @@ var volumesFilterFlag = &cli.BoolFlag{ } var serverPruneCommand = cli.Command{ - Name: "prune", - Aliases: []string{"p"}, - Usage: "Prune resources on a server", - Description: ` -Prunes unused containers, networks, and dangling images. + Name: "prune", + Aliases: []string{"p"}, + Usage: "Prune resources on a server", + UsageText: "abra server prune [options] ", + HideHelpCommand: true, + Description: `Prunes unused containers, networks, and dangling images. Use "-v/--volumes" to remove volumes that are not associated with a deployed app. This can result in unwanted data loss if not used carefully.`, diff --git a/cli/server/remove.go b/cli/server/remove.go index c3f53ce4..b2a8568e 100644 --- a/cli/server/remove.go +++ b/cli/server/remove.go @@ -14,16 +14,16 @@ import ( ) var serverRemoveCommand = cli.Command{ - Name: "remove", - Aliases: []string{"rm"}, - ArgsUsage: "", - Usage: "Remove a managed server", - Description: ` -Remove a managed server. + Name: "remove", + Aliases: []string{"rm"}, + UsageText: "abra server remove [options] ", + Usage: "Remove a managed server", + HideHelpCommand: true, + Description: `Remove a managed server. -Abra will remove the internal bookkeeping (~/.abra/servers/...) and underlying -client connection context. This server will then be lost in time, like tears in -rain.`, +Abra will remove the internal bookkeeping ($ABRA_DIR/servers/...) and +underlying client connection context. This server will then be lost in time, +like tears in rain.`, Flags: []cli.Flag{ internal.NoInputFlag, internal.OfflineFlag, diff --git a/cli/server/server.go b/cli/server/server.go index bb6bb53b..9a91cb02 100644 --- a/cli/server/server.go +++ b/cli/server/server.go @@ -9,6 +9,7 @@ var ServerCommand = cli.Command{ Name: "server", Aliases: []string{"s"}, Usage: "Manage servers", + UsageText: "abra server [command] [options] [arguments]", HideHelpCommand: true, Commands: []*cli.Command{ &serverAddCommand, diff --git a/cli/updater/updater.go b/cli/updater/updater.go index 921f353f..755aa274 100644 --- a/cli/updater/updater.go +++ b/cli/updater/updater.go @@ -46,17 +46,16 @@ var allFlag = &cli.BoolFlag{ // Notify checks for available upgrades var Notify = cli.Command{ - Name: "notify", - Aliases: []string{"n"}, - Usage: "Check for available upgrades", + Name: "notify", + Aliases: []string{"n"}, + Usage: "Check for available upgrades", + UsageText: "kadabra notify [options]", + HideHelpCommand: true, Flags: []cli.Flag{ majorFlag, - internal.OfflineFlag, }, Before: internal.SubCommandBefore, - Description: ` -Read the deployed app versions and look for new versions in the recipe -catalogue. + Description: `Notify on new versions for deployed apps. If a new patch/minor version is available, a notification is printed. @@ -93,20 +92,18 @@ Use "--major" to include new major versions.`, // UpgradeApp upgrades apps. var UpgradeApp = cli.Command{ - Name: "upgrade", - Aliases: []string{"u"}, - Usage: "Upgrade apps", - ArgsUsage: " ", + Name: "upgrade", + Aliases: []string{"u"}, + Usage: "Upgrade apps", + UsageText: "kadabra notify [options] ", + HideHelpCommand: true, Flags: []cli.Flag{ - internal.DebugFlag, internal.ChaosFlag, majorFlag, allFlag, - internal.OfflineFlag, }, Before: internal.SubCommandBefore, - Description: ` -Upgrade an app by specifying stack name and recipe. + Description: `Upgrade an app by specifying stack name and recipe. Use "--all" to upgrade every deployed app. @@ -471,17 +468,15 @@ func upgrade(cl *dockerclient.Client, stackName, recipeName, upgradeVersion stri func newAbraApp(version, commit string) *cli.Command { app := &cli.Command{ - Name: "kadabra", - Usage: `The Co-op Cloud auto-updater - ____ ____ _ _ - / ___|___ ___ _ __ / ___| | ___ _ _ __| | - | | / _ \ _____ / _ \| '_ \ | | | |/ _ \| | | |/ _' | - | |__| (_) |_____| (_) | |_) | | |___| | (_) | |_| | (_| | - \____\___/ \___/| .__/ \____|_|\___/ \__,_|\__,_| - |_| -`, + Name: "kadabra", + Usage: "The Co-op Cloud auto-updater 🤖🚀", Version: fmt.Sprintf("%s-%s", version, commit[:7]), + UsageText: "kadabra [command] [options] [arguments]", HideHelpCommand: true, + Flags: []cli.Flag{ + internal.OfflineFlag, + internal.DebugFlag, + }, Commands: []*cli.Command{ &Notify, &UpgradeApp,