Brand Presentation (brand)
Relevant source files
The following files were used as context for generating this wiki page:
The Brand Presentation module is responsible for the visual identity and versioning metadata of the putio-cli. It ensures that the "put.io" brand and application version are consistently rendered across different output formats, including human-readable terminal signatures and machine-readable JSON payloads.
This module provides utility commands that allow users and automated agents to verify the CLI's version and view the brand's signature. It serves as a foundational layer for user experience by greeting users with branded content during interactive sessions, such as the authentication flow.
Architecture and Command Structure
The brand presentation logic is split between command definitions and terminal-specific rendering helpers. The system uses the Effect library's CLI capabilities to define commands and the i18next library for localized strings.
Key Commands
| Command | Purpose | Output Types |
|---|---|---|
brand | Renders the put.io brand mark and version. | JSON, Terminal, NDJSON |
version | Prints the binary name and current version. | JSON, Terminal, NDJSON |
Sources: src/commands/brand.ts:18-42, src/internal/command-specs.ts:316-322
Component Interaction
The flow of brand data moves from the package.json and i18n catalogs through the command handlers to the output service.
Logic and Implementation
Metadata Definition
Commands are defined using CommandSpec objects, which categorize them as utility commands. These commands do not require authentication (auth: { required: false }) and support standard output flags.
Sources: src/commands/brand.ts:44-79, src/internal/command-specs.ts:117-124
Brand Rendering Logic
The terminal output for the brand signature is handled by renderPutioSignature(). When displaying version information in the terminal, the system combines this signature with a localized version label.
const renderVersionTerminal = (value: { readonly version: string }) =>
[renderPutioSignature(), translate("cli.brand.versionLabel", { version: value.version })].join(
"\n\n",
);
Sources: src/commands/brand.ts:12-16, src/internal/terminal/brand.ts
Internationalization (i18n)
The brand module relies on specific keys within the English translation catalog (en.ts) to provide consistent naming and labeling.
| Key | Value | Description |
|---|---|---|
cli.brand.binary | putio | The CLI binary name. |
cli.brand.name | put.io | The formal brand name. |
cli.brand.versionLabel | version {{version}} | The label used in version output. |
Sources: src/i18n/catalog/en.ts:89-93
Integration with Metadata and Discovery
The brand and version commands are included in the global command catalog, allowing them to be discovered by agents via the describe command. The metadata for these commands explicitly disables capabilities like dryRun, fieldSelection, and streaming, as they are simple utility functions.
Conclusion
The Brand Presentation module provides the essential "Who am I?" functionality for the CLI. By separating the raw data (version, brand name) from the presentation layers (ANSI signatures for humans, JSON for machines), it maintains the project's "agent-first" philosophy while providing a polished experience for human users.
Sources: README.md:5-9, src/commands/brand.ts