palyra) serves as the primary operator interface for managing both local and remote gateway runtimes. It is built using a deeply nested clap command structure that maps high-level operator intents to gRPC or HTTP/Admin API calls.
CLI Architecture and Command Parsing
The CLI is structured around theCli struct, which utilizes the clap crate for declarative argument parsing and help generation. The command surface is partitioned into logical domains (e.g., auth, memory, skills) to match the backend’s micro-service architecture.
Root Options and Context
Every command execution is wrapped in aRootOptions context. This context manages global flags such as --config, --profile, and --state-root, which are used to locate the palyra.toml configuration and initialize the transport layer crates/palyra-cli/src/lib.rs#60-100.
Data Flow: Command to Gateway
The CLI typically follows a “Request-Dispatch-Emit” pattern:- Parsing:
clapparses arguments into aCommandenum crates/palyra-cli/src/args/mod.rs#1-44. - Dispatch: The
run_commandfunction (inlib.rs) dispatches to specific command modules crates/palyra-cli/src/commands/mod.rs#1-50. - Execution: The command module establishes a gRPC connection (via
tonic) or an Admin API connection (viareqwest) crates/palyra-cli/src/commands/system.rs#15-22. - Output: Results are formatted as human-readable text or structured JSON/NDJSON based on the
--output-formatflag crates/palyra-cli/src/output/skills.rs#4-23.
Code Entity Mapping: Command Dispatch
The following diagram illustrates how the CLI translates a user string into a code execution path. CLI Dispatch Pipeline Sources: crates/palyra-cli/src/lib.rs#76-90, crates/palyra-cli/src/commands/memory.rs#4-22, crates/palyra-cli/src/commands/system.rs#10-22.Core Command Surface
Setup and Onboarding
Thesetup (alias init) and onboarding commands manage the initial bootstrap of the environment. This includes generating TLS certificates, initializing the SQLite journal, and configuring the RootFileConfig crates/palyra-cli/src/commands/operator_wizard.rs#239-250.
- Wizard Engine: The CLI includes an interactive
WizardSessionthat guides users throughquickstart,manual, orremotedeployment flows crates/palyra-cli/src/commands/operator_wizard.rs#63-86. - TLS Scaffolding: Supports
self-signedorprovidedcertificate modes for mTLS node communication crates/palyra-cli/src/args/mod.rs#77-77.
Memory and RAG Operations
Thememory command interacts with the MemoryServiceClient to manage the RAG (Retrieval-Augmented Generation) subsystem.
- Search: Performs hybrid search (lexical + vector) across specific scopes crates/palyra-cli/src/commands/memory.rs#36-48.
- Purge: Allows selective deletion of memories by
session_id,channel, orprincipalcrates/palyra-cli/src/commands/memory.rs#143-155. - Workspace: Manages local file indexing for the agent’s context crates/palyra-cli/src/args/memory.rs#1-10.
Skills and Plugin Management
Theskills command manages the lifecycle of WASM-based plugins and tool definitions.
- Package: The
skills package buildcommand creates a signed.palyra-skillartifact containing WASM modules, manifests, and SBOMs crates/palyra-cli/src/commands/skills.rs#5-16. - Audit/Verify: Validates signatures against the
SkillTrustStoreand performs security audits before installation crates/palyra-cli/src/commands/skills.rs#106-126.
System and Diagnostics
- Doctor: Performs a comprehensive health check of the local environment (dependencies, permissions, network) crates/palyra-cli/src/commands/mod.rs#16-16.
- Heartbeat: Queries the
/console/v1/system/heartbeatendpoint to verify gateway uptime and subsystem status crates/palyra-cli/src/commands/system.rs#20-23. - Logs: Tails the
JournalStorediagnostics directly from the SQLite database crates/palyra-cli/src/commands/mod.rs#20-20.
ACP and Agent Control Protocol
Theacp command facilitates communication between external tools (like IDE extensions) and the Palyra gateway.
- AcpBridge: Maps standard I/O (stdin/stdout) to the gateway’s gRPC stream, allowing non-gRPC-aware tools to interact with agents crates/palyra-cli/src/args/acp.rs#46-49.
- Legacy Shim: Provides a compatibility layer for v1 ACP protocols crates/palyra-cli/src/args/mod.rs#46-49.
TUI (Terminal User Interface)
Thetui command launches a ratatui-based interactive session. It utilizes the operator_client to provide a real-time view of agent runs, session transcripts, and approval requests crates/palyra-cli/src/commands/tui.rs#1-44.
Cross-Platform Parity and Testing
Palyra maintains strict CLI parity between Unix-like systems and Windows. This is enforced via theCliParityMatrix.
CliParityMatrix
TheCliParityMatrix defines a set of commands and their expected help outputs across platforms. It ensures that flags, aliases, and descriptions remain synchronized crates/palyra-cli/src/cli_parity.rs#1-20.
Snapshot Testing
The system uses snapshot files (e.g.,root-help-unix.txt) to detect regressions in the command surface.
- Test Runner:
help_snapshots_match_cli_parity_matrixiterates through the matrix and compares currentpalyra --helpoutput against stored snapshots crates/palyra-cli/tests/help_snapshots.rs#75-100. - Normalization: Help text is normalized (e.g., stripping
.exeon Windows) to allow cross-platform comparison crates/palyra-cli/tests/help_snapshots.rs#22-25.