v0.12.0: Templates for control outputs, two new formats →

Configuration Files


Configuration options are defined using HCL options blocks in one or more Steampipe config files. Steampipe will load ALL configuration files from ~/.steampipe/config that have a .spc extension. By default, Steampipe creates a ~/.steampipe/config/default.spc file for setting options.

Terminal options may also be set at the workspace level; workspace options will override any global options set in the ~/.steampipe/config directory. To set terminal options at the workspace level, add them to a workspace.spc file in the root of your workspace folder. The syntax and supported arguments are identical to the terminal options as set in the global config file.

Note that many of the options control settings that can also be specified via other mechanisms, such as command line arguments, environment variables, etc. These settings are resolved in a standard order:

  1. Explicitly set in session (via a meta-command).
  2. Specified in command line argument.
  3. Set in environment variable.
  4. Set in a configuration file options argument.
  5. If not specified, a default value is used.

The following options are currently supported:

Option TypeDescription
generalGeneral CLI options, such as auto-update options
terminalTerminal options, which generally map to meta-commands
databaseDatabase options
connectionOptions that apply to connections

General options

General options apply generally to the steampipe CLI.

Supported options

update_checktruetrue, falseEnable or disable automatic update checking. This can also be set via the STEAMPIPE_UPDATE_CHECK environment variable.
max_parallel5an integerSet the maximum number of parallel executions. When running steampipe check, Steampipe will attempt to run up to this many controls in parallel. This can also be set via the STEAMPIPE_MAX_PARALLEL environment variable.

Example: General Options

options "general" {
update_check = true # true, false
max_parallel = 3

Terminal Options

Terminal options can be used to change query output formats and other terminal options. Typically, these can also be set via meta-commands or command line arguments of the same name.

Supported options

headertruetrue, falseEnable or disable column headers.
multifalsetrue, falseEnable or disable multiline mode.
outputtablejson, csv, table, lineSet output format.
separator,Any single characterSet csv output separator.
timingfalsetrue, falseEnable or disable query execution timing.
search_pathThe active database search pathComma separated stringSet an exact search path. Note that setting the search path in the terminal options sets it for the session when running steampipe; this setting will not be in effect when connecting to Steampipe from 3rd party tools.
search_path_prefixEmptyComma separated stringMove connections to the front of the search path.
watchtruetrue, falseWatch SQL files in the current workspace for changes (works only in interactive mode).

Example: Terminal Options

options "terminal" {
header = true # true, false
multi = false # true, false
output = "table" # json, csv, table, line
separator = "," # any single character
timing = false # true, false
search_path = "aws,aws2,gcp,gcp2" # comma-separated string; an exact search_path
search_path_prefix = "aws2,gcp2" # comma-separated string; a search_path_prefix to prepend to the search_path
watch = true # true, false

Database Options

Database options are used to control database options, such as the IP address and port on which the database listens.

Supported options

port9193any valid, open port numberThe TCP port that postgres will listen on
listennetworklocal, networkThe network listen mode when steampipe is started in service mode. Use network to listen on all IP addresses, or local to restrict to localhost.
search_pathAll connections, alphabeticallyComma separated stringSet an exact search path. Note that setting the search path in the database options sets it in the database; this setting will also be in effect when connecting to Steampipe from 3rd party tools.

Example: Database Options

options "database" {
port = 9193 # any valid, open port number
listen = "local" # local, network
search_path = "aws,aws2,gcp,gcp2" # comma-separated string; an exact search_path

Connection Options

Connection options are options that can be set on a per-connection basis. Connection options may be set at 2 scopes:

  • Defined in a top-level options "connection", these apply to ALL connections that do not explicitly override them.
  • Defined in an options block under a connection, these apply only to that connection. Per-connection options always override top-level connection options, and their arguments are identical.

Supported options

cachetruetrue, falseEnable or disabled caching
cache_ttl300an integerThe length of time to cache results, in seconds

Example: Top-Level Connection Options

Top-Level connection options apply to ALL connections (unless overridden in an options block within a connection).

options "connection" {
cache = true # true, false
cache_ttl = 300 # expiration (TTL) in seconds

Example: Per-Connection Options

connection "aws_account1" {
plugin = "aws"
profile = "account1"
regions = ["us-east-1", "us-east-2", "us-west-1", "us-west-2", "eu-west-1", "eu-west-2"]
options "connection" {
cache = true # true, false
cache_ttl = 300 # expiration (TTL) in seconds