CLI Architecture & Command Dispatch

The Palyra CLI (palyra) serves as the primary operator interface for managing local and remote runtimes. It is built on a modular command dispatch architecture using clap for argument parsing and a centralized RootCommandContext for managing application state, identity, and transport configuration.

Core Architecture Overview

The CLI is structured to separate argument definition from execution logic. The entry point in main.rs (via lib.rs) parses the top-level Cli struct and delegates to specific command modules.

Component Breakdown

Component	Role	File Reference
`Cli` / `Command`	Top-level `clap` definition for all subcommands and global options.	crates/palyra-cli/src/cli.rs
`RootOptions`	Global flags (e.g., `--config`, `--profile`, `--output-format`).	crates/palyra-cli/src/args/mod.rs
`RootCommandContext`	Thread-safe singleton storing resolved paths, profiles, and trace IDs.	crates/palyra-cli/src/app/mod.rs#29-39
Command Modules	Implementation of specific logic (e.g., `run_secrets`, `run_objectives`).	crates/palyra-cli/src/commands/
Output Layer	Utilities for text, JSON, and NDJSON formatting.	crates/palyra-cli/src/output/mod.rs

Command Dispatch Flow

The dispatch process follows a linear transformation from raw arguments to an initialized execution context:

Parsing: clap parses std::env::args() into the Cli struct crates/palyra-cli/src/lib.rs#76.
Context Initialization: Global options are used to build the RootCommandContext via install_root_context crates/palyra-cli/src/app/mod.rs#124-130. This resolves the active profile and configuration file.
Dispatch: A large match statement in lib.rs (or specific sub-dispatchers) calls the corresponding function in the commands/ directory crates/palyra-cli/src/lib.rs#77-90.
Execution: The command function uses the context to resolve gRPC or HTTP connections crates/palyra-cli/src/app/mod.rs#173-201 and interacts with the daemon or local filesystem.

Sources: crates/palyra-cli/src/lib.rs#76-90, crates/palyra-cli/src/app/mod.rs#29-39, crates/palyra-cli/src/app/mod.rs#124-130

App Context & Identity Resolution

The RootCommandContext is the source of truth for the CLI’s runtime environment. It handles the resolution of connection details by merging defaults, configuration files, environment variables, and CLI overrides.

Identity & Connection Resolution Logic

The CLI supports multiple “Principals” (e.g., user:local, admin:local) and “Channels” (defaulting to cli). Key Functions:

resolve_grpc_connection: Combines ConnectionOverrides and ConnectionDefaults to produce an AgentConnection for gRPC calls crates/palyra-cli/src/app/mod.rs#173-186.
resolve_token: Determines the admin token by checking CLI flags, then profiles, then environment variables (PALYRA_ADMIN_TOKEN) crates/palyra-cli/src/app/mod.rs#240-260.

Sources: crates/palyra-cli/src/app/mod.rs#42-54, crates/palyra-cli/src/app/mod.rs#173-201, crates/palyra-cli/src/app/mod.rs#240-260

Output Formats & Logging

The CLI implements a unified output strategy controlled by the --output-format flag crates/palyra-cli/src/args/mod.rs#74.

Supported Formats

Text: Human-readable terminal output, often using tables or line-based status updates.
JSON: Structured, pretty-printed JSON for integration with tools like jq.
NDJSON: Newline-delimited JSON, used primarily for streaming events (e.g., logs or real-time run traces).

Logging & Tracing

The CLI uses the log crate with verbosity controlled by -v (debug) and -vv (trace) crates/palyra-cli/src/args/mod.rs#67-72. Every request generated by the CLI includes a unique trace_id (generated as a ULID) in the headers/metadata to allow correlation with daemon logs crates/palyra-cli/src/app/mod.rs#149-151. Sources: crates/palyra-cli/src/app/mod.rs#165-171, crates/palyra-cli/src/args/mod.rs#74, crates/palyra-cli/src/app/mod.rs#149-151

CLI Parity & Testing

To ensure consistency across platforms (Linux, macOS, Windows) and prevent command drift, Palyra employs a “CLI Parity Matrix.”

Parity Matrix Implementation

The parity matrix is defined in tests/cli_parity_matrix.toml and enforced via help_snapshots.rs. This system ensures that every command and subcommand:

Has a consistent help string across platforms.
Maintains its argument structure during refactors.

Key Code Entities:

CliParityMatrix: The TOML structure containing all command paths to be tested crates/palyra-cli/src/cli_parity.rs.
run_help: A helper function that executes the binary and captures stdout for comparison crates/palyra-cli/tests/help_snapshots.rs#26-53.
normalize_help_text: Strips platform-specific differences like .exe suffixes to allow cross-platform snapshot validation crates/palyra-cli/tests/help_snapshots.rs#22-24.

Sources: crates/palyra-cli/src/cli_parity.rs, crates/palyra-cli/tests/help_snapshots.rs#22-53, crates/palyra-cli/tests/help_snapshots.rs#75-126

Command Dispatch Implementation Example: Secrets

The secrets command demonstrates the typical flow of a CLI command that interacts with both the local vault and the configuration system.

Step	Action	Code Reference
Argument Parsing	`clap` parses `SecretsCommand::Set`.	crates/palyra-cli/src/args/mod.rs#105
Execution	`run_secrets` is called with the enum variant.	crates/palyra-cli/src/commands/secrets.rs#61
Local Logic	`open_cli_vault()` initializes the `Vault` runtime.	crates/palyra-cli/src/commands/secrets.rs#64
Output	Results are printed to stdout, respecting redaction rules.	crates/palyra-cli/src/commands/secrets.rs#70-76

Sources: crates/palyra-cli/src/commands/secrets.rs#61-78, crates/palyra-cli/src/args/mod.rs#105

​Core Architecture Overview

​Component Breakdown

​Command Dispatch Flow

​App Context & Identity Resolution

​Identity & Connection Resolution Logic

​Output Formats & Logging

​Supported Formats

​Logging & Tracing

​CLI Parity & Testing

​Parity Matrix Implementation

​Command Dispatch Implementation Example: Secrets