CLI: app, command, and subcommand templates

* swap options and args in all three * fix all readmes Signed-off-by: Alex Aizman <[email protected]>
NVIDIA · Jan 30, 2025 · 45c69e4 · 45c69e4
1 parent b61478e
commit 45c69e4
Show file tree

Hide file tree

Showing 29 changed files with 154 additions and 102 deletions.
diff --git a/ais/prxs3.go b/ais/prxs3.go
@@ -1,6 +1,6 @@
 // Package ais provides core functionality for the AIStore object storage.
 /*
- * Copyright (c) 2018-2024, NVIDIA CORPORATION. All rights reserved.
+ * Copyright (c) 2018-2025, NVIDIA CORPORATION. All rights reserved.
  */
 package ais
 

diff --git a/ais/target.go b/ais/target.go
@@ -1,6 +1,6 @@
 // Package ais provides core functionality for the AIStore object storage.
 /*
- * Copyright (c) 2018-2024, NVIDIA CORPORATION. All rights reserved.
+ * Copyright (c) 2018-2025, NVIDIA CORPORATION. All rights reserved.
  */
 package ais
 

diff --git a/ais/tgtbck.go b/ais/tgtbck.go
@@ -1,6 +1,6 @@
 // Package ais provides core functionality for the AIStore object storage.
 /*
- * Copyright (c) 2018-2024, NVIDIA CORPORATION. All rights reserved.
+ * Copyright (c) 2018-2025, NVIDIA CORPORATION. All rights reserved.
  */
 package ais
 

diff --git a/ais/tgtobj.go b/ais/tgtobj.go
@@ -1,6 +1,6 @@
 // Package ais provides core functionality for the AIStore object storage.
 /*
- * Copyright (c) 2018-2024, NVIDIA CORPORATION. All rights reserved.
+ * Copyright (c) 2018-2025, NVIDIA CORPORATION. All rights reserved.
  */
 package ais
 

diff --git a/cmd/cli/cli/app.go b/cmd/cli/cli/app.go
@@ -35,38 +35,6 @@ const (
    * download ` + cmn.GitHubHome + `/tree/main/cmd/cli/autocomplete
    * run 'cmd/cli/autocomplete/install.sh'
    To install CLI directly from GitHub: ` + cmn.GitHubHome + `/blob/main/scripts/install_from_binaries.sh`
-
-	// custom cli.AppHelpTemplate
-	// "You can render custom help text by setting this variable." (from github.com/urfave/cli)
-	appHelpTemplate = `NAME:
-   {{.Name}}{{if .Usage}} - {{.Usage}}{{end}}
-
-USAGE:
-   {{if .UsageText}}{{.UsageText}}{{else}}{{.HelpName}} {{if .VisibleFlags}}[global options]{{end}}{{if .Commands}} command [command options]{{end}} {{if .ArgsUsage}}{{.ArgsUsage}}{{else}}[arguments...]{{end}}{{end}}{{if .Version}}{{if not .HideVersion}}
-
-VERSION:
-   {{.Version}}{{end}}{{end}}{{if .Description}}
-
-TAB completions (Bash and Zsh):
-   {{.Description}}{{end}}{{if len .Authors}}
-
-AUTHOR{{with $length := len .Authors}}{{if ne 1 $length}}S{{end}}{{end}}:
-   {{range $index, $author := .Authors}}{{if $index}}
-   {{end}}{{$author}}{{end}}{{end}}{{if .VisibleCommands}}
-
-COMMANDS:{{range .VisibleCategories}}{{if .Name}}
-
-   {{.Name}}:{{range .VisibleCommands}}
-     {{join .Names ", "}}{{"\t"}}{{.Usage}}{{end}}{{else}}{{range .VisibleCommands}}
-   {{join .Names ", "}}{{"\t"}}{{.Usage}}{{end}}{{end}}{{end}}{{end}}{{if .VisibleFlags}}
-
-GLOBAL OPTIONS:
-   {{range $index, $option := .VisibleFlags}}{{if $index}}
-   {{end}}{{$option}}{{end}}{{end}}{{if .Copyright}}
-
-COPYRIGHT:
-   {{.Copyright}}{{end}}
-`
 )
 
 const (
@@ -292,7 +260,11 @@ func (a *acli) init(version string, emptyCmdline bool) {
 		cli.HelpPrinter = paginate
 	}
 
+	// custom templates
 	cli.AppHelpTemplate = appHelpTemplate
+	cli.CommandHelpTemplate = commandHelpTemplate
+	cli.SubcommandHelpTemplate = subcommandHelpTemplate
+
 	a.setupCommands(emptyCmdline)
 }
 

diff --git a/cmd/cli/cli/const.go b/cmd/cli/cli/const.go
@@ -330,8 +330,7 @@ const (
 	getLogArgument  = nodeIDArgument + " [OUT_FILE|OUT_DIR|-]"
 
 	// cluster
-	showClusterArgument = "[NODE_ID] | [target [NODE_ID]] | [proxy [NODE_ID]] | \n" +
-		"                     [smap [NODE_ID]] | [bmd [NODE_ID]] | [config [NODE_ID]] | [stats [NODE_ID]]"
+	showClusterArgument = "[NODE_ID] | [target [NODE_ID]] | [proxy [NODE_ID]] | [smap [NODE_ID]] | [bmd [NODE_ID]] | [config [NODE_ID]] | [stats [NODE_ID]]"
 
 	// config
 	showConfigArgument = "cli | cluster [CONFIG SECTION OR PREFIX] |\n" +

diff --git a/cmd/cli/cli/custom_templates.go b/cmd/cli/cli/custom_templates.go
@@ -0,0 +1,81 @@
+// Package cli provides easy-to-use commands to manage, monitor, and utilize AIS clusters.
+/*
+ * Copyright (c) 2018-2025, NVIDIA CORPORATION. All rights reserved.
+ */
+package cli
+
+// custom cli.AppHelpTemplate
+// "You can render custom help text by setting this variable." (from github.com/urfave/cli)
+const (
+	appHelpTemplate = `NAME:
+   {{.Name}}{{if .Usage}} - {{.Usage}}{{end}}
+
+USAGE:
+   {{if .UsageText}}{{.UsageText}}{{else}}{{.HelpName}} {{if .VisibleFlags}}[global options]{{end}} {{if .ArgsUsage}}{{.ArgsUsage}}{{else}}[arguments...]{{end}} {{if .Commands}} command [command options]{{end}} {{end}} {{if .Version}}{{if not .HideVersion}}
+
+VERSION:
+   {{.Version}}{{end}}{{end}}{{if .Description}}
+
+TAB completions (Bash and Zsh):
+   {{.Description}}{{end}}{{if len .Authors}}
+
+AUTHOR{{with $length := len .Authors}}{{if ne 1 $length}}S{{end}}{{end}}:
+   {{range $index, $author := .Authors}}{{if $index}}
+   {{end}}{{$author}}{{end}}{{end}}{{if .VisibleCommands}}
+
+COMMANDS:{{range .VisibleCategories}}{{if .Name}}
+
+   {{.Name}}:{{range .VisibleCommands}}
+     {{join .Names ", "}}{{"\t"}}{{.Usage}}{{end}}{{else}}{{range .VisibleCommands}}
+   {{join .Names ", "}}{{"\t"}}{{.Usage}}{{end}}{{end}}{{end}}{{end}}{{if .VisibleFlags}}
+
+GLOBAL OPTIONS:
+   {{range $index, $option := .VisibleFlags}}{{if $index}}
+   {{end}}{{$option}}{{end}}{{end}}{{if .Copyright}}
+
+COPYRIGHT:
+   {{.Copyright}}{{end}}
+`
+)
+
+// custom cli.CommandHelpTemplate
+// "... cli.go uses text/template to render templates. You can render custom help text by setting this variable."
+const (
+	commandHelpTemplate = `NAME:
+   {{.HelpName}} - {{.Usage}}
+
+USAGE:
+   {{if .UsageText}}{{.UsageText}}{{else}}{{.HelpName}} {{if .ArgsUsage}}{{.ArgsUsage}}{{else}}[arguments...]{{end}}{{if .VisibleFlags}} [command options]{{end}} {{end}}{{if .Category}}
+
+CATEGORY:
+   {{.Category}}{{end}}{{if .Description}}
+
+DESCRIPTION:
+   {{.Description}}{{end}}{{if .VisibleFlags}}
+
+OPTIONS:
+   {{range .VisibleFlags}}{{.}}
+   {{end}}{{end}}
+`
+)
+
+// custom cli.SubcommandHelpTemplate
+// "... cli.go uses text/template to render templates. You can render custom help text by setting this variable."
+const (
+	subcommandHelpTemplate = `NAME:
+   {{.HelpName}} - {{if .Description}}{{.Description}}{{else}}{{.Usage}}{{end}}
+
+USAGE:
+   {{if .UsageText}}{{.UsageText}}{{else}}{{.HelpName}} command {{if .ArgsUsage}}{{.ArgsUsage}}{{else}}[arguments...]{{end}} {{if .VisibleFlags}} [command options]{{end}}{{end}}
+
+COMMANDS:{{range .VisibleCategories}}{{if .Name}}
+
+   {{.Name}}:{{range .VisibleCommands}}
+     {{join .Names ", "}}{{"\t"}}{{.Usage}}{{end}}{{else}}{{range .VisibleCommands}}
+   {{join .Names ", "}}{{"\t"}}{{.Usage}}{{end}}{{end}}{{end}}{{if .VisibleFlags}}
+
+OPTIONS:
+   {{range .VisibleFlags}}{{.}}
+   {{end}}{{end}}
+`
+)
diff --git a/cmn/cos/stats.go b/cmn/cos/stats.go
@@ -1,6 +1,6 @@
 // Package cos provides common low-level types and utilities for all aistore projects
 /*
- * Copyright (c) 2018-2024, NVIDIA CORPORATION. All rights reserved.
+ * Copyright (c) 2018-2025, NVIDIA CORPORATION. All rights reserved.
  */
 package cos
 

diff --git a/deploy/dev/k8s/README.md b/deploy/dev/k8s/README.md
@@ -318,7 +318,7 @@ NAME:
    ais etl - use ETLs
 
 USAGE:
-   ais etl command [command options] [arguments...]
+   ais etl command [arguments...] [command options]
 
 COMMANDS:
    init    initialize ETL with yaml spec
@@ -337,7 +337,7 @@ NAME:
    ais etl object - transform object with given ETL
 
 USAGE:
-   ais etl object [command options] ETL_NAME BUCKET/OBJECT_NAME OUTPUT
+   ais etl object ETL_NAME BUCKET/OBJECT_NAME OUTPUT [command options]
 
 OPTIONS:
    --help, -h  show help

diff --git a/docs/blob_downloader.md b/docs/blob_downloader.md
@@ -77,7 +77,7 @@ NAME:
    When _not_ using '--progress' option, run 'ais show job' to monitor.
 
 USAGE:
-   ais blob-download [command options] BUCKET/OBJECT_NAME
+   ais blob-download BUCKET/OBJECT_NAME [command options]
 
 OPTIONS:
    --refresh value      interval for continuous monitoring;

diff --git a/docs/bucket.md b/docs/bucket.md
@@ -425,7 +425,7 @@ NAME:
      - 'evict "gs://abc/shard-{0000..9999}.tar.lz4"'             - same as above (notice double quotes)
 
 USAGE:
-   ais evict [command options] BUCKET[/OBJECT_NAME_or_TEMPLATE] [BUCKET[/OBJECT_NAME_or_TEMPLATE] ...]
+   ais evict BUCKET[/OBJECT_NAME_or_TEMPLATE] [BUCKET[/OBJECT_NAME_or_TEMPLATE] ...] [command options]
 
 OPTIONS:
    --list value         comma-separated list of object or file names, e.g.:

diff --git a/docs/cli/advanced.md b/docs/cli/advanced.md
@@ -23,7 +23,7 @@ Commands for special use cases (e.g. scripting) and *advanced* usage scenarios,
 $ ais advanced --help
 
 USAGE:
-   ais advanced command [command options] [arguments...]
+   ais advanced command [arguments...] [command options]
 
 COMMANDS:
    resilver          resilver user data on a given target (or all targets in the cluster); entails:

diff --git a/docs/cli/archive.md b/docs/cli/archive.md
@@ -37,7 +37,7 @@ NAME:
               - ais://abc/trunk-0123.tar 333.tar --archregx=subdir/ --archmode=prefix - 333.tar with all subdir/* files --/--
 
 USAGE:
-   ais archive get [command options] BUCKET[/SHARD_NAME] [OUT_FILE|OUT_DIR|-]
+   ais archive get BUCKET[/SHARD_NAME] [OUT_FILE|OUT_DIR|-] [command options]
 
 OPTIONS:
    --checksum           validate checksum
@@ -126,7 +126,7 @@ NAME:
      - to archive objects from a ais:// or remote bucket, run 'ais archive bucket' (see --help for details).
 
 USAGE:
-   ais archive put [command options] [-|FILE|DIRECTORY[/PATTERN]] BUCKET/SHARD_NAME
+   ais archive put [-|FILE|DIRECTORY[/PATTERN]] BUCKET/SHARD_NAME [command options]
 
 OPTIONS:
    --list value         comma-separated list of object or file names, e.g.:
@@ -353,7 +353,7 @@ NAME:
    ais archive bucket - archive multiple objects from SRC_BUCKET as (.tar, .tgz or .tar.gz, .zip, .tar.lz4)-formatted shard
 
 USAGE:
-   ais archive bucket [command options] SRC_BUCKET DST_BUCKET/SHARD_NAME
+   ais archive bucket SRC_BUCKET DST_BUCKET/SHARD_NAME [command options]
 
 OPTIONS:
    --template value   template to match object or file names; may contain prefix (that could be empty) with zero or more ranges
@@ -431,7 +431,7 @@ NAME:
    ais archive ls - list archived content (supported formats: .tar, .tgz or .tar.gz, .zip, .tar.lz4)
 
 USAGE:
-   ais archive ls [command options] BUCKET[/SHARD_NAME]
+   ais archive ls BUCKET[/SHARD_NAME] [command options]
 ```
 
 List archived content as a tree with archive ("shard") name as a root and archived files as leaves.
@@ -500,7 +500,7 @@ $ ais get --help
               - '-v' to produce verbose output when getting multiple objects.
 
 USAGE:
-   ais get [command options] BUCKET[/OBJECT_NAME] [OUT_FILE|OUT_DIR|-]
+   ais get BUCKET[/OBJECT_NAME] [OUT_FILE|OUT_DIR|-] [command options]
 
 OPTIONS:
    --offset value    object read offset; must be used together with '--length'; default formatting: IEC (use '--units' to override)

diff --git a/docs/cli/blob-downloader.md b/docs/cli/blob-downloader.md
@@ -30,7 +30,7 @@ NAME:
    Note: when _not_ using '--progress' option, run 'ais show job' to monitor.
 
 USAGE:
-   ais blob-download [command options] BUCKET/OBJECT_NAME
+   ais blob-download BUCKET/OBJECT_NAME [command options]
 
 OPTIONS:
    --refresh value      interval for continuous monitoring;

diff --git a/docs/cli/bucket.md b/docs/cli/bucket.md
@@ -164,7 +164,7 @@ Operation "destroy-bck" is not supported by "aws://bucket_name"
 
 ## List buckets
 
-`ais ls [command options] PROVIDER:[//BUCKET_NAME]`
+`ais ls PROVIDER:[//BUCKET_NAME]` [command options]
 
 **Notice** the optional `[//BUCKET_NAME]`. When there's no bucket, `ais ls` will list **buckets**. Otherwise, it'll list **objects**.
 
@@ -257,7 +257,7 @@ As a rule of thumb, when a (logical) `#namespace` in the bucket's name is omitte
 
 The command:
 
-`ais ls [command options] PROVIDER:[//BUCKET_NAME]`
+`ais ls PROVIDER:[//BUCKET_NAME]` [command options]
 
 can conveniently list buckets (with or without "summarizing" object counts and sizes) and objects.
 
@@ -297,7 +297,7 @@ NAME:
      * ais ls s3 --summary --all --dont-add           - same as above but without adding _non-present_ remote buckets to the cluster's BMD.
 
 USAGE:
-   ais ls [command options] [BUCKET[/PREFIX]] [PROVIDER]
+   ais ls [BUCKET[/PREFIX]] [PROVIDER] [command options]
 
 OPTIONS:
    --all                  Depending on the context, list:
@@ -638,7 +638,7 @@ To check the status, run: ais show job xaction mvlb ais://new_bucket_name
 
 ## Copy (list, range, and/or prefix) selected objects or entire (in-cluster or remote) buckets
 
-`ais cp [command options] SRC_BUCKET[/OBJECT_NAME_or_TEMPLATE] DST_BUCKET`
+`ais cp SRC_BUCKET[/OBJECT_NAME_or_TEMPLATE] DST_BUCKET` [command options]
 
 ```console
 $ ais cp --help
@@ -664,7 +664,7 @@ NAME:
      - 'ais cp gs://webdataset-coco/d-tokens/ ais:/dst --progress --all'                          - same as above.
 
 USAGE:
-   ais cp [command options] SRC_BUCKET[/OBJECT_NAME_or_TEMPLATE] DST_BUCKET
+   ais cp SRC_BUCKET[/OBJECT_NAME_or_TEMPLATE] DST_BUCKET [command options]
 
 OPTIONS:
    --all                  Copy all objects from a remote bucket including those that are not present (not cached) in cluster
@@ -899,7 +899,7 @@ Notice a certain limitation (that also shows up as the last step #15):
 
 ## Show bucket summary
 
-`ais storage summary [command options] PROVIDER:[//BUCKET_NAME] - show bucket sizes and the respective percentages of used capacity on a per-bucket basis
+`ais storage summary PROVIDER:[//BUCKET_NAME] - show bucket sizes and the respective percentages of used capacity on a per-bucket basis [command options]
 
 `ais bucket summary` - same as above.
 
@@ -910,7 +910,7 @@ NAME:
    ais storage summary - show bucket sizes and %% of used capacity on a per-bucket basis
 
 USAGE:
-   ais storage summary [command options] PROVIDER:[//BUCKET_NAME]
+   ais storage summary PROVIDER:[//BUCKET_NAME] [command options]
 
 OPTIONS:
    --refresh value   interval for continuous monitoring;
@@ -963,7 +963,7 @@ NAME:
      * ais scrub gs://abc --prefix images/  - same as above.
 
 USAGE:
-   ais storage validate [command options] [BUCKET[/PREFIX]] or [PROVIDER]
+   ais storage validate [BUCKET[/PREFIX]] or [PROVIDER] [command options]
 
 OPTIONS:
    --refresh value        time interval for continuous monitoring; can be also used to update progress bar (at a given interval);