From 13cf0ae4274490e2877d5d1013e5336367d014c7 Mon Sep 17 00:00:00 2001 From: Sarah Chavis <62406755+schavis@users.noreply.github.com> Date: Wed, 20 Nov 2024 10:33:03 -0800 Subject: [PATCH] [DOCS] Tweak the new CLI partials (#28964) * save for stash pop * fix anchor IDs and wrap parameters in links for easier use --- website/content/partials/cli/README.md | 98 ++++++++++++++++- .../partials/cli/agent/args/file_path.mdx | 4 + .../partials/cli/agent/flags/config.mdx | 5 + .../content/partials/cli/agent/flags/exec.mdx | 4 + .../cli/agent/flags/exit-after-auth.mdx | 4 + .../content/partials/cli/agent/flags/path.mdx | 4 + .../content/partials/cli/agent/flags/type.mdx | 4 + .../partials/cli/audit/args/device_path.mdx | 6 +- .../partials/cli/audit/args/device_type.mdx | 8 +- .../cli/audit/args/file/file_path.mdx | 6 +- .../partials/cli/audit/args/file/mode.mdx | 6 +- .../cli/audit/args/socket/address.mdx | 6 +- .../cli/audit/args/socket/socket_type.mdx | 6 +- .../cli/audit/args/socket/write_timeout.mdx | 6 +- .../cli/audit/args/syslog/facility.mdx | 6 +- .../partials/cli/audit/args/syslog/tag.mdx | 6 +- .../partials/cli/audit/flags/description.mdx | 4 + .../partials/cli/audit/flags/detailed.mdx | 4 + .../partials/cli/audit/flags/local.mdx | 4 + .../content/partials/cli/audit/flags/path.mdx | 4 + .../audit/options/elide_list_responses.mdx | 6 +- .../partials/cli/audit/options/exclude.mdx | 14 ++- .../partials/cli/audit/options/fallback.mdx | 6 +- .../partials/cli/audit/options/filter.mdx | 6 +- .../partials/cli/audit/options/format.mdx | 6 +- .../cli/audit/options/hmac_accessor.mdx | 6 +- .../partials/cli/audit/options/log_raw.mdx | 6 +- .../partials/cli/audit/options/prefix.mdx | 6 +- .../partials/cli/shared/flags/log-file.mdx | 4 + .../cli/shared/flags/log-rotate-bytes.mdx | 4 + .../cli/shared/flags/log-rotate-duration.mdx | 4 + .../cli/shared/flags/log-rotate-max-files.mdx | 6 +- .../partials/global-settings/both/address.mdx | 4 + .../global-settings/both/agent-address.mdx | 4 + .../partials/global-settings/both/ca-cert.mdx | 4 + .../partials/global-settings/both/ca-path.mdx | 4 + .../global-settings/both/client-cert.mdx | 4 + .../global-settings/both/client-key.mdx | 4 + .../both/disable-redirects.mdx | 4 + .../partials/global-settings/both/format.mdx | 10 +- .../global-settings/both/log-format.mdx | 4 + .../global-settings/both/log-level.mdx | 4 + .../partials/global-settings/both/mfa.mdx | 4 + .../global-settings/both/namespace.mdx | 4 + .../global-settings/both/tls-server-name.mdx | 4 + .../global-settings/both/tls-skip-verify.mdx | 4 + .../global-settings/both/wrap-ttl.mdx | 4 + .../global-settings/env/cli_no_color.mdx | 4 + .../global-settings/env/client_timeout.mdx | 4 + .../global-settings/env/cluster_addr.mdx | 4 + .../global-settings/env/http_proxy.mdx | 4 + .../partials/global-settings/env/license.mdx | 4 + .../global-settings/env/license_path.mdx | 4 + .../global-settings/env/max_retries.mdx | 4 + .../global-settings/env/proxy_addr.mdx | 4 + .../global-settings/env/rate_limit.mdx | 4 + .../global-settings/env/redirect_addr.mdx | 4 + .../global-settings/env/skip_verify.mdx | 4 + .../global-settings/env/srv_lookup.mdx | 4 + .../partials/global-settings/env/token.mdx | 4 + .../partials/global-settings/flags/header.mdx | 4 + .../global-settings/flags/non-interactive.mdx | 4 + .../flags/output-curl-string.mdx | 4 + .../global-settings/flags/output-policy.mdx | 4 + .../global-settings/flags/policy-override.mdx | 4 + .../global-settings/flags/unlock-key.mdx | 4 + website/templates/cli-page.mdx | 104 ++++++++++++++++++ 67 files changed, 484 insertions(+), 31 deletions(-) create mode 100644 website/templates/cli-page.mdx diff --git a/website/content/partials/cli/README.md b/website/content/partials/cli/README.md index 74329cd158..6cd61bf7b9 100644 --- a/website/content/partials/cli/README.md +++ b/website/content/partials/cli/README.md @@ -1,22 +1,108 @@ +## Terminology + +non-runnable a command with no side-effects other than printing help text. +command tree a hierarchical graph of CLI commands where internal nodes are + non-runnable and leaf nodes represent runnable CLI commands. +root command the root node in a tree or subtree of CLI commands. For example, + `plugin` is the root node for all plugin commands and + `plugin runtime` is the root node for runtime commands. +command family - the top-most root command for a collection of CLI commands. + For example `audit` or `plugin`. + +### Exceptions :( + +The `agent` family of commands is malformed. Rather than having a root node +(`agent`) with two subcommands (`agent start` and `agent generate-config`), the +root command is runnable. + + +## Why partials? 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 +- to make it easier to include and maintain parameters shared across commands in the same family. -- to make it easier to include and maintain elements shared across command +- to make it easier to include and maintain parameters 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 in place of -a default value): +## Directory structure - +partials/cli/ partials specific to a command family +partials/cli//args command-family arguments +partials/cli//flags command-family flags +partials/cli//options command-family options -**`-NAME (TYPE : DEFAULT)`** +partials/cli/shared partials for parameters shared across some, but not all, command families +partials/cli/shared/args shared arguments (does not exist yet) +partials/cli/shared/flags shared flags +partials/cli/shared/options shared options (does not exist yet) + +partials/global-settings partials for standard/global parameters +partials/global-settings/flags global flags (e.g., `-header`) +partials/global-settings/env global environment variables (e.g., `VAULT_LICENSE`) +partials/global-settings/both parameters that exits as flags and variables + +## Partial templates + +- Use the parameter name as the file name and "NAME" in the anchor definition, + even if the use of dashes or underscores is inconsistent with other parameters + or partial names. For example, if the flag is `-my_weird_flag`, make the + partial filename `my_weird_flag.mdx` and the anchor ID + `COMMAND-flag-my_weird_flag`. +- If the parameter is shared across command families, but not applicable to **all** + command families, it belongs under `partials/cli/shared` +- If the parameter is a flag with a cooresponding environment variable but + **does not** apply to all commands, talk with a technical writer before + creating your partials. +- If the parameter is required, use `` for the default entry. +- Include `-` as part of the name for flag names **except for anchor IDs**. +- Use `=` in example text for options +- Omit `=` in example text for flags + +### Template 1 - command-specific parameters + +Use the following template for parameters that exist as command-exclusively +arguments, flags, or options. "ANCHOR_ID" is the ID defined in the `` +HTML tag. + +-- Template (start) -- + + + + + + +**`NAME (TYPE : DEFAULT)`** + + DESCRIPTION **Example**: `EXAMPLE_OF_VALID_USE` + +-- Template (end) -- + + + +### Template 2 - shared parameters + +Use the following template for parameters that exist as arguments, flags, or +options that are not global but are shared across more than one command family. +"ANCHOR_ID" is the ID defined in the `` HTML tag. + + + + + + +**`NAME (TYPE : DEFAULT)`** + + + +DESCRIPTION + +**Example**: `EXAMPLE_OF_VALID_USE` \ No newline at end of file diff --git a/website/content/partials/cli/agent/args/file_path.mdx b/website/content/partials/cli/agent/args/file_path.mdx index bfd554bcdf..bb0048aec7 100644 --- a/website/content/partials/cli/agent/args/file_path.mdx +++ b/website/content/partials/cli/agent/args/file_path.mdx @@ -1,7 +1,11 @@ + + **`file_path (string : "./agent.hcl")`** + + The path where Vault should save the generated configuration file. **Example**: `"./agent/custom-config.hcl"` \ No newline at end of file diff --git a/website/content/partials/cli/agent/flags/config.mdx b/website/content/partials/cli/agent/flags/config.mdx index f339548d3b..fee77d50ae 100644 --- a/website/content/partials/cli/agent/flags/config.mdx +++ b/website/content/partials/cli/agent/flags/config.mdx @@ -1,7 +1,12 @@ + + **`-config (string : )`** + + + 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` diff --git a/website/content/partials/cli/agent/flags/exec.mdx b/website/content/partials/cli/agent/flags/exec.mdx index ba0e9664cc..b14c9d0a16 100644 --- a/website/content/partials/cli/agent/flags/exec.mdx +++ b/website/content/partials/cli/agent/flags/exec.mdx @@ -1,7 +1,11 @@ + + **`-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. diff --git a/website/content/partials/cli/agent/flags/exit-after-auth.mdx b/website/content/partials/cli/agent/flags/exit-after-auth.mdx index 4f3c1a2a36..c026ba5ec9 100644 --- a/website/content/partials/cli/agent/flags/exit-after-auth.mdx +++ b/website/content/partials/cli/agent/flags/exit-after-auth.mdx @@ -1,7 +1,11 @@ + + **`-exit-after-auth (bool : false)`** + + Exit with code `0` after a single successful auth. Success indicates successful token retrieval and write to sink. diff --git a/website/content/partials/cli/agent/flags/path.mdx b/website/content/partials/cli/agent/flags/path.mdx index bd1a3debd4..051602f69c 100644 --- a/website/content/partials/cli/agent/flags/path.mdx +++ b/website/content/partials/cli/agent/flags/path.mdx @@ -1,7 +1,11 @@ + + **`-path (string : "")`** + + Path to one or more `kv` secrets store. Paths that end with a wildcard (`*`) include all secrets under that path. diff --git a/website/content/partials/cli/agent/flags/type.mdx b/website/content/partials/cli/agent/flags/type.mdx index 216a84c92e..8bc947549e 100644 --- a/website/content/partials/cli/agent/flags/type.mdx +++ b/website/content/partials/cli/agent/flags/type.mdx @@ -1,7 +1,11 @@ + + **`-type (enum : )`** + + The configuration file entry to create. Enum | Description diff --git a/website/content/partials/cli/audit/args/device_path.mdx b/website/content/partials/cli/audit/args/device_path.mdx index 6d2160586f..ee0ebb7027 100644 --- a/website/content/partials/cli/audit/args/device_path.mdx +++ b/website/content/partials/cli/audit/args/device_path.mdx @@ -1,7 +1,11 @@ - + + + **`device_path (string : )`** + + The internal path where Vault accesses the audit device. Audit device paths are unique across all audit devices. diff --git a/website/content/partials/cli/audit/args/device_type.mdx b/website/content/partials/cli/audit/args/device_type.mdx index 3a8a75cbeb..eabfab07f9 100644 --- a/website/content/partials/cli/audit/args/device_type.mdx +++ b/website/content/partials/cli/audit/args/device_type.mdx @@ -1,6 +1,10 @@ - + -**`device_type (enum : )`** + + +**`audit-arg-device_type (enum : )`** + + The audit device type to create. diff --git a/website/content/partials/cli/audit/args/file/file_path.mdx b/website/content/partials/cli/audit/args/file/file_path.mdx index bd0f45a4c0..4f3a3eac59 100644 --- a/website/content/partials/cli/audit/args/file/file_path.mdx +++ b/website/content/partials/cli/audit/args/file/file_path.mdx @@ -1,7 +1,11 @@ - + + + **`file_path (string : )`** + + Location on the audit log on the Vault server. Must be one of the following: Value | Description diff --git a/website/content/partials/cli/audit/args/file/mode.mdx b/website/content/partials/cli/audit/args/file/mode.mdx index fbd575bb16..e416b915b5 100644 --- a/website/content/partials/cli/audit/args/file/mode.mdx +++ b/website/content/partials/cli/audit/args/file/mode.mdx @@ -1,7 +1,11 @@ - + + + **`mode (string : "0600")`** + + The `chmod`-style octal permissions for the audit file. Set `mode` to "0000" to prevent Vault from modifying the file mode. diff --git a/website/content/partials/cli/audit/args/socket/address.mdx b/website/content/partials/cli/audit/args/socket/address.mdx index ef764ddf22..38cd2cc80d 100644 --- a/website/content/partials/cli/audit/args/socket/address.mdx +++ b/website/content/partials/cli/audit/args/socket/address.mdx @@ -1,7 +1,11 @@ - + + + **`address (string : "")`** + + Location of the socket as a server IP and port or a local path. **Example**: `address="/tmp/audit.sock"` diff --git a/website/content/partials/cli/audit/args/socket/socket_type.mdx b/website/content/partials/cli/audit/args/socket/socket_type.mdx index ee2e8a3e6d..a564c6c0e4 100644 --- a/website/content/partials/cli/audit/args/socket/socket_type.mdx +++ b/website/content/partials/cli/audit/args/socket/socket_type.mdx @@ -1,7 +1,11 @@ - + + + **`socket_type (string : "tcp")`** + + Communication protocol expected by the socket. Vault can write to any [net.Dialer](https://pkg.go.dev/net#Dialer)-compatible socket. If a TCP socket stops responding, Vault may become unresponsive due to a diff --git a/website/content/partials/cli/audit/args/socket/write_timeout.mdx b/website/content/partials/cli/audit/args/socket/write_timeout.mdx index 205fe62bbc..e5ea695085 100644 --- a/website/content/partials/cli/audit/args/socket/write_timeout.mdx +++ b/website/content/partials/cli/audit/args/socket/write_timeout.mdx @@ -1,7 +1,11 @@ - + + + **`write_timeout (string : "2s")`** + + Duration in seconds that Vault will wait for a write to complete over the socket. Setting `write_timeout` to `0` disables time outs and forces Vault to always wait until the write completes. diff --git a/website/content/partials/cli/audit/args/syslog/facility.mdx b/website/content/partials/cli/audit/args/syslog/facility.mdx index 18e2204844..9de92fb008 100644 --- a/website/content/partials/cli/audit/args/syslog/facility.mdx +++ b/website/content/partials/cli/audit/args/syslog/facility.mdx @@ -1,7 +1,11 @@ - + + + **`facility (string : "AUTH")`** + + The process that generated the syslog entry (the syslog facility). **Example**: `facility="AUTO-AUTH"` diff --git a/website/content/partials/cli/audit/args/syslog/tag.mdx b/website/content/partials/cli/audit/args/syslog/tag.mdx index 66024e3042..7f1bd2e666 100644 --- a/website/content/partials/cli/audit/args/syslog/tag.mdx +++ b/website/content/partials/cli/audit/args/syslog/tag.mdx @@ -1,7 +1,11 @@ - + + + **`tag (string : "vault")`** + + The program that generated the syslog entry. **Example**: `tag="vault-agent"` diff --git a/website/content/partials/cli/audit/flags/description.mdx b/website/content/partials/cli/audit/flags/description.mdx index d106c4c16c..dad60a6a20 100644 --- a/website/content/partials/cli/audit/flags/description.mdx +++ b/website/content/partials/cli/audit/flags/description.mdx @@ -1,7 +1,11 @@ + + **`-description (string : "")`** + + A human-friendly string that explains the purpose of the audit device. **Example**: `-description "KV request auditing"` diff --git a/website/content/partials/cli/audit/flags/detailed.mdx b/website/content/partials/cli/audit/flags/detailed.mdx index 267458dff4..27a3db3de6 100644 --- a/website/content/partials/cli/audit/flags/detailed.mdx +++ b/website/content/partials/cli/audit/flags/detailed.mdx @@ -1,7 +1,11 @@ + + **`-detailed (bool : false)`** + + Print detailed information such as options and replication status about each audit device. diff --git a/website/content/partials/cli/audit/flags/local.mdx b/website/content/partials/cli/audit/flags/local.mdx index 9c8cbe4a2b..f9667ac3f3 100644 --- a/website/content/partials/cli/audit/flags/local.mdx +++ b/website/content/partials/cli/audit/flags/local.mdx @@ -1,7 +1,11 @@ + + **`-local (bool : false)`** + + Indicates that the audit device is local to the Vault server and ignored by replication. diff --git a/website/content/partials/cli/audit/flags/path.mdx b/website/content/partials/cli/audit/flags/path.mdx index 2f355410bb..4af182cd89 100644 --- a/website/content/partials/cli/audit/flags/path.mdx +++ b/website/content/partials/cli/audit/flags/path.mdx @@ -1,7 +1,11 @@ + + **`-path (string : "/")`** + + The internal path where Vault will access the audit device. Audit device paths must be unique across all audit devices. diff --git a/website/content/partials/cli/audit/options/elide_list_responses.mdx b/website/content/partials/cli/audit/options/elide_list_responses.mdx index 0aeec756a4..382e36a98c 100644 --- a/website/content/partials/cli/audit/options/elide_list_responses.mdx +++ b/website/content/partials/cli/audit/options/elide_list_responses.mdx @@ -1,7 +1,11 @@ - + + + **`elide_list_responses (bool : false)`** + + Replace the details for `response.data.keys` and `response.data.key_info` with the number of entries to reduce the size of audit records. See [Eliding list response bodies](/vault/docs/audit#eliding-list-response-bodies) diff --git a/website/content/partials/cli/audit/options/exclude.mdx b/website/content/partials/cli/audit/options/exclude.mdx index 6e1ee3910f..3ac7861a00 100644 --- a/website/content/partials/cli/audit/options/exclude.mdx +++ b/website/content/partials/cli/audit/options/exclude.mdx @@ -1,6 +1,11 @@ - + + + + +**`exclude (string : "")`** + + -**`exclude (string : "")`** Remove any fields matching the provided [exclusion filtering rules](/vault/docs/enterprise/audit/exclusion) from the @@ -14,8 +19,9 @@ audit entry before writing to the audit device. definitions to `exclude`: ``` - $ vault audit enable exclude=@rules.json file file_path="/var/logs/vault/audit.log"' + $ vault audit enable \ + exclude=@rules.json \ + file file_path="/var/logs/vault/audit.log"' ``` - diff --git a/website/content/partials/cli/audit/options/fallback.mdx b/website/content/partials/cli/audit/options/fallback.mdx index 6cec7108ba..d00c6699ff 100644 --- a/website/content/partials/cli/audit/options/fallback.mdx +++ b/website/content/partials/cli/audit/options/fallback.mdx @@ -1,7 +1,11 @@ - + + + **`fallback (bool : false)`** + + The audit device is the fallback for filtering purposes. **Vault only supports one fallback audit device at a time**. diff --git a/website/content/partials/cli/audit/options/filter.mdx b/website/content/partials/cli/audit/options/filter.mdx index 431c3e6482..42c2bc6a2d 100644 --- a/website/content/partials/cli/audit/options/filter.mdx +++ b/website/content/partials/cli/audit/options/filter.mdx @@ -1,7 +1,11 @@ - + + + **`filter (string : "")`** + + Only write audit log entries matching the provided [filtering expression](/vault/docs/enterprise/audit/filtering) to the audit device. diff --git a/website/content/partials/cli/audit/options/format.mdx b/website/content/partials/cli/audit/options/format.mdx index 1218ec0191..3dfac1137c 100644 --- a/website/content/partials/cli/audit/options/format.mdx +++ b/website/content/partials/cli/audit/options/format.mdx @@ -1,7 +1,11 @@ - + + + **`format (enum : json)`** + + Write audit log entries in the provided format. Enum | Description diff --git a/website/content/partials/cli/audit/options/hmac_accessor.mdx b/website/content/partials/cli/audit/options/hmac_accessor.mdx index fe4a88421f..79f4968bd5 100644 --- a/website/content/partials/cli/audit/options/hmac_accessor.mdx +++ b/website/content/partials/cli/audit/options/hmac_accessor.mdx @@ -1,7 +1,11 @@ - + + + **`hmac_accessor (bool : true)`** + + Hash all token accessor data before writing to the audit device. **Example**: `hmac_accessor=false` diff --git a/website/content/partials/cli/audit/options/log_raw.mdx b/website/content/partials/cli/audit/options/log_raw.mdx index 69870db322..d4a2eb3cd8 100644 --- a/website/content/partials/cli/audit/options/log_raw.mdx +++ b/website/content/partials/cli/audit/options/log_raw.mdx @@ -1,7 +1,11 @@ - + + + **`log_raw (bool : false)`** + + Hash all sensitive security information before writing to the audit device. **Example**: `log_raw=true` diff --git a/website/content/partials/cli/audit/options/prefix.mdx b/website/content/partials/cli/audit/options/prefix.mdx index bb6d812116..b4b2c2f08e 100644 --- a/website/content/partials/cli/audit/options/prefix.mdx +++ b/website/content/partials/cli/audit/options/prefix.mdx @@ -1,7 +1,11 @@ - + + + **`prefix (string : "")`** + + Prepend the provided string to each log entry when writing to the audit device. **Example**: `prefix="KV Request :: "` diff --git a/website/content/partials/cli/shared/flags/log-file.mdx b/website/content/partials/cli/shared/flags/log-file.mdx index 7e75bfd6e8..cddc393b5e 100644 --- a/website/content/partials/cli/shared/flags/log-file.mdx +++ b/website/content/partials/cli/shared/flags/log-file.mdx @@ -1,7 +1,11 @@ + + **`-log-file (string : "./.log")`** + + Absolute path where Vault Agent saves logging data. - Paths ending with `/` use the default file name `.log`. For example, diff --git a/website/content/partials/cli/shared/flags/log-rotate-bytes.mdx b/website/content/partials/cli/shared/flags/log-rotate-bytes.mdx index 37b5a1d5de..bc476e7017 100644 --- a/website/content/partials/cli/shared/flags/log-rotate-bytes.mdx +++ b/website/content/partials/cli/shared/flags/log-rotate-bytes.mdx @@ -1,7 +1,11 @@ + + **`-log-rotate-bytes (int : )`** + + File size, in bytes, after which log files must rotate. Leave `log-rotate-bytes` unset if you prefer not to limit log file size. diff --git a/website/content/partials/cli/shared/flags/log-rotate-duration.mdx b/website/content/partials/cli/shared/flags/log-rotate-duration.mdx index 487d3e7718..f153382a9b 100644 --- a/website/content/partials/cli/shared/flags/log-rotate-duration.mdx +++ b/website/content/partials/cli/shared/flags/log-rotate-duration.mdx @@ -1,7 +1,11 @@ + + **`-log-rotate-duration (string : "24h")`** + + Amount of time, in `[s|m|h|d]` format, after which log files must rotate. diff --git a/website/content/partials/cli/shared/flags/log-rotate-max-files.mdx b/website/content/partials/cli/shared/flags/log-rotate-max-files.mdx index 1e3b6cc122..ad80b5d086 100644 --- a/website/content/partials/cli/shared/flags/log-rotate-max-files.mdx +++ b/website/content/partials/cli/shared/flags/log-rotate-max-files.mdx @@ -1,7 +1,11 @@ - + + + **`-log-rotate-max-files (int : 0)`** + + The number of log file archives to preserve over time: - *`n`* - Preserve up to `n` archived logs. diff --git a/website/content/partials/global-settings/both/address.mdx b/website/content/partials/global-settings/both/address.mdx index d8417909b6..c59ca02ca8 100644 --- a/website/content/partials/global-settings/both/address.mdx +++ b/website/content/partials/global-settings/both/address.mdx @@ -1,7 +1,11 @@ + + **`[-address | VAULT_ADDR] (string : 'https://127.0.0.1:8200')`** + + Address of the Vault server. **Examples**: diff --git a/website/content/partials/global-settings/both/agent-address.mdx b/website/content/partials/global-settings/both/agent-address.mdx index 7e27fedb28..23b4d108f4 100644 --- a/website/content/partials/global-settings/both/agent-address.mdx +++ b/website/content/partials/global-settings/both/agent-address.mdx @@ -1,7 +1,11 @@ + + **`[-agent-address | VAULT_AGENT_ADDR] (string : "")`** + + Address of the Vault Agent, if used. **Examples**: diff --git a/website/content/partials/global-settings/both/ca-cert.mdx b/website/content/partials/global-settings/both/ca-cert.mdx index b98ecfca43..1448c7fdc5 100644 --- a/website/content/partials/global-settings/both/ca-cert.mdx +++ b/website/content/partials/global-settings/both/ca-cert.mdx @@ -1,7 +1,11 @@ + + **`[-ca-cert | VAULT_CACERT] (string : "")`** + + Path to a PEM-encoded CA certificate file on the local disk. Used to verify SSL certificates for the server. **Takes precedence over `-ca_path`**. diff --git a/website/content/partials/global-settings/both/ca-path.mdx b/website/content/partials/global-settings/both/ca-path.mdx index cb8d1dfada..43d41cb77d 100644 --- a/website/content/partials/global-settings/both/ca-path.mdx +++ b/website/content/partials/global-settings/both/ca-path.mdx @@ -1,7 +1,11 @@ + + **`[-ca-path | VAULT_CAPATH] (string : "")`** + + Path to a directory with PEM-encoded CA certificate files on the local disk. Used to verify SSL certificates for the server. diff --git a/website/content/partials/global-settings/both/client-cert.mdx b/website/content/partials/global-settings/both/client-cert.mdx index dbde772483..fa7c0b3ec5 100644 --- a/website/content/partials/global-settings/both/client-cert.mdx +++ b/website/content/partials/global-settings/both/client-cert.mdx @@ -1,7 +1,11 @@ + + **`[-client-cert | VAULT_CLIENT_CERT] (string : "")`** + + Path to a PEM-encoded CA certificate file on the local disk. Used for TLS communication with the server. **The specified certificate must match to the private key specified with `-client-cert`**. diff --git a/website/content/partials/global-settings/both/client-key.mdx b/website/content/partials/global-settings/both/client-key.mdx index 12b574fb64..16bde7074b 100644 --- a/website/content/partials/global-settings/both/client-key.mdx +++ b/website/content/partials/global-settings/both/client-key.mdx @@ -1,7 +1,11 @@ + + **`[-client-key | VAULT_CLIENT_KEY] (string : "")`** + + Path to a PEM-encoded private key that matches the client certificate set with `-client-cert`. diff --git a/website/content/partials/global-settings/both/disable-redirects.mdx b/website/content/partials/global-settings/both/disable-redirects.mdx index 815de5818c..9eb2676be0 100644 --- a/website/content/partials/global-settings/both/disable-redirects.mdx +++ b/website/content/partials/global-settings/both/disable-redirects.mdx @@ -1,7 +1,11 @@ + + **`[-disable-redirects | VAULT_DISABLE_REDIRECTS] (bool : false)`** + + Disable the default CLI redirect behavior so the CLI honors the first redirect response from the underlying API instead of following the full HTTP redirect chain. diff --git a/website/content/partials/global-settings/both/format.mdx b/website/content/partials/global-settings/both/format.mdx index c0d437e482..ad3e5a245b 100644 --- a/website/content/partials/global-settings/both/format.mdx +++ b/website/content/partials/global-settings/both/format.mdx @@ -1,6 +1,10 @@ -**`[-format | VAULT_FORMAT] (enum: json)`** + + +**`[-format | VAULT_FORMAT] (enum: table)`** + + Set the CLI output format. @@ -13,6 +17,6 @@ Value | Description **Examples**: -- CLI flag: `-format table` -- Environment variable: `export VAULT_FORMAT=table` +- CLI flag: `-format json` +- Environment variable: `export VAULT_FORMAT=json` diff --git a/website/content/partials/global-settings/both/log-format.mdx b/website/content/partials/global-settings/both/log-format.mdx index ab7c74f03e..de3564b7ca 100644 --- a/website/content/partials/global-settings/both/log-format.mdx +++ b/website/content/partials/global-settings/both/log-format.mdx @@ -1,7 +1,11 @@ + + **`[-log-format | VAULT_LOG_FORMAT] (enum : standard)`** + + Format of log data: - **`standard`** - Write log data as basic text. diff --git a/website/content/partials/global-settings/both/log-level.mdx b/website/content/partials/global-settings/both/log-level.mdx index c211091539..206e149d82 100644 --- a/website/content/partials/global-settings/both/log-level.mdx +++ b/website/content/partials/global-settings/both/log-level.mdx @@ -1,7 +1,11 @@ + + **`[-log-level | VAULT_LOG_LEVEL] (enum : info)`** + + Default logging level for the Vault server. Enum | Logging behavior diff --git a/website/content/partials/global-settings/both/mfa.mdx b/website/content/partials/global-settings/both/mfa.mdx index a3eb933d8f..1bd495e1d6 100644 --- a/website/content/partials/global-settings/both/mfa.mdx +++ b/website/content/partials/global-settings/both/mfa.mdx @@ -1,7 +1,11 @@ + + **`[-mfa | VAULT_MFA] (string : "")`** + + A multi-factor authentication (MFA) credential, in the format `mfa_method_name[:key[=value]]`, that the CLI should use to authenticate to Vault. The CLI adds MFA credentials to the `X-Vault-MFA` header when calling the diff --git a/website/content/partials/global-settings/both/namespace.mdx b/website/content/partials/global-settings/both/namespace.mdx index 05c87c1548..dcf81d6eac 100644 --- a/website/content/partials/global-settings/both/namespace.mdx +++ b/website/content/partials/global-settings/both/namespace.mdx @@ -1,7 +1,11 @@ + + **`[-namespace | -ns | VAULT_NAMESPACE] (string : )`** + + Root namespace for the CLI command. Setting a default namespace allow relative mount paths. diff --git a/website/content/partials/global-settings/both/tls-server-name.mdx b/website/content/partials/global-settings/both/tls-server-name.mdx index 5adc392b37..68f6c49bea 100644 --- a/website/content/partials/global-settings/both/tls-server-name.mdx +++ b/website/content/partials/global-settings/both/tls-server-name.mdx @@ -1,7 +1,11 @@ + + **`[-tls-server-name | VAULT_TLS_SERVER_NAME] (string : "")`** + + Name of the SNI host for TLS handshake resolution for TLS connections to Vault. **Examples**: diff --git a/website/content/partials/global-settings/both/tls-skip-verify.mdx b/website/content/partials/global-settings/both/tls-skip-verify.mdx index c2a1f510f3..884849a574 100644 --- a/website/content/partials/global-settings/both/tls-skip-verify.mdx +++ b/website/content/partials/global-settings/both/tls-skip-verify.mdx @@ -1,7 +1,11 @@ + + **`[-tls-skip-verify | VAULT_SKIP_VERIFY] (bool : false)`** + + Disable verification for all TLS certificates. **Use with caution**. Disabling TLS certificate verification decreases the security of data transmissions to and from the Vault server. diff --git a/website/content/partials/global-settings/both/wrap-ttl.mdx b/website/content/partials/global-settings/both/wrap-ttl.mdx index d90b32455b..878fb8a288 100644 --- a/website/content/partials/global-settings/both/wrap-ttl.mdx +++ b/website/content/partials/global-settings/both/wrap-ttl.mdx @@ -1,7 +1,11 @@ + + **`[-wrap-ttl | VAULT_WRAP_TTL] (string : "")`** + + Default time-to-live in `[s|m|h|d]` format for the Cubbyhole token used to wrap CLI responses. You must use `vault unwrap` to view response data before the duration expires. Leave `wrap_ttl` unset to leave CLI responses unwrapped. diff --git a/website/content/partials/global-settings/env/cli_no_color.mdx b/website/content/partials/global-settings/env/cli_no_color.mdx index c2b934925a..ea15350490 100644 --- a/website/content/partials/global-settings/env/cli_no_color.mdx +++ b/website/content/partials/global-settings/env/cli_no_color.mdx @@ -1,7 +1,11 @@ + + **`VAULT_CLI_NO_COLOR (bool : true)`** + + Exclude ANSI color escape sequence characters from the CLI output. **Example**: `export VAULT_CLI_NO_COLOR=0` diff --git a/website/content/partials/global-settings/env/client_timeout.mdx b/website/content/partials/global-settings/env/client_timeout.mdx index de34432605..29533482ab 100644 --- a/website/content/partials/global-settings/env/client_timeout.mdx +++ b/website/content/partials/global-settings/env/client_timeout.mdx @@ -1,7 +1,11 @@ + + **`VAULT_CLIENT_TIMEOUT (string : "60s")`** + + Amount of time, in `[s|m|h|d]` format, the CLI should wait on a response from Vault. diff --git a/website/content/partials/global-settings/env/cluster_addr.mdx b/website/content/partials/global-settings/env/cluster_addr.mdx index 239cdd77c9..fea888813f 100644 --- a/website/content/partials/global-settings/env/cluster_addr.mdx +++ b/website/content/partials/global-settings/env/cluster_addr.mdx @@ -1,7 +1,11 @@ + + **`VAULT_CLUSTER_ADDR (string : "")`** + + Address of the local Vault node. Vault uses cluster addresses for cluster-to-cluster communication when running in high-availability mode. diff --git a/website/content/partials/global-settings/env/http_proxy.mdx b/website/content/partials/global-settings/env/http_proxy.mdx index 8617d0c092..2d7f0d0ebb 100644 --- a/website/content/partials/global-settings/env/http_proxy.mdx +++ b/website/content/partials/global-settings/env/http_proxy.mdx @@ -1,7 +1,11 @@ + + **`VAULT_HTTP_PROXY (string : "")`** + + Legacy alias for `VAULT_PROXY_ADDR`. diff --git a/website/content/partials/global-settings/env/license.mdx b/website/content/partials/global-settings/env/license.mdx index 8e8477d178..704e0a3ca9 100644 --- a/website/content/partials/global-settings/env/license.mdx +++ b/website/content/partials/global-settings/env/license.mdx @@ -1,7 +1,11 @@ + + **`VAULT_LICENSE (string : "")`** + + Vault Enterprise license string for the local server or node. `VAULT_LICENSE` takes precedence over `VAULT_LICENSE_PATH` **and** the `license_path` parameter in the Vault configuration file. diff --git a/website/content/partials/global-settings/env/license_path.mdx b/website/content/partials/global-settings/env/license_path.mdx index ae4d61faaa..cd84d53f7d 100644 --- a/website/content/partials/global-settings/env/license_path.mdx +++ b/website/content/partials/global-settings/env/license_path.mdx @@ -1,7 +1,11 @@ + + **`VAULT_LICENSE_PATH (string : "")`** + + Local path to a file containing a valid Vault Enterprise license for the server or node. `VAULT_LICENSE_PATH` takes precedence over the `license_path` parameter in the Vault configuration file. diff --git a/website/content/partials/global-settings/env/max_retries.mdx b/website/content/partials/global-settings/env/max_retries.mdx index 111126a153..5a48277d22 100644 --- a/website/content/partials/global-settings/env/max_retries.mdx +++ b/website/content/partials/global-settings/env/max_retries.mdx @@ -1,7 +1,11 @@ + + **`VAULT_MAX_RETRIES (integer : 2)`** + + The number of times the CLI should retry a request to the Vault server when the CLI receives one of the following recoverable error codes: diff --git a/website/content/partials/global-settings/env/proxy_addr.mdx b/website/content/partials/global-settings/env/proxy_addr.mdx index eb862b0b1d..060ffa321d 100644 --- a/website/content/partials/global-settings/env/proxy_addr.mdx +++ b/website/content/partials/global-settings/env/proxy_addr.mdx @@ -1,7 +1,11 @@ + + **`VAULT_PROXY_ADDR (string : "")`** + + The HTTPS or HTTP address, including server and port, where clients can access Vault. Setting `VAULT_HTTP_PROXY` overrides the default proxy resolution behavior and tells Vault to ignore the following proxy-related environment diff --git a/website/content/partials/global-settings/env/rate_limit.mdx b/website/content/partials/global-settings/env/rate_limit.mdx index 1fde590935..25b8d60ffc 100644 --- a/website/content/partials/global-settings/env/rate_limit.mdx +++ b/website/content/partials/global-settings/env/rate_limit.mdx @@ -1,7 +1,11 @@ + + **`VAULT_RATE_LIMIT (string : unset)`** + + The number of operations per second, in `rate[:burst]` format, used to throttle requests between the CLI and the server. The `burst` value is optional and defaults to `rate` when not specified. diff --git a/website/content/partials/global-settings/env/redirect_addr.mdx b/website/content/partials/global-settings/env/redirect_addr.mdx index 7c400efb6d..02b14449f6 100644 --- a/website/content/partials/global-settings/env/redirect_addr.mdx +++ b/website/content/partials/global-settings/env/redirect_addr.mdx @@ -1,7 +1,11 @@ + + **`VAULT_REDIRECT_ADDR (string : "")`** + + Local node address that listens for redirected client communication when Vault runs in high-availability mode. diff --git a/website/content/partials/global-settings/env/skip_verify.mdx b/website/content/partials/global-settings/env/skip_verify.mdx index fb79ae2ebc..61075467de 100644 --- a/website/content/partials/global-settings/env/skip_verify.mdx +++ b/website/content/partials/global-settings/env/skip_verify.mdx @@ -1,7 +1,11 @@ + + **`VAULT_SKIP_VERIFY (bool : false)`** + + Allow communication between the CLI and Vault server before verifying the authentication certificate presented by Vault. diff --git a/website/content/partials/global-settings/env/srv_lookup.mdx b/website/content/partials/global-settings/env/srv_lookup.mdx index 195ce532d5..c16ee16b0b 100644 --- a/website/content/partials/global-settings/env/srv_lookup.mdx +++ b/website/content/partials/global-settings/env/srv_lookup.mdx @@ -1,7 +1,11 @@ + + **`VAULT_SRV_LOOKUP (bool : false)`** + + Use SRV records instead of standard DNS to look up hostnames as described in the Network Working Group draft ["Use of SRV records in conjunction with HTTP and URIs"](https://datatracker.ietf.org/doc/html/draft-andrews-http-srv-02). diff --git a/website/content/partials/global-settings/env/token.mdx b/website/content/partials/global-settings/env/token.mdx index 11e1161899..56eb99eda3 100644 --- a/website/content/partials/global-settings/env/token.mdx +++ b/website/content/partials/global-settings/env/token.mdx @@ -1,7 +1,11 @@ + + **`VAULT_TOKEN (string : "")`** + + A Vault-issued service token that authenticates the CLI user to Vault. See the [tokens concepts page](/vault/docs/concepts/tokens) for more information on token types. diff --git a/website/content/partials/global-settings/flags/header.mdx b/website/content/partials/global-settings/flags/header.mdx index 3699d39447..c7c04454d0 100644 --- a/website/content/partials/global-settings/flags/header.mdx +++ b/website/content/partials/global-settings/flags/header.mdx @@ -1,7 +1,11 @@ + + **`-header (string : "")`** + + Optional HTTP header in the form `"="` for the CLI request. Repeat the `-header` flag as needed with one string per flag. User-defined headers cannot start with `X-Vault-` diff --git a/website/content/partials/global-settings/flags/non-interactive.mdx b/website/content/partials/global-settings/flags/non-interactive.mdx index 43725e8ad7..fe6d1e0c3a 100644 --- a/website/content/partials/global-settings/flags/non-interactive.mdx +++ b/website/content/partials/global-settings/flags/non-interactive.mdx @@ -1,7 +1,11 @@ + + **`-non-interactive (bool : false)`** + + Prevent the CLI from asking users for input through the terminal. **Example**: `-non-interactive` diff --git a/website/content/partials/global-settings/flags/output-curl-string.mdx b/website/content/partials/global-settings/flags/output-curl-string.mdx index a10a86f01b..e7e15184b8 100644 --- a/website/content/partials/global-settings/flags/output-curl-string.mdx +++ b/website/content/partials/global-settings/flags/output-curl-string.mdx @@ -1,7 +1,11 @@ + + **`-output-curl-string (bool : false)`** + + Print the API call(s) required to execute the CLI command as `cURL` strings then exit without running the command. diff --git a/website/content/partials/global-settings/flags/output-policy.mdx b/website/content/partials/global-settings/flags/output-policy.mdx index 457a178690..749240600e 100644 --- a/website/content/partials/global-settings/flags/output-policy.mdx +++ b/website/content/partials/global-settings/flags/output-policy.mdx @@ -1,7 +1,11 @@ + + **`-output-policy (bool : false)`** + + Print the Vault policy required to execute the CLI command as HCL then exit without running the command. diff --git a/website/content/partials/global-settings/flags/policy-override.mdx b/website/content/partials/global-settings/flags/policy-override.mdx index af33f609c9..340c12d93c 100644 --- a/website/content/partials/global-settings/flags/policy-override.mdx +++ b/website/content/partials/global-settings/flags/policy-override.mdx @@ -1,7 +1,11 @@ + + **`-policy-override (bool : false)`** + + Overrides any Sentinel policy where `enforcement_level` is "soft-mandatory". **Example**: `-policy-override` diff --git a/website/content/partials/global-settings/flags/unlock-key.mdx b/website/content/partials/global-settings/flags/unlock-key.mdx index 38f8c01e3d..097b18a6f2 100644 --- a/website/content/partials/global-settings/flags/unlock-key.mdx +++ b/website/content/partials/global-settings/flags/unlock-key.mdx @@ -1,7 +1,11 @@ + + **`-unlock-key (string : )`** + + Plaintext key that unlocks the underlying API endpoint for a given namespace. **Example**: `-unlock-key "7oXtdlmvRQ"` diff --git a/website/templates/cli-page.mdx b/website/templates/cli-page.mdx new file mode 100644 index 0000000000..596b69346e --- /dev/null +++ b/website/templates/cli-page.mdx @@ -0,0 +1,104 @@ +--- +layout: docs +page_title: "COMMAND_NAME - Vault CLI" +description: >- + DESCRIPTION +--- + +# `COMMAND_NAME` + +TLDR_SUMMARY + + + +```shell-session +$ vault COMMAND_NAME SYNTAX_STRING + +$ vault COMMAND_NAME [-help | -h] +``` + + + +## Description + +`COMMAND_NAME` does a thing.... (full description here) + + + + ENDPOINT_NAME - [`HTTP_VERB:ENDPOINT_PATH`](API_DOC_URL) + + + +### Limitations and warnings (omit if not needed) + +List and explicit limitations/warning users should be aware of with the command + + +## Command arguments + +None. + +-- OR -- + +@include 'PATH_TO_ARGUMENT_PARTIAL_1' + +

+ +@include 'PATH_TO_ARGUMENT_PARTIAL_2' + +

+ +@include 'PATH_TO_ARGUMENT_PARTIAL_N' + + + +## Command options + +None. + +-- OR -- + +@include 'PATH_TO_OPTION_PARTIAL_1' + +

+ +@include 'PATH_TO_OPTION_PARTIAL_1' + +

+ +@include 'PATH_TO_OPTION_PARTIAL_1' + + +## Command flags + +None. + +-- OR -- + +@include 'PATH_TO_FLAG_PARTIAL_1' + +

+ +@include 'PATH_TO_FLAG_PARTIAL_2' + +

+ +@include 'PATH_TO_FLAG_PARTIAL_N' + + + +## Global flags + +
+ +@include 'cli/standard-settings/all-standard-flags-but-format.mdx' + +- OR - + +@include 'cli/standard-settings/all-standard-flags-but-format.mdx' + + + +## Examples + +LIST_OF_USEFUL_EXAMPLES \ No newline at end of file