_images/login_button.png _images/signup_button.png

Terraform CLI with Scalr

Reading time: 2-3 minutes

Scalr is an enhanced remote backend for the Terraform CLI. This provides the following capabilities:

  • State files stored centrally in Scalr

  • Terraform operations (plan, apply, destroy) run in workspaces in Scalr

  • Automatic policy evaluation (if configured)

To utilize Scalr as a remote backed there are 3 steps:

  1. Obtain an API token from Scalr

  2. Add a backed configuration to a Terraform configuration

  3. Set Terraform and Shell variables in the workspace

API Token

  1. In the environment create a token

  2. Add the token to the CLI Configuration file.

  • Windows : terraform.rc in %APPDATA% directory.

  • Unix/Linux/Mac : ~/.terraformrc

    credentials "my-account.scalr.io" {
      token = "<user-token>"

Backend Terraform Configuration

  1. Get the organization id from the environment switcher on the UI by hovering over, or get it from the Dashboard.

  2. Add a terraform block to a Terraform configuration. The hostname will be the local installation if IaCP is self-hosted. A workspace name can be chosen at this point.

terraform {
  backend "remote" {
    hostname = "my-account.scalr.io"
    organization = "<id of the environment>"  // e.g. org-t4737mmm538mabc
    workspaces {
      name = "<workspace-name>"


The ID of the environment can be either env-xxxxxxxxxxxxxxx or org-xxxxxxxxxxxxxxx

  1. Now run terraform init to create the workspace


If there is an existing state file in the local system or state had previously been stored in another remote backed, then the terraform init command will automatically migrate the state to Scalr. See Migrating to Scalr for more details


Version Mismatch. If the workspace is pre-created manually in Scalr and the Terraform version of the workspace does not match the version of the CLI then an error like this might be displayed.
Error reading local state: state snapshot was created by Terraform vx.x.x, which is newer than current vx.x.x; upgrade to Terraform vx.x.x or greater to work with this state.
This message is generated by Terraform, not Scalr, and is slightly misleading. Just make sure the workspace version and CLI version are the same.

Set Terraform Variables

If the Terraform configuration contains input variables that do not have assigned values, then these must be assigned values in then Scalr workspace via the UI. Scalr will automatically create the variables.




If the local workspace contains any *.auto.tfvars files these will provide default variable values that Terraform will automatically use.

If variables in the *.auto.tfvars files have the same names as variables specified in the workspace, the workspace’s values will be used. For map variables the values in *.auto.tfvars are merged with values in the same named variable in the workspace.

Set Shell Variables

If the Terraform configuration utilizes shell variables (export var=value), e.g. for credentials and other provider parameters, these must be set in Scalr.

Shell variables can be set at all levels in Scalr and are inherited by lower levels. Use environment or account level for shell variables that are needed in multiple workspaces or environments. Use workspace level for shell variables that are specific to individual Terraform configurations.

Example: Workspace level.


See Shell Variables for full details.

Supported CLI Commands

Scalr remote backend provides the following support for commands of Terraform CLI. Scalr only supports the CLI for versions >= 0.12.0:

CLI command