Download Links (download-links)
Relevant source files
The following files were used as context for generating this wiki page:
The Download Links module provides the functionality to generate and retrieve direct download URLs for files hosted on put.io. This system operates as an asynchronous job-based mechanism where a user first creates a "job" targeting specific files or a cursor selection, and subsequently polls or retrieves the completed job to access grouped download, media, and MP4 links.
This module is essential for automation and agents that need to extract direct URLs for external processing, streaming, or local downloading without navigating the standard web interface. Sources: src/commands/download-links.ts:109-112, skills/putio-cli/SKILL.md:1-5
Command Architecture
The download-links feature is implemented as a subcommand of the main putio CLI, utilizing the Effect framework for functional control flow and the @putdotio/sdk for API communication. Sources: src/commands/download-links.ts:109-111
Command Structure
The module consists of two primary subcommands:
- create: Initiates a new link generation job.
- get: Retrieves the status and results of an existing job using its ID.
Sources: src/commands/download-links.ts:110-111
Execution Flow
The following diagram illustrates the lifecycle of a download link generation request, from initial command input to the final rendering of links.
Job Creation (create)
The create command requires at least one file ID or a valid cursor to initiate the link generation. The input is validated using DownloadLinksCreateInputSchema. Sources: src/commands/download-links.ts:43-55
Input Validation Logic
The resolveDownloadLinksCreateInput function ensures that the request is not empty. It normalizes input by converting empty arrays to undefined to satisfy SDK requirements. Sources: src/commands/download-links.ts:38-55
| Flag | Type | Required | Description |
|---|---|---|---|
--id | Integer (Repeated) | Conditional | One or more file IDs to include in the job. |
--cursor | Text | Conditional | A cursor representing a selection of files. |
--exclude-id | Integer (Repeated) | No | File IDs to exclude from the job selection. |
--dry-run | Boolean | No | Previews the request without hitting the API. |
--json | Text | No | Accepts a raw JSON payload for the creation input. |
Sources: src/commands/download-links.ts:114-131
Dry Run Capability
Users can use the --dry-run flag to verify the payload that would be sent to the API. This is particularly useful for agents to validate logic before execution. Sources: src/commands/download-links.ts:77-79, src/command-paths.test.ts:333-352
Link Retrieval (get)
Once a job is created, its result is fetched using the get command. The API returns a status and, upon completion, groups of links. Sources: src/commands/download-links.ts:92-107
Link Grouping
The system categorizes links into three distinct types:
- Download Links: Direct links to the original files.
- Media Links: Links optimized for streaming or media players.
- MP4 Links: Links specifically for MP4 transcoded versions.
Sources: src/internal/terminal/download-links-terminal.ts:17-21
Terminal Rendering
The renderDownloadLinksTerminal function handles the visual presentation of the job state. If the job is not yet finished, it displays the current status (e.g., IN_QUEUE). Once completed, it renders a summary and sections for each link group. Sources: src/internal/terminal/download-links-terminal.ts:1-41
Error Handling and Localization
The module includes specialized error mapping to provide actionable feedback for common link generation issues. Sources: src/i18n/catalog/en.ts:122-145
| Error Code/Condition | Title | Description/Recovery |
|---|---|---|
DownloadLinksConcurrentLimit | Too many jobs running | Wait for an active job to finish. |
DownloadLinksTooManyFilesRequested | Too many files | Request fewer files at a time. |
DownloadLinksTooManyChildren | Too many nested files | Narrow the selection before creating. |
404 Not Found | Job not found | The job may have expired or the ID is incorrect. |
400 Bad Request | Invalid request | Review file IDs or cursor. |
Sources: src/internal/localize-error.test.ts:149-216, src/i18n/catalog/en.ts:122-145
Technical Implementation Details
Data Structures
The creation input is structured according to the SDK's schema. Sources: src/commands/download-links.ts:41-43
// Example Creation Input Structure
{
cursor?: string;
excludeIds?: number[];
ids?: number[];
}
Summary of Commands
| Command | Kind | Purpose | Auth Required |
|---|---|---|---|
download-links create | Write | Create a browser-link generation job. | Yes |
download-links get | Read | Inspect a job and read completed links. | Yes |
Sources: src/commands/download-links.ts:114-142
Summary
The download-links module provides a robust interface for handling asynchronous direct link generation. By utilizing a job-based architecture, it allows for processing large selections of files that might be too heavy for synchronous API responses. It integrates tightly with the project's terminal rendering and localization systems to ensure both machine-readable JSON output and human-readable terminal summaries are accurate and descriptive. Sources: src/commands/download-links.ts:1-143, src/internal/terminal/download-links-terminal.ts:1-42