setup), guided configuration and user integration (onboarding), and automated health maintenance and recovery (doctor).
Setup and Initialization
Thesetup command (aliased as init) is the primary entry point for bootstrapping a Palyra environment. It handles filesystem scaffolding, TLS certificate generation, and initial configuration file creation.
Implementation Details
The setup logic is driven byrun_setup_wizard in crates/palyra-cli/src/commands/operator_wizard.rs#239-251. It supports two primary modes:
- Local: Configures a daemon intended to run on the same machine as the CLI.
- Remote: Configures the CLI to connect to an existing gateway, often requiring TLS scaffold selection (e.g.,
self-signed) crates/palyra-cli/src/args/tests.rs#33-51.
Data Flow: Setup Execution
- Argument Parsing:
clapparsesInitModeArgandInitTlsScaffoldArgcrates/palyra-cli/src/args/mod.rs#77-77. - Wizard Invocation: If
--wizardis passed, it delegates to theWizardSessionengine crates/palyra-cli/src/commands/operator_wizard.rs#246-251. - Config Generation: The CLI generates a
RootFileConfigand writes it to the specified path, typically usingwrite_document_with_backupsto ensure safety crates/palyra-cli/src/lib.rs#95-98.
Onboarding Wizard
The onboarding system provides a high-level, interactive flow for users to configure their identity, model providers (e.g., OpenAI), and workspace settings.Wizard Engine
The wizard is implemented using a genericWizardBackend trait crates/palyra-cli/src/commands/operator_wizard.rs#10-15.
- Interactive: Uses
dialoguerfor terminal prompts whenIsTerminalis true. - Non-Interactive: Consumes
WizardOverridesArgto automate the flow in CI or scripted environments crates/palyra-cli/src/commands/operator_wizard.rs#32-61.
Mutation Plan
During the wizard, the CLI builds anOnboardingMutationPlan crates/palyra-cli/src/commands/operator_wizard.rs#168-194. This plan tracks:
- Auth Methods: API keys or admin tokens.
- Network Bindings: Ports for gRPC (default 7443) and QUIC (default 7444) crates/palyra-cli/src/lib.rs#150-155.
- Risk Events: Tracking potentially dangerous configurations (e.g., binding to
0.0.0.0).
Onboarding Flow Mapping
| Flow Name | Purpose | Key Entity |
|---|---|---|
quickstart | Default local setup | WizardFlowKind::Quickstart |
manual | Granular control over every field | WizardFlowKind::Manual |
remote | Connecting to a remote gateway | WizardFlowKind::Remote |
Doctor: Diagnostic and Recovery Pipeline
Thedoctor command is a comprehensive diagnostic tool that audits the toolchain, validates connectivity, and provides automated repair capabilities for corrupted states.
Diagnostic Pipeline
The pipeline executes a series of checks defined incrates/palyra-cli/src/commands/doctor/recovery.rs.
1. Toolchain & Config Audit
- Schema Validation: Checks if
palyra.tomlmatches the expectedRootFileConfigversion. - Registry Integrity: Audits
auth_profiles.tomlandaccess_registry.jsoncrates/palyra-cli/src/commands/doctor/recovery.rs#25-30.
2. Connectivity Probes
- Gateway Health: Executes a probe against the
/healthendpoint crates/palyra-cli/src/lib.rs#145-147. - Mtls/TLS Validation: Verifies certificate expiration and CA trust chains.
3. Access Registry Audit
- Principal Verification: Ensures the current CLI profile has valid permissions in the daemon’s
access_registry.
Recovery and Repair
If inconsistencies are found,doctor --repair generates a DoctorRepairPlan crates/palyra-cli/src/commands/doctor/recovery.rs#172-175.
Repair Actions (DoctorRepairKind):
MigrateConfigVersion: Automatically upgrades TOML schemas crates/palyra-cli/src/commands/doctor/recovery.rs#182-184.BackfillAccessRegistry: Restores missing permission entries crates/palyra-cli/src/commands/doctor/recovery.rs#234-236.RestoreConfigBackup: Reverts to a known good state from therecovery/runsdirectory crates/palyra-cli/src/commands/doctor/recovery.rs#23-24.
System Mapping: Doctor Logic to Code Entities
Sources: crates/palyra-cli/src/commands/doctor/recovery.rs#8-10, crates/palyra-cli/src/commands/doctor/recovery.rs#48-57, crates/palyra-cli/src/commands/doctor/recovery.rs#141-155, crates/palyra-cli/src/commands/doctor/recovery.rs#172-237Configuration Migration
Palyra handles configuration evolution through a migration layer inpalyra-common.
Data Flow: Config Loading
- Read: CLI locates config via
default_config_search_pathscrates/palyra-cli/src/lib.rs#101-101. - Parse & Migrate:
parse_document_with_migrationis called crates/palyra-cli/src/lib.rs#95-98. - Redaction: Before displaying or logging,
redact_secret_config_valuesis applied to prevent leaking API keys crates/palyra-cli/src/lib.rs#100-100.
Migration Lifecycle Diagram
Sources: crates/palyra-cli/src/lib.rs#95-105, crates/palyra-cli/src/commands/doctor/recovery.rs#182-188Diagnostic Handlers (Daemon-side)
While the CLI initiates diagnostics, the daemon provides the underlying data via theconsole_diagnostics_handler crates/palyra-daemon/src/transport/http/handlers/console/diagnostics.rs#6-9.
Key Diagnostic Payloads:
- Model Provider: Status of LLM connectivity and circuit breakers crates/palyra-daemon/src/transport/http/handlers/console/diagnostics.rs#22-27.
- Browserd: Health of the headless browser service crates/palyra-daemon/src/transport/http/handlers/console/diagnostics.rs#37-37.
- Memory: RAG maintenance status and SQLite vacuum schedules crates/palyra-daemon/src/transport/http/handlers/console/diagnostics.rs#54-56.