Terminal Display & Layouts

Terminal Display & Layouts refer to the system within the putio-cli responsible for transforming raw API data and application state into human-readable, formatted text for terminal environments. While the CLI is designed as "agent-first" with a focus on deterministic JSON output, it includes a robust adapter layer for rendering tables, panels, and specialized visual components like activation code boxes for human users.

The system handles output mode detection, data sanitization (including redaction of sensitive tokens), and localized string rendering via an internationalization (i18n) catalog. This ensures that while machines receive stable JSON contracts, humans receive readable summaries and interactive feedback.

Output Management and Sanitization

The CLI differentiates between structured machine output and human-readable terminal output. The CliOutputService manages this transition by detecting the requested output mode from command-line arguments and applying appropriate sanitization filters.

Output Mode Detection

The system supports three primary output modes: json, ndjson, and terminal (often referred to as text in CLI flags).

The logic defaults to terminal in interactive sessions and json for non-interactive sessions (e.g., pipes or scripts) to ensure machine compatibility by default.
Sources: src/internal/output-service.ts:25-58

Content Sanitization & Redaction

Security is a core component of the display logic. All output, regardless of mode, passes through sanitizers that redact sensitive information like OAuth tokens and passwords.

Sources: src/internal/output-service.ts:71-180

Visual Components and Layouts

The CLI uses a set of layout primitives to organize information in the terminal. These are primarily located in src/internal/terminal/layout.ts (referenced) and utilized across specific terminal implementations.

Table Rendering

Tables are the primary way the CLI displays lists of files or transfers. The renderFilesTerminal function uses a renderTable utility to define columns with specific alignments, keys, and value formatters (such as converting bytes to human-readable file sizes).

Specialized Layouts

The CLI includes unique layouts for specific workflows:

• Activation Boxes: For auth login, the CLI renders a boxed activation code using specific Unicode box-drawing characters (┌, ┬, ┐, etc.).
• Panels: Used in success screens to group related configuration details like API base URLs and config paths.
• Status Sections: Used in download-links to show progress status and grouped links (Download, Media, MP4).

Sources: src/internal/terminal/auth-terminal.ts:18-35, src/internal/terminal/download-links-terminal.ts

Error Presentation

Errors are handled by a dedicated formatting layer that converts internal TaggedError or SDK errors into human-friendly views.

The error display includes a title, a message, and optional hints or metadata (like "Try this" suggestions).
Sources: src/internal/output-service.ts:193-242, src/internal/terminal/error-terminal.ts

Logic Flow: Rendering a Command

When a command like files list is executed, the following flow occurs to produce the final terminal display:

1. Resolve Controls: The command resolves outputMode and requestedFields via resolveReadOutputControls.
2. Fetch Data: Data is retrieved from the SDK.
3. Terminal Transformation: If the mode is terminal, the renderTerminal function is called.
4. Formatting: Specific renderers (e.g., renderFilesTerminal) apply tables and localization.
5. Final Redaction: The entire string is processed by redactSensitiveText before being written to stdout.

Sources: src/internal/command.ts:430-450, src/internal/output-service.ts:265-276

Summary

The "Terminal Display & Layouts" system in putio-cli acts as a presentation adapter for the underlying SDK data. It prioritizes security through multi-layered redaction and provides clear, localized feedback to human users through structured tables, panels, and status summaries, while maintaining the ability to switch to raw JSON for automation.