CLI Overview

Vector provides a powerful command-line interface for running, testing, and managing your observability pipeline.

Basic Usage

vector [OPTIONS] [COMMAND]

When run without a subcommand, Vector starts in daemon mode and processes data according to your configuration.

Global Options

These options apply to all commands and control Vector’s runtime behavior:

Configuration

-c, --config

string[]

Read configuration from one or more files. Wildcard paths are supported. File format is detected from the file name.

vector --config /etc/vector/vector.yaml
vector --config "/etc/vector/*.yaml"
vector -c config1.yaml,config2.yaml

Environment: VECTOR_CONFIG

-C, --config-dir

string[]

Read configuration from files in one or more directories. Files not ending in .toml, .json, .yaml, or .yml are ignored.

vector --config-dir /etc/vector/conf.d/

Environment: VECTOR_CONFIG_DIR

--config-toml

string[]

Read configuration from TOML files.

vector --config-toml vector.toml

Environment: VECTOR_CONFIG_TOML

--config-json

string[]

Read configuration from JSON files.

vector --config-json vector.json

Environment: VECTOR_CONFIG_JSON

--config-yaml

string[]

Read configuration from YAML files.

vector --config-yaml vector.yaml

Environment: VECTOR_CONFIG_YAML

Runtime Options

-t, --threads

integer

Number of threads to use for processing. Defaults to the number of available CPU cores.

vector --threads 4

Environment: VECTOR_THREADS

-r, --require-healthy

boolean

Exit on startup if any sinks fail healthchecks.

vector --require-healthy

Environment: VECTOR_REQUIRE_HEALTHY

-w, --watch-config

boolean

Watch for changes in configuration files and reload accordingly.

vector --watch-config

Environment: VECTOR_WATCH_CONFIG

--watch-config-method

string

Method for configuration watching: recommended or poll. Defaults to recommended (uses inotify on Linux, kqueue on macOS). Use poll for network filesystems like NFS.

vector --watch-config --watch-config-method poll

Environment: VECTOR_WATCH_CONFIG_METHOD

--watch-config-poll-interval-seconds

integer

Poll interval in seconds when using poll watch method. Default: 30 seconds.

vector --watch-config --watch-config-method poll --watch-config-poll-interval-seconds 60

Environment: VECTOR_WATCH_CONFIG_POLL_INTERVAL_SECONDS

Logging Options

-v, --verbose

flag

Enable more detailed internal logging. Can be repeated to increase level.

vector -v        # Debug level
vector -vv       # Trace level

Levels: -v = debug, -vv = trace

-q, --quiet

flag

Reduce detail of internal logging. Repeat to reduce further. Overrides --verbose.

vector -q        # Warn level
vector -qq       # Error level
vector -qqq      # Off

Levels: -q = warn, -qq = error, -qqq = off

--log-format

string

Set the logging format: text or json. Default: text.

vector --log-format json

Environment: VECTOR_LOG_FORMAT

--color

string

Control ANSI terminal formatting: auto, always, or never. Default: auto.

vector --color always

Environment: VECTOR_COLOR

-l, --internal-log-rate-limit

integer

Set the internal log rate limit in seconds. Default: 10 seconds.

vector --internal-log-rate-limit 60

Environment: VECTOR_INTERNAL_LOG_RATE_LIMIT

Shutdown Options

--graceful-shutdown-limit-secs

integer

Duration in seconds to wait for graceful shutdown after SIGINT or SIGTERM. Default: 60 seconds.

vector --graceful-shutdown-limit-secs 120

Environment: VECTOR_GRACEFUL_SHUTDOWN_LIMIT_SECS

--no-graceful-shutdown-limit

boolean

Never time out while waiting for graceful shutdown. Vector will attempt to send data until terminated by SIGKILL.

vector --no-graceful-shutdown-limit

Environment: VECTOR_NO_GRACEFUL_SHUTDOWN_LIMIT

Advanced Options

--disable-env-var-interpolation

boolean

Disable interpolation of environment variables in configuration files.

vector --disable-env-var-interpolation

Environment: VECTOR_DISABLE_ENV_VAR_INTERPOLATION

--openssl-no-probe

boolean

Disable probing and configuration of root certificate locations for OpenSSL. Useful when using the exec source.

vector --openssl-no-probe

Environment: VECTOR_OPENSSL_NO_PROBE

--allow-empty-config

boolean

Allow the configuration to run without any components. Useful with --watch-config for dynamic configuration loading.

vector --allow-empty-config --watch-config

Environment: VECTOR_ALLOW_EMPTY_CONFIG

Available Commands

Vector provides several subcommands for different operations:

validate

Validate configuration files

test

Run unit tests for your configuration

graph

Output topology as visual representation

top

Display topology and metrics in real-time

generate

Generate configuration from templates

list

List available components

convert-config

Convert configuration between formats

Examples

Start Vector with Configuration

vector --config /etc/vector/vector.yaml

Start with Multiple Configs

vector --config sources.yaml --config sinks.yaml

Run with Debug Logging

vector -v --config vector.yaml

Watch Configuration for Changes

vector --watch-config --config /etc/vector/vector.yaml

Run with Custom Thread Count

vector --threads 8 --config vector.yaml

Require Healthy Sinks on Startup

vector --require-healthy --config vector.yaml

Exit Codes

Vector uses standard exit codes:

0 - Success
1 - Generic error
78 - Configuration error

Environment Variables

All command-line options can be set via environment variables. See individual option descriptions for the corresponding environment variable names. Example:

export VECTOR_CONFIG=/etc/vector/vector.yaml
export VECTOR_THREADS=4
export VECTOR_LOG_FORMAT=json
vector

Signal Handling

Vector responds to the following signals:

SIGINT / SIGTERM - Initiates graceful shutdown
SIGHUP - Reloads configuration (if --watch-config is not used)
SIGKILL - Forces immediate termination (not recommended)

Example:

# Reload configuration
sudo kill -HUP $(pidof vector)

# Graceful shutdown
sudo kill -TERM $(pidof vector)

Sources

Transforms

Sinks

VRL

CLI

API

Basic Usage

Global Options

Configuration

Runtime Options

Logging Options

Shutdown Options

Advanced Options

Available Commands

validate

test

graph

top

generate

list

convert-config

Examples

Start Vector with Configuration

Start with Multiple Configs

Run with Debug Logging

Watch Configuration for Changes

Run with Custom Thread Count

Require Healthy Sinks on Startup

Exit Codes

Environment Variables

Signal Handling

Next Steps

Commands Reference

Configuration

Build docs developers (and LLMs) love

Sources

Transforms

Sinks

VRL

CLI

API

​Basic Usage

​Global Options

​Configuration

​Runtime Options

​Logging Options

​Shutdown Options

​Advanced Options

​Available Commands

validate

test

graph

top

generate

list

convert-config

​Examples

​Start Vector with Configuration

​Start with Multiple Configs

​Run with Debug Logging

​Watch Configuration for Changes

​Run with Custom Thread Count

​Require Healthy Sinks on Startup

​Exit Codes

​Environment Variables

​Signal Handling

​Next Steps

Commands Reference

Configuration

Build docs developers (and LLMs) love

Basic Usage

Global Options

Configuration

Runtime Options

Logging Options

Shutdown Options

Advanced Options

Available Commands

Examples

Start Vector with Configuration

Start with Multiple Configs

Run with Debug Logging

Watch Configuration for Changes

Run with Custom Thread Count

Require Healthy Sinks on Startup

Exit Codes

Environment Variables

Signal Handling

Next Steps