workspace

A Steampipe workspace is a "profile" that allows you to define a unified environment that the Steampipe client can interact with. Each workspace is composed of:

  • a single Steampipe database instance
  • a single mod directory (which may also contain dependency mods)
  • context-specific settings and options (snapshot location, query timeout, etc)

Workspace configurations can be defined in any .spc file in the ~/.steampipe/config directory, but by convention they are defined in ~/.steampipe/config/workspaces.spc file. This file may contain multiple workspace definitions that can then be referenced by name.

Steampipe workspaces allow you to define multiple named configurations and easily switch between them using the --workspace argument or STEAMPIPE_WORKSPACE environment variable.

workspace "local" {
workspace_database = "local"
}
workspace "dev_insights" {
workspace_database = "local"
mod_location = "~/mods/steampipe-mod-aws-insights"
}
workspace "acme_prod" {
workspace_database = "acme/prod"
snapshot_location = "acme/prod"
}

To learn more, see Managing Workspaces →

Workspace Arguments

Many of the workspace arguments correspond to CLI flags and/or environment variables. Any unset arguments will assume the default values.

ArgumentDefaultDescription
baseA reference to a named workspace resource that this workspace should source its definition from. Any argument can be overridden after sourcing via base.
cachetrueEnable/disable caching. Note that is a client setting - if the database (options "database") has the cache disabled, then the cache is disabled regardless of the workspace setting.

Env: STEAMPIPE_CACHE
cache_ttl300Set the client query cache expiration (TTL) in seconds. Note that is a client setting - if the database cache_max_ttl is lower than the cache_ttl in the workspace, then the effective ttl for this workspace is the cache_max_ttl.

Env: STEAMPIPE_CACHE_TTL
cloud_hostpipes.turbot.comSet the Turbot Pipes host for connecting to Turbot Pipes workspace. DEPRECATED - Use pipes_host.

Env: STEAMPIPE_CLOUD_HOST, PIPES_HOST
CLI: --cloud-host
cloud_tokenThe token obtained by steampipe loginSet the Turbot Pipes authentication token for connecting to a Turbot Pipes workspace. DEPRECATED - Use pipes_token,

Env: STEAMPIPE_CLOUD_TOKEN, PIPES_TOKEN
CLI: --cloud-token
inputtrueEnable/Disable interactive prompts for missing variables. To disable prompts and fail on missing variables, set to false. This is useful when running from scripts.

CLI: --input
install_dir~/.steampipeThe directory in which the Steampipe database, plugins, and supporting files can be found.

Env: STEAMPIPE_INSTALL_DIR
CLI: --install-dir
introspectionnoneEnable introspection tables that allow you to query the mod resources in the workspace. Supported values are none and info.

Env: STEAMPIPE_INTROSPECTION
max_parallel5Set the maximum number of parallel executions. When running steampipe check, Steampipe will attempt to run up to this many controls in parallel.

Env: STEAMPIPE_MAX_PARALLEL
CLI: --max-parallel
mod_locationThe current working directorySet the workspace working directory.

Env: STEAMPIPE_MOD_LOCATION
CLI: --mod-location
optionsAn options block to set command-specific options for this workspace. Query, check, and dashboard options are supported.
pipes_hostpipes.turbot.comSet the Turbot Pipes host for connecting to Turbot Pipes workspace.

Env: PIPES_HOST
CLI: --pipes-host
pipes_tokenThe token obtained by steampipe loginSet the Turbot Pipes authentication token for connecting to a Turbot Pipes workspace. This may be a token obtained by steampipe login or a user-generated token.

Env: PIPES_TOKEN
CLI: --pipes-token
progresstrueEnable or disable progress information.

CLI: --progress
query_timeout240 for controls, unlimited otherwiseThe maximum time (in seconds) a query is allowed to run before it times out.

Env: STEAMPIPE_QUERY_TIMEOUT
CLI: --query_timeout
search_pathpublic, then alphabeticalA comma-separated list of connections to use as a custom search path for the control run. See also: Using search_path to target connections and aggregators.

CLI: --search-path
search_path_prefixA comma-separated list of connections to use as a prefix to the current search path for the control run. See also: Using search_path to target connections and aggregators.

CLI: --search-path-prefix
snapshot_locationThe Turbot Pipes user's personal workspaceSet the Turbot Pipes workspace or filesystem path for writing snapshots.

Env: STEAMPIPE_SNAPSHOT_LOCATION
CLI: --snapshot-location
themedarkSelect output theme (color scheme, etc) when running steampipe check. Possible values are light,dark, and plain

CLI: --theme
watchtrueWatch .sql and .sp files in the current workspace (works only in interactive mode).

CLI: --watch
workspace_databaselocalWorkspace database. This can be local or a remote Turbot Pipes database.

Env: STEAMPIPE_WORKSPACE_DATABASE
CLI: --workspace-database

Steampipe Query Options

A workspace may include an options "query" block to specify values specific to the steampipe query command.

These options often correspond to CLI flags.

ArgumentDefaultDescription
autocompletetrueEnable or disable autocomplete in the interactive query shell.
headertrueEnable or disable column headers.

CLI: --header
multifalseEnable or disable multiline mode.
outputtableSet output format (json, csv, table, or line).

CLI: --output
separator,Set csv output separator.

CLI: --separator
timingoffEnable or disable query execution timing: off, on, or verbose

CLI: --timing

Steampipe Check Options

A workspace may include an options "check" block to specify values specific to the steampipe check command.

These options often correspond to CLI flags.

ArgumentDefaultDescription
headertrueEnable or disable column headers.

CLI: --header
outputtextSet output format (brief, csv, html, json, md, sps (snapshot), text, none).

CLI: --output
separator,Set csv output separator.

CLI: --separator
timingfalseEnable or disable query execution timing: false or true

CLI: --timing

Steampipe Dashboard Options

A workspace may include a options "dashboard" block to specify values specific to the steampipe dashboard command.

These options often correspond to CLI flags.

ArgumentDefaultDescription
browsertrueSpecify whether to launch the browser after starting the dashboard server.

CLI: --browser

Examples

workspace "default" {
query_timeout = 300
}
workspace "dev" {
base = workspace.default
snapshot_location = "~/snapshots/"
}
workspace "all_options" {
pipes_host = "pipes.turbot.com"
pipes_token = "tpt_999faketoken99999999_111faketoken1111111111111"
install_dir = "~/steampipe2"
mod_location = "~/src/steampipe-mod-aws-insights"
query_timeout = 300
snapshot_location = "acme/dev"
workspace_database = "local"
search_path = "aws,aws_1,aws_2,gcp,gcp_1,gcp_2,slack,github"
search_path_prefix = "aws_all"
watch = true
max_parallel = 5
introspection = false
input = true
progress = true
theme = "dark" # light, dark, plain
cache = true
cache_ttl = 300
options "query" {
autocomplete = true
header = true # true, false
multi = false # true, false
output = "table" # json, csv, table, line
separator = "," # any single char
timing = "on" # on, off, verbose
}
options "check" {
header = true # true, false
output = "text" # brief, csv, html, json, md, text, snapshot or none (default "text")
separator = "," # any single char
timing = true # true, false
}
options "dashboard" {
browser = true
}
}