[docs] Update Elastic Agent command-line flags for 7.9 (elastic#20533) (

elastic#20621)

* [docs] Update Elastic Agent command-line flags for 7.9

* Add changes from review

x-pack/elastic-agent/docs/elastic-agent-command-line.asciidoc

@@ -1,3 +1,5 @@
+:global-flags-link: For more flags, see <<elastic-agent-global-flags>>.
+
 [[elastic-agent-cmd-options]]
 [role="xpack"]
 = {agent} command line options
@@ -8,40 +10,268 @@
 
 beta[]
 
-The `elastic-agent run` command provides flags that alter the behavior of an
-agent:
+{agent} provides commands for running the agent and doing common tasks:
 
-`--path.home`::
-The home directory of the {agent}. `path.home` determines the location of the
-configuration files and data directory.
+* <<elastic-agent-enroll-command,enroll>>
+* <<elastic-agent-help-command,help>>
+* <<elastic-agent-inspect-command,inspect>>
+* <<elastic-agent-run-command,run>>
+* <<elastic-agent-version-command,version>>
+
+++++
+<hr>
+++++
+
+[discrete]
+[[elastic-agent-enroll-command]]
+== elastic-agent enroll
+
+Enroll the {elastic-agent} in {fleet}.
+
+We recommend that you run this command as the root user because some
+integrations require root privileges to collect sensitive data. This command
+overwrites the `elastic-agent.yml` file in the agent directory.
+
+[discrete]
+=== Synopsis
+
+[source,shell]
+----
+elastic-agent enroll <kibana_url> <enrollment_token> [--ca-sha256 <string>]
+                     [--certificate-authorities <string>] [--force] [--help]
+                     [--insecure][global-flags]
+----
+
+[discrete]
+=== Options
+
+`kibana_url`::
+Required. URL of the {kib} endpoint where {ingest-manager} is running.
+
+`enrollment_token`::
+Required. Enrollment token generated by {ingest-manager}. You can use the same
+enrollment token for multiple agents.
+
+`--ca-sha256 <string>`::
+Comma-separated list of certificate authority hash pins used for certificate
+verification.
+
+`--certificate-authorities <string>`::
+Comma-separated list of root certificates used for server verification.
+
+`--force`::
+Force overwrite of current configuration without prompting for confirmation.
+This flag is helpful when using automation software or scripted deployments.
+
+`--help`::
+Show help for the `enroll` command.
+
+`--insecure`::
+Allow an insecure connection to {kib}. When this flag is specified, API keys are
+sent in clear text. We strongly recommend that you use a secure connection.
+
+{global-flags-link}
+
+[discrete]
+=== Example
+
+[source,shell]
+----
+elastic-agent enroll http://localhost:5601 ZnmNIdzVITUJua2QIdU5FTWROVjY6dHY2N1EybWNTMUdPejg5ODbYcVpNUQ==
+----
+
+++++
+<hr>
+++++
+
+[discrete]
+[[elastic-agent-help-command]]
+== elastic-agent help
+
+Show help for a specific command.
+
+[discrete]
+=== Synopsis
+
+[source,shell]
+----
+elastic-agent help <command> [--help] [global-flags]
+----
+
+[discrete]
+=== Options
+
+`command`::
+The name of the command.
+
+`--help`::
+Show help for the `help` command.
+
+{global-flags-link}
+
+[discrete]
+=== Example
+
+[source,shell]
+----
+elastic-agent help enroll
+----
+
+++++
+<hr>
+++++
+
+[discrete]
+[[elastic-agent-inspect-command]]
+== elastic-agent inspect
+
+Show the current {agent} configuration.
+
+If no parameters are specified, shows the full {agent} configuration.
+
+[discrete]
+=== Synopsis
+
+[source,shell]
+----
+elastic-agent inspect [--help] [global-flags]
+elastic-agent inspect output [--output <string>] [--program <string>]
+                             [--help] [global-flags]
+----
+
+
+//TODO: Clarify what these commands return.
+
+[discrete]
+=== Options
+
+`output`:: Display the current configuration for the output. This command
+accepts additional flags:
 +
-If not specified, {agent} uses current working directory.
+--
+`--output <string>`::
+The name of the output to introspect.
+
+`--program <string>`::
+The type of program to introspect. For example, `filebeat`. This option must be
+combined with `--output`. 
+--
+
+`--help`::
+Show help for the `inspect` command.
+
+{global-flags-link}
+
+[discrete]
+=== Examples
+
+[source,shell]
+----
+elastic-agent inspect
+elastic-agent inspect output --output default
+elastic-agent inspect output --output default --program filebeat
+----
+
+++++
+<hr>
+++++
+
+[discrete]
+[[elastic-agent-run-command]]
+== elastic-agent run
+
+Start the `elastic-agent` process.
+
+[discrete]
+=== Synopsis
+
+[source,shell]
+----
+elastic-agent run [global-flags]
+----
+
+[discrete]
+[[elastic-agent-global-flags]]
+=== Global flags
+
+These flags are valid whenever you run `elastic-agent` on the command line.
+
+`-c <string>`::
+The configuration file to use. If not specified, {agent} uses
+`{path.home}/elastic-agent.yml`.
 
-`--path.data`::
-The data directory used by {agent} to store downloaded artifacts. Also stores
-logs for any {beats} started and managed by {agent}.
+`--e`::
+Log to stderr and disable syslog/file output.
+
+`--environment <environmentVar>`::
+The environment in which the agent will run.
+
+//TODO: Clarify what we mean by environment by showing an example.
+
+`--path.config <string>`::
+The directory where {agent} looks for its configuration file. The default
+varies by platform.
+
+`--path.data <string>`::
+The data directory where {agent} stores managed binaries and their logs. Also
+stores logs for any programs started and managed by {agent}.
 +
 If not specified, {agent} uses `{path.home}/data`.
 
-`-c`::
-The configuration file to load.
+`--path.home <string>`::
+The home directory of {agent}. `path.home` determines the location of the
+configuration files and data directory.
 +
-If not specified, {agent} uses `{path.home}/elastic-agent.yml`.
+If not specified, {agent} uses the current working directory.
 
-The `elastic-agent enroll` command provides flags that alter the behaviour of
-the enrollment process.
+`--path.logs <string>`::
+Path to the log output for {agent}. The default varies by platform.
 
-`--ca-sha256`::
-Comma separated list of certificate authorities hash pins used for certificate verifications.
+`--v`::
+Set log level to INFO.
 
-`--certificate-authorities`::
-Comma separated list of root certificate for server verifications.
+[discrete]
+=== Example
 
-`--force`::
-Force overwrite the current and do not prompt for confirmation.
+[source,shell]
+----
+elastic-agent run -v --path.logs path/to/my/logs
+----
 
-`--insecure`::
-Allow insecure connection to Kibana.
+++++
+<hr>
+++++
+
+[discrete]
+[[elastic-agent-version-command]]
+== elastic-agent version
 
-`--staging`::
-Configures agent to download artifacts from a staging build.
+Show the version of {agent}.
+
+[discrete]
+=== Synopsis
+
+[source,shell]
+----
+elastic-agent version [--help] [global-flags]
+----
+
+[discrete]
+=== Options
+
+`--help`::
+Show help for the `version` command.
+
+{global-flags-link}
+
+[discrete]
+=== Example
+
+[source,shell]
+----
+elastic-agent version
+----
+
+++++
+<hr>
+++++