--- updatedAt: 2026-04-23T20:14:34.000Z agentTools: projectIndex: https://docs.scalr.io/llms.txt --- # Scalr CLI Overview # 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) ```bash 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](https://github.com/Scalr/scalr-cli/releases) and drop the binary somewhere in your `PATH`. ## Self-update Once installed, `scalr` can replace its own binary in place: ```bash 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: ```bash $ 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](https://docs.scalr.io/reference/overview-1) for how to obtain an API token. ## Profiles `scalr.conf` can hold multiple named profiles. Pick one with `-profile` or `SCALR_PROFILE`: ```json { "default": { "hostname": "example.scalr.io", "token": "..." }, "staging": { "hostname": "staging.scalr.io", "token": "..." } } ``` ```bash 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 ```shell $ 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: ```bash 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](https://docs.scalr.io/reference/overview-1). The CLI is generated from the same OpenAPI spec, so anything you find in the API has a corresponding subcommand. ## Per-command help ```shell $ 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: | Alias | Resolves to | | ------ | ------------------- | | `ws` | `get-workspaces` | | `envs` | `list-environments` | | `runs` | `get-runs` | # Passing data: flags or JSON For create/update commands, the same request can be built two ways. Flags: shortest path for simple calls: ```bash 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: ```json 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. ```bash 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`: ```bash 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: ```bash 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`: ```bash 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: | Code | Meaning | | ---- | --------------------------------------------------------------- | | `0` | Success | | `1` | Permanent error — bad input, 4xx, missing flag, not found | | `3` | Transient error — 5xx, network failure, timeout (safe to retry) | Retry loops should only retry on `3`: ```bash 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. ```bash 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: ```bash scalr open account scalr open environment scalr open workspace scalr open run ``` # Shell tab completion ```bash 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 ```