palyra CLI is built on a strictly typed, hierarchical command tree designed for discoverability and cross-platform consistency. It serves as the primary operator interface for both local and remote daemon management, implementing a robust “Parity Matrix” system to ensure that the CLI surface remains synchronized across Unix and Windows environments.
Command Tree Architecture
The CLI utilizesclap for its command-line argument parsing and sub-command routing crates/palyra-cli/src/lib.rs#77-91. The architecture is divided into “Canonical Command Families” (preferred entry points) and “Top-Level Commands” (legacy or specialized utilities).
Core Data Flow
The CLI execution flow follows a standard pattern:- Parsing:
Cli::parse()generates theClistruct crates/palyra-cli/src/cli.rs#1-100. - Profile Resolution: Global options like
--profileand--configare evaluated to establish the connection context crates/palyra-cli/src/args/mod.rs#63-89. - Dispatch: The
Commandenum routes the request to specific module handlers crates/palyra-cli/src/commands/mod.rs#1-53.
Command Family Organization
The system categorizes commands to provide a clean operator surface while maintaining backward compatibility:| Category | Description | Examples |
|---|---|---|
| Canonical | Preferred, high-level workflows. | setup, acp, gateway, onboarding |
| Top-Level | Specific subsystem utilities. | doctor, health, logs, memory |
| Nested | Specialized sub-surfaces. | auth profiles, mcp serve, memory learning |
Profile Guardrails & Strict Mode
The CLI implements safety mechanisms to prevent accidental destructive actions against production environments.Profile Attributes
Profiles (defined viapalyra profile) contain metadata that the CLI uses to enforce safety:
- Risk Level: Can be set to
highorelevatedcrates/palyra-cli/src/args/tests.rs#49-50. - Strict Mode: When enabled, the CLI requires explicit flags for sensitive operations crates/palyra-cli/src/args/tests.rs#51.
Global Guardrail Flags
--expect-profile <NAME>: Aborts execution if the active profile does not match the expected name crates/palyra-cli/tests/help_snapshots/root-help-unix.txt#65.--allow-strict-profile-actions: Required to bypass safety prompts on profiles marked as high-risk crates/palyra-cli/tests/help_snapshots/root-help-unix.txt#88.
Parity Testing & Snapshot System
To ensure the CLI provides a consistent experience across all supported platforms, Palyra employs a “Parity Matrix” system. This system validates the CLI surface against a canonical specification.The Parity Matrix (cli_parity_matrix.toml)
The matrix defines every valid command path, its expected status (done, partial), required aliases, and required flags crates/palyra-cli/tests/cli_parity_matrix.toml#1-31.
Snapshot Validation Logic
The testing suite performs the following steps:- Load Matrix: Reads the TOML specification crates/palyra-cli/tests/help_snapshots.rs#14-20.
- Execute Help: Runs
palyra <path> --helpfor every entry crates/palyra-cli/tests/help_snapshots.rs#26-53. - Normalize: Strips platform-specific line endings (
\r\nto\n) and binary extensions (palyra.exetopalyra) crates/palyra-cli/tests/help_snapshots.rs#22-24. - Compare: Validates the output against stored snapshots in
tests/help_snapshots/crates/palyra-cli/tests/help_snapshots.rs#100-118.
Parity Acceptance Matrix Diagram
This diagram illustrates how theCliParityMatrix mediates between the code (Clap tree) and the documentation (Snapshots).
CLI Parity Verification Flow
Sources: crates/palyra-cli/tests/help_snapshots.rs#76-126, crates/palyra-cli/tests/cli_parity_matrix.toml#1-36
Implementation Details
Command Dispatch System
Thepalyra-cli crate uses a central dispatching logic in lib.rs that maps parsed CliCommand variants to their respective implementation modules.
Command Routing Diagram
Sources: crates/palyra-cli/src/lib.rs#78-90, crates/palyra-cli/src/commands/mod.rs#1-53, crates/palyra-cli/src/args/mod.rs#1-47
Summary Matrix Example
The system generates acli_parity_report.md during CI to track progress and regressions across the 100+ command entries crates/palyra-cli/tests/cli_parity_report.md#1-24.
| Feature | Verification Method |
|---|---|
| Command Existence | Clap CommandFactory validation against Matrix crates/palyra-cli/tests/help_snapshots.rs#76-84 |
| Flag Parity | required_flags check in cli_parity_matrix.toml crates/palyra-cli/tests/cli_parity_matrix.toml#8 |
| Cross-Platform | Separate Unix/Windows snapshots for root help crates/palyra-cli/tests/cli_parity_matrix.toml#12-13 |
| Install Smoke | installed_smoke.rs runs binary against temp workdirs crates/palyra-cli/tests/installed_smoke.rs#39-148 |