palyra CLI serves as the primary administrative and operational interface for the Palyra ecosystem. It is built using the clap library for robust argument parsing and supports a deeply nested command tree designed for managing local runtimes, remote nodes, and security policies.
CLI Architecture and Implementation
The CLI is structured to separate argument definition, command dispatch, and transport logic. It utilizes a “Command” pattern where the parsedCli struct determines which internal module handles the request.
Command Execution Flow
The entry point incrates/palyra-cli/src/lib.rs initializes the runtime and dispatches to specific command handlers.
- Parsing:
clapderives theClistructure fromcrates/palyra-cli/src/args/mod.rscrates/palyra-cli/src/args/mod.rs#1-44. - Context Resolution: The CLI determines the
RootContext, which includes loading thepalyra.tomlconfiguration and identifying the target daemon (local vs. remote) crates/palyra-cli/src/lib.rs#7-12. - Dispatch: The
matchstatement in the main execution loop routes the command to the appropriate module incrates/palyra-cli/src/commands/crates/palyra-cli/src/commands/mod.rs#1-50. - Transport: Commands interact with the daemon via either the Admin/Console HTTP API (using
reqwest) or the Gateway gRPC Service (usingtonic) crates/palyra-cli/src/lib.rs#15-59.
CLI Component Mapping
The following diagram maps CLI logical components to their implementation files and structures. CLI Entity Mapping Sources: crates/palyra-cli/src/lib.rs#76-90, crates/palyra-cli/src/args/mod.rs#1-44, crates/palyra-cli/src/commands/mod.rs#1-50Global Flags and Configuration
The CLI supports several global options that modify behavior across all subcommands.| Flag | Env Var | Description |
|---|---|---|
--config <PATH> | PALYRA_CONFIG | Path to palyra.toml crates/palyra-cli/src/lib.rs#62-63. |
--profile <NAME> | PALYRA_PROFILE | Selects a specific configuration profile (e.g., staging). |
--state-root <DIR> | PALYRA_STATE_ROOT | Overrides the directory for identity and local state. |
--output-format | PALYRA_OUTPUT | Options: text (default), json, ndjson crates/palyra-cli/tests/help_snapshots/root-help-unix.txt#73-75. |
--verbose, -v | PALYRA_LOG | Increases logging verbosity (debug/trace). |
Primary Command Tree
The CLI organizes commands into functional families.1. Setup and Diagnostics
setup(aliasinit): Bootstraps a new installation, generates mTLS certificates, and creates the initialpalyra.tomlcrates/palyra-cli/src/commands/setup.rs#1-5.doctor: Runs a diagnostic suite including configuration validation, sandbox connectivity, and identity health crates/palyra-cli/src/commands/doctor.rs#1-10.health: Performs narrow liveness/readiness probes on HTTP and gRPC ports crates/palyra-cli/src/commands/health.rs#1-10.
2. Runtime and Gateway
gateway(aliasdaemon): Controls the core process. Includesstatus,usage-cost, andadmin-statuscrates/palyra-cli/src/args/daemon.rs#1-10.logs: Tails the local journal from the SQLite-backedjournal.sqlite3crates/palyra-cli/src/commands/logs.rs#1-10.system: Inspects theheartbeatandpresenceof subsystems like the cron scheduler and sandbox crates/palyra-cli/src/commands/system.rs#20-27.
3. Security and Secrets
secrets: Manages the Palyra Vault. Supportsset,get,list, andauditcrates/palyra-cli/src/commands/secrets.rs#61-146.auth: Managesprofiles(API keys/OAuth) andaccesscontrol tokens crates/palyra-cli/src/commands/auth.rs#4-24.policy: Evaluates and explains Cedar-based access control policies crates/palyra-cli/src/commands/policy.rs#1-10.
4. Memory and Intelligence
memory: Interface for the RAG (Retrieval-Augmented Generation) system. Supportssearch,recall, andpurgecrates/palyra-cli/src/commands/memory.rs#36-142.models: Lists available LLM backends and validates provider connectivity crates/palyra-cli/src/commands/models.rs#1-10.skills: Manages signed skill artifacts and their security audits crates/palyra-cli/src/commands/skills.rs#1-10.
Secret Management and Vault Interaction
Thesecrets command family interacts directly with the palyra-vault crate. It supports both interactive configuration and offline auditing of configuration files to ensure no raw secrets are stored in palyra.toml.
Secret Audit and Apply Logic
Sources: crates/palyra-cli/src/commands/secrets.rs#147-163, crates/palyra-cli/tests/secrets_cli.rs#144-184
Cross-Platform Parity Testing
To ensure consistent behavior across Windows, macOS, and Linux, Palyra employs a CLI Parity Matrix. This system snapshots the--help output and argument parsing behavior for every command.
- Implementation: The
CliParityMatrixincrates/palyra-cli/src/cli_parity.rsdefines expected snapshots crates/palyra-cli/src/cli_parity.rs#1-10. - Snapshots: Stored in
crates/palyra-cli/tests/help_snapshots/crates/palyra-cli/tests/help_snapshots.rs#7. - Normalization: The test runner normalizes line endings (
\r\nto\n) and binary names (palyra.exetopalyra) to ensure platform-agnostic comparisons crates/palyra-cli/tests/help_snapshots.rs#22-24.