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:

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

1. Connect your repository to Tuist: Follow the

   GitHub integration guide to connect your GitHub repository to your Tuist project.

2. 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

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:

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:

tuist account tokens list my-account

To revoke a token by name:

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:

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