Skip to main content
The palyra CLI, implemented in the palyra-cli crate, is the primary operator interface for managing local and remote Palyra runtimes. It provides a unified command-line surface for system bootstrapping, diagnostic health checks, real-time agent interaction via the Agent Control Protocol (ACP), and administrative governance of routines, approvals, and security policies.

​
Command Architecture

The CLI is built using clap for robust argument parsing and sub-command nesting. The entry point resides in crates/palyra-cli/src/lib.rs, which dispatches to specific command handlers in crates/palyra-cli/src/commands/.

​
Root Command Tree

The CLI categorizes operations into several major families:
  • Lifecycle: setup (alias init), onboarding, configure, update, uninstall.
  • Diagnostics: doctor, health, status, logs, system, support-bundle.
  • Agent Operations: acp, tui, agent, agents, sessions, approvals.
  • Automation: routines, cron, hooks, webhooks.
  • Resources: memory, plugins, skills, secrets, config, models.
  • Infrastructure: gateway (alias daemon), node, nodes, pairing, browser.

​
CLI Execution Flow

The following diagram maps the transition from user input to the internal RootCommandContext and subsequent execution. CLI Entry Point to Context Mapping Sources: crates/palyra-cli/src/lib.rs#76-90, crates/palyra-cli/src/app/mod.rs#28-39, crates/palyra-cli/src/app/mod.rs#124-130

​
Connection and Transport

The CLI interacts with the Palyra Daemon (palyrad) via two primary protocols:
  1. gRPC (Tonic): Used for high-performance streaming (e.g., RunStream) and administrative tasks (e.g., ApprovalsService).
  2. HTTP (Reqwest): Used for RESTful admin APIs, onboarding probes, and webhook management.
The RootCommandContext resolves connection details by merging CLI flags, environment variables (e.g., PALYRA_DAEMON_URL), and profile configuration from cli/profiles.toml crates/palyra-cli/src/app/mod.rs#23-26.
TransportImplementationPrimary Use Case
gRPCgateway_v1::gateway_service_clientAgent execution, Health probes, Approvals
HTTPreqwest::blocking::ClientSetup, Discord onboarding, Webhook config
Sources: crates/palyra-cli/src/client/grpc.rs#32-42, crates/palyra-cli/src/client/channels.rs#69-74, crates/palyra-cli/src/app/mod.rs#173-201

​
Major Subsystems

​
Setup and Diagnostics

The CLI manages the initial bootstrap of the environment through the setup command and provides a comprehensive diagnostic suite via doctor.
  • Setup: Supports local and remote modes, including a guided operator_wizard.
  • Doctor: A diagnostic framework that checks configuration validity, connectivity, and sandbox health.
For details, see Setup, Onboarding, and Doctor.

​
ACP Bridge and TUI

The Agent Control Protocol (ACP) bridge allows external tools (like IDEs) to communicate with Palyra agents via stdio. The CLI also provides a ratatui-based TUI for a native terminal-based chat experience.
  • ACP: Handles stdio multiplexing and session branching.
  • TUI: Provides real-time transcript rendering and tool execution visibility.
For details, see ACP Bridge, TUI, and Session Management.

​
Automation and Governance

Administrative commands manage the background lifecycle of the daemon: For details, see Routines, Cron, and Approvals CLI.

​
Platform Parity and Testing

The CLI ensures a consistent experience across Windows, macOS, and Linux through a dedicated parity framework.
  • CliParityMatrix: A configuration-driven matrix used to verify that help text and command behavior remain consistent across platforms.
  • Snapshot Testing: Automated tests compare actual CLI help output against platform-specific snapshots crates/palyra-cli/tests/help_snapshots.rs#75-77.
CLI Testing Architecture Sources: crates/palyra-cli/src/cli_parity.rs#1-10, crates/palyra-cli/tests/help_snapshots.rs#14-20, crates/palyra-cli/tests/help_snapshots/root-help-unix.txt#1-54 For details, see CLI Platform Parity and Testing.

​
Sub-pages Reference

​
Child Pages