palyra) is the primary interface for operators to manage both local and remote runtimes. It serves as a unified entry point for bootstrapping installations, performing diagnostics, managing automation routines, and interacting with the core daemon via gRPC and REST transports.
The CLI is built using clap for command-line argument parsing and uses a hierarchical dispatch pattern to route commands to specific handler functions located in the crates/palyra-cli/src/commands/ directory.
CLI Architecture & Dispatch Flow
The CLI follows a strict separation between argument definition (args/) and execution logic (commands/).
- Parsing:
clapparses the command line into theClistruct defined incrates/palyra-cli/src/args/mod.rs. - Context Resolution: The
app::current_root_context()is used to resolve configuration paths, state roots, and identity crates/palyra-cli/src/commands/memory.rs#5-6. - Dispatch: The
mainfunction (vialib.rs) matches the parsedCliCommandand calls the correspondingrun_function crates/palyra-cli/src/lib.rs#77-90. - Transport: Commands either perform local filesystem operations (e.g.,
backup,setup) or connect to the daemon usingAgentConnectionfor gRPC orConsoleApiClientfor REST crates/palyra-cli/src/commands/memory.rs#16-21, crates/palyra-cli/src/commands/system.rs#16-17.
Command Dispatch Mapping
| Command Family | Primary Purpose | Implementation Module |
|---|---|---|
setup / init | Bootstrap and installation | commands::setup, commands::init |
gateway / daemon | Runtime lifecycle & status | commands::gateway, commands::daemon |
acp | Agent Control Protocol bridge | commands::acp |
doctor | Diagnostics and repair | commands::doctor |
routines / cron | Automation and scheduling | commands::routines, commands::cron |
memory | Vector/lexical search management | commands::memory |
skills | WASM plugin management | commands::skills |
system | Heartbeat and event logs | commands::system |
Core Command Reference
Setup & Onboarding
Thesetup command (aliased to init) is the entry point for creating a new Palyra installation. It supports local and remote modes and can trigger a wizard for interactive configuration crates/palyra-cli/src/args/mod.rs#144-152.
- Implementation:
crates/palyra-cli/src/commands/setup.rs - Key Logic: Handles TLS scaffolding (self-signed or provided), config generation, and identity creation crates/palyra-cli/src/args/tests.rs#33-43.
Gateway & Daemon
Provides administrative access to thepalyrad process.
gateway status: Checks connectivity across HTTP and gRPC surfaces crates/palyra-cli/src/args/mod.rs#172-185.gateway usage-cost: Aggregates token usage from the journal.gateway admin-status: Detailed health metrics requiring an admin token.
Memory & Search
Interacts with theMemoryService to manage the daemon’s long-term memory.
Memory Command Flow
memory search: Performs hybrid search with scoring breakdown crates/palyra-cli/src/commands/memory.rs#37-48.memory purge: Deletes memories by session, channel, or principal crates/palyra-cli/src/commands/memory.rs#144-156.- Sources: crates/palyra-cli/src/commands/memory.rs#25-73, crates/palyra-cli/src/proto/palyra.memory.v1.rs
Skills & Plugins
Manages the lifecycle of WASM-based skills.skills package build: Compiles askill.tomland WASM modules into a signed.palyra-skillartifact crates/palyra-cli/src/commands/skills.rs#5-18.skills package verify: Checks artifact signatures against theTrustStorecrates/palyra-cli/src/commands/skills.rs#106-126.skills list: Displays installed skills, their trust status, and eligibility crates/palyra-cli/src/output/skills.rs#41-54.
System & Diagnostics
Observability tools for the runtime.system heartbeat: Retrieves a JSON payload containing uptime, version, and transport state crates/palyra-cli/src/commands/system.rs#20-23.system event list: Fetches the tamper-evident system event log from theJournalStorecrates/palyra-cli/src/commands/system.rs#28-33.doctor: Runs a suite ofDoctorCheckunits to identify and repair configuration drift or connectivity issues crates/palyra-cli/src/args/tests.rs#86-100.
Backup & Recovery
Handles portable state management.backup create: Compresses the config, state root (SQLite DBs), and workspace into a ZIP archive with amanifest.jsoncrates/palyra-cli/src/commands/backup.rs#90-115.backup verify: Validates the SHA256 hashes of all entries in a backup archive crates/palyra-cli/src/commands/backup.rs#85.- Sources: crates/palyra-cli/src/commands/backup.rs#184-202
CLI Entity Mapping
This diagram maps CLI user-facing concepts to the internal code structures and protocols. Sources: crates/palyra-cli/src/lib.rs#15-59, crates/palyra-cli/src/commands/system.rs#16-21, crates/palyra-cli/src/commands/memory.rs#25-34Global Options & Environment
The CLI supports global flags that modify the behavior of all subcommands:| Option | Environment Variable | Description |
|---|---|---|
--config | PALYRA_CONFIG | Path to palyra.toml |
--profile | PALYRA_PROFILE | Selects a specific configuration profile |
--state-root | PALYRA_STATE_ROOT | Override for data/identity storage |
--output-format | N/A | text, json, or ndjson crates/palyra-cli/tests/help_snapshots/root-help-unix.txt#73-75 |
-v, -vv | RUST_LOG | Increases verbosity (debug, trace) crates/palyra-cli/tests/help_snapshots/root-help-unix.txt#66-67 |