Scalr CLI

scalr is a single-binary command-line client for the Scalr API. It exposes every operation in the API (every endpoint becomes a subcommand), plus a handful of convenience commands for scripting.

The CLI is the right choice when you want to drive Scalr from a shell, a CI job, or a script. Output is JSON by default so it pipes cleanly into jq, and exit codes distinguish permanent errors from transient ones so retries are straightforward.

Installation

Homebrew (macOS, Linux)

brew tap Scalr/scalr
brew install scalr

Manual

The CLI is a single static binary with no runtime dependencies. Download the archive for your OS and architecture from the releases page and drop the binary somewhere in your PATH.

Self-update

Once installed, scalr can replace its own binary in place:

scalr -update

Configure

The CLI needs a hostname and API token before it can make any calls. Configuration is resolved in the following order:

1. Command-line environment: SCALR_HOSTNAME, SCALR_TOKEN, SCALR_ACCOUNT, SCALR_PROFILE
2. ~/.scalr/scalr.conf (selected profile, or the top-level block in legacy flat format)
3. ~/.terraform.d/credentials.tfrc.json — picked up automatically if no token was found above

Run the interactive wizard to write a config file:

$ scalr -configure
Scalr Hostname [ex: example.scalr.io]: example.scalr.io
Scalr Token (not echoed!):
Default Scalr Account-ID [ex: acc-tq8cgt2hu6hpfuj]: acc-tq8cgt2hu6h1234
Configuration saved in /home/user/.scalr/scalr.conf

See the API reference for how to obtain an API token.

Profiles

scalr.conf can hold multiple named profiles. Pick one with -profile or SCALR_PROFILE:

{
  "default": {
    "hostname": "example.scalr.io",
    "token": "..."
  },
  "staging": {
    "hostname": "staging.scalr.io",
    "token": "..."
  }
}

scalr -profile=staging get-workspaces
SCALR_PROFILE=staging scalr get-workspaces

If the file has the legacy flat shape (hostname/token at the top level), it continues to work unchanged.

Basic usage

$ scalr

Usage: scalr [OPTION] COMMAND [FLAGS]

  'scalr' is a command-line interface tool that communicates directly with the Scalr API

Examples:
  $ scalr -help
  $ scalr -help get-workspaces
  $ scalr get-foo-bar -flag=value
  $ scalr -verbose create-foo-bar -flag=value -flag2=value2
  $ scalr create-foo-bar < json-blob.txt

Environment variables:
  SCALR_HOSTNAME  Scalr Hostname, i.e example.scalr.io
  SCALR_TOKEN     Scalr API Token
  SCALR_ACCOUNT   Default Scalr Account ID, i.e acc-tq8cgt2hu6hpfuj
  SCALR_PROFILE   Named profile to load from scalr.conf

Options:
  -version       Shows current version of this binary
  -help          Shows documentation for all (or specified) command(s)
  -verbose       Shows complete request and response communication data
  -configure     Run configuration wizard
  -update        Updates this tool to the latest version by downloading and replacing current binary
  -autocomplete  Enable shell tab auto-complete
  -quiet         Disables printing server responses
  -format=STRING Output format: json (default), table, csv
  -fields=LIST   Comma-separated list of fields to include in output
  -page=INT      Fetch only a specific page (default: fetch all pages)
  -page-size=INT Number of items per page (default: 100)
  -profile=STRING Use a named configuration profile from scalr.conf
  -query=STRING  Dot-path expression to extract values (e.g. .name, .[].id)
  -no-color      Disable colored output

Exit codes:
  0  Success
  1  Error (bad input, 4xx, missing flags, not found)
  3  Transient error (5xx, network failure, timeout) — safe to retry

Discover commands

Every API operation is available as a subcommand:

scalr -help                       # list every command, grouped by resource
scalr -help create-workspace      # show flags for one command
scalr -help | grep workspace      # filter to a resource area

The canonical reference for every command, its flags, and its JSON body is the Scalr API reference. The CLI is generated from the same OpenAPI spec, so anything you find in the API has a corresponding subcommand.

Per-command help

$ scalr -help create-environment

Usage: scalr [OPTION] create-environment [FLAGS] [< json-blob.txt]

  Create a new environment in the account.

Flags:
  -cost-estimation-enabled=BOOLEAN           Indicates if the cost estimation should be performed for `runs` in the environment.
  -default-provider-configurations-id=LIST   Provider configurations used in the environment workspaces by default.
  -name=STRING                               The name of the environment. [*required]
  -policy-groups-id=LIST
  -tags-id=LIST

Required flags are marked [*required]. Running a command with missing required flags prints a short error and exits 1:

$ scalr lock-workspace
Missing required flag(s): [workspace]

Aliases

A few common commands have short aliases built in:

Passing data: flags or JSON

For create/update commands, the same request can be built two ways.

Flags: shortest path for simple calls:

scalr create-environment -name=development

Raw JSON:API body on stdin, which is useful when you already have a payload, are templating requests, or need to set attributes the flag interface doesn't expose:

scalr create-environment < env.json

echo '
{
  "data": {
    "attributes": {"name": "development"},
    "relationships": {
      "account": {"data": {"id": "acc-t2fcrq6h1v3nf0g", "type": "accounts"}}
    },
    "type": "environments"
  }
}
' | scalr create-environment

Flags and a JSON body can be combined; flags override the corresponding fields in the body.

Output

Formats

The default format is JSON.

scalr get-workspaces                          # JSON (default)
scalr -format=table get-workspaces            # aligned columns, best-effort defaults per resource
scalr -format=csv get-workspaces > ws.csv     # RFC 4180 CSV
scalr -format=table get-workspace -workspace=ws-xxx   # single object → key/value view

Table and CSV formats pick a sensible default column set per resource type (e.g. workspaces show id, name, status, terraform-version, auto-apply, execution-mode). Override with -fields:

scalr -format=table -fields=id,name,status get-workspaces

-fields also filters JSON output — handy for trimming big responses before piping them further.

Querying with -query

-query takes a dot-path expression and extracts values. Scalar results are printed one per line (no JSON quoting) so they drop straight into shell loops:

scalr -query=.id get-workspace -workspace=ws-xxx
# ws-xxx

scalr -query='.[].id' get-workspaces
# ws-aaa
# ws-bbb
# ws-ccc

for id in $(scalr -query='.[].id' get-workspaces); do
  scalr lock-workspace -workspace="$id"
done

Supported forms: .field, .a.b for nested access, .[] to iterate an array, .[].field to get a field from each element. Anything more complex, pipe to jq.

Pagination

List commands fetch every page by default. Cap the response with -page and -page-size:

scalr -page-size=25 get-workspaces           # 25 per page, still paginates through all
scalr -page=1 -page-size=25 get-workspaces   # just the first 25

When a specific page is requested, the CLI prints pagination metadata (page N of M, total count) to stderr.

Quiet, verbose, color

• -quiet — suppress server response output (useful when you only care about the exit code, e.g. in CI gates).
• -verbose — dump full request and response, including headers. Use when debugging auth or permission errors.
• -no-color — strip ANSI codes. Also disabled automatically if NO_COLOR or CI is set, or when stdout is not a terminal.

Scripting patterns

Exit codes

Exit codes are stable and meaningful:

Retry loops should only retry on 3:

while :; do
  scalr ping
  rc=$?
  [ $rc -ne 3 ] && break
  sleep 5
done
exit $rc

Waiting for a run

scalr wait-for-run is a built-in (not a generated API command) that polls a run until it reaches a terminal state and exits with 0 on success (applied, planned_and_finished) or 1 otherwise. It also exits 1 if the run gets stuck on human input (policy override, cost approval) so CI doesn't hang forever.

run=$(scalr -query=.id create-run < run.json)
scalr wait-for-run -run="$run" -timeout=30m

Opening the UI

For the times when a script needs to drop the user into the browser:

scalr open account
scalr open environment <name-or-id>
scalr open workspace <name-or-id>
scalr open run <run-id>

Shell tab completion

scalr -autocomplete

Restart your shell, then press TAB twice to see available commands, flags, and enum values. Completion covers command names, flag names, filter/sort/include values, and comma-separated list continuations:

$ scalr list-e
list-endpoints           list-environment-tags    list-environments        list-event-definitions

$ scalr list-environments -sort=
account                  cost-estimation-enabled  created-at               created-by-email         name

$ scalr list-environments -sort=account -include=tags,
tags,account             tags,created-by          tags,policy-groups       tags,tags
tags,cloud-credentials   tags,default-provider-configurations              tags,provider-configurations