Command-Line Interface (CLI)

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.
-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.

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: https://vector.dev/docs/setup/guides/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>

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>

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.

    • View examples
  • commonoptionalstring

    AWS_CONFIG_FILE

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

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

    AWS_CREDENTIAL_EXPIRATION

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

    • View examples
  • commonoptionalstring

    AWS_DEFAULT_REGION

    The default AWS region.

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

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

    • View examples
  • commonoptionalstring

    AWS_SECRET_ACCESS_KEY

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

    • View examples
  • commonoptionalstring

    AWS_SESSION_TOKEN

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

    • View examples
  • commonoptionalstring

    AWS_SHARED_CREDENTIALS_FILE

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

    • 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.
    • View examples
  • commonoptionalstring

    DOCKER_CONFIG

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

    • View examples
  • commonoptionalstring

    DOCKER_HOST

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

    • View examples
  • commonoptionalstring

    GOOGLE_APPLICATION_CREDENTIALS

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

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

    RUST_BACKTRACE

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

    • 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