palyra) is a thick client designed for secure local and remote management of the Palyra runtime. It employs a deeply nested command tree built on the clap library, providing a unified interface for operations ranging from low-level gateway diagnostics to high-level agent orchestration and security governance.
Command Tree and Parser Implementation
The CLI uses a declarative argument structure defined incrates/palyra-cli/src/args/mod.rs. The root parser, Cli, handles global options like --profile, --config, and --output-format, while delegating specific logic to subcommands crates/palyra-cli/src/args/mod.rs#49-118.
Parser Architecture
The implementation follows a modular pattern where each major command family has a corresponding file insrc/args/ for definition and src/commands/ for execution crates/palyra-cli/src/commands/mod.rs#1-51.
| Component | Role | File Reference |
|---|---|---|
Cli | Root parser struct using clap(Parser) | crates/palyra-cli/src/lib.rs#76-80 |
Command | Top-level enum for all subcommands | crates/palyra-cli/src/lib.rs#80-89 |
GlobalOptions | Shared flags for profiles, logging, and state roots | crates/palyra-cli/tests/help_snapshots/root-help-unix.txt#62-89 |
Command Logic Data Flow
The following diagram illustrates how a CLI command moves from user input to gRPC or HTTP execution against the daemon. CLI Execution Flow Sources: crates/palyra-cli/src/lib.rs#76-89, crates/palyra-cli/src/commands/system.rs#10-17, crates/palyra-cli/src/commands/objectives.rs#12-19Primary Command Families
Setup and Configuration
setup: The primary bootstrap workflow for new installations (alias:init) crates/palyra-cli/src/args/mod.rs#139-139.configure: Guided reconfiguration of existingpalyra.tomlsettings using the onboarding engine crates/palyra-cli/src/args/mod.rs#140-140.onboarding: Multi-step wizard for operator setup (alias:onboard) crates/palyra-cli/src/args/mod.rs#155-155.
Runtime and Diagnostics
gateway: Family for daemon lifecycle, health probes, and admin status (alias:daemon) crates/palyra-cli/src/args/mod.rs#143-143.doctor: Comprehensive environment diagnostics, repair previews, and rollback orchestration crates/palyra-cli/tests/cli_parity_report.md#31-31.system: Observability into runtime heartbeats, subsystem presence, and thehash_chainprotected event log crates/palyra-cli/src/commands/system.rs#20-54.
Orchestration and Automation
objectives: Management of durableheartbeat,standing_order, andprogramtypes crates/palyra-cli/src/args/objectives.rs#149-155.routines: Unified surface for schedules and event triggers crates/palyra-cli/src/args/mod.rs#146-146.acp: Agent Control Protocol bridge for stdio-based agent communication crates/palyra-cli/src/args/mod.rs#141-141.mcp: Model Context Protocol facade for tool and resource exposure crates/palyra-cli/src/args/mod.rs#81-81.
Security and Governance
approvals: Audit and decision workflows for high-risk tool executions crates/palyra-cli/src/args/mod.rs#55-58.sandbox: Inspection of Tier A (WASM) and Tier B/C (Process) isolation policies crates/palyra-cli/src/args/mod.rs#149-149.secrets: Management of thepalyra-vaultbacked credentials crates/palyra-cli/src/args/mod.rs#109-109.
Parity Matrix and Help Snapshot Testing
To ensure consistency across platforms and prevent command drift, the CLI utilizes a Parity Acceptance Matrix and automated snapshot testing.Parity Matrix
The matrix defines the expected posture of every command, categorized by its “Canonical Family” or “Nested Surface” status crates/palyra-cli/tests/cli_parity_matrix.toml#3-14.- Postures:
done,partial,intentional_deviation,capability_gated. - Validation: The
cli_paritymodule verifies that the liveclaptree matches the requirements (flags, aliases, paths) defined in the matrix crates/palyra-cli/tests/cli_parity_report.md#8-24.
Snapshot Testing
The system captures the--help output for every command in the tree and compares it against committed .txt files in tests/help_snapshots/ crates/palyra-cli/tests/help_snapshots.rs#6-9.
- Normalization: Output is normalized to handle platform-specific line endings and binary extensions (e.g.,
palyra.exevspalyra) crates/palyra-cli/tests/help_snapshots.rs#22-24. - Regression: CI fails if the CLI help text drifts from the snapshots without an explicit update via
PALYRA_UPDATE_HELP_SNAPSHOTS=1crates/palyra-cli/tests/help_snapshots.rs#75-126.
Argument Structure Detail: Objectives
Theobjectives family demonstrates the complexity of the argument parser, handling nested structures for scheduling and delivery crates/palyra-cli/src/args/objectives.rs#88-147.
| Argument | Type | Description |
|---|---|---|
--kind | ObjectiveKindArg | One of objective, heartbeat, standing_order, program |
--priority | ObjectivePriorityArg | Escalation level from low to critical |
--schedule-type | ObjectiveScheduleTypeArg | Logic for execution: cron, every, or at |
--delivery-mode | RoutineDeliveryModeArg | How results are returned (e.g., SameChannel) |