agent: Better help text for agent generate-config (#20967)

command/agent_generate_config.go

@@ -40,7 +40,46 @@ func (c *AgentGenerateConfigCommand) Synopsis() string {
 
 func (c *AgentGenerateConfigCommand) Help() string {
 	helpText := `
-Usage: vault agent generate-config [options] [args]
+Usage: vault agent generate-config [options] [path/to/config.hcl]
+
+  Generates a simple Vault Agent configuration file from the given parameters.
+
+  Currently, the only supported configuration type is 'env-template', which
+  helps you generate a configuration file with environment variable templates
+  for running Vault Agent in process supervisor mode.
+
+  For every specified secret -path, the command will attempt to generate one or
+  multiple 'env_template' entries based on the JSON key(s) stored in the
+  specified secret. If the secret -path ends with '/*', the command will
+  attempt to recurse through the secrets tree rooted at the given path,
+  generating 'env_template' entries for each encountered secret. Currently,
+  only kv-v1 and kv-v2 paths are supported.
+
+  The command specified in the '-exec' option will be used to generate an
+  'exec' entry, which will tell Vault Agent which child process to run.
+
+  In addition to env_template entries, the command generates an 'auto_auth'
+  section with 'token_file' authentication method. While this method is very
+  convenient for local testing, it should NOT be used in production. Please
+  see https://developer.hashicorp.com/vault/docs/agentandproxy/autoauth for
+  a list of production-ready auto_auth methods that you can use instead.
+
+  By default, the file will be generated in the local directory as 'agent.hcl'
+  unless a path is specified as an argument.
+
+  Generate a simple environment variable template configuration:
+
+      $ vault agent generate-config -type="env-template" \
+                    -exec="./my-app arg1 arg2" \
+                    -path="secret/foo"
+
+  Generate an environment variable template configuration for multiple secrets:
+
+      $ vault agent generate-config -type="env-template" \
+                    -exec="./my-app arg1 arg2" \
+                    -path="secret/foo" \
+                    -path="secret/bar" \
+                    -path="secret/my-app/*"
 
 ` + c.Flags().Help()
 
@@ -73,7 +112,7 @@ func (c *AgentGenerateConfigCommand) Flags() *FlagSets {
 		Name:    "exec",
 		Target:  &c.flagExec,
 		Default: "env",
-		Usage:   "The command to execute in env-template mode.",
+		Usage:   "The command to execute in agent process supervisor mode.",
 	})
 
 	return set