Command Discovery Interface

Relevant source files

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

• src/internal/cli-contract.ts
• src/internal/command-specs.ts
• src/internal/agent-dx.ts
• src/internal/metadata.ts (Referenced via tests in src/internal/metadata.test.ts)
• skills/putio-cli/references/discovery.md
• src/cli.test.ts

The Command Discovery Interface in putio-cli is a system designed to provide machine-readable metadata about the CLI's capabilities, structure, and safety posture. It is primarily exposed through the putio describe command, which allows automated agents and scripts to programmatically discover available commands, their input requirements (flags and arguments), and their architectural capabilities such as streaming or dry-run support.

The interface serves as a "living contract" between the CLI and its consumers, ensuring that agents can operate deterministically by inspecting the live metadata rather than relying on hardcoded assumptions. It includes an "Agent DX" (Developer Experience) scorecard that quantifies how well the CLI supports automated interaction.

Sources: README.md:12-14, skills/putio-cli/references/discovery.md:1-12, src/internal/cli-contract.ts:21-30

Architecture and Core Components

The discovery interface is built upon a centralized command catalog that aggregates specifications from across the various modules of the CLI.

Command Catalog

The commandCatalog is the central registry of all CLI commands. It uses a decoding process to ensure all command specifications adhere to a strict schema before they are exposed. This catalog includes utility, auth, and data-related commands (files, transfers, etc.).

Sources: src/internal/cli-contract.ts:32-42, src/internal/command-specs.ts:133-143

Discovery Data Flow

When a user or agent executes putio describe --output json, the system invokes the discovery logic to generate a structured JSON payload.

This diagram shows the high-level flow from a discovery request to the final structured output.
Sources: src/internal/cli-contract.ts:21-30, src/internal/metadata.test.ts:6-14

Metadata Schema and Descriptors

The discovery interface provides detailed information for each command through a standardized CommandDescriptor.

Command Descriptor Fields

Each command in the discovery output includes:

• Command Name: The full string used to invoke the command (e.g., "files list").
• Kind: The category of the command (utility, auth, read, or write).
• Purpose: A localized description of what the command does.
• Capabilities: Boolean flags indicating support for dryRun, fieldSelection, rawJsonInput, and streaming.
• Input: Detailed specification of flags, arguments, and JSON payload shapes.

Sources: src/internal/command-specs.ts:114-122, src/internal/metadata.test.ts:46-60

Capability Matrix

Capability	Description	Requirements
dryRun	Previews mutations without executing them.	Must have a --dry-run flag.
fieldSelection	Allows narrowing the response fields.	Must have a --fields flag.
rawJsonInput	Accepts complex structured input via JSON.	Must have a --json flag and a JSON schema.
streaming	Supports continuous output (NDJSON).	Command must support cursor-backed reads or watch flows.

Sources: src/internal/command-specs.ts:145-175, src/internal/agent-dx.ts:80-97

Agent DX Scorecard

A unique feature of the Discovery Interface is the AgentDxScorecard, which evaluates the CLI's readiness for agent-based automation across several dimensions.

The dimensions used to calculate the automation readiness score of the CLI.
Sources: src/internal/agent-dx.ts:3-23

Scoring Dimensions

Dimension	Logic / Requirement	Max Score
machineReadableOutput	Scores higher if JSON is the default and NDJSON is available.	3
rawPayloadInput	Evaluates if all mutating commands support --json input.	3
schemaIntrospection	Checks if describe provides full flag and JSON shapes.	3
contextWindowDiscipline	Checks for field filtering and streaming support to save tokens.	3
safetyRails	Evaluates availability of dry-run and response sanitization.	3

Sources: src/internal/agent-dx.ts:33-125

JSON Input Shapes

For commands with rawJsonInput capability, the discovery interface provides a structural definition of the expected JSON payload. This is derived from the internal Schema objects used for validation.

Shape Types

The system can describe various JSON structures:

• Scalars: string, integer, boolean, null.
• Enum: A fixed list of allowed values.
• Array: A list of items of a specific shape.
• Object: A collection of named properties, marked as required or optional.

Sources: src/internal/command-specs.ts:25-50, src/internal/command-specs.ts:258-305

Example: files mkdir Metadata

The describe output for a write command like files mkdir includes the specific properties required in its JSON payload.

{
  "command": "files mkdir",
  "input": {
    "json": {
      "kind": "object",
      "properties": [
        { "name": "name", "required": true, "schema": { "kind": "string" } },
        { "name": "parent_id", "required": false, "schema": { "kind": "integer" } }
      ],
      "rules": ["`name` rejects control characters and path traversal segments..."]
    }
  }
}

Sources: src/cli.test.ts:167-175, src/internal/metadata.test.ts:108-117

Conclusion

The Command Discovery Interface is the foundation for the "agent-first" philosophy of putio-cli. By exposing every aspect of the command surface—including validation rules, safety features, and structured input schemas—it enables programmatic consumers to interact with the put.io API with high confidence and minimal manual configuration. Developers and agents are encouraged to start every session with putio describe --output json to align with the current runtime contract.

Sources: README.md:5-6, skills/putio-cli/references/discovery.md:1-5