Output Management & Formatters

Relevant source files

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

• src/internal/output-service.ts
• src/internal/output.test.ts
• src/internal/command.ts
• src/commands/files.ts
• src/cli.test.ts
• CLAUDE.md

The Output Management system in putio-cli is designed to provide deterministic, machine-readable data for automation and agents, while maintaining human-readable formatting for terminal users. It serves as an abstraction layer between internal command logic and the final string representation sent to stdout.

The system architecture treats JSON as the primary machine contract and provides a separate adapter layer for terminal output. This ensures that scripts and AI agents receive stable, structured data regardless of how a human might prefer to view the same information in a TTY.

Sources: CLAUDE.md:31-32, src/internal/output-service.ts:1-15

Output Modes & Detection

The CLI supports three primary output modes. The mode is determined based on command-line flags, environmental context (interactive vs. non-interactive), and the specific command being executed.

Supported Modes

Mode	Format	Use Case
json	Structured JSON	Default for non-interactive shells and automation.
ndjson	Newline Delimited JSON	Used for streaming large datasets or continuous read workflows.
terminal	Human-readable text	Default for interactive terminal sessions; often uses tables or status messages.

Sources: src/internal/output-service.ts:7-27, README.md:104-106

Selection Logic

The detectOutputModeFromArgv and normalizeOutputMode functions handle the selection of the output format.

1. Explicit Flag: If --output <mode> or --output=<mode> is provided, that mode is used.
2. Environment Default: In the absence of a flag, the system checks if the session is an interactive terminal. If it is, it defaults to terminal (text). If not, it defaults to json.
3. Command Specifics: Some commands, like describe, default to json regardless of interactivity to ensure agents can always discover the CLI contract.

Sources: src/internal/output-service.ts:16-56, src/cli.test.ts:133-138

Security & Sanitization

A critical responsibility of the output service is the protection of sensitive information and the labeling of untrusted content.

Redaction of Sensitive Data

The system identifies sensitive keys (e.g., auth_token, password, secret, cookie) and redacts their values in the output. It uses regex patterns to scrub bearer tokens and credential assignments from both structured objects and raw terminal text.

Sources: src/internal/output-service.ts:58-100, src/internal/output.test.ts:17-45

Agent Safety & Injection Protection

For structured output (JSON/NDJSON), the system inspects strings for potential prompt injection patterns (e.g., "ignore previous instructions"). If such patterns are found in API-returned content, the system attaches safety metadata rather than modifying the string. This allows agents to process the data while being warned about its untrusted nature.

• Metadata Field: _meta.agentSafety
• Property: untrustedTextPaths (A list of JSON paths containing suspicious strings).

Sources: src/internal/output-service.ts:141-174, src/internal/output.test.ts:110-153

Data Flow & Architecture

Output generation follows a structured flow where raw data is filtered, sanitized, and then passed to a specific renderer.

Key Components

CliOutput Service

The CliOutput service is an Effect-native service that encapsulates the formatting and writing logic. It provides methods like write and formatError.
Sources: src/internal/output-service.ts:223-241

Field Selection

When using structured output, users can specify --fields to narrow the response. The selectTopLevelFields function filters the API response to only include requested keys, keeping payloads small for bandwidth efficiency and agent processing.
Sources: src/internal/command.ts:443-470

Pagination Handling

The output system coordinates with the command layer to handle paginated results.

• --page-all: Collects all pages into a single JSON array before outputting.
• NDJSON Streaming: Writes each page as a separate JSON object followed by a newline, allowing for real-time processing of large lists.

Sources: src/internal/command.ts:586-646, src/commands/files.ts:145-164

Error Formatting

Error handling is localized and formatted based on the active output mode.

1. Terminal Errors: Rendered using a dedicated terminal view that includes a title, a human-readable recovery suggestion, and optional hints or metadata.
2. JSON Errors: Provided as a structured object containing the error title, message, and a machine-readable recoverySuggestion type (e.g., "instruction").

Sources: src/internal/output-service.ts:182-221, src/internal/output.test.ts:205-256

Summary

The Output Management system ensures that putio-cli remains a robust tool for both human operators and automated agents. By decoupling the data representation from the command execution and enforcing strict sanitization and safety protocols, the project provides a predictable and secure interface for interacting with the put.io API.