palyra CLI is the primary operator interface for managing secure local and remote Palyra runtimes crates/palyra-cli/src/lib.rs#1-4. It is built using clap for command-line argument parsing and provides a unified surface for administration, agent interaction, and system diagnostics crates/palyra-cli/src/lib.rs#77-91.
CLI Architecture & Command Dispatch
The CLI follows a modular dispatch pattern where theCli struct defines the global hierarchy, and execution is delegated to specialized command modules crates/palyra-cli/src/commands/mod.rs#1-52.
Data Flow: Command Execution
The CLI resolves aRootContext to handle configuration and identity before establishing gRPC or HTTP connections to the daemon crates/palyra-cli/src/commands/agent.rs#28-59.
Sources: crates/palyra-cli/src/args/mod.rs#1-118, crates/palyra-cli/src/commands/mod.rs#1-52, crates/palyra-cli/src/client/operator.rs#1-100
Lifecycle & Setup Commands
setup / init
Thesetup command (aliased as init) bootstraps a Palyra installation crates/palyra-cli/tests/cli_parity_matrix.toml#26-31. It handles identity generation, filesystem layout, and initial configuration crates/palyra-cli/src/args/mod.rs#139-140.
doctor
Thedoctor command runs environment diagnostics and provides repair/rollback workflows crates/palyra-cli/src/commands/doctor.rs#8-10. It utilizes the DoctorCommandRequest to analyze system state and can generate support bundles crates/palyra-cli/src/commands/doctor/recovery.rs#5-7.
Sources: crates/palyra-cli/src/commands/doctor.rs#1-11, crates/palyra-cli/src/args/mod.rs#139-140
Agent & Session Management
agent
Provides workflows for running agents in one-off or interactive modes crates/palyra-cli/src/commands/agent.rs#27-30.agent run: Executes a single prompt and streams the response crates/palyra-cli/src/commands/agent.rs#31-74.agent interactive: Launches a REPL for multi-turn sessions with slash-command support (e.g.,/reset,/session,/abort) crates/palyra-cli/src/commands/agent.rs#75-109.
sessions
Manages the lifecycle of agent sessions, including history retrieval, branching, and transcript searching crates/palyra-cli/src/commands/sessions.rs#18-43.- Implementation: Uses
OperatorRuntime::list_sessionsandresolve_sessiongRPC calls crates/palyra-cli/src/commands/sessions.rs#45-50. - Compaction: Supports
CompactPreviewandCompactApplyto manage session context window efficiency crates/palyra-cli/src/commands/sessions.rs#31-32.
acp / mcp
- acp: Implements the Agent Control Protocol bridge for stdio-based integration crates/palyra-cli/src/args/mod.rs#49-52.
- mcp: Provides a Model Context Protocol facade, allowing external LLMs to consume Palyra tools via
mcp servecrates/palyra-cli/src/args/mod.rs#81-81.
System & Infrastructure
gateway (daemon)
Controls thepalyrad background process. Commands include status, health, and admin-status crates/palyra-cli/src/args/mod.rs#187-196. It allows operators to check gRPC/HTTP surface liveness crates/palyra-cli/tests/help_snapshots/root-help-unix.txt#9-11.
memory
Handles long-term memory operations, including ingestion, search, and “Phase 6” learning candidate review crates/palyra-cli/src/args/mod.rs#82-84.memory learning review: Promotes procedure candidates into skills crates/palyra-cli/tests/cli_parity_matrix.toml#193-204.
sandbox
Explains the effective isolation policy forprocess-runner (Tier B/C) and WASM (Tier A) runtimes crates/palyra-cli/src/args/mod.rs#108-108. It uses SandboxRuntimeArg to toggle between runtime views crates/palyra-cli/src/args/sandbox.rs#1-20.
CLI-Daemon Interaction Model
Sources: crates/palyra-cli/src/commands/agent.rs#49-74, crates/palyra-cli/src/commands/sessions.rs#127-137, crates/palyra-cli/src/lib.rs#24-28Configuration & Security
profile
Manages CLI connection profiles stored inpalyra.toml crates/palyra-cli/src/args/mod.rs#101-101. Profiles define daemon_url, grpc_url, and default principal identities crates/palyra-cli/src/args/tests.rs#35-66.
secrets / auth
- secrets: Manages the vault-backed secret storage crates/palyra-cli/src/args/mod.rs#109-109.
- auth: Configures authentication profiles for LLM providers (e.g., OpenAI OAuth) and agent-specific credentials crates/palyra-cli/src/commands/auth.rs#4-25.
skills
Manages WASM-based plugin artifacts. Includes commands for packaging (skills package), signing, and auditing security via SBOM analysis crates/palyra-cli/src/lib.rs#117-122.
Sources: crates/palyra-cli/src/args/tests.rs#35-92, crates/palyra-cli/src/commands/auth.rs#27-110, crates/palyra-cli/src/lib.rs#117-122
Command Reference Table
| Command | Purpose | Key Function / Argument |
|---|---|---|
setup | Bootstrap environment | InitModeArg crates/palyra-cli/src/args/init.rs#1-10 |
doctor | Diagnostics & Repair | run_doctor crates/palyra-cli/src/commands/doctor.rs#8 |
agent | Execution & REPL | execute_agent_stream crates/palyra-cli/src/commands/agent.rs#73 |
sessions | History & Compaction | list_sessions crates/palyra-cli/src/commands/sessions.rs#50 |
approvals | Human-in-the-loop | ApprovalDecisionArg crates/palyra-cli/src/args/approvals.rs#1-15 |
objectives | Standing orders | ObjectiveUpsertCommandArgs crates/palyra-cli/src/args/objectives.rs#1-20 |
cron | Scheduled tasks | CronCommand crates/palyra-cli/src/args/cron.rs#1-10 |
backup | Portable snapshots | BackupComponentArg crates/palyra-cli/src/args/backup.rs#1-10 |
channels | Platform integration | ChannelsDiscordCommand crates/palyra-cli/src/args/channels.rs#1-15 |