CLI Reference

Vector is a single binary that be managed through a command line interface. This page documents all of the available flags, options, subcommands, and environment variables.

vector [FLAGS] [OPTIONS] [SUBCOMMAND] [ARGS]

Commands

Start

The root command (no subcommand) starts Vector.

vector [FLAGS] [OPTIONS]

Flags	Description
-h, --help	Prints help information
-q, --quiet	Reduce detail of internal logging. Repeat to reduce further. Overrides --verbose
-r, --require-healthy	Exit on startup if any sinks fail healthchecks The VECTOR_REQUIRE_HEALTHY is also supported.
-v, --verbose	Enable more detailed logging. Repeat to reduce further. Overrides --verbose
-V, --version	Prints version information
-w, --watch-config	Watch for changes in the configuration file, and reload accordingly The VECTOR_WATCH_CONFIG is also supported.
Options	Description
--color <enum>	Control when ANSI terminal formatting is used. Must be one of always, auto, and never. The VECTOR_COLOR is also supported.
-c, --config <string>	Read configuration from one or more files. Wildcard paths are supported. If zero files are specified the default config path /etc/vector/vector.toml will be targeted. TOML, YAML and JSON file formats are supported. The format to interpret the file with is determined from the file extension (.toml, .yaml, .json). We will fallback to TOML if we are unable to detect a supported format. The VECTOR_CONFIG is also supported.
--config-toml <string>	Read configuration from one or more files. Wildcard paths are supported. TOML file format is assumed. The VECTOR_CONFIG_TOML is also supported.
--config-json <string>	Read configuration from one or more files. Wildcard paths are supported. JSON file format is assumed. The VECTOR_CONFIG_JSON is also supported.
--config-yaml <string>	Read configuration from one or more files. Wildcard paths are supported. YAML file format is assumed. The VECTOR_CONFIG_YAML is also supported.
-t, --threads <integer>	Number of threads to use for processing (default is number of available cores) The VECTOR_THREADS is also supported.
--log-format <enum>	Set the logging format [default: text] Must be one of json and text. The VECTOR_LOG_FORMAT is also supported.

generate

Generate a Vector configuration containing a list of components

vector generate [FLAGS] [OPTIONS] <pipeline>

Flags	Description
-h, --help	Prints help information
-f, --fragment	Whether to skip the generation of global fields
-V, --version	Prints version information
Options	Description
--file <string>	Generate config as a file
Args
<pipeline>

help

Prints this message or the help of the given subcommand(s)

vector help

list

List available components, then exit

vector list [FLAGS] [OPTIONS]

Flags	Description
-h, --help	Prints help information
-V, --version	Prints version information
Options	Description
--format <enum>	Format the list in an encoding schema Must be one of avro, json, and text.

test

Run Vector config unit tests, then exit. This command is experimental and therefore subject to change. For guidance on how to write unit tests check out: /guides/level-up/unit-testing/

vector test [OPTIONS] <paths>

Options	Description
--config-toml <string>	Test configuration from one or more files. Wildcard paths are supported. TOML file format is assumed. The VECTOR_CONFIG_TOML is also supported.
--config-json <string>	Test configuration from one or more files. Wildcard paths are supported. JSON file format is assumed. The VECTOR_CONFIG_JSON is also supported.
--config-yaml <string>	Test configuration from one or more files. Wildcard paths are supported. YAML file format is assumed. The VECTOR_CONFIG_YAML is also supported.
Args
<paths>

tap

Observe log events from topology components.

vector tap [FLAGS] [OPTIONS] <components>

Flags	Description
-h, --help	Prints help information
-V, --version	Prints version information
Options	Description
-i, --interval <integer>	Interval to sample metrics at, in milliseconds
-u, --url <string>	Vector GraphQL API server endpoint
-l, --limit <integer>	Sample log events to the provided limit
-f, --format <enum>	Encoding format for logs printed to screen Must be one of json and yaml.
Args
<components>

top

Display topology and metrics in the console, for a local or remote Vector instance

vector top [FLAGS] [OPTIONS]

Flags	Description
-h, --help	Prints help information
-h, --human-metrics	Humanize metrics, using numeric suffixes - e.g. 1,100 = 1.10 k, 1,000,000 = 1.00 M
-V, --version	Prints version information
Options	Description
-i, --refresh-interval <integer>	How often the screen refreshes (in milliseconds)
-u, --url <string>	The URL for the GraphQL endpoint of the running Vector instance

validate

Validate the target config, then exit

vector validate [FLAGS] [OPTIONS] <paths>

Flags	Description
-h, --help	Prints help information
-ne, --no-environment	Disables environment checks. That includes component checks and health checks
-V, --version	Prints version information
-d, --deny-warnings	Fail validation on warnings
Options	Description
--config-toml <string>	Any number of Vector config files to validate. TOML file format is assumed.
--config-json <string>	Any number of Vector config files to validate. JSON file format is assumed.
--config-yaml <string>	Any number of Vector config files to validate. YAML file format is assumed.
Args
<paths>

vrl

Vector Remap Language CLI

vector vrl [FLAGS] [OPTIONS] <program>

Flags	Description
-h, --help	Prints help information
-o, --print-object	Print the (modified) object, instead of the result of the final expression. The same result can be achieved by using . as the final expression.
-V, --version	Prints version information
Options	Description
-i, --input <string>	File containing the object(s) to manipulate. Leave empty to use stdin.
-p, --program <string>	File containing the program to execute. Can be used instead of PROGRAM.
Args
<program>

Environment Variables

You can control Vector's behavior through select environment variables:

ENV_VAR1=val ENV_VAR2=val vector --config=/etc/vector/vector.toml

In addition, we recommend that you look at the global configuration options as well.

21 items

common

• commonoptionalstring

  AWS_ACCESS_KEY_ID

  The AWS access key id. Used for AWS authentication when communicating with AWS services.

  • Syntax: literal
  • View examples
• commonoptionalstring

  AWS_CONFIG_FILE

  Specifies the location of the file that the AWS CLI uses to store configuration profiles.

  • Syntax: literal
  • Default: "~/.aws/config"
• commonoptionalstring

  AWS_CREDENTIAL_EXPIRATION

  Expiration time in RFC 3339 format. If unset, credentials won't expire.

  • Syntax: literal
  • View examples
• commonoptionalstring

  AWS_DEFAULT_REGION

  The default AWS region.

  • Syntax: literal
  • Only relevant when: endpoint = null
  • View examples
• commonoptionalstring

  AWS_PROFILE

  Specifies the name of the CLI profile with the credentials and options to use. This can be the name of a profile stored in a credentials or config file.

  • Syntax: literal
  • Default: "default"
  • View examples
• commonoptionalstring

  AWS_ROLE_SESSION_NAME

  Specifies a name to associate with the role session. This value appears in CloudTrail logs for commands performed by the user of this profile.

  • Syntax: literal
  • View examples
• commonoptionalstring

  AWS_SECRET_ACCESS_KEY

  The AWS secret access key. Used for AWS authentication when communicating with AWS services.

  • Syntax: literal
  • View examples
• commonoptionalstring

  AWS_SESSION_TOKEN

  The AWS session token. Used for AWS authentication when communicating with AWS services.

  • Syntax: literal
  • View examples
• commonoptionalstring

  AWS_SHARED_CREDENTIALS_FILE

  Specifies the location of the file that the AWS CLI uses to store access keys.

  • Syntax: literal
  • Default: "~/.aws/credentials"
• commonoptionalstring

  DOCKER_CERT_PATH

  Path to look for TLS certificates when tls configuration is absent. Vector will use:

  • $DOCKER_CERT_PATH/ca.pem: CA certificate.
  • $DOCKER_CERT_PATH/cert.pem: TLS certificate.
  • $DOCKER_CERT_PATH/key.pem: TLS key.
  • Syntax: literal
  • View examples
• commonoptionalstring

  DOCKER_CONFIG

  Path to look for TLS certificates when both tls configuration and DOCKER_CERT_PATH are absent.

  • Syntax: literal
  • View examples
• commonoptionalstring

  DOCKER_HOST

  The Docker host to connect to when docker_host configuration is absent.

  • Syntax: literal
  • View examples
• commonoptionalstring

  GOOGLE_APPLICATION_CREDENTIALS

  The filename for a Google Cloud service account credentials JSON file used for authentication.

  • Syntax: literal
  • Only relevant when: endpoint = null
  • View examples
• optionalstring

  LOG

  Sets Vector's log level. See the log section in the monitoring guide for more information on the available levels.

  • View examples
• commonoptionalstring

  PROCFS_ROOT

  Sets an arbitrary path to the system's Procfs root. Can be used to expose host metrics from within a container. Unset and uses system /proc by default.

  • Syntax: literal
  • View examples
• optionalbool

  RUST_BACKTRACE

  Enables backtraces when errors are logged. Use this when debugging only since it can degrade performance.

  • View examples
• commonoptionalstring

  SYSFS_ROOT

  Sets an arbitrary path to the system's Sysfs root. Can be used to expose host metrics from within a container. Unset and uses system /sys by default.

  • Syntax: literal
  • View examples
• optionalstring

  VECTOR_CONFIG

  Sets the location of Vector's configuration file.

  • View examples
• optionalbool

  VECTOR_REQUIRE_HEALTHY

  Exit on startup if any sinks fail healthchecks.

  • View examples
• optionaluint

  VECTOR_THREADS

  Number of threads to use for processing (default is number of available cores).

  • View examples
• optionalbool

  VECTOR_WATCH_CONFIG

  Watch for changes in configuration file, and reload accordingly.

  • View examples