palyra-cli crate provides the primary operator interface for managing Palyra installations, both local and remote. It serves as a unified binary for administrative tasks, diagnostic audits, agent interaction via the Agent Control Protocol (ACP), and a terminal-based user interface (TUI).
The CLI is designed with a “local-first, remote-capable” philosophy, allowing operators to manage a local daemon via filesystem and Unix sockets or a remote gateway via mTLS-secured gRPC crates/palyra-cli/src/lib.rs#1-13.
Command Structure and Context
The CLI usesclap for command-line argument parsing, organized into a hierarchical structure of subcommands crates/palyra-cli/src/args/mod.rs#1-44. Global options such as --profile, --config, and --output-format allow for consistent behavior across different environments crates/palyra-cli/tests/help_snapshots/root-help-unix.txt#59-75.
Root Command Context
Every execution initializes aRootCommandContext which resolves configuration paths, state roots, and connection profiles crates/palyra-cli/src/app/mod.rs#29-39. Profiles are stored in cli/profiles.toml and allow switching between different deployment environments (e.g., local desktop vs. staging gateway) crates/palyra-cli/src/app/mod.rs#23-26.
Connection Resolution
The CLI distinguishes between two primary connection types:- Admin Connections: Used for system-level tasks (managing agents, auditing logs, configuring skills). These typically target the
/admin/v1HTTP surface or theApprovalsServicegRPC surface crates/palyra-cli/src/app/mod.rs#52-54. - User/Agent Connections: Used for interacting with the orchestration engine, often via the Agent Control Protocol (ACP) crates/palyra-cli/src/app/mod.rs#49-50.
CLI Command Entity Mapping
The following diagram illustrates how CLI commands map to internal application logic and external protocol services. CLI Architecture and Service Mapping Sources: crates/palyra-cli/src/lib.rs#76-89, crates/palyra-cli/src/app/mod.rs#173-201, crates/palyra-cli/src/commands/approvals.rs#28-32Core Subsystems
gRPC and HTTP Clients
The CLI contains generated gRPC stubs for all major Palyra protocols, includinggateway, auth, browser, cron, and memory crates/palyra-cli/src/lib.rs#15-59. It implements a retry mechanism for gRPC calls using exponential backoff to handle transient network issues crates/palyra-cli/src/client/grpc.rs#5-30.
ACP Bridge and TUI
The CLI provides an implementation of the Agent Control Protocol (ACP), allowing it to act as a bridge between standard I/O and the Palyra orchestration engine. This enables users to run agents in a “shim” mode or launch the interactive Terminal User Interface (TUI) for real-time session management crates/palyra-cli/src/args/mod.rs#46-49, crates/palyra-cli/src/args/mod.rs#104.Channel and Connector Management
The CLI handles the administrative setup of external connectors, such as Discord. This involves interactive “probes” to validate bot tokens and permission audits before applying configuration to the daemon crates/palyra-cli/src/commands/channels/connectors/discord/setup.rs#10-46. It also manages the Channel Router, allowing operators to preview routing rules and mint pairing codes for new nodes crates/palyra-cli/src/commands/channels/router.rs#9-152. Discord Onboarding Flow Sources: crates/palyra-cli/src/commands/channels/connectors/discord/setup.rs#33-96Detailed Command Groups
The CLI’s functionality is partitioned into several major areas, detailed in the following child pages:Core Commands: Setup, Doctor, and Onboarding
Covers the initial bootstrap of the Palyra environment.setup: Bootstraps local or remote installations crates/palyra-cli/src/args/mod.rs#77.doctor: A diagnostic pipeline that validates toolchains, connectivity, and performs configuration repairs crates/palyra-cli/src/args/tests.rs#86-101.onboarding: Interactive wizards for guided configuration crates/palyra-cli/src/args/mod.rs#83-86.
ACP Bridge, TUI, and Agent Commands
Covers agent interaction and session management.acp: The stdio bridge for the Agent Control Protocol crates/palyra-cli/src/args/mod.rs#46-49.tui: The terminal operator client crates/palyra-cli/src/args/mod.rs#104.agent/agents: CRUD operations and execution control for agents crates/palyra-cli/src/args/mod.rs#50-51.approvals: Management of human-in-the-loop tool execution decisions crates/palyra-cli/src/commands/approvals.rs#7-19.
CLI Parity, Testing, and Help Snapshots
Covers the infrastructure used to ensure CLI stability across platforms.CliParityMatrix: Ensures command consistency between Unix and Windows crates/palyra-cli/tests/help_snapshots.rs#4-6.help_snapshots: Automated regression tests that compare current--helpoutput against committed snapshots crates/palyra-cli/tests/help_snapshots.rs#76-120.