palyra CLI is the primary operator interface for the Palyra platform. It serves as a unified entry point for bootstrapping installations, managing the background daemon, interacting with AI agents via the Agent Control Protocol (ACP), and performing administrative tasks such as secret management and policy evaluation crates/palyra-cli/src/args/mod.rs#109-140.
High-Level Role and Communication
The CLI acts as a gRPC and HTTP client to thepalyrad daemon. It abstracts complex multi-step workflows (like onboarding or skill auditing) into single commands. While most commands communicate with a running daemon, some (like setup, init, and doctor) operate directly on the local filesystem or system environment crates/palyra-cli/src/lib.rs#77-90.
Communication Architecture
The CLI utilizes a generated proto-client layer to interact with various daemon subsystems. Sources: crates/palyra-cli/src/lib.rs#15-59, crates/palyra-cli/src/lib.rs#140-143, crates/palyra-cli/src/commands/mod.rs#1-49Command Hierarchy
The CLI is built usingclap and organized into a deeply nested hierarchy of subcommands. The root Cli struct defines global options like --config, --profile, and --state-root which are shared across all operations crates/palyra-cli/src/lib.rs#76-89.
| Command Group | Purpose | Primary Entities |
|---|---|---|
setup / init | Installation and environment bootstrapping. | InitModeArg, InitTlsScaffoldArg |
gateway / daemon | Lifecycle and health of the palyrad process. | JournalCheckpointModeArg |
acp | Bridge for IDEs and external tools via stdio. | AcpBridgeArgs, AcpShimArgs |
routines / cron | Management of scheduled and event-driven tasks. | CronScheduleTypeArg |
skills | Packaging, auditing, and installing WASM plugins. | SkillsPackageCommand, SkillManifest |
tui | Interactive terminal interface for agent chat. | TuiCommand |
Subsystem Integration
The CLI maps high-level intent to specific internal crates and logic:- Identity & Security: Commands like
pairingandauthutilizepalyra-identityfor device handshakes andpalyra-authfor credential management crates/palyra-cli/src/lib.rs#112-115. - Vault & Secrets: The
secretscommand interfaces withpalyra-vaultto store and retrieve encrypted sensitive data using platform-specific backends crates/palyra-cli/src/lib.rs#122-125. - Policy Enforcement: The
policycommand allows operators to testCedarpolicies against specific contexts usingpalyra-policycrates/palyra-cli/src/lib.rs#115-115.
CLI-to-Code Mapping
The following diagram bridges the CLI command structure to the underlying Rust modules and data structures. Sources: crates/palyra-cli/src/lib.rs#76-125, crates/palyra-cli/src/args/mod.rs#1-45Cross-Platform Parity
To ensure consistent behavior across Linux, macOS, and Windows, the CLI uses aCliParityMatrix. This system compares command output snapshots (e.g., root-help-unix.txt vs root-help-windows.txt) to prevent regression in the operator experience across different operating systems crates/palyra-cli/tests/help_snapshots.rs#4-7.
Sources: crates/palyra-cli/tests/help_snapshots.rs#75-120, crates/palyra-cli/tests/help_snapshots/root-help-unix.txt#1-112
Detailed Documentation
For more in-depth information on specific CLI components, refer to the following child pages:- Command Reference and Architecture: Full documentation of the command surface, argument parsing, and the parity testing matrix.
- ACP Bridge and Agent Control Protocol: Technical details on how the CLI bridges standard input/output to gRPC streams for external tool integration.
- Terminal User Interface (TUI): Overview of the
ratatui-based interactive interface for managing sessions and interacting with agents.