Refresh CLI docs: vault agent family (#28770)

* save progress

* fix file name

* save progress

* save progress

* remove uneeded subheader

* Fix build error

* fix another build error

website/content/docs/commands/agent/generate-config.mdx

@@ -0,0 +1,115 @@
+---
+layout: docs
+page_title: "agent generate-config - Vault CLI"
+description: >-
+  Use vault agent generate-config to generate a basic Vault Agent configuration
+  file from secrets plugin data.
+---
+
+# `agent generate-config`
+
+Use secrets plugin data to generate a basic
+[configuration file](/vault/docs/agent-and-proxy/agent#configuration-file-options)
+for running Vault Agent in [process supervisor mode](/vault/docs/agent-and-proxy/agent/process-supervisor).
+
+<CodeBlockConfig hideClipboard>
+
+```shell-session
+$ vault agent generate-config -type <config_file_type> [options] [<file_path>]
+```
+
+</CodeBlockConfig>
+
+## Description 
+
+`agent generate-config` composes configuration details for Vault Agent
+based on the configuration `type` and writes a local configuration file for
+running Vault agent in process supervisor mode.
+
+<Tip title="Related API endpoints">
+
+  - None
+
+</Tip>
+
+### Limitations and warnings
+
+Limitations:
+
+- Plugin support limited to KV plugins.
+- Configuration type limited to environment variable templates.
+
+<Warning title="Not appropriate for production">
+
+  The file created by `agent generate-config` includes an `auto_auth` section
+  configured to use the `token_file` authentication method.
+
+  Token files are convenient for local testing, but **are not** appropriates for
+  production use. Refer to the full list of Vault Agent
+  [autoAuth methods](/vault/docs/agent-and-proxy/autoauth/methods) for available
+  production-ready authentication methods.
+
+</Warning>
+
+## Arguments
+
+<br />
+
+@include 'cli/agent/args/file_path.mdx'
+
+
+
+## Options
+
+None.
+
+
+
+## Command Flags
+
+<br />
+
+@include 'cli/agent/flags/exec.mdx'
+
+<br /><hr /><br />
+
+@include 'cli/agent/flags/path.mdx'
+
+<br /><hr /><br />
+
+@include 'cli/agent/flags/type.mdx'
+
+
+
+## Global flags
+
+<br />
+
+@include 'cli/standard-settings/all-standard-flags-but-format.mdx'
+
+
+
+## Examples
+
+Generate an environment variable template configuration for the `foo` secrets
+plugin:
+
+```shell-session
+$ vault agent generate-config  \
+    -type="env-template"       \
+    -exec="./my-app arg1 arg2" \
+    -path="secret/foo"
+
+Command output
+```
+
+Generate an environment variable template configuration for more than one
+secrets plugin:
+
+```shell-session
+$ vault agent generate-config -type="env-template" \
+    -exec="./my-app arg1 arg2" \
+    -path="secret/foo" \
+    -path="secret/bar" \
+    -path="secret/my-app/*"
+```

website/content/docs/commands/agent/index.mdx

@@ -0,0 +1,101 @@
+---
+layout: docs
+page_title: "agent - Vault CLI"
+description: >-
+  Use vault agent to start an instance of Vault Agent.
+---
+
+# `vault agent`
+
+Start an instance of Vault Agent.
+
+<CodeBlockConfig hideClipboard>
+
+```shell-session
+$ vault agent -config <config_file>
+
+$ vault agent [-help | -h]
+```
+
+</CodeBlockConfig>
+
+## Description
+
+`vault agent` start an instance of Vault Agent, which automatically
+authenticates and fetches secrets for client applications.
+
+<Tip title="Related API endpoints">
+
+  **None**
+
+</Tip>
+
+## Command arguments
+
+None.
+
+## Command options
+
+None.
+
+## Command flags
+
+<br />
+
+@include 'cli/agent/flags/config.mdx'
+
+<br /><hr /><br />
+
+@include 'cli/agent/flags/exit-after-auth.mdx'
+
+<br /><hr /><br />
+
+@include 'cli/shared/flags/log-file.mdx'
+
+<br /><hr /><br />
+
+@include 'cli/shared/flags/log-format.mdx'
+
+<br /><hr /><br />
+
+@include 'cli/shared/flags/log-level.mdx'
+
+<br /><hr /><br />
+
+@include 'cli/shared/flags/log-rotate-bytes.mdx'
+
+<br /><hr /><br />
+
+@include 'cli/shared/flags/log-rotate-duration.mdx'
+
+<br /><hr /><br />
+
+@include 'cli/shared/flags/log-rotate-max-files.mdx'
+
+## Standard flags
+
+<br />
+
+@include 'cli/standard-settings/all-standard-flags-but-format.mdx'
+
+## Examples
+
+Start Vault Agent with a single configuration file:
+
+```shell-session
+$ vault agent -config=/etc/vault/agent/config.hcl
+```
+
+Start Vault Agent with a two discrete configuration files:
+
+```shell-session
+$ vault agent                                   \
+    -config=/etc/vault/agent/base-config.hcl    \
+    -config=/etc/vault/agent/auto-auth-config.hcl
+```
+
+Start Vault Agent with a set of configuration files under the `` directory:
+
+```shell-session
+$ vault agent -config=/etc/vault/agent/config-files/
+```

website/content/docs/commands/audit/enable.mdx

@@ -31,9 +31,7 @@ configuration parameters depend on the audit device type.
 
 </Tip>
 
-### Limitations and warnings 
 
-- None
 
 ## Command arguments
 

website/content/docs/commands/audit/list.mdx

@@ -29,10 +29,6 @@ $ vault audit list [-help | -h]
 
 </Tip>
 
-### Limitations and warnings
-
-None.
-
 ## Command arguments
 
 None.

website/content/docs/commands/index.mdx

@@ -243,7 +243,7 @@ command.
 
 ---
 
-@include 'cli/standard-settings/all-env-variables.mdx'
+@include 'global-settings/all-env-variables.mdx'
 
 
 

website/content/partials/cli/README.md

@@ -0,0 +1,22 @@
+
+We document CLI command arguments, options, and flags as partials:
+
+- as a first step toward templatizing and autogenerating the CLI command pages.
+- to make it easier to include and maintain elements shared across commands in
+  the same family.
+- to make it easier to include and maintain elements shared across command
+  families.
+- to make it easier to include information about standard flags on the command
+  pages.
+
+
+Partial template for CLI elements (required elements use <required> in place of
+a default value):
+
+<a id="COMMAND-[arg | option | flag]-NAME" />
+
+**`-NAME (TYPE : DEFAULT)`**
+
+DESCRIPTION
+
+**Example**: `EXAMPLE_OF_VALID_USE`

website/content/partials/cli/agent/args/file_path.mdx

@@ -0,0 +1,7 @@
+<a id="agent-arg-file_path" />
+
+**`file_path (string : "./agent.hcl")`**
+
+The path where Vault should save the generated configuration file.
+
+**Example**: `"./agent/custom-config.hcl"`

website/content/partials/cli/agent/flags/config.mdx

@@ -0,0 +1,12 @@
+<a id="agent-flag-config" />
+
+**`-config (string : <required>)`**
+
+Path to a single
+[Vault Agent configuration file](/vault/docs/agent-and-proxy/agent#configuration-file-options)
+or directory of configuration files with agent directives. Repeat the `-config`
+flag as needed to specify more than one discrete configuration file. If you
+specify more than one configuration file, Agent composes the source files into
+a single configuration file at runtime.
+
+**Example**: `-config /path/to/file.hcl`

website/content/partials/cli/agent/flags/exec.mdx

@@ -0,0 +1,9 @@
+<a id="agent-flag-exec" />
+
+**`-exec (string : "")`**
+
+Path to the command for child processes with optional arguments. Relative paths
+start from the current working directory when executed. Corresponds to
+`exec.command` in the Vault Agent configuration file.
+
+**Example**: `-exec "./my-app arg1 arg2"`

website/content/partials/cli/agent/flags/exit-after-auth.mdx

@@ -0,0 +1,8 @@
+<a id="agent-flag-exit-after-auth" />
+
+**`-exit-after-auth (bool : false)`**
+
+Exit with code `0` after a single successful auth. Success indicates successful
+token retrieval and write to sink.
+
+**Example**: `-exit-after-auth`

website/content/partials/cli/agent/flags/path.mdx

@@ -0,0 +1,12 @@
+<a id="agent-flag-path" />
+
+**`-path (string : "")`**
+
+Path to one or more `kv` secrets store. Paths that end with a wildcard (`*`)
+include all secrets under that path.
+
+Repeat the `-path` flag as needed to specify the full set of target secrets.
+
+
+**Example**: `-path secret/kv/agent-keys/*`
+

website/content/partials/cli/agent/flags/type.mdx

@@ -0,0 +1,11 @@
+<a id="agent-flag-type" />
+
+**`-type (enum : <required>)`**
+
+The configuration file entry to create.
+
+Enum           | Description
+-------------- | -----------
+`env-template` | Create environment variable templates from JSON keys in `kv` plugins
+
+**Example**: `-type env-template`

website/content/partials/cli/audit/args/device_path.mdx

@@ -1,6 +1,6 @@
 <a id="audit-arg-path" />
 
-**`path (string : <required>)`**
+**`device_path (string : <required>)`**
 
 The internal path where Vault accesses the audit device. Audit device paths are
 unique across all audit devices.

website/content/partials/cli/shared/flags/log-file.mdx

@@ -0,0 +1,12 @@
+<a id="shared-flag-log-file" />
+
+**`-log-file (string : "./<service>.log")`**
+
+Absolute path where Vault Agent saves logging data.
+
+- Paths ending with `/` use the default file name `<service>.log`. For example,
+  `vault.log` for Vault and `agent.log` for Vault Agent.
+- Paths ending with a name but not an extension use the `.log` extension.
+- Paths ending with a name and extension use the provided file name.
+
+**Example**: `-log-file "/var/log/vault-logs/"`

website/content/partials/cli/shared/flags/log-format.mdx

@@ -0,0 +1,9 @@
+<!--
+
+  Alias file for the global log-format partial to keep CLI-related partials
+  together and anchor names consistent.
+-->
+
+<a id="shared-flag-log-format" />
+
+@include 'global-settings/both/log-format.mdx'

website/content/partials/cli/shared/flags/log-level.mdx

@@ -0,0 +1,9 @@
+<!--
+
+  Alias file for the global log-level partial to keep CLI-related partials
+  together and anchor names consistent.
+-->
+
+<a id="shared-flag-log-level" />
+
+@include 'global-settings/both/log-level.mdx'