OpenTofu CLI

Connect the OpenTofu CLI to a StackShip workspace and run plans and applies from your machine or CI.

StackShip is an OpenTofu cloud backend: run plans and applies in a StackShip workspace with the standard tofu command. There’s nothing extra to install and no separate stackship CLI.

Before you start

OpenTofu 1.6.0 or later.
A StackShip workspace.

Connect a workspace

In the dashboard, open Workspaces, select your workspace, and open CLI access.

Copy the Cloud block into your configuration:

terraform {
  cloud {
    hostname     = "stackship.run"
    organization = "acme"

    workspaces {
      name = "networking-production"
    }
  }
}

Sign in from your terminal:
```
tofu login stackship.run
```
Sign in in the browser and select Authorize. The login lasts 90 days and works in every organization you belong to.
Initialize:
```
tofu init
```

To bring existing state, follow Migrate state before your first plan.

Plan and apply

Command	What happens in StackShip
`tofu plan`	Starts a plan-only run that plans and checks policy. It can’t be applied.
`tofu plan -out=FILE`	Starts a saved plan that you can apply later with `tofu apply FILE`.
`tofu apply`	Starts a run that plans, checks policy, and then waits for your confirmation before applying.

Runs execute in StackShip, not on your machine, with the workspace’s OpenTofu version, variables, and cloud credentials. Output streams to your terminal, and each run appears under Runs in the dashboard.

Confirming an apply approves the plan, so you need a role with approval permission. See Run approvals.

Use OpenTofu in CI

For non-interactive use, create a workspace token instead of using tofu login:

On the workspace’s CLI access page, choose a purpose: Remote plan and apply for pipelines, or State migration for a one-time state import.
Choose when it expires: 1, 7, 30, 90, or 365 days.
Select Create token and copy it. It’s shown only once.

Store it as a CI secret and expose it as TF_TOKEN_stackship_run:

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

Creating tokens requires credential management permission (owners and admins). See Access tokens.

Private modules

The same login or token lets tofu init download modules from your organization’s private module registry:

module "vpc" {
  source  = "stackship.run/acme/vpc/aws"
  version = "~> 1.2"
}

Troubleshooting

Symptom	What to do
`tofu init` can’t find the workspace	Check that `organization` and `name` match the Cloud block on the CLI access page. If someone changed the organization slug, update your configuration.
Unauthorized or forbidden errors	Run `tofu login stackship.run` again, or check that your CI token hasn’t expired and was created for this workspace.
An apply waits and then fails to confirm	Your role can’t approve runs. Ask an owner or admin to approve it in the dashboard.
`tofu show -json` on a remote plan reports that the plan wasn’t found	Plan JSON can contain sensitive values, so it requires permission to read state and sensitive run artifacts (owner or admin). Other roles and workspace tokens get a not-found error. Ask an owner or admin.