palyra CLI and its built-in automation.
Environment Bootstrapping
The Palyra repository utilizes a set of bootstrap scripts to ensure consistent toolchains across different operating systems. These scripts prepare the environment forcargo and the palyra CLI.
The Bootstrap Process
- Toolchain Verification: Checks for
rustc,cargo, and required LLVM/Clang dependencies for Wasm compilation. - Dependency Installation: Installs system-level dependencies (e.g.,
sqlite3,openssl,pkg-config). - CLI Compilation: Builds the
palyraCLI binary from source.
Initialization with palyra setup
The palyra setup command is the primary entry point for configuring a new installation. It supports both automated and interactive “Wizard” modes to generate the necessary configuration files and directory structures.
Setup Modes and Flows
The setup process is governed by theInitModeArg and WizardOverridesArg structures crates/palyra-cli/src/commands/setup.rs#4-10.
| Flow | Description | Key Arguments |
|---|---|---|
| Quickstart | Minimal interaction; sets up a local daemon with OpenAI/Anthropic defaults. | --flow quickstart --wizard |
| Manual | Step-by-step configuration of TLS, ports, and provider settings. | --flow manual --wizard |
| Remote | Configures the CLI to connect to an existing remote gateway. | --mode remote --flow remote |
The Onboarding Wizard
The Wizard implementation uses aWizardSession that interacts with a WizardBackend to handle user input crates/palyra-cli/src/commands/wizard.rs#155-161. It supports various step types:
StepKind::Select: For choosing providers or bind profiles crates/palyra-cli/src/commands/wizard.rs#13.StepKind::SensitiveText: For API keys and tokens (redacted in logs) crates/palyra-cli/src/commands/wizard.rs#101.StepKind::Confirm: For risk acknowledgments crates/palyra-cli/src/commands/wizard.rs#15.
Wizard Logic Flow
The following diagram illustrates the flow from the CLI command to the generation of configuration. Setup Wizard Data Flow Sources: crates/palyra-cli/src/commands/setup.rs#3-55, crates/palyra-cli/src/commands/wizard.rs#147-157, crates/palyra-cli/src/commands/configure.rs#6-78Profile Management
Palyra uses a profile system to manage multiple environments (e.g.,local, staging, prod) within the same installation. Profiles are stored in a CliProfilesDocument located at cli/profiles.toml within the state root crates/palyra-cli/src/app/mod.rs#82-89.
Profile Structure
EachCliConnectionProfile tracks:
- Paths:
config_pathandstate_rootcrates/palyra-cli/src/app/mod.rs#94-95. - Connection:
daemon_urlandgrpc_urlcrates/palyra-cli/src/app/mod.rs#96-97. - Security:
admin_token_env,risk_level, andstrict_modecrates/palyra-cli/src/app/mod.rs#99-108.
Profile Commands
palyra profile create <name>: Initializes a new isolated environment crates/palyra-cli/src/args/profile.rs#61-97.palyra profile use <name>: Switches the active context by updating thedefault_profilein the registry crates/palyra-cli/src/args/profile.rs#143-147.palyra profile export: Generates aPortableProfileBundle(optionally encrypted with AES-256-GCM) for sharing environments crates/palyra-cli/src/commands/profile.rs#141-149.
Environment Verification with palyra doctor
The doctor command provides a comprehensive diagnostic and repair suite. It identifies inconsistencies in configuration, state, and connectivity.
Diagnostic Categories
Thedoctor command executes a series of DoctorRepairStep checks crates/palyra-cli/src/commands/doctor/recovery.rs#105-118:
- Toolchain: Verifies required binaries and versions.
- Configuration: Checks for schema mismatches or missing files crates/palyra-cli/src/commands/doctor/recovery.rs#179-191.
- Connectivity: Tests gRPC and HTTP gateway reachability crates/palyra-cli/src/commands/doctor/recovery.rs#206-208.
- Security: Audits the
AccessRegistryandAuthProfileRegistrycrates/palyra-cli/src/commands/doctor/recovery.rs#195-205.
Repair and Rollback
When run with--repair, the doctor generates a DoctorRepairPlan crates/palyra-cli/src/commands/doctor/recovery.rs#172-176.
- Backups: Before applying changes, it creates backups of sensitive files (e.g.,
profiles.toml.bak.N) crates/palyra-cli/tests/wizard_cli.rs#58-62. - Rollback: Every repair run generates a
run_id. Users can revert changes usingpalyra doctor --rollback-run <run_id>crates/palyra-cli/src/commands/doctor/recovery.rs#56-57.
Summary of Setup Commands
| Command | Purpose |
|---|---|
palyra setup --wizard | Guided first-time installation and provider configuration. |
palyra profile list | View all configured environments and the active profile. |
palyra profile use <name> | Switch the active CLI context. |
palyra doctor | Run diagnostics on the current environment. |
palyra doctor --repair | Interactively fix identified issues and misconfigurations. |