Skip to main content
The Palyra CLI is built around a multi-stage boot sequence that resolves the execution environment before any command logic is dispatched. This environment is encapsulated in the RootCommandContext, which manages profile resolution, state isolation, and connection parameters for the daemon.

​
RootCommandContext and Boot Sequence

The RootCommandContext is the central authority for the CLI’s operational state crates/palyra-cli/src/app/mod.rs#34-46. It is initialized during the CLI’s startup phase and stored in a global OnceLock crates/palyra-cli/src/app/mod.rs#146-150.

​
Multi-Stage Boot Sequence

  1. Argument Parsing: The CLI uses clap to parse RootOptions, which include global overrides like --profile, --config, and --state-root crates/palyra-cli/src/args/mod.rs.
  2. Context Installation: The install_root_context function is called crates/palyra-cli/src/app/mod.rs#152-158, which triggers build_root_context.
  3. Profile Resolution: The system looks for a profiles.toml file to determine the active profile crates/palyra-cli/src/app/mod.rs#26-31.
  4. State/Config Mapping: Based on the profile or global flags, the state_root and config_path are finalized crates/palyra-cli/src/app/mod.rs#35-37.
  5. Connection Setup: The context resolves the AgentConnection (gRPC/HTTP URLs and credentials) required to talk to the palyrad daemon crates/palyra-cli/src/app/mod.rs#216-223.

​
CLI Boot Data Flow

The following diagram illustrates how raw inputs are transformed into a validated RootCommandContext. Title: CLI Initialization and Context Resolution Sources: crates/palyra-cli/src/app/mod.rs#34-158, crates/palyra-cli/src/args/mod.rs

​
Profile Resolution (profiles.toml)

Profiles allow users to switch between different daemon instances (e.g., local vs. remote) and isolated environments. Profiles are stored in a TOML registry located at cli/profiles.toml within the CLI state root crates/palyra-cli/src/app/mod.rs#24-31.

​
Profile Configuration Structure

The CliConnectionProfile struct defines the attributes of a profile crates/palyra-cli/src/app/mod.rs#94-114:
FieldDescription
daemon_urlThe base HTTP URL for the daemon (e.g., http://127.0.0.1:7142).
grpc_urlThe gRPC endpoint for the gateway.
state_rootIsolated directory for logs, identity, and temporary files.
strict_modeEnables guardrails that prevent accidental destructive actions.
risk_levelMetadata indicating the sensitivity of the environment (Low, High, etc.).

​
Connection Overrides

Connection parameters are resolved using a hierarchy of precedence crates/palyra-cli/src/app/mod.rs#216-240:
  1. Explicit CLI arguments (e.g., --daemon-url).
  2. Environment variables like PALYRA_DAEMON_URL crates/palyra-cli/src/lib.rs#160.
  3. Active profile settings in profiles.toml.
  4. Hardcoded defaults (e.g., 127.0.0.1:7142) crates/palyra-cli/src/lib.rs#151-160.
Sources: crates/palyra-cli/src/app/mod.rs#85-114, crates/palyra-cli/src/lib.rs#151-160

​
State Root and Isolation

Palyra enforces strict isolation via the state_root. This directory contains all per-profile data, including: When a profile defines a state_root, the CLI automatically switches its internal file lookups to that path, ensuring that a “Production” profile cannot accidentally use “Development” credentials. Title: Profile Isolation and Resource Mapping Sources: crates/palyra-cli/src/app/mod.rs#28-31, crates/palyra-cli/src/lib.rs#123-126

​
Strict Mode and Guardrails

To prevent accidental damage in high-risk environments, profiles can enable strict_mode crates/palyra-cli/src/app/mod.rs#109.

​
Guardrail Mechanisms

  • Destructive Actions: Commands like profile delete or secrets unset require the --allow-strict-profile-actions flag if the active profile is in strict mode crates/palyra-cli/src/app/mod.rs#45.
  • Risk Awareness: The risk_level field (Low, Elevated, High, Critical) is used by the TUI and CLI to colorize output and provide additional confirmation prompts crates/palyra-cli/src/app/mod.rs#107.
  • Profile Mismatch Protection: The CLI can be configured to fail if the --expect-profile argument does not match the resolved active profile.
Sources: crates/palyra-cli/src/app/mod.rs#107-110, crates/palyra-cli/src/app/mod.rs#196-198

​
Implementation Reference

​
Key Classes and Functions

EntityFilePurpose
RootCommandContextcrates/palyra-cli/src/app/mod.rs#34Holds the resolved CLI environment.
CliProfilesDocumentcrates/palyra-cli/src/app/mod.rs#85The deserialized structure of profiles.toml.
AgentConnectioncrates/palyra-cli/src/lib.rs#221Connection details for gRPC and HTTP APIs.
resolve_grpc_urlcrates/palyra-cli/src/app/mod.rs#216Logic for merging profile and override URLs.
install_root_contextcrates/palyra-cli/src/app/mod.rs#152Entry point for CLI initialization.

​
Configuration Precedence

The resolution logic in build_root_context follows this order:
  1. RootOptions passed via command line.
  2. Environment variables (e.g., PALYRA_STATE_ROOT).
  3. CliConnectionProfile fields from profiles.toml.
  4. Platform-specific default paths (via palyra_common).
Sources: crates/palyra-cli/src/app/mod.rs#34-158, crates/palyra-cli/src/lib.rs#151-160