Put.io API SDK

Relevant source files

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

• src/internal/state.ts
• src/command-paths.test.ts
• src/internal/config.ts
• src/internal/localizers/shared.ts
• src/internal/auth-flow.ts
• package.json
• src/internal/metadata.test.ts

The Put.io API SDK is the core integration layer between the putio-cli and the official Put.io backend services. It leverages the @putdotio/sdk library to provide a type-safe, programmatic interface for managing cloud storage, transfers, and account settings. Within the CLI architecture, the SDK is managed as an Effect-native service, ensuring that authentication and configuration are resolved before any network requests are dispatched.

The SDK handles a wide range of operations including file management (list, search, delete, move, rename), transfer monitoring, and download link generation. It is designed to work seamlessly with the CLI's profile management system, allowing the SDK to switch between different user accounts and API environments dynamically.

Architecture and Integration

The integration of the SDK into the project follows a service-oriented architecture using the Effect library. The CLI provides a layer that resolves the necessary apiBaseUrl and token before providing an instance of the SDK to the command handlers.

SDK Initialization Flow

The initialization process depends on the resolution of the CliRuntimeConfig and the CliState. The CLI ensures that a valid token is present—either from environment variables (PUTIO_CLI_TOKEN) or from a persisted profile—before the SDK service is made available to the application.

Key SDK Modules

The SDK is organized into logical modules that correspond to Put.io API domains. Based on the implementation and testing mocks, the following modules are primary:

Module	Purpose	Key Methods
account	Manage user profile and storage	getInfo
files	Cloud storage management	list, search, mkdir, rename, move, delete, continue
transfers	Manage active downloads/transfers	addMany, list, cancel, clean, retry, watch
downloadLinks	Generate browser-ready links	create, get
events	Retrieve account history	list
auth	Handle device-link authorization	getCode, checkCodeMatch

Sources: src/command-paths.test.ts:167-195, src/internal/metadata.test.ts:35-65

Authentication and State Management

The SDK's behavior is dictated by the CliState service, which manages how authentication material is retrieved and persisted.

Resolved Auth State

When a command is executed, the resolveAuthState function determines the origin of the credentials. The SDK can be authenticated via three primary sources:

1. Environment: PUTIO_CLI_TOKEN takes highest precedence.
2. Profile: A named profile selected via PUTIO_CLI_PROFILE or CLI arguments.
3. Config: The legacy single-token configuration file.

Error Handling and Localization

API errors returned by the SDK are intercepted and processed by a localization layer before being displayed. This layer maps standard HTTP status codes and Put.io-specific error_type strings to human-readable (and agent-readable) messages.

Localizer Logic

The cliSharedErrorLocalizers use match conditions to identify specific error types and provide recovery suggestions.

• Rate Limits (429): Extracts retry_after, reset, and action. If a captcha is needed, it generates a resolution URL using the webAppUrl.
• Auth Failures (401/403): Suggests running putio auth login and provides hints about session status.
• Transport Errors: Specifically identifies PutioTransportError for network-level failures.
• Validation Errors: Handles PutioValidationError when the SDK receives unexpected data formats.

Sources: src/internal/localizers/shared.ts:38-142

Rate Limit Resolution URL Construction

For captcha-needed actions, the SDK localizer constructs a URL following this pattern:
{webAppUrl}/captcha/{rateLimitId}.

Sources: src/internal/localizers/shared.ts:10-16

Operational Data Flow: File Management

File operations demonstrate the interaction between the SDK modules and the CLI's pagination logic.

Search and List Pagination

The SDK supports cursor-based pagination. The CLI implements a page-all capability that recursively calls the SDK's continue methods until the full dataset is retrieved or a safety limit is reached.

Configuration

The SDK's runtime environment is configured through the CliConfig service.

Parameter	Default Value	Environment Variable
apiBaseUrl	https://api.put.io	PUTIO_API_BASE_URL
webAppUrl	https://app.put.io	PUTIO_CLI_WEB_APP_URL
appId	8993	N/A (Internal Constant)
clientName	putio-cli@{hostname}	PUTIO_CLI_CLIENT_NAME

Sources: src/internal/config.ts:80-95, src/internal/constants.ts

The Put.io API SDK integration provides a robust, configuration-driven foundation for all CLI operations. By abstracting the @putdotio/sdk behind Effect services, the project ensures consistent authentication, reliable error handling, and predictable data flows across all supported API modules.