Authentication Command (auth)

Relevant source files

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

• src/commands/auth.ts
• src/internal/auth-flow.ts
• src/internal/state.ts
• src/internal/config.ts
• src/internal/terminal/auth-terminal.ts
• skills/putio-cli/SKILL.md

The auth command module is a core component of the putio-cli, responsible for managing user credentials and session states. It provides the necessary infrastructure to authorize the CLI against the put.io API using a device-link flow, maintain persisted configuration, and support multiple named profiles for different environments or users.

This module ensures that the CLI can operate both in interactive terminal modes for human users and in deterministic, headless modes for automated agents and scripts. It handles the lifecycle of authentication tokens from acquisition via OOB (Out-of-Band) device pairing to secure local storage and retrieval.
Sources: src/commands/auth.ts:1-20, README.md:95-120

Authentication Architecture

The authentication system is built on an Effect-based service architecture, primarily utilizing the CliState service to manage persisted configurations and the CliRuntime to handle environment-specific logic.

Component Overview

Component	Responsibility
authLogin	Orchestrates the device pairing flow to acquire a new OAuth token.
CliState	Manages the reading, writing, and clearing of the config.json file.
auth-flow.ts	Logic for building link URLs and polling the API for token completion.
auth-terminal.ts	Specialized renderers for displaying boxed activation codes and login success messages.

Sources: src/commands/auth.ts:121-205, src/internal/state.ts:66-120

Logic Flow: Device Pairing

The device pairing flow allows the CLI to be authorized without requiring the user to type their password directly into the terminal. Instead, a code is generated and verified through the put.io web application.

Configuration and Profile Management

The CLI supports a sophisticated configuration schema that allows for a global authentication state or isolated "profiles".

Configuration Schema

The configuration is stored in a JSON file (typically config.json) with the following structure:

• api_base_url: The target API endpoint.
• auth_token: The legacy/global authentication token.
• default_profile: The name of the profile to use if no other is specified.
• profiles: A record of named profiles, each containing its own api_base_url and auth_token.

Sources: src/internal/state.ts:19-29

Profile Resolution Order

When a command is executed, the CLI resolves the authentication token and API base URL using the following precedence:

1. Environment Variable: PUTIO_CLI_TOKEN (overrides everything).
2. Explicit Flag: The --profile flag passed to the command.
3. Environment Profile: The PUTIO_CLI_PROFILE environment variable.
4. Default Profile: The default_profile key in the configuration file.
5. Legacy Global: The top-level auth_token in the configuration file.

Subcommands

The auth command contains several subcommands for managing the authentication lifecycle.

Command Reference

Subcommand	Purpose	Key Parameters
login	Starts the device-link flow to persist a token.	--profile, --open, --timeout-seconds
status	Reports current resolution (authenticated, source, profile).	--profile, --output json
logout	Removes the token from the specified profile or global config.	--profile
profiles list	Lists all named profiles and their authentication status.	--output json
profiles use	Sets a specific named profile as the default.	[profile] (Argument)
profiles remove	Completely deletes a profile entry from the config.	[profile] (Argument)
preview	Visualizes the login UI without hitting the API.	--code

Sources: src/commands/auth.ts:258-355

Auth Status Data Structure

The status command provides a structured object (when using --output json) representing the resolved state:

export const AuthStatusSchema = Schema.Struct({
  apiBaseUrl: Schema.String,
  authenticated: Schema.Boolean,
  configPath: Schema.String,
  defaultProfile: Schema.NullOr(Schema.String),
  profile: Schema.NullOr(Schema.String),
  source: Schema.NullOr(Schema.Literals("env", "config", "profile")),
});

Sources: src/internal/state.ts:39-46

Security and Sanitization

The auth module integrates with the CLI's output service to ensure sensitive information is never leaked in logs or terminal output.

• Redaction: Tokens and sensitive keys (like auth_token or password) are automatically redacted with [REDACTED] when rendering to the terminal or JSON, unless explicitly requested for internal use.
• File Permissions: When savePersistedState is called, the CLI ensures the configuration file is created with restricted permissions (0o600) to prevent other users on the system from reading the tokens.
• URL Sanitization: Token query parameters (e.g., oauth_token=...) are stripped from URLs before they are printed.

Sources: src/internal/output.test.ts:15-55, src/internal/state.test.ts:79-110

Conclusion

The auth command is a robust gateway for the putio-cli, balancing user-friendly interactive flows with the strict requirements of automated environments. By utilizing a layered resolution strategy and a secure persistence model, it provides flexible account management while maintaining high security standards for user credentials.