palyra CLI is the primary operator interface for managing both local and remote Palyra runtimes. It is built using clap and provides a hierarchical command structure for bootstrap, diagnostics, agent orchestration, and system configuration.
CLI Architecture and Global Flags
The CLI entry point is defined incrates/palyra-cli/src/args/mod.rs using the Cli struct crates/palyra-cli/src/args/mod.rs#1-140. It implements a set of global options that influence how the CLI interacts with the daemon and local state.
Global Options
| Flag | Description | Code Reference |
|---|---|---|
--profile | Selects a named configuration profile from cli/profiles.toml. | crates/palyra-cli/src/args/mod.rs#60-60 |
--config | Explicit path to a palyra.toml daemon configuration file. | crates/palyra-cli/src/args/mod.rs#62-62 |
--state-root | Overrides the root directory for local state (logs, identity, etc.). | crates/palyra-cli/src/args/mod.rs#64-64 |
--output-format | Switches output between text, json, and ndjson. | crates/palyra-cli/src/args/mod.rs#73-76 |
--verbose | Increases logging verbosity (-v for debug, -vv for trace). | crates/palyra-cli/src/args/mod.rs#66-67 |
Command Tree Overview
The CLI structure is divided into several functional families. While many commands are top-level for convenience, they often map to underlying gRPC services or local state managers.Core Lifecycle and Setup
setup(alias:init): Bootstraps a new installation. It supports--mode localor--mode remoteand can trigger an interactive--wizardcrates/palyra-cli/src/args/mod.rs#77-77.doctor: The primary diagnostic tool. It performsDoctorCheckpipelines to identify configuration drift, connectivity issues, or state corruption crates/palyra-cli/src/commands/doctor/recovery.rs#48-57.configure: Re-runs the onboarding wizard engine to modify an existing installation safely crates/palyra-cli/src/args/mod.rs#71-71.
Agent and Runtime Operation
agent/agents: Commands for interacting with specific agents or listing available agent definitions crates/palyra-cli/src/args/mod.rs#50-51.acp: The Agent Control Protocol bridge. It provides a stdio-to-gRPC shim for connecting legacy agents or IDE extensions to the Palyra daemon crates/palyra-cli/src/args/mod.rs#46-49.routines/cron: Management of scheduled tasks and event-driven automation crates/palyra-cli/src/args/mod.rs#72-72, crates/palyra-cli/src/args/mod.rs#93-96.tui: Launches theratatui-based terminal user interface for interactive session management crates/palyra-cli/src/args/mod.rs#104-104.
System and Security
gateway(alias:daemon): Direct control and status inspection of thepalyradprocess crates/palyra-cli/src/args/mod.rs#73-73.secrets: Interface for the Vault system, allowing secure storage of API keys and credentials crates/palyra-cli/src/args/mod.rs#98-98.policy: Evaluates and explains Cedar policies governing tool execution crates/palyra-cli/src/args/mod.rs#90-90.node/nodes/pairing: Manages multi-node networking and device identity crates/palyra-cli/src/args/mod.rs#81-82, crates/palyra-cli/src/args/mod.rs#87-87.
Implementation Data Flow
The following diagram illustrates how a CLI command is parsed, routed through the transport layer, and executed against the daemon.CLI Command Execution Flow
Sources: crates/palyra-cli/src/lib.rs#76-90, crates/palyra-cli/src/transport/mod.rs#1-10, crates/palyra-daemon/src/transport/http/handlers/console/diagnostics.rs#6-114The Doctor Diagnostic System
Thedoctor command implements a complex recovery and repair system defined in crates/palyra-cli/src/commands/doctor/recovery.rs. It can detect and fix issues ranging from missing config files to corrupted browser profiles.
Key Components
DoctorCommandRequest: Encapsulates flags like--repair,--dry-run, and--strictcrates/palyra-cli/src/commands/doctor/recovery.rs#48-57.DoctorRepairStep: A discrete unit of repair (e.g.,MigrateConfigVersion,RestoreConfigBackup) crates/palyra-cli/src/commands/doctor/recovery.rs#105-118.DoctorRecoveryManifest: A JSON record of changes made during a repair session, enabling the--rollback-runfeature crates/palyra-cli/src/commands/doctor/recovery.rs#141-155.
Doctor Execution Logic
Sources: crates/palyra-cli/src/commands/doctor/recovery.rs#8-175, crates/palyra-daemon/src/transport/http/handlers/console/diagnostics.rs#6-114CLI Parity Matrix and Testing
To ensure consistency across platforms and prevent command drift, Palyra uses a CLI Parity Matrix. This system is implemented incrates/palyra-cli/src/cli_parity.rs and validated via tests in crates/palyra-cli/tests/help_snapshots.rs.
Parity Mechanism
- Matrix Definition: A TOML file (
tests/cli_parity_matrix.toml) defines all expected commands, their flags, and their parity status (done,partial, etc.) crates/palyra-cli/tests/cli_parity_report.md#1-24. - Snapshot Testing: The test suite executes
--helpfor every command in the matrix and compares the output against committed snapshots intests/help_snapshots/crates/palyra-cli/tests/help_snapshots.rs#75-126. - Normalization: To handle platform differences (e.g.,
.exeextensions on Windows), the system normalizes help text before comparison crates/palyra-cli/tests/help_snapshots.rs#22-24.
Parity Status Summary
| Status | Meaning |
|---|---|
verified | The command exists and matches the committed help snapshot. |
done | Full feature parity is expected and implemented. |
partial | Some flags or subcommands are pending implementation. |