Update the Agent CLI topics to clarify flow mode syntax (#4697)

* Update executable name * More executable name updates * Change bullet order and add missing info * Switch to command name remove binary Co-authored-by: Robert Fratto <[email protected]> * Update metadata change note to caution * Swap command order in usage section * Fix a typo * General cleanup and formatting * Remove a gerund --------- Co-authored-by: Robert Fratto <[email protected]>
grafana · Aug 4, 2023 · 6f885c9 · 6f885c9
1 parent cc68f26
commit 6f885c9
Show file tree

Hide file tree

Showing 5 changed files with 102 additions and 61 deletions.
diff --git a/docs/sources/flow/reference/cli/_index.md b/docs/sources/flow/reference/cli/_index.md
@@ -1,6 +1,8 @@
 ---
 canonical: https://grafana.com/docs/agent/latest/flow/reference/cli/
-title: Command-line interface
+description: The Grafana Agent command line interface provides subcommands to perform various operations.
+title: The Grafana Agent command line interface
+menuTitle: Command-line interface
 weight: 100
 ---
 
@@ -14,10 +16,14 @@ starts Grafana Agent Flow.
 
 Available commands:
 
-* [`grafana-agent run`][run]: Start Grafana Agent Flow, given a config file.
-* [`grafana-agent fmt`][fmt]: Format a Grafana Agent Flow config file.
-* `grafana-agent completion`: Generate shell completion for the `grafana-agent` CLI.
-* `grafana-agent help`: Print help for supported commands.
+* [`convert`][convert]: Convert a Grafana Agent configuration file.
+* [`fmt`][fmt]: Format a Grafana Agent Flow configuration file.
+* [`run`][run]: Start Grafana Agent Flow, given a configuration file.
+* [`tools`][tools]: Read the WAL and provide statistical information.
+* `completion`: Generate shell completion for the `grafana-agent-flow` CLI.
+* `help`: Print help for supported commands.
 
 [run]: {{< relref "./run.md" >}}
 [fmt]: {{< relref "./fmt.md" >}}
+[convert]: {{< relref "./convert.md" >}}
+[tools]: {{< relref "./tools.md" >}}
diff --git a/docs/sources/flow/reference/cli/convert.md b/docs/sources/flow/reference/cli/convert.md
@@ -2,24 +2,33 @@
 canonical: https://grafana.com/docs/agent/latest/flow/reference/cli/convert/
 labels:
   stage: beta
-title: grafana-agent convert
+description: The `convert` command converts supported configuration formats to River format.
+title: convert command
+menuTitle: convert
 weight: 100
 ---
 
-# `grafana-agent convert` command
+# `convert` command
 
-The `grafana-agent convert` command converts a supported configuration format
-to Grafana Agent Flow River format.
+The `convert` command converts a supported configuration format to Grafana Agent Flow River format.
 
 ## Usage
 
-Usage: `grafana-agent convert [FLAG ...] FILE_NAME`
+Usage: 
+
+* `AGENT_MODE=flow grafana-agent convert [FLAG ...] FILE_NAME`
+* `grafana-agent-flow convert [FLAG ...] FILE_NAME`
+
+   Replace the following:
+
+   * `FLAG`: One or more flags that define the input and output of the command.
+   * `FILE_NAME`: The Grafana Agent configuration file.
 
 If the `FILE_NAME` argument is not provided or if the `FILE_NAME` argument is
-equal to `-`, `grafana-agent convert` converts the contents of standard input. Otherwise,
-`grafana-agent convert` reads and converts the file from disk specified by the argument.
+equal to `-`, `convert` converts the contents of standard input. Otherwise,
+`convert` reads and converts the file from disk specified by the argument.
 
-There are several different flags available for the `grafana-agent convert` command. You can use the `--output` flag to write the contents of the converted config to a specified path. You can use the `--report` flag to generate a diagnostic report. The `--bypass-errors` flag allows you to bypass any [errors] generated during the file conversion.
+There are several different flags available for the `convert` command. You can use the `--output` flag to write the contents of the converted config to a specified path. You can use the `--report` flag to generate a diagnostic report. The `--bypass-errors` flag allows you to bypass any [errors] generated during the file conversion.
 
 The command fails if the source config has syntactically incorrect
 configuration or cannot be converted to Grafana Agent Flow River format.
@@ -41,12 +50,9 @@ The following flags are supported:
 ### Defaults
 
 Flow Defaults are managed as follows:
-* If a provided source config value matches a Flow default value, the
-property is left off the Flow output.
-* If a non-provided source config value default matches a Flow default value,
-the property is left off the Flow output.
-* If a non-provided source config value default doesn't match a Flow default
-value, the Flow default value is included in the Flow output.
+* If a provided source config value matches a Flow default value, the property is left off the Flow output.
+* If a non-provided source config value default matches a Flow default value, the property is left off the Flow output.
+* If a non-provided source config value default doesn't match a Flow default value, the Flow default value is included in the Flow output.
 
 ### Errors
 

diff --git a/docs/sources/flow/reference/cli/fmt.md b/docs/sources/flow/reference/cli/fmt.md
@@ -1,24 +1,34 @@
 ---
 canonical: https://grafana.com/docs/agent/latest/flow/reference/cli/fmt/
-title: grafana-agent fmt
-weight: 100
+description: The `fmt` command formats a Grafana Agent configuration file.
+title: fmt command
+menuTitle: fmt
+weight: 200
 ---
 
-# `grafana-agent fmt` command
+# `fmt` command
 
-The `grafana-agent fmt` command formats a given Grafana Agent Flow configuration file.
+The `fmt` command formats a given Grafana Agent Flow configuration file.
 
 ## Usage
 
-Usage: `grafana-agent fmt [FLAG ...] FILE_NAME`
+Usage:
+
+* `AGENT_MODE=flow grafana-agent fmt [FLAG ...] FILE_NAME`
+* `grafana-agent-flow fmt [FLAG ...] FILE_NAME`
+
+   Replace the following:
+
+   * `FLAG`: One or more flags that define the input and output of the command.
+   * `FILE_NAME`: The Grafana Agent configuration file.
 
 If the `FILE_NAME` argument is not provided or if the `FILE_NAME` argument is
-equal to `-`, `grafana-agent fmt` formats the contents of standard input. Otherwise,
-`grafana-agent fmt` reads and formats the file from disk specified by the argument.
+equal to `-`, `fmt` formats the contents of standard input. Otherwise,
+`fmt` reads and formats the file from disk specified by the argument.
 
 The `--write` flag can be specified to replace the contents of the original
 file on disk with the formatted results. `--write` can only be provided when
-`grafana-agent fmt` is not reading from standard input.
+`fmt` is not reading from standard input.
 
 The command fails if the file being formatted has syntactically incorrect River
 configuration, but does not validate whether Flow components are configured

diff --git a/docs/sources/flow/reference/cli/run.md b/docs/sources/flow/reference/cli/run.md
@@ -1,29 +1,38 @@
 ---
 canonical: https://grafana.com/docs/agent/latest/flow/reference/cli/run/
-title: grafana-agent run
-weight: 100
+description: The `run` command runs Grafana Agent in the foreground until an interrupt is received.
+title: run command
+menuTitle: run
+weight: 300
 ---
 
-# `grafana-agent run` command
+# `run` command
 
-The `grafana-agent run` command runs Grafana Agent Flow in the foreground until an
+The `run` command runs Grafana Agent Flow in the foreground until an
 interrupt is received.
 
 ## Usage
 
-Usage: `grafana-agent run [FLAG ...] FILE_NAME`
+Usage:
 
-`grafana-agent run` must be provided an argument which points at the River config file
-to use. `grafana-agent run` will immediately exit with an error if the River file
-wasn't specified, can't be loaded, or contained errors during the initial load.
+* `AGENT_MODE=flow grafana-agent run [FLAG ...] FILE_NAME`
+* `grafana-agent-flow run [FLAG ...] FILE_NAME`
 
-Grafana Agent Flow will continue to run if subsequent reloads of the config
+   Replace the following:
+
+   * `FLAG`: One or more flags that define the input and output of the command.
+   * `FILE_NAME`: Required. The Grafana Agent configuration file.
+
+If the `FILE_NAME` argument is not provided, or if the configuration file can't be loaded or 
+contains errors during the initial load, the `run` command will immediately exit and show an error message.
+
+Grafana Agent Flow will continue to run if subsequent reloads of the configuration
 file fail, potentially marking components as unhealthy depending on the nature
 of the failure. When this happens, Grafana Agent Flow will continue functioning
 in the last valid state.
 
-`grafana-agent run` launches an HTTP server for expose metrics about itself and
-components. The HTTP server is also used for exposing a UI at `/` for debugging
+`run` launches an HTTP server that exposes metrics about itself and its
+components. The HTTP server is also exposes a UI at `/` for debugging
 running components.
 
 The following flags are supported:
@@ -32,7 +41,7 @@ The following flags are supported:
 * `--server.http.memory-addr`: Address to listen for [in-memory HTTP traffic][] on
   (default `agent.internal:12345`).
 * `--server.http.listen-addr`: Address to listen for HTTP traffic on (default `127.0.0.1:12345`).
-* `--server.http.ui-path-prefix`: Base path where the UI will be exposed (default `/`).
+* `--server.http.ui-path-prefix`: Base path where the UI is exposed (default `/`).
 * `--storage.path`: Base directory where components can store data (default `data-agent/`).
 * `--disable-reporting`: Disable [usage reporting][] of enabled [components][] to Grafana (default `false`).
 * `--cluster.enabled`: Start the Agent in clustered mode (default `false`).
@@ -47,17 +56,17 @@ The following flags are supported:
 [usage reporting]: {{< relref "../../../static/configuration/flags.md#report-information-usage" >}}
 [components]: {{< relref "../../concepts/components.md" >}}
 
-## Updating the config file
+## Update the configuration file
 
-The config file can be reloaded from disk by either:
+The configuration file can be reloaded from disk by either:
 
 * Sending an HTTP POST request to the `/-/reload` endpoint.
 * Sending a `SIGHUP` signal to the Grafana Agent process.
 
 When this happens, the [component controller][] synchronizes the set of running
-components with the latest set of components specified in the config file.
-Components that are no longer defined in the config file after reloading are
-shut down, and components that have been added to the config file since the
+components with the latest set of components specified in the configuration file.
+Components that are no longer defined in the configuration file after reloading are
+shut down, and components that have been added to the configuration file since the
 previous reload are created.
 
 All components managed by the component controller are reevaluated after
@@ -94,13 +103,13 @@ align the port numbers on as many nodes as possible to simplify the deployment
 process.
 
 The `--cluster.discover-peers` command-line flag expects a list of tuples in
-the form of `provider=XXX key=val key=val ...`. Clustering makes use of the
+the form of `provider=XXX key=val key=val ...`. Clustering uses the
 [go-discover] package to discover peers and fetch their IP addresses, based
 on the chosen provider and the filtering key-values it supports. Clustering
 supports the default set of providers available in go-discover and registers
 the `k8s` provider on top.
 
-If either the key or the value in a pair contains a space, a backslash or
+If either the key or the value in a pair contains a space, a backslash, or
 double quotes, then it must be quoted with double quotes. Within this quoted
 string, the backslash can be used to escape double quotes or the backslash
 itself.
@@ -122,13 +131,13 @@ Clustered agents are in one of three states:
   participating in workload distribution.
 
 * **Participant**: The agent is participating in workload distribution for
-  components which have clustering enabled.
+  components that have clustering enabled.
 
-* **Terminating**: The agent is shutting down, and will no longer assign new
+* **Terminating**: The agent is shutting down and will no longer assign new
   work to itself.
 
-Agents initially join the cluster in the viewer state, and then transition to
-the participant state after the processs startup completes. Agents then
+Agents initially join the cluster in the viewer state and then transition to
+the participant state after the process startup completes. Agents then
 transition to the terminating state when shutting down.
 
 The current state of a clustered agent is shown on the clustering page in the
@@ -142,13 +151,13 @@ When you use the `--config.format` command-line argument with a value
 other than `flow`, Grafana Agent converts the configuration file from
 the source format to River and immediately starts running with the new
 configuration. This conversion uses the converter API described in the
-[grafana-agent convert][] docs.
+[grafana-agent-flow convert][] docs.
 
 If you also use the `--config.bypass-conversion-errors` command-line argument,
 Grafana Agent will ignore any errors from the converter. Use this argument
 with caution because the resulting conversion may not be equivalent to the
 original configuration.
 
-[grafana-agent convert]: {{< relref "./convert.md" >}}
+[grafana-agent-flow convert]: {{< relref "./convert.md" >}}
 [clustering]:  {{< relref "../../concepts/clustering.md" >}}
 [go-discover]: https://github.com/hashicorp/go-discover
diff --git a/docs/sources/flow/reference/cli/tools.md b/docs/sources/flow/reference/cli/tools.md
@@ -1,15 +1,16 @@
 ---
 canonical: https://grafana.com/docs/agent/latest/flow/reference/cli/tools/
-title: grafana-agent tools
-weight: 100
+description: Command line tools that read the WAL and provide statistical information.
+title: tools command
+menuTitle: tools
+weight: 400
 ---
 
-# `grafana-agent tools` command
+# `tools` command
 
-The `grafana-agent tools` command contains command line tooling grouped by Flow
-component.
+The `tools` command contains command line tooling grouped by Flow component.
 
-{{% admonition type="note" %}}
+{{% admonition type="caution" %}}
 Utilities in this command have no backward compatibility
 guarantees and may change or be removed between releases.
 {{% /admonition %}}
@@ -18,7 +19,10 @@ guarantees and may change or be removed between releases.
 
 ### prometheus.remote_write sample-stats
 
-Usage: `grafana-agent tools prometheus.remote_write sample-stats [FLAG ...] WAL_DIRECTORY`
+Usage: 
+
+* `AGENT_MODE=flow grafana-agent tools prometheus.remote_write sample-stats [FLAG ...] WAL_DIRECTORY`
+* `grafana-agent-flow tools prometheus.remote_write sample-stats [FLAG ...] WAL_DIRECTORY`
 
 The `sample-stats` command reads the Write-Ahead Log (WAL) specified by
 `WAL_DIRECTORY` and collects information on metric samples within it.
@@ -38,7 +42,10 @@ The following flag is supported:
 
 ### prometheus.remote_write target-stats
 
-Usage: `grafana-agent tools prometheus.remote_write target-stats --job JOB --instance INSTANCE WAL_DIRECTORY`
+Usage: 
+
+* `AGENT_MODE=flow grafana-agent tools prometheus.remote_write target-stats --job JOB --instance INSTANCE WAL_DIRECTORY`
+* `grafana-agent-flow tools prometheus.remote_write target-stats --job JOB --instance INSTANCE WAL_DIRECTORY`
 
 The `target-stats` command reads the Write-Ahead Log (WAL) specified by
 `WAL_DIRECTORY` and collects metric cardinality information for a specific
@@ -57,7 +64,10 @@ The `--job` and `--instance` labels are required.
 
 ### prometheus.remote_write wal-stats
 
-Usage: `grafana-agent tools prometheus.remote_write wal-stats WAL_DIRECTORY`
+Usage: 
+
+* `AGENT_MODE=flow grafana-agent tools prometheus.remote_write wal-stats WAL_DIRECTORY`
+* `grafana-agent-flow tools prometheus.remote_write wal-stats WAL_DIRECTORY`
 
 The `wal-stats` command reads the Write-Ahead Log (WAL) specified by
 `WAL_DIRECTORY` and collects general information about it.