Identity Insight (whoami)

Relevant source files

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

• src/commands/whoami.ts (Implicitly used via metadata and command path references)
• src/internal/metadata.test.ts
• src/command-paths.test.ts
• src/i18n/catalog/en.ts
• src/test-support/command-path-mocks.ts
• README.md
• CLAUDE.md

Identity Insight, implemented via the whoami command, is a core diagnostic and informational feature of the putio-cli. It serves as the primary mechanism for users and automated agents to retrieve broad account information and verify the active authentication context. The command integrates with the underlying put.io SDK to fetch real-time account status, storage metrics, and user settings.

Within the ecosystem of the CLI, whoami is categorized as a "read" kind of operation. It is designed for deterministic automation, supporting field selection to minimize payload size and offering structured JSON output for machine consumption while maintaining readable terminal output for human users.

Sources: CLAUDE.md:1-25, README.md:1-40, src/internal/metadata.test.ts:47-60

Command Architecture and Execution Flow

The whoami command follows a standard execution pattern within the Effect-native architecture of the CLI. It requires an authenticated session and utilizes the withAuthedSdk helper to interact with the put.io API.

Execution Lifecycle

1. Auth Resolution: The CLI resolves the authentication token from environment variables (e.g., PUTIO_CLI_TOKEN), the selected profile (PUTIO_CLI_PROFILE), or the default persisted config.
2. API Request: The command invokes sdk.account.getInfo({}) to retrieve the full account payload.
3. Field Filtering: If the --fields flag is provided, the CLI filters the raw SDK response to include only requested top-level fields.
4. Output Rendering: The data is passed to the output service, which handles sanitization (redacting sensitive tokens) and formatting for either the terminal or JSON streams.

The command identifies itself as a utility with specific capabilities:

• Auth Required: True
• Kind: Read
• Field Selection: Supported

Sources: src/internal/metadata.test.ts:47-60, src/command-paths.test.ts:404-430, src/test-support/command-path-mocks.ts:168-185

Input Parameters and Configuration

The whoami command supports standard global flags and specific options for narrowing the data returned.

Flag	Type	Description
--fields	String	Comma-separated list of top-level field names to include in the response.
--output	Enum	Determines the format: json, terminal, or ndjson.
--profile	String	Specifies a named auth profile to use for the identity check.

The --fields flag is particularly relevant for agents to keep reads small and deterministic. For example, an agent might request only the auth field to verify connectivity without fetching full account metrics.

Sources: src/internal/metadata.test.ts:47-60, README.md:95-105, src/command-paths.test.ts:419-430

Data Model and Schema

The information returned by whoami is derived from the put.io SDK's account information model. It encompasses user identity, subscription status, and storage utilization.

Account Information Fields

Field	Description	Derived Source
username	The unique identifier for the user account.	account.username
mail	The primary email address associated with the account.	account.mail
account_status	Current status (e.g., ACTIVE).	account_status
disk	Object containing storage metrics: avail, size, and used.	disk
settings	User preferences such as theme and two_factor_enabled.	settings
trash_size	The amount of storage occupied by items in the trash.	trash_size
auth	CLI-specific metadata regarding the resolved API base URL and auth source.	CLI Internal State

Sources: src/command-paths.test.ts:121-140, src/test-support/command-path-mocks.ts:5-24

Terminal Representation

When used in a human-interactive terminal, the data is transformed into a localized, readable summary. This includes sections for account details, storage availability, and security settings (like 2FA status).

The terminal output uses specific localized labels such as "Family owner," "Sub-account," and "Trash" to provide a user-friendly view of the SDK data.

Sources: src/i18n/catalog/en.ts:251-271, src/command-paths.test.ts:404-418

Machine-Readable Output (JSON)

For automation and agent interaction, the command provides a stable machine contract. This output includes an additional auth object that reveals the provenance of the current session.

{
  "auth": {
    "apiBaseUrl": "https://api.put.io",
    "source": "env",
    "configPath": "/tmp/putio-cli.json"
  },
  "info": {
    "username": "altay",
    "mail": "altay@put.io",
    "disk": {
      "avail": 700,
      "size": 1000,
      "used": 300
    }
  }
}

Note: Sensitive fields like auth_token are automatically redacted by the output service before rendering.

Sources: src/command-paths.test.ts:404-430, src/internal/output.test.ts:20-40

Summary

Identity Insight (whoami) serves as the foundational "Handshake" command for both human users and automated agents. By combining real-time account data from the put.io SDK with CLI-specific authentication metadata, it provides a comprehensive view of the current operational context. Its support for field selection and machine-readable output aligns with the project's "agent-first" philosophy, ensuring efficient and deterministic account auditing.