palyra-cli crate provides the operator interface for managing both local and remote Palyra runtimes. It is built using a layered architecture that resolves configuration, handles profile-based guardrails, and dispatches commands to specialized modules.
CLI Dispatch Lifecycle
The entry point for the CLI is therun function in crates/palyra-cli/src/lib.rs. It follows a deterministic lifecycle to ensure environment consistency before any command logic executes.
- Argument Parsing: Uses
clapto parseargvinto theClistruct crates/palyra-cli/src/lib.rs#3-5. - Context Resolution: The
RootCommandContextis initialized, resolving the active profile, state root, and configuration path crates/palyra-cli/src/app/mod.rs#45-58. - Guardrail Validation: If a command is executed with
--expect-profile, the CLI verifies the resolved profile matches before proceeding crates/palyra-cli/src/args/mod.rs#79-80. - Command Dispatch: The
CliCommandenum fans out to specific modules undercommands/crates/palyra-cli/src/lib.rs#115-130.
CLI Dispatch Flow
This diagram illustrates the transition from the OS entry point to the internal command handlers. Sources: crates/palyra-cli/src/lib.rs#1-15, crates/palyra-cli/src/app/mod.rs#41-58RootContext and Global Options
TheRootCommandContext is the source of truth for every CLI invocation. It encapsulates formatting, logging, and connection defaults crates/palyra-cli/src/app/mod.rs#45-58.
| Option | Code Reference | Description |
|---|---|---|
--profile | RootOptions::profile | Selects a named connection profile from cli/profiles.toml crates/palyra-cli/src/app/mod.rs#139-147. |
--config | RootOptions::config | Explicit path to palyra.toml crates/palyra-cli/src/app/mod.rs#49. |
--state-root | RootOptions::state_root | Directory for durable state (logs, DBs, keys) crates/palyra-cli/src/app/mod.rs#46-48. |
--output-format | OutputFormatArg | Supports text, json, and ndjson crates/palyra-cli/src/args/mod.rs#97-102. |
Profile Guardrails and Strict Mode
Palyra implements “Profile Guardrails” to prevent accidental operations on production environments. Profiles are stored in a registry located atcli/profiles.toml within the state root crates/palyra-cli/src/app/mod.rs#139-147.
- Strict Mode: If a profile has
strict_mode: true, destructive actions (likereset) require the--allow-strict-profile-actionsflag crates/palyra-cli/src/app/mod.rs#168, crates/palyra-cli/src/args/mod.rs#112-113. - Expect Profile: The
--expect-profile <NAME>flag forces the CLI to exit if the resolved profile doesn’t match the expected name crates/palyra-cli/src/args/mod.rs#79-80.
Gateway and Daemon Commands
Thegateway (aliased as daemon) family provides administrative control over the palyrad process. It communicates via the Admin HTTP API and gRPC surfaces crates/palyra-cli/src/commands/daemon.rs#3-5.
- Status: Aggregates health, transport, and admin status crates/palyra-cli/src/commands/daemon.rs#11-12.
- Health: Performs narrow liveness/readiness probes crates/palyra-cli/src/commands/health.rs#1-10.
- Logs: Tails the SQLite-backed journal crates/palyra-cli/src/commands/logs.rs#1-5.
- Service Management: Handles platform-specific service installation (systemd, launchd, Windows Tasks) via the
GatewayServiceMetadatarecord crates/palyra-cli/src/support/service.rs#25-39.
Service Lifecycle Management
Sources: crates/palyra-cli/src/support/service.rs#1-40, crates/palyra-cli/src/commands/daemon.rs#1-10The Doctor Diagnostic System
Thedoctor command is a comprehensive diagnostic engine that identifies and repairs environment issues. It operates on a “Check and Report” model crates/palyra-cli/src/commands/doctor.rs#1-10.
- Check Discovery: Aggregates checks for filesystem permissions, configuration validity, network connectivity, and security posture crates/palyra-cli/src/commands/security.rs#118-123.
- Snapshot Generation: Captures the current state into a
HealthResponsecrates/palyra-common/src/health.rs#45-48. - Repair Logic: Provides remediation steps or executes automatic repairs when the
--repairflag is present crates/palyra-cli/src/args/mod.rs#42.
security audit command extends the Doctor system by ranking findings into blocking, warning, and info severities crates/palyra-cli/src/commands/security.rs#23-48.
Sources: crates/palyra-cli/src/commands/doctor.rs#1-10, crates/palyra-cli/src/commands/security.rs#115-163, crates/palyra-common/src/health.rs#45-48
Config and State Commands
The CLI provides tools to inspect and mutate the local environment without manual file editing.- Config Validate: Checks
palyra.tomlagainst theRootFileConfigschema crates/palyra-cli/tests/config_validate.rs#37-49, crates/palyra-common/src/daemon_config_schema.rs#142-145. - Config Set/Unset: Mutates TOML values at specific paths using the
config_systemutilities crates/palyra-common/src/config_system.rs#136-141. - State Inspect: Analyzes the state root for database integrity and disk usage crates/palyra-cli/src/args/mod.rs#141.