File Management (files)

Relevant source files

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

• src/commands/files.ts
• src/internal/terminal/files-terminal.ts
• src/i18n/catalog/en.ts
• src/commands/files.test.ts
• src/command-paths.test.ts
• src/internal/metadata.test.ts

The File Management module is a core component of the putio-cli, designed to provide a robust interface for interacting with the put.io file system. It enables users to perform standard operations such as listing directory contents, creating folders, renaming files, moving assets between directories, and searching for specific content. The system is built for "deterministic automation first," supporting both human-readable terminal tables and machine-readable JSON/NDJSON outputs.

Sources: README.md:9-11, src/commands/files.ts:442-444

Command Architecture and capabilities

The module is organized into several subcommands under the primary files command. Each subcommand is defined with specific metadata that dictates its behavior regarding authentication, dry-run support, and output streaming.

Support Matrix

Command	Purpose	Auth Required	Dry-Run	Field Selection	Raw JSON Input
list	List directory contents	Yes	No	Yes	No
search	Search files by query	Yes	No	Yes	No
mkdir	Create a new folder	Yes	Yes	No	Yes
rename	Change file name	Yes	Yes	No	Yes
move	Relocate files	Yes	Yes	No	Yes
delete	Remove files	Yes	Yes	No	Yes

Sources: src/commands/files.ts:446-599, src/internal/metadata.test.ts:36-62

Execution Flow

The following diagram illustrates the typical data flow when a file mutation command (like mkdir or rename) is executed.

The execution flow ensures that inputs are validated against traversal segments and control characters before hitting the SDK.
Sources: src/commands/files.ts:216-247, src/commands/files.ts:258-292

Data Validation and Schemas

The module uses the Effect schema library to strictly define and validate input data structures. This ensures that only well-formed data is sent to the put.io API.

Key Input Schemas

• FilesMkdirInputSchema: Requires a non-blank string name and an optional parent_id.
• FilesRenameInputSchema: Requires a numeric file_id and a non-blank name.
• FilesDeleteInputSchema: Requires a non-empty array of IDs and an optional skip_trash boolean.
• FilesMoveInputSchema: Requires a non-empty array of IDs and a destination parent_id.

Sources: src/commands/files.ts:80-112

Security Constraints

A specialized NonBlankStringSchema and a validateNameLikeInput helper are used to reject control characters and path traversal segments such as ../ or %2e.
Sources: src/commands/files.ts:75-78, src/commands/files.ts:526-528

const NonBlankStringSchema = Schema.String.check(
  Schema.makeFilter((value) =>
    value.trim().length > 0 ? undefined : "Expected a non-empty string",
  ),
);

Sources: src/commands/files.ts:75-78

Listing and Pagination Logic

The list and search commands implement cursor-based pagination. This allows the CLI to handle large directories by fetching data in chunks.

Pagination is managed via writeReadPages, which handles the accumulation of items when the --page-all flag is present, or streams results line-by-line in ndjson mode.
Sources: src/commands/files.ts:161-205, src/command-paths.test.ts:391-445

Terminal Output Rendering

When running in a human-interactive terminal, the module renders file data into a formatted table. The renderer supports different views based on whether a parent directory context is available.

Table Columns

The standard file table includes the following columns:

• ID: The unique identifier for the file (right-aligned).
• Type: The file category (e.g., FOLDER, VIDEO, AUDIO).
• Size: Human-readable file size (e.g., "42 MB").
• Name: The filename, with a maximum width of 48 characters for readability.

Sources: src/internal/terminal/files-terminal.ts:40-68

Localized Feedback

Mutations provide specific feedback strings localized via the i18n catalog:

• Created: created folder "name" (id 42, parent 0)
• Renamed: renamed file 42 to "new-name"
• Moved: moved file ids: 1, 2 to parent 9
• Deleted: deleted file ids: 1, 2 (skipped: 1)

Sources: src/commands/files.ts:125-159, src/i18n/catalog/en.ts:241-255

Search Capabilities

The search functionality is exposed via both files search and a top-level search alias. It supports filtering by:

• Query: The text to search for.
• File Type: Filters by categories like VIDEO, AUDIO, IMAGE, etc.
• Pagination: Controlled via --per-page and --page-all.

Sources: src/commands/files.ts:389-434, src/commands/files.ts:50-60

Conclusion

The File Management module provides a comprehensive suite of tools for manipulating put.io resources. By leveraging Effect schemas for validation and a tiered output system for humans and machines, it ensures high reliability and flexibility. Its architecture prioritizes safety by preventing path traversal attacks and supports advanced features like automatic pagination and dry-run execution plans.

Sources: src/commands/files.ts, src/internal/terminal/files-terminal.ts