Transfer Operations (transfers)
Relevant source files
The following files were used as context for generating this wiki page:
Transfer Operations encompass the suite of commands and internal logic used to manage the lifecycle of remote data fetching within the put.io CLI. This system allows users to add new transfers via URLs, monitor their progress, manage existing jobs (canceling, retrying, or reannouncing), and perform cleanup of completed or failed transfers.
The module is built using the Effect library, prioritizing deterministic automation for agents while providing formatted terminal output for human users. It interfaces directly with the put.io SDK's transfer methods to perform mutations and reads against the user's account state.
Sources: src/commands/transfers.ts:285-300, README.md:12-15
Core Command Architecture
The transfers module is implemented as a branched command structure using @effect/cli. It centralizes authentication requirements, input validation, and output formatting.
Command Structure and Subcommands
The root transfers command serves as a namespace for several specialized subcommands:
| Subcommand | Purpose | Key Flags |
|---|---|---|
list | Lists current transfers | --fields, --page-all, --per-page |
add | Adds transfers from URLs or magnet links | --url, --save-parent-id, --callback-url |
cancel | Cancels one or more active transfers | --id (repeated) |
retry | Retries a failed transfer | --id |
clean | Removes finished or selected transfers | --id (optional) |
reannounce | Reannounces torrent transfers to trackers | --id |
watch | Monitors a transfer until a terminal status | --id, --interval-seconds, --timeout-seconds |
Sources: src/commands/transfers.ts:285-300, src/i18n/catalog/en.ts:233-241
Execution Flow
Most transfer commands follow a standardized execution pattern: resolving input (from flags or raw JSON), checking for dry-run status, executing the SDK call via an authenticated client, and rendering the result.
Transfer Lifecycle Management
Adding Transfers
The add command accepts multiple URLs and optional parent folder IDs for organization. It supports a "dry-run" mode to validate inputs without triggering actual API requests.
- Validation: Requires at least one URL.
- Input Schemas: Uses
TransfersAddInputSchemawhich expects a non-empty array of objects containing a URL and optional metadata.
Sources: src/commands/transfers.ts:46-48, src/commands/transfers.ts:133-162
Monitoring with "Watch"
The watch command implements a polling mechanism to track a transfer's progress until it reaches a "terminal" status.
- Terminal Statuses: Defined as
COMPLETED,ERROR, orSEEDING. - Logic: The command enters a loop, fetching the transfer status at defined intervals (defaulting to 2 seconds) until the status is terminal or a timeout (default 300 seconds) is reached.
- Streaming: Supports
ndjsonoutput for real-time progress updates in machine-readable formats.
Data Models and Schemas
The CLI uses Schema from the effect library to enforce strict types for all transfer-related inputs.
export const TransfersAddInputSchema = Schema.Array(TransferAddInputSchema).check(
Schema.isNonEmpty(),
);
export const TransfersCancelInputSchema = Schema.Struct({
ids: Schema.Array(Schema.Number).check(Schema.isNonEmpty()),
});
export const TransfersSingleIdInputSchema = Schema.Struct({
id: Schema.Number,
});
Sources: src/commands/transfers.ts:45-60
Field Selection and Pagination
Read-heavy commands like list and watch utilize shared internal helpers to allow users to narrow the returned data.
--fields: Limits the JSON/NDJSON response to specific top-level fields (e.g.,id,status,name).--page-all: Automatically follows pagination cursors to retrieve the entire transfer list.
Sources: src/commands/transfers.ts:108-111, src/internal/metadata.test.ts:133-145
Error Handling and Localization
Transfer operations include specific error localization to provide meaningful feedback for common API failures.
| Error Context | Localized Message | Recovery Suggestion |
|---|---|---|
EMPTY_URL | Transfer URL is required | Provide at least one valid URL. |
TOO_MANY_URLS | Too many transfer URLs submitted | Split request into smaller batches. |
404 (Not Found) | Transfer not found | Check ID; transfer may have finished or been removed. |
403 (Forbidden) | Action not allowed | Transfer cannot be changed in current state. |
Sources: src/i18n/catalog/en.ts:138-166, src/internal/localize-error.test.ts:117-142
Terminal Rendering
For human-driven sessions, the CLI provides formatted tab-separated output. The renderTransfers function converts raw transfer objects into readable rows containing ID, Status, Percentage Done, and Name.
// Example Terminal Output Format
// ID STATUS DONE NAME
// 7 COMPLETED 100 ubuntu.iso
Sources: src/commands/transfers.ts:86-95, src/commands/transfers.test.ts:13-25
The CLI also provides summarized feedback for bulk actions:
- Add Results: Displays a count of successful transfers and a separate section for failed URLs with status codes.
- Clean Results: Lists the specific IDs that were successfully deleted from the transfer list.
Sources: src/commands/transfers.ts:97-113, src/commands/transfers.ts:206-210
Summary
Transfer Operations in putio-cli provide a robust interface for managing data ingestion. By leveraging Effect for control flow and Schema for validation, the system ensures that both human users and automated agents can reliably add, monitor, and clean transfers with clear feedback and deterministic behavior.