State and CLI access

Connect the tofu CLI to a workspace, browse state history, download state, and share outputs between workspaces.

StackShip keeps every version of a workspace’s state. Use it from the tofu CLI as you would with Terraform Cloud.

Connect the tofu CLI

Open the workspace and select the CLI access tab.

Copy the cloud block into your configuration:

terraform {
  cloud {
    hostname     = "stackship.run"
    organization = "your-org-slug"

    workspaces {
      name = "network-foundation"
    }
  }
}

The workspace name is the Cloud workspace name shown on CLI access and Settings, not the display name.

Use the cloud block, not the generic http backend. api.stackship.run also works as the hostname, but stackship.run is preferred.

Tokens for automation

For CI or other non-interactive use, create a token scoped to one workspace:

On CLI access, choose a Purpose:
- Remote plan and apply — start, read, and approve runs, and read state.
- State migration — read, lock, and write state. Use it to migrate state.
Choose when it Expires after: 1, 7, 30, 90, or 365 days.
Select Create token, copy it into your secret manager, then select I saved this token. The token isn’t shown again.

Provide it to tofu through an environment variable:

export TF_TOKEN_stackship_run='<token>'
tofu init
tofu plan

Creating tokens requires the admin or owner role. The dashboard can’t list or revoke tokens yet, so choose the shortest expiry that works. See access tokens.

State history

The State tab lists every state version, newest first, with its serial, creation time, resource count, size, and checksum. The active version is marked Current. The resource count is the number of managed resource instances in the state, so a resource with count = 3 counts three times and data sources are not counted.

Each successful apply or tofu state push creates a new version; older versions are never overwritten.

With the API, list versions with GET /v1/workspaces/{workspace_id}/state-versions.

Download state

Raw state can contain secrets, so downloads are restricted and recorded in the audit log.

On the State tab, select Download on the version you want.
Enter a reason (up to 500 characters).
Select Download raw state.

You need the admin or owner role. From the CLI, tofu state pull downloads the current version with a token that has state read access. With the API, use POST /v1/state-versions/{state_version_id}/download.

Store downloaded state outside your repository and delete temporary copies when you’re done.

Outputs

Members can read non-sensitive outputs, so tofu output works for everyone with access to the workspace. Sensitive outputs require state read access (admin or owner, or a token that includes it).

Locking

Runs and local tofu commands share one state lock, so a local tofu apply can’t collide with a run in progress.

As in Terraform Cloud, a lock request on a locked workspace fails with 409, even from the login or token that holds the lock. Two CI jobs that share a token can’t both hold the lock.

Push state

tofu state push works as in Terraform Cloud, except that lineage is checked even on a forced push.

The pushed state must have the workspace’s lineage and a higher serial than the current version. Any higher serial is accepted.
tofu state push -force skips the serial check but not the lineage check; a forced push with a different lineage is refused as soon as it starts. To adopt state with a different lineage, push it to a new workspace.
A push that starts but never finishes uploading blocks other pushes for up to 15 minutes; after that, the next push replaces it.

Restore an older version

There’s no rollback button. Download the earlier version and push it back with tofu state push -force (its serial is lower than the current one). Run a plan afterwards to confirm the result.

By default, no workspace can read another workspace’s state. To let one workspace read from another:

Open the workspace that produces the outputs and select the Access tab.
Choose a Role:
- Outputs consumer — read current non-sensitive outputs. This is what the tfe_outputs data source needs. Prefer this role.
- State consumer — read the full current state, including sensitive values. Required by terraform_remote_state. This exposes every attribute of every resource, so use it only when you must.
Under Who, choose a specific workspace, all workspaces in a project, or all workspaces in the organization.
Select Grant access.

Runs in the consuming workspace can then read the producer’s current state without extra tokens. Consumers only see the current version, and every full-state read is audited. Managing access requires the admin or owner role.

Read outputs with `tfe_outputs`

In the consuming workspace’s configuration, point the tfe provider at StackShip and name the producer workspace:

provider "tfe" {
  hostname = "stackship.run"
}

data "tfe_outputs" "network" {
  organization = "your-org-slug"
  workspace    = "network-foundation"
}

resource "aws_instance" "app" {
  subnet_id = data.tfe_outputs.network.nonsensitive_values.subnet_id
  # ...
}

Inside a StackShip run, the provider uses the run’s own credentials. You don’t need to configure a token.
From your laptop, run tofu login stackship.run first, or set the TFE_TOKEN environment variable to a StackShip access token.

With the Outputs consumer role, tfe_outputs returns only the producer’s non-sensitive outputs. Sensitive outputs are left out. Grant the State consumer role when the consumer needs sensitive outputs too.

Limits

Limit	Value
State file size	100 MB
Download reason	500 characters

Troubleshooting

The workspace is locked or busy — another run or tofu command holds the lock. Wait for it to finish, or cancel the active run.
A crashed job left the workspace locked — a tofu command or CI job that exited without unlocking still holds the lock, and retries with the same login or token get 409. An organization owner or admin, signed in with tofu login, runs this from the workspace’s configuration directory:
```
tofu force-unlock <organization>/<workspace>
```
For example, tofu force-unlock acme/production. Workspace and service account tokens can’t force-unlock. A lock held by a StackShip run can’t be force-unlocked: cancel the run instead.
tofu init can’t find the workspace — check that name matches the Cloud workspace name and organization matches your organization slug.
An apply was interrupted — the run page shows recovery options so an admin can confirm the correct state before the next run. See run lifecycle.