palyra-cli crate provides the primary command-line interface for operators to manage both local and remote Palyra runtimes crates/palyra-cli/src/lib.rs#1-5. It serves as a unified entry point for administrative tasks, agent interaction, and system diagnostics.
The CLI is built using a strict output contract where all user-visible strings and JSON field names are pinned by parity and snapshot tests crates/palyra-cli/src/lib.rs#23-25.
Architecture Overview
The CLI follows a dispatch lifecycle managed by theRootCommandContext. It parses global options to establish the environment before executing specific subcommand logic.
CLI Execution Lifecycle
The following diagram illustrates how a command moves from the shell into the internal execution logic. CLI Dispatch Pipeline Sources: crates/palyra-cli/src/lib.rs#3-15, crates/palyra-cli/src/app/mod.rs#45-58, crates/palyra-cli/src/args/mod.rs#1-12Key Components
| Component | Role | Code Reference |
|---|---|---|
Cli | Top-level clap derive structure for argument parsing. | crates/palyra-cli/src/args/mod.rs#12 |
RootCommandContext | Resolves profiles, state roots, and connection endpoints. | crates/palyra-cli/src/app/mod.rs#45 |
CliConnectionProfile | Named configuration for targeting specific environments. | crates/palyra-cli/src/app/mod.rs#153 |
OutputFormatArg | Global flag for switching between Text, JSON, and NDJSON. | crates/palyra-cli/src/args/mod.rs#97-101 |
Command Families
The CLI is organized into functional groups, often referred to as “command families” crates/palyra-cli/src/args/mod.rs#154-191. Command Hierarchy Mapping Sources: crates/palyra-cli/tests/help_snapshots/root-help-unix.txt#5-66, crates/palyra-cli/src/commands/mod.rs#4-67CLI Architecture and Core Commands
This group handles the fundamental lifecycle of the Palyra installation. It includessetup (the preferred bootstrap workflow), gateway (admin and runtime diagnostics), and the doctor diagnostic system for environment repair crates/palyra-cli/src/args/mod.rs#175-179.
For details, see CLI Architecture and Core Commands.
Agent and Session Commands
These commands facilitate interaction with agents. Theacp command provides the Agent Control Protocol bridge, while agent allows for interactive or one-off sessions crates/palyra-cli/src/args/mod.rs#71-75. This family also includes the tui (Terminal User Interface) and the mcp (Model Context Protocol) facade crates/palyra-cli/src/args/mod.rs#110-148.
For details, see Agent and Session Commands.
CLI Output, Profiles, and Auxiliary Commands
This family manages the operator’s local environment. Theprofile command manages a registry of connection profiles (local, remote, or custom) with isolated state roots crates/palyra-cli/src/args/profile.rs#10-27. It also covers auth for credential management and backup for portable system snapshots crates/palyra-cli/src/args/mod.rs#81-85.
For details, see CLI Output, Profiles, and Auxiliary Commands.
Design Patterns
Profile Isolation
The CLI enforces isolation by assigning per-profile state roots and config snapshots crates/palyra-cli/src/args/profile.rs#25-27. When a profile is created viapalyra profile create, it typically resides in a subdirectory of the global state root crates/palyra-cli/src/app/mod.rs#34-39.
Global Guardrails
--expect-profile: Ensures the command only runs if the resolved profile matches the operator’s expectation crates/palyra-cli/tests/help_snapshots/root-help-unix.txt#79-80.--allow-strict-profile-actions: A safety gate required for destructive actions likeresetwhen targeting production profiles crates/palyra-cli/src/app/mod.rs#57, crates/palyra-cli/tests/help_snapshots/root-help-unix.txt#131.
Parity Testing
The CLI maintains aCliParityMatrix to ensure feature parity across platforms and consistent help output crates/palyra-cli/tests/cli_parity_matrix.toml#1-15. Help snapshots are pinned for every command to prevent accidental UX regressions crates/palyra-cli/tests/help_snapshots.rs#1-8.
Sources: crates/palyra-cli/src/app/mod.rs#32-58, crates/palyra-cli/src/args/profile.rs#10-27, crates/palyra-cli/tests/cli_parity_matrix.toml#1-15, crates/palyra-cli/tests/help_snapshots.rs#1-8