Skip to main content

Getting Started

What is the Tharsis CLI?​

The Tharsis CLI is a command-line interface to the Tharsis remote Terraform backend. It communicates directly with the Tharsis API via gRPC.

For installation instructions, see the CLI setup guide.

SDK Deprecation

The Tharsis SDK for Go is deprecated. The CLI now uses the gRPC client package from the Tharsis API directly.

Have a question?

Check the FAQ to see if there's already an answer.

Authentication methods​

Single Sign-On (SSO)​

SSO authentication is meant to be used by human users interacting with Tharsis.

  • When using SSO, the CLI:
    1. Temporarily opens up a web browser session.
    2. Gets a token from the configured sign-in provider via a callback server.
    3. Stores that in the credentials file.
    4. Uses the token to authenticate against the Tharsis API via gRPC.
caution

The token must be periodically renewed via the SSO process.
It is recommended that the token be renewed before running a long job to avoid expiration mid-run.

Service account​

A service account is meant to be used for Machine to Machine (M2M) authentication like a CI/CD pipeline.

  • The CLI expects the following environment variables:
    • THARSIS_SERVICE_ACCOUNT_ID
      • Required.
      • The ID or TRN of the service account within Tharsis (e.g., trn:service_account:my-group/my-sa).
    • THARSIS_SERVICE_ACCOUNT_TOKEN
      • Required.
      • The OIDC token to be used for authentication.
      • Must satisfy the boundClaims you set in oidcTrustPolicies when the service account was created.
note

THARSIS_SERVICE_ACCOUNT_PATH is deprecated but still supported for backwards compatibility. It cannot be used together with THARSIS_SERVICE_ACCOUNT_ID.

  • Alternatively, a static token can be supplied via:
    • THARSIS_STATIC_TOKEN
      • A pre-existing authentication token (e.g., from an SSO login).
important

Environment variables for service accounts take precedence over SSO authentication.

Profiles​

The CLI includes a profile system making it possible to easily switch back and forth between different Tharsis instances.

Each profile has its own name, the Tharsis API URL, and state token from the SSO process. Profile settings are stored in a settings file, while tokens are stored separately in a credentials file for security.

Switch profiles using the -p global option or the THARSIS_PROFILE environment variable:

tharsis -p production workspace list
export THARSIS_PROFILE=production
tharsis workspace list
info

The -p flag takes precedence over the THARSIS_PROFILE environment variable. If neither is set, the default profile is used.

Environment variables​

VariableDescription
THARSIS_PROFILESets the active profile. Overridden by the -p flag.
THARSIS_CLI_LOGSets the log level for debugging (e.g., debug, info, warn, error). Defaults to off.
NO_COLORDisables colored output when set to any non-empty value. Also available as the -no-color flag.

Resource identifiers​

CLI commands accept both Global IDs and TRNs as resource identifiers. Global IDs are stable across renames and moves, while TRNs provide a human-readable way to reference resources by type and path — avoiding ambiguity between resource types that share similar path structures. See Resource Identifiers for details on each format.

Using a TRN
tharsis workspace get trn:workspace:my-group/my-workspace
Using a Global ID
tharsis workspace get V1NfZjA5OWVkMmQtNDZmMS00ZmYw...

Shell autocomplete​

The CLI supports shell autocompletion for commands and flags. To enable it:

tharsis -enable-autocomplete

To disable it:

tharsis -disable-autocomplete

Frequently asked questions (FAQ)​

Is it possible to use Terraform CLI with Tharsis?​

Yes. Terraform CLI is compatible with Tharsis, although it will only provide a subset of the features that the Tharsis CLI offers. Learn more. You can also run Terraform commands directly through the Tharsis CLI using the tf-exec subcommand — see the command reference.