//////////////////////////////////////////////////////////////////////////
//// This content is shared by all Elastic Beats. Make sure you keep the
//// descriptions here generic enough to work for all Beats that include
//// this file. When using cross references, make sure that the cross
//// references resolve correctly for any files that include this one.
//// Use the appropriate variables defined in the index.asciidoc file to
//// resolve Beat names: beatname_uc and beatname_lc
//// Use the following include to pull this content into a doc file:
//// include::../../libbeat/docs/command-reference.asciidoc[]
//////////////////////////////////////////////////////////////////////////


// These attributes are used to resolve short descriptions
// tag::attributes[]

:global-flags: Also see <<global-flags,Global flags>>.

:deploy-command-short-desc: Deploys the specified function to your serverless environment

:apikey-command-short-desc: Manage API Keys for communication between APM agents and server.

ifndef::serverless[]
ifndef::no_dashboards[]
:export-command-short-desc: Exports the configuration, index template, ILM policy, or a dashboard to stdout
endif::no_dashboards[]

ifdef::no_dashboards[]
:export-command-short-desc: Exports the configuration, index template, or ILM policy to stdout
endif::no_dashboards[]
endif::serverless[]

ifdef::serverless[]
:export-command-short-desc: Exports the configuration, index template, or {cloudformation-ref} template to stdout
endif::serverless[]

:help-command-short-desc: Shows help for any command
:keystore-command-short-desc: Manages the <<keystore,secrets keystore>>
:modules-command-short-desc: Manages configured modules
:package-command-short-desc: Packages the configuration and executable into a zip file
:remove-command-short-desc: Removes the specified function from your serverless environment
:run-command-short-desc: Runs {beatname_uc}. This command is used by default if you start {beatname_uc} without specifying a command

ifdef::has_ml_jobs[]
:setup-command-short-desc: Sets up the initial environment, including the index template, ILM policy and write alias, {kib} dashboards (when available), and machine learning jobs (when available)
endif::[]

ifdef::no_dashboards[]
:setup-command-short-desc: Sets up the initial environment, including the ES index template, and ILM policy and write alias
endif::no_dashboards[]

ifndef::has_ml_jobs,no_dashboards[]
:setup-command-short-desc: Sets up the initial environment, including the index template, ILM policy and write alias, and {kib} dashboards (when available)
endif::[]

:update-command-short-desc: Updates the specified function
:test-command-short-desc: Tests the configuration
:version-command-short-desc: Shows information about the current version

// end::attributes[]

[[command-line-options]]
=== {beatname_uc} command reference

++++
<titleabbrev>Command reference</titleabbrev>
++++

ifndef::no_dashboards[]
{beatname_uc} provides a command-line interface for starting {beatname_uc} and
performing common tasks, like testing configuration files and loading dashboards.
endif::no_dashboards[]

ifdef::no_dashboards[]
{beatname_uc} provides a command-line interface for starting {beatname_uc} and
performing common tasks, like testing configuration files.
endif::no_dashboards[]

The command-line also supports <<global-flags,global flags>>
for controlling global behaviors.

ifeval::["{beatname_lc}"!="winlogbeat"]
[TIP]
=========================
Use `sudo` to run the following commands if:

* the config file is owned by `root`, or
* {beatname_uc} is configured to capture data that requires `root` access

=========================
endif::[]

Some of the features described here require an Elastic license. For
more information, see https://www.elastic.co/subscriptions and
{kibana-ref}/managing-licenses.html[License Management].


[options="header"]
|=======================
|Commands |
ifeval::["{beatname_lc}"=="functionbeat"]
|<<deploy-command,`deploy`>> | {deploy-command-short-desc}.
endif::[]
ifdef::apm-server[]
|<<apikey-command,`apikey`>> |{apikey-command-short-desc}.
endif::[]
|<<export-command,`export`>> |{export-command-short-desc}.
|<<help-command,`help`>> |{help-command-short-desc}.
ifndef::serverless[]
|<<keystore-command,`keystore`>> |{keystore-command-short-desc}.
endif::[]
ifeval::["{beatname_lc}"=="functionbeat"]
|<<package-command,`package`>> |{package-command-short-desc}.
|<<remove-command,`remove`>> |{remove-command-short-desc}.
endif::[]
ifdef::has_modules_command[]
|<<modules-command,`modules`>> |{modules-command-short-desc}.
endif::[]
ifndef::serverless[]
|<<run-command,`run`>> |{run-command-short-desc}.
endif::[]
|<<setup-command,`setup`>> |{setup-command-short-desc}.
|<<test-command,`test`>> |{test-command-short-desc}.
ifeval::["{beatname_lc}"=="functionbeat"]
|<<update-command,`update`>> |{update-command-short-desc}.
endif::[]
|<<version-command,`version`>> |{version-command-short-desc}.
|=======================

Also see <<global-flags,Global flags>>.

ifdef::apm-server[]
[[apikey-command]]
==== `apikey` command

experimental::[]

Communication between APM agents and APM Server now supports sending an
<<api-key,API Key in the Authorization header>>.
APM Server provides an `apikey` command that can create, verify, invalidate,
and show information about API Keys for agent/server communication.
Most operations require the `manage_api_key` cluster privilege,
and you must ensure that `apm-server.api_key` or `output.elasticsearch` are configured appropriately.

*SYNOPSIS*

["source","sh",subs="attributes"]
----
{beatname_lc} apikey SUBCOMMAND [FLAGS]
----

*SUBCOMMANDS*

// tag::apikey-subcommands[]
*`create`*::
Create an API Key with the specified privilege(s). No required flags.
+
The user requesting to create an API Key needs to have APM privileges used by the APM Server.
A superuser, by default, has these privileges. For other users,
you can create them. See <<privileges-api-key,create an API key user>> for required privileges.

*`info`*::
Query API Key(s). `--id` or `--name` required.

*`invalidate`*::
Invalidate API Key(s). `--id` or `--name` required.

*`verify`*::
Check if a credentials string has the given privilege(s).
 `--credentials` required.
// end::apikey-subcommands[]

*FLAGS*

*`--agent-config`*::
Required for agents to read configuration remotely. Valid with the `create` and `verify` subcommands.
When used with `create`, gives the `config_agent:read` privilege to the created key.
When used with `verify`, asks for the `config_agent:read` privilege.

*`--credentials CREDS`*::
Required for the `verify` subcommand. Specifies the credentials for which to to check privileges.
Credentials are the base64 encoded representation of the API key's `id:name`.

*`--expiration TIME`*::
When used with `create`, specifies the expiration for the key, e.g., "1d" (default never).

*`--id ID`*::
ID of the API key. Valid with the `info` and `invalidate` subcommands.
When used with `info`, queries the specified ID.
When used with `invalidate`, deletes the specified ID.

*`--ingest`*::
Required for ingesting events. Valid with the `create` and `verify` subcommands.
When used with `create`, gives the `event:write` privilege to the created key.
When used with `verify`, asks for the `event:write` privilege.

*`--json`*::
Prints the output of the command as JSON.
Valid with all `apikey` subcommands.

*`--name NAME`*::
Name of the API key(s). Valid with the `create`, `info`, and `invalidate` subcommands.
When used with `create`, specifies the name of the API key to be created (default: "apm-key").
When used with `info`, specifies the API key to query (multiple matches are possible).
When used with `invalidate`, specifies the API key to delete (multiple matches are possible).

*`--sourcemap`*::
Required for uploading sourcemaps. Valid with the `create` and `verify` subcommands.
When used with `create`, gives the `sourcemap:write` privilege to the created key.
When used with `verify`, asks for the `sourcemap:write` privilege.

*`--valid-only`*::
When used with `info`, only returns valid API Keys (not expired or invalidated).

{global-flags}

*EXAMPLES*

["source","sh",subs="attributes"]
-----
{beatname_lc} apikey create --ingest --agent-config --name example-001
{beatname_lc} apikey info --name example-001 --valid-only
{beatname_lc} apikey invalidate --name example-001
-----

For more information, see <<api-key>>.

endif::[]

ifeval::["{beatname_lc}"=="functionbeat"]
[[deploy-command]]
==== `deploy` command

{deploy-command-short-desc}. Before deploying functions, make sure the user has
the credentials required by your cloud service provider.

*SYNOPSIS*

["source","sh",subs="attributes"]
----
{beatname_lc} deploy FUNCTION_NAME [FLAGS]
----

*`FUNCTION_NAME`*::
Specifies the name of the function to deploy.

*FLAGS*

*`-h, --help`*::
Shows help for the `deploy` command.

{global-flags}

*EXAMPLES*

["source","sh",subs="attributes"]
-----
{beatname_lc} deploy cloudwatch
{beatname_lc} deploy sqs
-----
endif::[]

[[export-command]]
==== `export` command

ifndef::serverless[]
ifndef::no_dashboards[]
{export-command-short-desc}. You can use this
command to quickly view your configuration, see the contents of the index
template and the ILM policy, or export a dashboard from {kib}.
endif::no_dashboards[]

ifdef::no_dashboards[]
{export-command-short-desc}. You can use this
command to quickly view your configuration or see the contents of the index
template or the ILM policy.
endif::no_dashboards[]
endif::serverless[]

ifdef::serverless[]
{export-command-short-desc}. You can use this
command to quickly view your configuration, see the contents of the index
template and the ILM policy, or export an CloudFormation template.
endif::serverless[]

*SYNOPSIS*

["source","sh",subs="attributes"]
----
{beatname_lc} export SUBCOMMAND [FLAGS]
----

*SUBCOMMANDS*

*`config`*::
Exports the current configuration to stdout. If you use the `-c` flag, this
command exports the configuration that's defined in the specified file.

ifndef::no_dashboards[]
[[dashboard-subcommand]]*`dashboard`*::
Exports a dashboard. You can use this option to store a dashboard on disk in a
module and load it automatically. For example, to export the dashboard to a JSON
file, run:
+
["source","shell",subs="attributes"]
----
{beatname_lc} export dashboard --id="DASHBOARD_ID" > dashboard.json
----
+
To find the `DASHBOARD_ID`, look at the URL for the dashboard in {kib}. By
default, `export dashboard` writes the dashboard to stdout. The example shows
how to write the dashboard to a JSON file so that you can import it later. The
JSON file will contain the dashboard with all visualizations and searches. You
must load the index pattern separately for {beatname_uc}.
+
To load the dashboard, copy the generated `dashboard.json` file into the
`kibana/6/dashboard` directory of {beatname_uc}, and run
+{beatname_lc} setup --dashboards+ to import the dashboard.
+
If {kib} is not running on `localhost:5061`, you must also adjust the
{beatname_uc} configuration under `setup.kibana`.
endif::no_dashboards[]

[[template-subcommand]]*`template`*::
Exports the index template to stdout. You can specify the `--es.version` and
`--index` flags to further define what gets exported. Furthermore you can export
the template to a file instead of `stdout` by defining a directory via `--dir`.

[[ilm-policy-subcommand]]
*`ilm-policy`*::
Exports the index lifecycle management policy to stdout. You can specify the
`--es.version` and a `--dir` to which the policy should be exported as a
file rather than exporting to `stdout`.

ifdef::serverless[]
[[function-subcommand]]*`function` FUNCTION_NAME*::
Exports an {cloudformation-ref} template to stdout.
endif::serverless[]

*FLAGS*

*`--es.version VERSION`*::
When used with <<template-subcommand,`template`>>, exports an index
template that is compatible with the specified version.
When used with <<ilm-policy-subcommand,`ilm-policy`>>, exports the ILM policy
if the specified ES version is enabled for ILM.

*`-h, --help`*::
Shows help for the `export` command.

*`--index BASE_NAME`*::
When used with <<template-subcommand,`template`>>, sets the base name to use for
the index template. If this flag is not specified, the default base name is
+{beatname_lc}+.

*`--dir DIRNAME`*::
Define a directory to which the template and ILM policy should be exported to
as files instead of printing them to `stdout`.

ifndef::no_dashboards[]
*`--id DASHBOARD_ID`*::
When used with <<dashboard-subcommand,`dashboard`>>, specifies the dashboard ID.
endif::no_dashboards[]

{global-flags}

*EXAMPLES*

ifndef::serverless[]
ifndef::no_dashboards[]
["source","sh",subs="attributes"]
-----
{beatname_lc} export config
{beatname_lc} export template --es.version {version} --index myindexname
{beatname_lc} export dashboard --id="a7b35890-8baa-11e8-9676-ef67484126fb" > dashboard.json
-----
endif::no_dashboards[]

ifdef::no_dashboards[]
["source","sh",subs="attributes"]
-----
{beatname_lc} export config
{beatname_lc} export template --es.version {version} --index myindexname
-----
endif::no_dashboards[]
endif::serverless[]

ifdef::serverless[]
["source","sh",subs="attributes"]
-----
{beatname_lc} export config
{beatname_lc} export template --es.version {version} --index myindexname
{beatname_lc} export function cloudwatch
-----
endif::serverless[]

[[help-command]]
==== `help` command

{help-command-short-desc}.
ifndef::serverless[]
If no command is specified, shows help for the `run` command.
endif::[]

*SYNOPSIS*

["source","sh",subs="attributes"]
----
{beatname_lc} help COMMAND_NAME [FLAGS]
----


*`COMMAND_NAME`*::
Specifies the name of the command to show help for.

*FLAGS*

*`-h, --help`*:: Shows help for the `help` command.

{global-flags}

*EXAMPLE*

["source","sh",subs="attributes"]
-----
{beatname_lc} help export
-----

ifndef::serverless[]
[[keystore-command]]
==== `keystore` command

{keystore-command-short-desc}.

*SYNOPSIS*

["source","sh",subs="attributes"]
----
{beatname_lc} keystore SUBCOMMAND [FLAGS]
----

*SUBCOMMANDS*

*`add KEY`*::
Adds the specified key to the keystore. Use the `--force` flag to overwrite an
existing key. Use the `--stdin` flag to pass the value through `stdin`.

*`create`*::
Creates a keystore to hold secrets. Use the `--force` flag to overwrite the
existing keystore.

*`list`*::
Lists the keys in the keystore.

*`remove KEY`*::
Removes the specified key from the keystore.

*FLAGS*

*`--force`*::
Valid with the `add` and `create` subcommands. When used with `add`, overwrites
the specified key. When used with `create`, overwrites the keystore.

*`--stdin`*::
When used with `add`, uses the stdin as the source of the key's value.

*`-h, --help`*::
Shows help for the `keystore` command.


{global-flags}

*EXAMPLES*

["source","sh",subs="attributes"]
-----
{beatname_lc} keystore create
{beatname_lc} keystore add ES_PWD
{beatname_lc} keystore remove ES_PWD
{beatname_lc} keystore list
-----

See <<keystore>> for more examples.

endif::[]

ifeval::["{beatname_lc}"=="functionbeat"]
[[package-command]]
==== `package` command

{package-command-short-desc}.

*SYNOPSIS*

["source","sh",subs="attributes"]
----
{beatname_lc} package [FLAGS]
----

*FLAGS*

*`-h, --help`*::
Shows help for the `package` command.

*`-o, --output`*::
Specifies the full path pattern to use when creating the packages.

{global-flags}

*EXAMPLES*

["source","sh",subs="attributes"]
-----
{beatname_lc} package --output /path/to/folder/package-{{.Provider}}.zip
-----

[[remove-command]]
==== `remove` command

{remove-command-short-desc}. Before removing functions, make sure the user has
the credentials required by your cloud service provider.

*SYNOPSIS*

["source","sh",subs="attributes"]
----
{beatname_lc} remove FUNCTION_NAME [FLAGS]
----

*`FUNCTION_NAME`*::
Specifies the name of the function to remove.

*FLAGS*

*`-h, --help`*::
Shows help for the `remove` command.

{global-flags}

*EXAMPLES*

["source","sh",subs="attributes"]
-----
{beatname_lc} remove cloudwatch
{beatname_lc} remove sqs
-----
endif::[]

ifdef::has_modules_command[]
[[modules-command]]
==== `modules` command

{modules-command-short-desc}. You can use this command to enable and disable
specific module configurations defined in the `modules.d` directory. The
changes you make with this command are persisted and used for subsequent
runs of {beatname_uc}.

To see which modules are enabled and disabled, run the `list` subcommand.

*SYNOPSIS*

["source","sh",subs="attributes"]
----
{beatname_lc} modules SUBCOMMAND [FLAGS]
----


*SUBCOMMANDS*

*`disable MODULE_LIST`*::
Disables the modules specified in the space-separated list.

*`enable MODULE_LIST`*::
Enables the modules specified in the space-separated list.

*`list`*::
Lists the modules that are currently enabled and disabled.


*FLAGS*

*`-h, --help`*::
Shows help for the `export` command.


{global-flags}

*EXAMPLES*

ifeval::["{beatname_lc}"=="filebeat"]
["source","sh",subs="attributes"]
-----
{beatname_lc} modules list
{beatname_lc} modules enable apache2 auditd mysql
-----
endif::[]

ifeval::["{beatname_lc}"=="metricbeat"]
["source","sh",subs="attributes"]
-----
{beatname_lc} modules list
{beatname_lc} modules enable apache nginx system
-----
endif::[]
endif::[]

ifndef::serverless[]
[[run-command]]
==== `run` command

{run-command-short-desc}.

*SYNOPSIS*

["source","sh",subs="attributes"]
-----
{beatname_lc} run [FLAGS]
-----

Or:

["source","sh",subs="attributes"]
-----
{beatname_lc} [FLAGS]
-----

*FLAGS*

ifeval::["{beatname_lc}"=="packetbeat"]
*`-I, --I FILE`*::
Reads packet data from the specified file instead of reading packets from the
network. This option is useful only for testing {beatname_uc}.
+
["source","sh",subs="attributes"]
-----
{beatname_lc} run -I ~/pcaps/network_traffic.pcap
-----
endif::[]

*`-N, --N`*:: Disables publishing for testing purposes.
ifndef::no_file_output[]
This option disables all outputs except the <<file-output,File output>>.
endif::[]

ifeval::["{beatname_lc}"=="packetbeat"]
*`-O, --O`*::
Read packets one by one by pressing _Enter_ after each. This option is useful
only for testing {beatname_uc}.
endif::[]

*`--cpuprofile FILE`*::
Writes CPU profile data to the specified file. This option is useful for
troubleshooting {beatname_uc}.

ifeval::["{beatname_lc}"=="packetbeat"]
*`-devices`*::
Prints the list of devices that are available for sniffing and then exits.
endif::[]

ifeval::["{beatname_lc}"=="packetbeat"]
*`-dump FILE`*::
Writes all captured packets to the specified file. This option is useful for
troubleshooting {beatname_uc}.
endif::[]

*`-h, --help`*::
Shows help for the `run` command.

*`--httpprof [HOST]:PORT`*::
Starts an http server for profiling. This option is useful for troubleshooting
and profiling {beatname_uc}.

ifeval::["{beatname_lc}"=="packetbeat"]
*`-l N`*::
Reads the pcap file `N` number of times. The default is 1. Use this option in
combination with the `-I` option. For an infinite loop, use _0_. The `-l`
option is useful only for testing {beatname_uc}.
endif::[]

*`--memprofile FILE`*::
Writes memory profile data to the specified output file. This option is useful
for troubleshooting {beatname_uc}.

ifeval::["{beatname_lc}"=="filebeat"]
*`--modules MODULE_LIST`*::
Specifies a comma-separated list of modules to run. For example:
+
["source","sh",subs="attributes"]
-----
{beatname_lc} run --modules nginx,mysql,system
-----
+
Rather than specifying the list of modules every time you run {beatname_uc},
you can use the <<modules-command,`modules`>> command to enable and disable
specific modules. Then when you run {beatname_uc}, it will run any modules
that are enabled.
endif::[]

ifeval::["{beatname_lc}"=="filebeat"]
*`--once`*::
When the `--once` flag is used, {beatname_uc} starts all configured harvesters
and inputs, and runs each input until the harvesters are closed. If you set the
`--once` flag, you should also set `close_eof` so the harvester is closed when
the end of the file is reached. By default harvesters are closed after
`close_inactive` is reached.
endif::[]

ifeval::["{beatname_lc}"=="metricbeat"]
*`--system.hostfs MOUNT_POINT`*::

Specifies the mount point of the host's filesystem for use in monitoring a host
from within a container.
endif::[]

ifeval::["{beatname_lc}"=="packetbeat"]
*`-t`*::
Reads packets from the pcap file as fast as possible without sleeping. Use this
option in combination with the `-I` option. The `-t` option is useful only for
testing Packetbeat.
endif::[]

{global-flags}

*EXAMPLE*

["source","sh",subs="attributes"]
-----
{beatname_lc} run -e
-----

Or:

["source","sh",subs="attributes"]
-----
{beatname_lc} -e
-----
endif::[]


[[setup-command]]
==== `setup` command

{setup-command-short-desc}

* The index template ensures that fields are mapped correctly in Elasticsearch.
If index lifecycle management is enabled it also ensures that the defined ILM policy
and write alias are connected to the indices matching the index template.
The ILM policy takes care of the lifecycle of an index, when to do a rollover,
when to move an index from the hot phase to the next phase, etc.

ifndef::no_dashboards[]
* The {kib} dashboards make it easier for you to visualize {beatname_uc} data
in {kib}.
endif::no_dashboards[]

ifdef::has_ml_jobs[]
* The machine learning jobs contain the configuration information and metadata
necessary to analyze data for anomalies.
endif::[]

This command sets up the environment without actually running
{beatname_uc} and ingesting data.

*SYNOPSIS*

// tag::setup-command-tag[]
["source","sh",subs="attributes"]
----
{beatname_lc} setup [FLAGS]
----


*FLAGS*

ifndef::no_dashboards[]
*`--dashboards`*::
Sets up the {kib} dashboards (when available). This option loads the dashboards
from the {beatname_uc} package. For more options, such as loading customized
dashboards, see {beatsdevguide}/import-dashboards.html[Importing Existing Beat
Dashboards] in the _Beats Developer Guide_.
endif::no_dashboards[]

*`-h, --help`*::
Shows help for the `setup` command.

ifdef::has_ml_jobs[]
*`--machine-learning`*::
Sets up machine learning job configurations only.
endif::[]

ifeval::["{beatname_lc}"=="filebeat"]
*`--modules MODULE_LIST`*::
Specifies a comma-separated list of modules. Use this flag to avoid errors when
there are no modules defined in the +{beatname_lc}.yml+ file.

*`--pipelines`*::
Sets up ingest pipelines for configured filesets. {beatname_uc} looks for
enabled modules in the +{beatname_lc}.yml+ file. If you used the
<<modules-command,`modules`>> command to enable modules in the `modules.d`
directory, also specify the `--modules` flag.
endif::[]

*`--index-management`*::
Sets up components related to Elasticsearch index management including
template, ILM policy, and write alias (if supported and configured).

ifdef::apm-server[]
*`--pipelines`*::
Registers the <<configuring-ingest-node,pipeline>> definitions set in `ingest/pipeline/definition.json`.
endif::apm-server[]

*`--template`*::
deprecated:[7.2]
Sets up the index template only.
It is recommended to use `--index-management` instead.

*`--ilm-policy`*::
deprecated:[7.2]
Sets up the index lifecycle management policy.
It is recommended to use `--index-management` instead.

{global-flags}

*EXAMPLES*

ifeval::["{beatname_lc}"=="filebeat"]
["source","sh",subs="attributes"]
-----
{beatname_lc} setup --dashboards
{beatname_lc} setup --machine-learning
{beatname_lc} setup --pipelines
{beatname_lc} setup --pipelines --modules system,nginx,mysql <1>
{beatname_lc} setup --index-management
-----
<1> If you used the <<modules-command,`modules`>> command to enable modules in
the `modules.d` directory, also specify the `--modules` flag to indicate which
modules to load pipelines for.
endif::[]

ifeval::["{beatname_lc}"!="filebeat"]

ifndef::no_dashboards[]
["source","sh",subs="attributes"]
-----
{beatname_lc} setup --dashboards
{beatname_lc} setup --machine-learning
{beatname_lc} setup --index-management
-----
endif::no_dashboards[]

ifndef::apm-server[]
ifdef::no_dashboards[]
["source","sh",subs="attributes"]
-----
{beatname_lc} setup --machine-learning
{beatname_lc} setup --index-management
-----
endif::no_dashboards[]
endif::apm-server[]

ifdef::apm-server[]
["source","sh",subs="attributes"]
-----
{beatname_lc} setup --index-management
{beatname_lc} setup --pipelines
-----
endif::apm-server[]

endif::[]
// end::setup-command-tag[]

[[test-command]]
==== `test` command

{test-command-short-desc}.

*SYNOPSIS*

["source","sh",subs="attributes"]
----
{beatname_lc} test SUBCOMMAND [FLAGS]
----

*SUBCOMMANDS*

*`config`*::
Tests the configuration settings.

ifeval::["{beatname_lc}"=="metricbeat"]
*`modules [MODULE_NAME] [METRICSET_NAME]`*::
Tests module settings for all configured modules. When you run this command,
{beatname_uc} does a test run that applies the current settings, retrieves the
metrics, and shows them as output. To test the settings for a specific module,
specify `MODULE_NAME`. To test the settings for a specific metricset in the
module, also specify `METRICSET_NAME`.
endif::[]

*`output`*::
Tests that {beatname_uc} can connect to the output by using the
current settings.

*FLAGS*

*`-h, --help`*:: Shows help for the `test` command.

{global-flags}

ifeval::["{beatname_lc}"!="metricbeat"]
*EXAMPLE*

["source","sh",subs="attributes"]
-----
{beatname_lc} test config
-----
endif::[]

ifeval::["{beatname_lc}"=="metricbeat"]
*EXAMPLES*

["source","sh",subs="attributes"]
-----
{beatname_lc} test config
{beatname_lc} test modules system cpu
-----
endif::[]

ifeval::["{beatname_lc}"=="functionbeat"]
[[update-command]]
==== `update` command

{update-command-short-desc}. Before updating functions, make sure the user has
the credentials required by your cloud service provider.

*SYNOPSIS*

["source","sh",subs="attributes"]
----
{beatname_lc} update FUNCTION_NAME [FLAGS]
----

*`FUNCTION_NAME`*::
Specifies the name of the function to update.

*FLAGS*

*`-h, --help`*::
Shows help for the `update` command.

{global-flags}

*EXAMPLES*

["source","sh",subs="attributes"]
-----
{beatname_lc} update cloudwatch
{beatname_lc} update sqs
-----
endif::[]

[[version-command]]
==== `version` command

{version-command-short-desc}.

*SYNOPSIS*

["source","sh",subs="attributes"]
----
{beatname_lc} version [FLAGS]
----


*FLAGS*

*`-h, --help`*:: Shows help for the `version` command.

{global-flags}

*EXAMPLE*

["source","sh",subs="attributes"]
-----
{beatname_lc} version
-----


[float]
[[global-flags]]
=== Global flags

These global flags are available whenever you run {beatname_uc}.

*`-E, --E "SETTING_NAME=VALUE"`*::
Overrides a specific configuration setting. You can specify multiple overrides.
For example:
+
["source","sh",subs="attributes"]
----------------------------------------------------------------------
{beatname_lc} -E "name=mybeat" -E "output.elasticsearch.hosts=['http://myhost:9200']"
----------------------------------------------------------------------
+
This setting is applied to the currently running {beatname_uc} process.
The {beatname_uc} configuration file is not changed.

ifeval::["{beatname_lc}"=="filebeat"]
*`-M, --M "VAR_NAME=VALUE"`*:: Overrides the default configuration for a
{beatname_uc} module. You can specify multiple variable overrides. For example:
+
["source","sh",subs="attributes"]
----------------------------------------------------------------------
{beatname_lc} -modules=nginx -M "nginx.access.var.paths=['/var/log/nginx/access.log*']" -M "nginx.access.var.pipeline=no_plugins"
----------------------------------------------------------------------
endif::[]

*`-c, --c FILE`*::
Specifies the configuration file to use for {beatname_uc}. The file you specify
here is relative to `path.config`. If the `-c` flag is not specified, the
default config file, +{beatname_lc}.yml+, is used.

*`-d, --d SELECTORS`*::
Enables debugging for the specified selectors. For the selectors, you can
specify a comma-separated
list of components, or you can use `-d "*"` to enable debugging for all
components. For example, `-d "publisher"` displays all the publisher-related
messages.

*`-e, --e`*::
Logs to stderr and disables syslog/file output.

*`-environment`*::
For logging purposes, specifies the environment that {beatname_uc} is running in.
This setting is used to select a default log output when no log output is configured.
Supported values are: `systemd`, `container`, `macos_service`, and `windows_service`.
If `systemd` or `container` is specified, {beatname_uc} will log to stdout and stderr
by default.

*`--path.config`*::
Sets the path for configuration files. See the <<directory-layout>> section for
details.

*`--path.data`*::
Sets the path for data files. See the <<directory-layout>> section for details.

*`--path.home`*::
Sets the path for miscellaneous files. See the <<directory-layout>> section for
details.

*`--path.logs`*::
Sets the path for log files. See the <<directory-layout>> section for details.

*`--strict.perms`*::
Sets strict permission checking on configuration files. The default is `-strict.perms=true`.
ifndef::apm-server[]
See {beats-ref}/config-file-permissions.html[Config file ownership and permissions]
for more information.
endif::[]
ifdef::apm-server[]
See <<config-file-ownership>> for more information.
endif::[]

*`-v, --v`*::
Logs INFO-level messages.
