Skip to main content
The Palyra CLI uses a sophisticated profile management system to orchestrate connections across diverse environments (local, staging, production). This system encapsulates connection metadata, security guardrails, and environment-specific configurations into named Profiles. These profiles are resolved into a RootCommandContext during CLI initialization, which then governs the behavior of all subsequent commands.

​
Connection Profiles

A Profile is a named set of configuration parameters that defines how the CLI communicates with a palyrad gateway. Profiles are stored in a TOML registry, typically located at cli/profiles.toml within the state root crates/palyra-cli/src/app/mod.rs#26-26.

​
Profile Structure

The CliConnectionProfile struct defines the schema for these entries:
FieldDescription
daemon_urlThe HTTP URL of the gateway (e.g., http://127.0.0.1:7142) crates/palyra-cli/src/app/mod.rs#96-96.
grpc_urlThe gRPC endpoint for high-performance RPC calls crates/palyra-cli/src/app/mod.rs#97-97.
admin_token_envEnvironment variable name holding the administrative bearer token crates/palyra-cli/src/app/mod.rs#99-99.
risk_levelCategorization of the environment (e.g., low, elevated, high) crates/palyra-cli/src/app/mod.rs#106-106.
strict_modeBoolean flag enabling aggressive safety guardrails crates/palyra-cli/src/app/mod.rs#108-108.
state_rootCustom filesystem path for profile-specific data crates/palyra-cli/src/app/mod.rs#95-95.

​
Profile Data Flow

The following diagram illustrates how a profile is selected and transformed into an active runtime context. Profile Resolution and Context Injection Sources: crates/palyra-cli/src/app/mod.rs#145-161, crates/palyra-cli/src/lib.rs#76-89

​
Root Context Initialization

The app::install_root_context function is the entry point for CLI lifecycle management crates/palyra-cli/src/app/mod.rs#151-157. It consumes RootOptions (global flags like --profile, --config, and --state-root) and produces a RootCommandContext.

​
Initialization Logic

  1. Profile Selection: If --profile is provided, it loads that specific profile from the registry. If not, it checks the PALYRA_CLI_PROFILE environment variable, falling back to the default_profile defined in profiles.toml crates/palyra-cli/src/app/mod.rs#24-26.
  2. Configuration Merging: It merges profile-specific URLs and tokens with any command-line overrides (e.g., --daemon-url).
  3. Trace ID Generation: A unique ULID trace_id is generated for the context to provide request correlation across gateway logs crates/palyra-cli/src/app/mod.rs#41-41.
  4. Global Storage: The resulting context is stored in a OnceLock<Mutex<Option<RootCommandContext>>> crates/palyra-cli/src/app/mod.rs#145-145, allowing any downstream command to access it via current_root_context() crates/palyra-cli/src/app/mod.rs#159-161.
Sources: crates/palyra-cli/src/app/mod.rs#151-161, crates/palyra-cli/src/app/mod.rs#34-45

​
Guardrails and Strict Mode

Palyra implements “Guardrails” to prevent accidental destructive actions on sensitive environments. This is controlled by the risk_level and strict_mode fields.

​
Risk Levels

Profiles can be assigned one of the following risk levels crates/palyra-cli/src/args/profile.rs#101-101:
  • Low: Local development or ephemeral sandboxes.
  • Elevated: Shared staging or QA environments.
  • High: Production clusters or sensitive data environments.

​
Strict Mode Enforcement

When strict_mode is enabled (standard for high risk profiles), the CLI activates the enforce_profile_guardrails mechanism. This results in:
  1. Mandatory Confirmation: Destructive commands (like reset or delete) require the --yes flag AND the --allow-strict-profile-actions global flag crates/palyra-cli/src/args/mod.rs#135-135.
  2. Profile Expectation Check: Users can pass --expect-profile <NAME> to ensure the command only executes if the active profile matches the expectation, preventing “wrong terminal” accidents crates/palyra-cli/tests/help_snapshots/root-help-unix.txt#65-65.
  3. Credential Isolation: Strict profiles often use admin_token_env instead of storing tokens in plaintext, forcing the use of secure environment secret injection crates/palyra-cli/src/app/mod.rs#99-99.
Sources: crates/palyra-cli/src/app/mod.rs#188-194, crates/palyra-cli/src/commands/profile.rs#42-43

​
Profile Lifecycle Management

The palyra profile command family manages the registry crates/palyra-cli/src/commands/profile.rs#215-216.

​
Clone, Import, and Export

Palyra supports portable profile bundles for team onboarding and environment synchronization.

​
Implementation Detail: Portability

Sources: crates/palyra-cli/src/commands/profile.rs#107-161

​
Implementation Mapping

System ConceptCode EntityFile Location
Profile RegistryCliProfilesDocumentcrates/palyra-cli/src/app/mod.rs#84-89
Active ContextRootCommandContextcrates/palyra-cli/src/app/mod.rs#34-45
Global State StorageROOT_CONTEXTcrates/palyra-cli/src/app/mod.rs#145-145
Guardrail LogicRootCommandContext::allow_strict_profile_actionscrates/palyra-cli/src/app/mod.rs#192-194
Profile CLIrun_profilecrates/palyra-cli/src/commands/profile.rs#215-216
Encryption ParamsPROFILE_EXPORT_PBKDF2_ITERATIONScrates/palyra-cli/src/commands/profile.rs#27-27
Sources: crates/palyra-cli/src/app/mod.rs, crates/palyra-cli/src/commands/profile.rs