palyra-cli crate, leveraging a unified wizard engine to guide users through complex setup tasks while ensuring system integrity through the “Doctor” diagnostic suite.
1. Doctor Diagnostic Pipeline
Thedoctor command serves as the primary diagnostic and repair tool for Palyra installations. It evaluates the health of the toolchain, connectivity, permissions, and security configurations.
1.1 Diagnostic Logic and Execution
The core logic resides incrates/palyra-cli/src/commands/doctor/recovery.rs. The doctor executes in several modes defined by DoctorExecutionMode: Diagnostics, RepairPreview, RepairApply, RollbackPreview, and RollbackApply crates/palyra-cli/src/commands/doctor/recovery.rs#68-74.
Key diagnostic areas include:
- Configuration Integrity: Checks for missing or malformed
palyra.tomlfiles and version mismatches crates/palyra-cli/src/commands/doctor/recovery.rs#179-191. - Auth & Identity: Validates the
auth_profiles.tomlregistry and ensures browser authentication tokens are valid crates/palyra-cli/src/commands/doctor/recovery.rs#192-205. - Runtime State: Inspects the node runtime (
node-runtime.v1.json) and routine definitions crates/palyra-cli/src/commands/doctor/recovery.rs#220-233. - Security & Permissions: Evaluates the
access_registry.jsonand ensures sensitive directories (like the vault) have correct permissions crates/palyra-cli/src/commands/doctor/recovery.rs#234-236.
1.2 Automated Repair & Rollback
When run with the--repair flag, the doctor generates a DoctorRepairPlan crates/palyra-cli/src/commands/doctor/recovery.rs#172-176. This plan consists of multiple DoctorRepairStep objects that describe the problem, the impact, and the proposed fix crates/palyra-cli/src/commands/doctor/recovery.rs#105-118.
To ensure safety, every repair operation that modifies the filesystem creates a backup entry in a DoctorRecoveryManifest crates/palyra-cli/src/commands/doctor/recovery.rs#141-155. This allows the user to trigger a rollback using a specific run_id if a repair causes regressions crates/palyra-cli/src/commands/doctor/recovery.rs#130-138.
Doctor Execution Flow
Sources: crates/palyra-cli/src/commands/doctor.rs#8-10, crates/palyra-cli/src/commands/doctor/recovery.rs#77-83, crates/palyra-cli/src/commands/doctor/recovery.rs#141-169.
2. Setup & Onboarding Wizard
Thesetup (aliased as init) command is the entry point for new users. It handles the initial generation of configuration files, identity stores, and vault initialization.
2.1 Onboarding Flows
The wizard supports three primary flows defined inOnboardingFlowArg crates/palyra-cli/src/args/onboarding.rs#6-10:
- Quickstart: A streamlined path for local evaluation, defaulting to
gpt-4o-miniorclaude-3-5-sonnet-latestcrates/palyra-cli/src/commands/operator_wizard.rs#18-21. - Manual: Allows granular control over ports, TLS certificates, and bind profiles (e.g.,
LoopbackOnlyvsPublicTls) crates/palyra-cli/src/args/onboarding.rs#21-24. - Remote: Configures the CLI to connect to an existing remote gateway, including server certificate pinning and SSH tunnel setup crates/palyra-cli/src/commands/operator_wizard.rs#68-70.
2.2 Implementation Details
The onboarding process is driven byrun_onboarding_wizard, which consumes an OnboardingWizardRequest crates/palyra-cli/src/commands/operator_wizard.rs#24-30. It generates an OnboardingMutationPlan that tracks intended changes to the system crates/palyra-cli/src/commands/operator_wizard.rs#169-195.
The wizard uses a WizardBackend trait to support both InteractiveWizardBackend (TTY-based prompts) and NonInteractiveWizardBackend (automated via CLI flags) crates/palyra-cli/src/commands/operator_wizard.rs#10-13.
Onboarding Data Flow
Sources: crates/palyra-cli/src/commands/operator_wizard.rs#240-248, crates/palyra-cli/src/args/onboarding.rs#34-89, crates/palyra-cli/src/commands/operator_wizard.rs#169-195.
3. Configuration Wizard (configure)
The configure command provides a safe way to modify an existing installation by reusing the onboarding wizard’s logic. It targets specific ConfigureSectionArg areas like workspace, auth-model, gateway, or skills crates/palyra-cli/tests/help_snapshots/configure-help.txt#8-9.
3.1 Safety and Backups
Unlike direct manual edits topalyra.toml, the configure command:
- Validates Changes: Runs pre-flight checks to ensure new ports are available or API keys are valid.
- Automated Backups: Maintains up to 5 historical backups of the configuration file crates/palyra-cli/src/commands/operator_wizard.rs#17.
- Summary Reports: Generates a
ConfigureSummaryindicating which sections changed and whether a daemon restart is required crates/palyra-cli/src/commands/operator_wizard.rs#229-238.
3.2 Configuration Summary Structure
| Field | Description |
|---|---|
changed_sections | List of TOML tables modified during the session. |
restart_required | Boolean flag indicating if palyrad must be restarted to apply changes. |
follow_up_checks | Specific doctor checks recommended after the update. |
warnings | Non-fatal issues (e.g., deprecated keys). |
4. Integration with Console API
The Palyra Daemon (palyrad) exposes endpoints to monitor and manage recovery jobs via the Web Console. These are defined in the Axum transport layer.
- List Jobs:
console_doctor_jobs_list_handlerretrieves a paginated list of recovery attempts crates/palyra-daemon/src/transport/http/handlers/console/doctor.rs#3-18. - Create Job:
console_doctor_job_create_handlerinitiates a new diagnostic/repair job from the UI crates/palyra-daemon/src/transport/http/handlers/console/doctor.rs#20-28. - Get Job Details:
console_doctor_job_get_handlerprovides the status and logs for a specificjob_idcrates/palyra-daemon/src/transport/http/handlers/console/doctor.rs#30-46.