palyra CLI is the primary entry point for operators to manage both local and remote Palyra runtimes. It provides a comprehensive command hierarchy for bootstrapping, diagnostics, agent interaction (ACP/MCP), and system administration.
Command Hierarchy and Architecture
The CLI is built usingclap for declarative argument parsing and command dispatch. The root command structure is defined in crates/palyra-cli/src/args/mod.rs, which aggregates subcommands from various domain-specific modules.
Core Command Groups
| Group | Commands | Purpose |
|---|---|---|
| Lifecycle | setup, configure, onboarding, uninstall, update | Installation, initial configuration, and maintenance. |
| Diagnostics | doctor, health, status, logs, system | Environment verification and runtime observability. |
| Protocols | acp, mcp, tui | Agent Control Protocol, Model Context Protocol, and TUI. |
| Management | profile, auth, secrets, policy, config | Identity, connection profiles, and security configuration. |
| Runtime | gateway, node, nodes, sandbox, plugins | Daemon control, node management, and isolation policies. |
| Data | memory, objectives, routines, sessions, backup | Persistence, long-term goals, and automation schedules. |
Command Dispatch Flow
The CLI follows a standard pattern:- Parse:
Cli::parse()generates aClistruct crates/palyra-cli/src/lib.rs#77-77. - Context Initialization: The
RootCommandContextis built to resolve profiles, state roots, and logging levels crates/palyra-cli/src/app/mod.rs#151-157. - Dispatch: The
runfunction matches theCliCommandenum to specific handler functions incrates/palyra-cli/src/commands/crates/palyra-cli/src/commands/mod.rs#1-52.
CLI Parity Matrix
The codebase maintains a CLI Parity Acceptance Matrix to ensure consistency across platforms (Unix/Windows) and feature completeness.- Verified Entries: 114 crates/palyra-cli/tests/cli_parity_report.md#10-13
- Help Snapshots: Automated tests compare
clapoutput against committed snapshots incrates/palyra-cli/tests/help_snapshots/to detect regressions crates/palyra-cli/tests/cli_parity_matrix.toml#1-14.
Canonical Command Map
To improve discoverability, several commands serve as preferred aliases for underlying subsystems:setup(alias forinit): Preferred bootstrap workflow crates/palyra-cli/src/args/mod.rs#139-139.gateway(alias fordaemon): Runtime/admin control surface crates/palyra-cli/src/args/mod.rs#143-143.skills(alias forskill): Plugin and tool management crates/palyra-cli/tests/cli_parity_report.md#85-85.
Connection Profiles and Environment Selection
The CLI uses Connection Profiles to manage multiple Palyra environments (e.g.,local, staging, prod).
Profile Implementation
Profiles are stored in aprofiles.toml file within the CLI state root crates/palyra-cli/src/app/mod.rs#26-26. The CliConnectionProfile struct tracks:
daemon_urlandgrpc_urlfor service endpoints crates/palyra-cli/src/app/mod.rs#96-97.admin_token_envfor secure credential retrieval crates/palyra-cli/src/app/mod.rs#99-99.strict_mode: When enabled, requires explicit confirmation for destructive actions crates/palyra-cli/src/app/mod.rs#108-108.
Profile Dispatch Logic
Sources: crates/palyra-cli/src/app/mod.rs#151-161, crates/palyra-cli/src/commands/profile.rs#215-250Output Formats and Serialization
The CLI supports three primary output formats, controlled by the--output-format global flag crates/palyra-cli/tests/help_snapshots/root-help-unix.txt#78-80:
- Text (Default): Human-readable tables and stylized output.
- JSON: Single valid JSON object for scripting.
- NDJSON: Newline-delimited JSON for streaming data (e.g., logs or run events).
RootCommandContext provides helper methods prefers_json() and prefers_ndjson() to allow command handlers to branch their rendering logic crates/palyra-cli/src/app/mod.rs#204-210.
Subsystem Details
1. Setup and Onboarding (setup, onboard)
The setup command invokes the operator_wizard crates/palyra-cli/src/commands/mod.rs#29-29. It supports a --flow quickstart mode for non-interactive bootstrapping, which automatically handles API key injection and config generation crates/palyra-cli/tests/wizard_cli.rs#68-91.
2. Diagnostics and Doctor (doctor, health)
The doctor command performs environment checks, including:
- Connectivity snapshots for HTTP and gRPC.
- Identity/Auth inspection.
- Repair previews and rollback workflows crates/palyra-cli/src/args/mod.rs#38-42.
3. Agent Bridges (acp, mcp)
- ACP: Launches the
AcpBridgewhich handles stdio-to-gRPC translation for agent communication crates/palyra-cli/src/args/acp.rs#1-52. - MCP: Implements the Model Context Protocol facade, allowing external tools to consume Palyra capabilities crates/palyra-cli/src/args/mod.rs#81-81.
4. Memory and Learning (memory)
The memory command family allows operators to manage the daemon’s long-term memory:
memory learning list: Review candidates for promotion into permanent facts crates/palyra-cli/tests/cli_parity_matrix.toml#183-191.memory learning promote-procedure: Converts a learned behavior into a skill scaffold crates/palyra-cli/tests/cli_parity_matrix.toml#203-211.
Data Flow: From CLI to Daemon
This diagram illustrates how a CLI command (e.g.,palyra gateway status) traverses the application layers.
Sources: crates/palyra-cli/src/app/mod.rs#212-225, crates/palyra-cli/src/lib.rs#24-28, crates/palyra-cli/src/commands/status.rs#1-20