Command: tusk auth

Relevant source files

The following files were used as context for generating this wiki page:

• cmd/auth.go
• cmd/auth_login.go
• cmd/auth_logout.go
• internal/auth/auth.go
• cmd/auth_status.go
• internal/cliconfig/config.go
• internal/agent/tools/cloud.go

The tusk auth command is the primary interface for managing authentication with Tusk Drift Cloud. It provides a set of subcommands to handle user login, logout, and status checking. Authentication is performed against an Auth0 instance using the Device Authorization Flow, which allows CLI users to authenticate via a web browser.

This system is designed to handle JWT-based authentication for interactive use and also respects API key-based authentication (via the TUSK_API_KEY environment variable), which is suitable for CI/CD environments. The CLI securely stores access and refresh tokens locally and manages token refresh automatically.

Sources: cmd/auth.go:13-14, cmd/auth_login.go:15-16, internal/auth/auth.go:33-35

Subcommands

The auth command is a parent command that groups several authentication-related actions.

Command	Description	Source File
login	Authenticate with Tusk Cloud.	cmd/auth_login.go
logout	Log out from Tusk Cloud.	cmd/auth_logout.go
status	Show authentication and connection status.	cmd/auth_status.go
select-org	Select the active organization for Tusk Cloud.	cmd/auth_select_org.go

Sources: cmd/auth.go:13, cmd/auth_login.go:15, cmd/auth_logout.go:13, cmd/auth_status.go:15

Authentication Flow (tusk auth login)

The tusk auth login command initiates the Auth0 Device Authorization Flow. This process allows a user to authenticate on a browser-based device and grant the CLI access to Tusk Cloud resources.

The following sequence diagram illustrates the login process:

This diagram shows the interactions between the user, the CLI, Auth0, and the Tusk Cloud API during the tusk auth login process.

Key Components

• auth.Authenticator: The central struct that encapsulates authentication logic. It holds Auth0 client details and the current token state.
  Sources: internal/auth/auth.go:33-42
• Login() function: The main entry point in cmd/auth_login.go. It creates an Authenticator and calls its Login method.
  Sources: cmd/auth_login.go:23-32
• RequestDeviceCode(): Initiates the flow by requesting a device code from Auth0.
  Sources: internal/auth/auth.go:102-120
• PollForToken(): After the user is prompted to authenticate, this function polls Auth0's token endpoint until the user completes the browser flow or the request times out.
  Sources: internal/auth/auth.go:123-157
• cacheAuthInfo(): After a successful login, this function is called to fetch user and organization details from the Tusk Cloud API and store them in the local CLI configuration file.
  Sources: cmd/auth_login.go:40-97

Token Management

Authentication tokens (access, refresh, and ID) are stored locally to maintain the user's session across CLI invocations.

Token Storage

• Location: Tokens are stored in a JSON file located at ~/.config/tusk/cli.json.

• Structure: The file contains the tokens and their expiry time. The Token struct defines this structure.

  // internal/auth/auth.go:44-49
  type Token struct {
  	AccessToken  string    `json:"access_token"`
  	RefreshToken string    `json:"refresh_token"`
  	IDToken      string    `json:"id_token"`
  	Expiry       time.Time `json:"expiry"`
  }
  

• Functions:

  • SaveTokenFile(): Writes the current token to the file.
  • loadTokenFile(): Reads the token from the file.
  • clearTokenFile(): Deletes the token file, effectively logging the user out.

Sources: internal/auth/auth.go:44-49, 214-245, cmd/auth_logout.go:23

Token Refresh

The CLI automatically attempts to use existing or refresh tokens to avoid requiring the user to log in repeatedly.

• TryExistingAuth(): This method is called at the start of commands that require authentication (like tusk auth status). It first tries to load a token from the local file.
• Refresh Logic: If the access token is expired, it uses the refresh token to request a new set of tokens from Auth0. If successful, the new tokens are saved.
• Failure: If the refresh token is also invalid or the refresh fails, the user is considered logged out.

Sources: internal/auth/auth.go:62-99

Status Check (tusk auth status)

The tusk auth status command provides a summary of the current authentication state and connectivity to Tusk Cloud.

The logic for determining the status is as follows:

This flowchart shows how tusk auth status determines the effective authentication method and reports the connection status.

Implementation Details

1. Check Auth0 Login: It first calls auth.TryExistingAuth() to see if a valid JWT session exists.
2. Check API Key: It checks for the TUSK_API_KEY environment variable.
3. Determine Effective Method: The API key takes precedence over the JWT. If neither is present, the method is None.
4. Connect to Tusk Cloud: If an authentication method is available, it creates an api.Client and calls the GetAuthInfo endpoint.
5. Display Information: It prints the user's name, the active organization, the effective authentication method, and the connection status.

Sources: cmd/auth_status.go:20-111, internal/cliconfig/config.go:111-122

Configuration

Authentication state, including tokens and selected organization, is stored in a local configuration file.

• File Path: The configuration is stored at ~/.config/tusk/cli.json.
• Key Fields:

Field	Type	Description	Source File
access_token	string	The Auth0 access token. (Stored within the token object)	internal/auth/auth.go:45
refresh_token	string	The Auth0 refresh token. (Stored within the token object)	internal/auth/auth.go:46
selected_client_id	string	The ID of the Tusk Cloud organization selected by the user.	internal/cliconfig/config.go:21
user_id	string	The Tusk Cloud user ID, cached from the API.	internal/cliconfig/config.go:18
user_name	string	The user's name, cached from the API.	internal/cliconfig/config.go:19
is_tusk_developer	bool	A flag to disable analytics for Tusk developers.	CONTRIBUTING.md

Sources: internal/cliconfig/config.go:15-30, internal/auth/auth.go:44-49

AI Agent Integration

The authentication flow is also integrated into the AI-powered setup agent (tusk exp init). The agent can use a set of cloud-related tools to perform authentication on behalf of the user.

• cloud_check_auth: Checks if the user is already authenticated.
• cloud_login: Initiates the device code login flow.
• cloud_wait_for_login: Polls for the device code authentication to complete.

This allows the agent to guide the user through a full cloud setup, including authentication, without forcing them to manually run tusk auth login.

Sources: internal/agent/tools/cloud.go:39-204, internal/agent/executor.go:38-41, 319-340