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]
FlagsDescription
-h, --helpPrints help information
-q, --quietReduce detail of internal logging. Repeat to reduce further. Overrides --verbose
-r, --require-healthyExit on startup if any sinks fail healthchecks The VECTOR_REQUIRE_HEALTHY is also supported.
-v, --verboseEnable more detailed logging. Repeat to reduce further. Overrides --verbose
-V, --versionPrints version information
-w, --watch-configWatch for changes in the configuration file, and reload accordingly The VECTOR_WATCH_CONFIG is also supported.
OptionsDescription
--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>
FlagsDescription
-h, --helpPrints help information
-f, --fragmentWhether to skip the generation of global fields
-V, --versionPrints version information
OptionsDescription
--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]
FlagsDescription
-h, --helpPrints help information
-V, --versionPrints version information
OptionsDescription
--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>
OptionsDescription
--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>
FlagsDescription
-h, --helpPrints help information
-V, --versionPrints version information
OptionsDescription
-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]
FlagsDescription
-h, --helpPrints help information
-h, --human-metricsHumanize metrics, using numeric suffixes - e.g. 1,100 = 1.10 k, 1,000,000 = 1.00 M
-V, --versionPrints version information
OptionsDescription
-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>
FlagsDescription
-h, --helpPrints help information
-ne, --no-environmentDisables environment checks. That includes component checks and health checks
-V, --versionPrints version information
-d, --deny-warningsFail validation on warnings
OptionsDescription
--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>
FlagsDescription
-h, --helpPrints help information
-o, --print-objectPrint the (modified) object, instead of the result of the final expression. The same result can be achieved by using . as the final expression.
-V, --versionPrints version information
OptionsDescription
-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.

  • commonoptionalstring

    AWS_ACCESS_KEY_ID

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

    • Syntax: literal
  • 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
  • commonoptionalstring

    AWS_DEFAULT_REGION

    The default AWS region.

    • Syntax: literal
    • Only relevant when: endpoint = null
  • 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"
  • 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
  • commonoptionalstring

    AWS_SECRET_ACCESS_KEY

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

    • Syntax: literal
  • commonoptionalstring

    AWS_SESSION_TOKEN

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

    • Syntax: literal
  • 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
  • commonoptionalstring

    DOCKER_CONFIG

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

    • Syntax: literal
  • commonoptionalstring

    DOCKER_HOST

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

    • Syntax: literal
  • 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
  • optionalstring

    LOG

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

  • 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
  • optionalbool

    RUST_BACKTRACE

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

  • 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
  • optionalstring

    VECTOR_CONFIG

    Sets the location of Vector's configuration file.

  • optionalbool

    VECTOR_REQUIRE_HEALTHY

    Exit on startup if any sinks fail healthchecks.

  • optionaluint

    VECTOR_THREADS

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

  • optionalbool

    VECTOR_WATCH_CONFIG

    Watch for changes in configuration file, and reload accordingly.