Authentication

To interact with the server, the CLI needs to authenticate the requests using bearer authentication. The CLI supports authenticating as a user, as an account, or using an OIDC token.

As a user#

When using the CLI locally on your machine, we recommend authenticating as a user. To authenticate as a user, you need to run the following command:

bash

tuist auth login

The command will take you through a web-based authentication flow. Once you authenticate, the CLI will store a long-lived refresh token and a short-lived access token under ~/.config/tuist/credentials. Each file in the directory represents the domain you authenticated against, which by default should be tuist.dev.json. The information stored in that directory is sensitive, so make sure to keep it safe.

The CLI will automatically look up the credentials when making requests to the server. If the access token is expired, the CLI will use the refresh token to get a new access token.

OIDC tokens#

For CI environments that support OpenID Connect (OIDC), Tuist can authenticate automatically without requiring you to manage long-lived secrets. When running in a supported CI environment, the CLI will automatically detect the OIDC token provider and exchange the CI-provided token for a Tuist access token.

Supported CI providers#

GitHub Actions
CircleCI
Bitrise

Setting up OIDC authentication#

Connect your repository to Tuist: Follow the GitHub integration guide to connect your GitHub repository to your Tuist project.
Run tuist auth login: In your CI workflow, run tuist auth login before any commands that require authentication. The CLI will automatically detect the CI environment and authenticate using OIDC.

See the Continuous Integration guide for provider-specific configuration examples.

OIDC token scopes#

OIDC tokens are granted the ci scope group, which provides access to all projects connected to the repository. See Scope groups for details about what the ci scope includes.

Security Benefits

OIDC authentication is more secure than long-lived tokens because:

No secrets to rotate or manage
Tokens are short-lived and scoped to individual workflow runs
Authentication is tied to your repository identity

Account tokens#

For CI environments that don't support OIDC, or when you need fine-grained control over permissions, you can use account tokens. Account tokens allow you to specify exactly which scopes and projects the token can access.

Creating an account token#

bash

tuist account tokens create my-account \
  --scopes project:cache:read project:cache:write \
  --name ci-cache-token \
  --expires 1y

The command accepts the following options:

Option	Description
`--scopes`	Required. Comma-separated list of scopes to grant the token.
`--name`	Required. A unique identifier for the token (1-32 characters, alphanumeric, hyphens, and underscores only).
`--expires`	Optional. When the token should expire. Use format like `30d` (days), `6m` (months), or `1y` (years). If not specified, the token never expires.
`--projects`	Limit the token to specific project handles. The token has access to all projects if not specified.

Available scopes#

Scope	Description
`account:members:read`	Read account members
`account:members:write`	Manage account members
`account:registry:read`	Read from the Swift package registry
`account:registry:write`	Publish to the Swift package registry
`project:previews:read`	Download previews
`project:previews:write`	Upload previews
`project:admin:read`	Read project settings
`project:admin:write`	Manage project settings
`project:cache:read`	Download cached binaries
`project:cache:write`	Upload cached binaries
`project:bundles:read`	View bundles
`project:bundles:write`	Upload bundles
`project:tests:read`	Read test results
`project:tests:write`	Upload test results
`project:builds:read`	Read build analytics
`project:builds:write`	Upload build analytics
`project:runs:read`	Read command runs
`project:runs:write`	Create and update command runs

Scope groups#

Scope groups provide a convenient way to grant multiple related scopes with a single identifier. When you use a scope group, it automatically expands to include all the individual scopes it contains.

Scope Group	Included Scopes
`ci`	`project:cache:write`, `project:previews:write`, `project:bundles:write`, `project:tests:write`, `project:builds:write`, `project:runs:write`

Continuous Integration#

For CI environments that don't support OIDC, you can create an account token with the ci scope group to authenticate your CI workflows:

bash

tuist account tokens create my-account --scopes ci --name ci

This creates a token with all the scopes needed for typical CI operations (cache, previews, bundles, tests, builds, and runs). Store the generated token as a secret in your CI environment and set it as the TUIST_TOKEN environment variable.

Managing account tokens#

To list all tokens for an account:

bash

tuist account tokens list my-account

To revoke a token by name:

bash

tuist account tokens revoke my-account ci-cache-token

Using account tokens#

Account tokens are expected to be defined as the environment variable TUIST_TOKEN:

bash

export TUIST_TOKEN=your-account-token

When To Use Account Tokens

Use account tokens when you need:

Authentication in CI environments that don't support OIDC
Fine-grained control over which operations the token can perform
A token that can access multiple projects within an account
Time-limited tokens that automatically expire