Introduction & Overview
Relevant source files
The following files were used as context for generating this wiki page:
The putio-cli is an "agent-first" command-line interface designed to interact with the put.io API. While providing readable terminal output for human users, its primary design philosophy prioritizes deterministic automation and compatibility with AI agents and scripts. It achieves this through stable JSON/NDJSON output contracts, granular field selection, and a robust "dry-run" capability for safety during mutations.
The project is built as a standalone TypeScript package leveraging the Effect ecosystem for functional domain logic, services, and error handling. It utilizes @effect/cli for command parsing and definition, ensuring a consistent and type-safe interface across its various modules, which include file management, transfers, account information, and authentication.
Sources: README.md:10-15, CLAUDE.md:12-25, src/internal/cli-contract.ts
Core Architecture & Design Philosophy
The system architecture is centered around "Effect-native" helpers and services. The CLI is organized to keep command modules thin by moving shared behavior into internal services. This modularity allows for clear boundaries between the machine-readable contract (JSON) and the human-readable adapter layer (Terminal/Text).
Design Principles
- Agent-First: Prioritizes machine-readable output (
--output json) and stable contracts for automated workflows. - Safety: Implements
--dry-runfor all mutating commands and treats API-returned text as untrusted content via safety metadata. - Efficiency: Provides
--fieldsto minimize data transfer and--page-allfor controlled streaming of large datasets. - Functional Foundation: Uses
Effect,Schema, and tagged errors instead of ad-hoc control flow.
Sources: README.md:12-13, CLAUDE.md:20-25, skills/putio-cli/SKILL.md:10-20
System Data Flow
The following diagram illustrates how a user request flows through the CLI layers to the put.io API and back to the user in the requested format.
The diagram shows the transition from raw input to authenticated API calls and the eventual split between machine-readable and human-readable output.
Sources: CLAUDE.md:20-25, src/cli.test.ts, src/internal/state.ts
Command System & Metadata
The CLI provides a rich set of commands categorized by their operational "kind," such as read, write, or utility. Every command's capabilities—including whether it supports field selection, dry runs, or streaming—are explicitly defined in a command catalog.
Command Categories
| Category | Purpose | Examples |
|---|---|---|
| Read | Fetching data from the API | files list, transfers list, whoami |
| Write | Mutating data or states | files mkdir, transfers add, files delete |
| Utility | Local or informational tasks | describe, version, auth preview |
Sources: src/internal/metadata.test.ts:25-50, src/internal/cli-contract.ts:25-35
Discovery and Contracts
The describe command is a critical utility for agents. It prints a machine-readable JSON representation of the entire CLI's surface area, including available commands, their expected flags, and their safety posture.
// Example of a Command Descriptor structure
{
command: "files list",
kind: "read",
auth: { required: true },
capabilities: {
dryRun: false,
fieldSelection: true,
streaming: true
}
}
Sources: src/cli.test.ts:135-155, src/internal/cli-contract.ts:25-35
Authentication & Profile Management
Authentication in putio-cli is flexible, supporting environment variables, legacy single-token configurations, and modern named profiles. Profiles allow users to maintain multiple authenticated sessions (e.g., for different accounts or automated environments) without re-authenticating.
Auth Resolution Hierarchy
- Environment Variable:
PUTIO_CLI_TOKEN(highest precedence, overrides all). - Explicit Profile: Passing
--profile <name>or settingPUTIO_CLI_PROFILE. - Default Profile: The profile set via
putio auth profiles use <name>. - Legacy Config: The
auth_tokenfound in the root of theconfig.jsonfile.
Sources: src/internal/state.ts:400-450, README.md:95-105
State Machine for Device Authorization
The CLI implements the put.io device-link flow, allowing authorization on any device via a browser and an activation code.
The sequence diagram represents the device-link flow used in putio auth login.
Sources: src/internal/auth-flow.test.ts:100-140, src/internal/state.ts:270-300
Output & Safety Handling
The OutputService manages how data is presented to the user. It is responsible for sanitization, redacting sensitive information like tokens, and adding safety metadata to untrusted API content.
Safety Metadata
When the CLI detects text returned from the API that could potentially contain malicious instructions (Prompt Injection protection), it flags those paths in the JSON output.
| Field | Description |
|---|---|
_meta.agentSafety.message | Warning for the agent to treat content as untrusted. |
_meta.agentSafety.untrustedTextPaths | JSON paths (e.g., $.files[0].name) containing untrusted strings. |
Sources: src/internal/output.test.ts:115-150, src/internal/output-service.js
Configuration Storage
Configuration is stored in config.json at paths determined by OS standards:
- Explicit:
PUTIO_CLI_CONFIG_PATH - XDG:
$XDG_CONFIG_HOME/putio/config.json - Home:
~/.config/putio/config.json
Sources: src/internal/state.test.ts:40-60, src/internal/state.ts:245-260
Summary
The putio-cli provides a robust, developer-centric interface for the put.io platform. By abstracting complex API interactions into a set of well-defined commands and prioritizing machine-readable contracts, it serves as both a powerful tool for power users and a reliable interface for automated agents. The integration of the Effect library ensures that the tool is resilient, maintainable, and highly observable through detailed metadata and error localization.
Sources: README.md:12-15, CLAUDE.md:20-25