> ## Documentation Index
> Fetch the complete documentation index at: https://docs-code.palyra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Architecture and Core Commands

<details>
  <summary>Relevant source files</summary>

  The following files were used as context for generating this wiki page:

  * crates/palyra-cli/src/app/mod.rs
  * crates/palyra-cli/src/args/config.rs
  * crates/palyra-cli/src/args/daemon.rs
  * crates/palyra-cli/src/args/mod.rs
  * crates/palyra-cli/src/args/profile.rs
  * crates/palyra-cli/src/args/security.rs
  * crates/palyra-cli/src/args/tests.rs
  * crates/palyra-cli/src/commands/config.rs
  * crates/palyra-cli/src/commands/daemon.rs
  * crates/palyra-cli/src/commands/doctor.rs
  * crates/palyra-cli/src/commands/doctor/recovery.rs
  * crates/palyra-cli/src/commands/health.rs
  * crates/palyra-cli/src/commands/logs.rs
  * crates/palyra-cli/src/commands/mod.rs
  * crates/palyra-cli/src/commands/profile.rs
  * crates/palyra-cli/src/commands/security.rs
  * crates/palyra-cli/src/lib.rs
  * crates/palyra-cli/src/support/lifecycle.rs
  * crates/palyra-cli/src/support/service.rs
  * crates/palyra-cli/tests/cli\_parity\_matrix.toml
  * crates/palyra-cli/tests/cli\_parity\_report.md
  * crates/palyra-cli/tests/config\_mutation.rs
  * crates/palyra-cli/tests/config\_validate.rs
  * crates/palyra-cli/tests/daemon\_status.rs
  * crates/palyra-cli/tests/doctor\_cli.rs
  * crates/palyra-cli/tests/help\_snapshots.rs
  * crates/palyra-cli/tests/help\_snapshots/health-help.txt
  * crates/palyra-cli/tests/help\_snapshots/logs-help.txt
  * crates/palyra-cli/tests/help\_snapshots/profile-clone-help.txt
  * crates/palyra-cli/tests/help\_snapshots/profile-create-help.txt
  * crates/palyra-cli/tests/help\_snapshots/profile-export-help.txt
  * crates/palyra-cli/tests/help\_snapshots/profile-help.txt
  * crates/palyra-cli/tests/help\_snapshots/profile-import-help.txt
  * crates/palyra-cli/tests/help\_snapshots/root-help-unix.txt
  * crates/palyra-cli/tests/help\_snapshots/root-help-windows.txt
  * crates/palyra-cli/tests/logs\_cli.rs
  * crates/palyra-cli/tests/output\_format\_cli.rs
  * crates/palyra-cli/tests/pairing\_flow\.rs
  * crates/palyra-common/src/config\_system.rs
  * crates/palyra-common/src/lib.rs
  * crates/palyra-daemon/tests/health\_endpoint.rs
</details>

The `palyra-cli` crate provides the operator interface for managing both local and remote Palyra runtimes. It is built using a layered architecture that resolves configuration, handles profile-based guardrails, and dispatches commands to specialized modules.

### CLI Dispatch Lifecycle

The entry point for the CLI is the `run` function in `crates/palyra-cli/src/lib.rs`. It follows a deterministic lifecycle to ensure environment consistency before any command logic executes.

1. **Argument Parsing**: Uses `clap` to parse `argv` into the `Cli` struct [crates/palyra-cli/src/lib.rs#3-5](http://crates/palyra-cli/src/lib.rs#3-5).
2. **Context Resolution**: The `RootCommandContext` is initialized, resolving the active profile, state root, and configuration path [crates/palyra-cli/src/app/mod.rs#45-58](http://crates/palyra-cli/src/app/mod.rs#45-58).
3. **Guardrail Validation**: If a command is executed with `--expect-profile`, the CLI verifies the resolved profile matches before proceeding [crates/palyra-cli/src/args/mod.rs#79-80](http://crates/palyra-cli/src/args/mod.rs#79-80).
4. **Command Dispatch**: The `CliCommand` enum fans out to specific modules under `commands/` [crates/palyra-cli/src/lib.rs#115-130](http://crates/palyra-cli/src/lib.rs#115-130).

#### CLI Dispatch Flow

This diagram illustrates the transition from the OS entry point to the internal command handlers.

```mermaid theme={null}
graph TD
    subgraph "Natural Language Space"
        User["Operator Command"]
    end

    subgraph "Code Entity Space"
        main["main()"]
        Cli["cli::Cli (Parser)"]
        RCC["RootCommandContext"]
        Dispatch["run_cli() Matcher"]
        CmdHandler["commands::*::run_*"]

        User -->|palyra --profile prod gateway status| main
        main --> Cli
        Cli --> RCC
        RCC --> Dispatch
        Dispatch -->|GatewayCommand::Status| CmdHandler
    end
```

Sources: [crates/palyra-cli/src/lib.rs#1-15](http://crates/palyra-cli/src/lib.rs#1-15), [crates/palyra-cli/src/app/mod.rs#41-58](http://crates/palyra-cli/src/app/mod.rs#41-58)

***

### RootContext and Global Options

The `RootCommandContext` is the source of truth for every CLI invocation. It encapsulates formatting, logging, and connection defaults [crates/palyra-cli/src/app/mod.rs#45-58](http://crates/palyra-cli/src/app/mod.rs#45-58).

| Option            | Code Reference            | Description                                                                                                                                              |
| :---------------- | :------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--profile`       | `RootOptions::profile`    | Selects a named connection profile from `cli/profiles.toml` [crates/palyra-cli/src/app/mod.rs#139-147](http://crates/palyra-cli/src/app/mod.rs#139-147). |
| `--config`        | `RootOptions::config`     | Explicit path to `palyra.toml` [crates/palyra-cli/src/app/mod.rs#49](http://crates/palyra-cli/src/app/mod.rs#49).                                        |
| `--state-root`    | `RootOptions::state_root` | Directory for durable state (logs, DBs, keys) [crates/palyra-cli/src/app/mod.rs#46-48](http://crates/palyra-cli/src/app/mod.rs#46-48).                   |
| `--output-format` | `OutputFormatArg`         | Supports `text`, `json`, and `ndjson` [crates/palyra-cli/src/args/mod.rs#97-102](http://crates/palyra-cli/src/args/mod.rs#97-102).                       |

Sources: [crates/palyra-cli/src/app/mod.rs#41-70](http://crates/palyra-cli/src/app/mod.rs#41-70), [crates/palyra-cli/src/args/mod.rs#75-113](http://crates/palyra-cli/src/args/mod.rs#75-113)

***

### Profile Guardrails and Strict Mode

Palyra implements "Profile Guardrails" to prevent accidental operations on production environments. Profiles are stored in a registry located at `cli/profiles.toml` within the state root [crates/palyra-cli/src/app/mod.rs#139-147](http://crates/palyra-cli/src/app/mod.rs#139-147).

* **Strict Mode**: If a profile has `strict_mode: true`, destructive actions (like `reset`) require the `--allow-strict-profile-actions` flag [crates/palyra-cli/src/app/mod.rs#168](http://crates/palyra-cli/src/app/mod.rs#168), [crates/palyra-cli/src/args/mod.rs#112-113](http://crates/palyra-cli/src/args/mod.rs#112-113).
* **Expect Profile**: The `--expect-profile <NAME>` flag forces the CLI to exit if the resolved profile doesn't match the expected name [crates/palyra-cli/src/args/mod.rs#79-80](http://crates/palyra-cli/src/args/mod.rs#79-80).

Sources: [crates/palyra-cli/src/app/mod.rs#151-173](http://crates/palyra-cli/src/app/mod.rs#151-173), [crates/palyra-cli/src/args/mod.rs#109-113](http://crates/palyra-cli/src/args/mod.rs#109-113)

***

### Gateway and Daemon Commands

The `gateway` (aliased as `daemon`) family provides administrative control over the `palyrad` process. It communicates via the Admin HTTP API and gRPC surfaces [crates/palyra-cli/src/commands/daemon.rs#3-5](http://crates/palyra-cli/src/commands/daemon.rs#3-5).

* **Status**: Aggregates health, transport, and admin status [crates/palyra-cli/src/commands/daemon.rs#11-12](http://crates/palyra-cli/src/commands/daemon.rs#11-12).
* **Health**: Performs narrow liveness/readiness probes [crates/palyra-cli/src/commands/health.rs#1-10](http://crates/palyra-cli/src/commands/health.rs#1-10).
* **Logs**: Tails the SQLite-backed journal [crates/palyra-cli/src/commands/logs.rs#1-5](http://crates/palyra-cli/src/commands/logs.rs#1-5).
* **Service Management**: Handles platform-specific service installation (systemd, launchd, Windows Tasks) via the `GatewayServiceMetadata` record [crates/palyra-cli/src/support/service.rs#25-39](http://crates/palyra-cli/src/support/service.rs#25-39).

#### Service Lifecycle Management

```mermaid theme={null}
graph TD
    subgraph "Code Entities"
        CLI["palyra gateway install"]
        GSM["GatewayServiceMetadata"]
        JSON["gateway-service.json"]
        Platform["Platform Manager (systemd/launchd/TaskSchd)"]
    end

    CLI -->|Install Request| Platform
    CLI -->|Persist| GSM
    GSM -->|Serialize| JSON
    JSON -.->|Source of Truth| CLI
```

Sources: [crates/palyra-cli/src/support/service.rs#1-40](http://crates/palyra-cli/src/support/service.rs#1-40), [crates/palyra-cli/src/commands/daemon.rs#1-10](http://crates/palyra-cli/src/commands/daemon.rs#1-10)

***

### The Doctor Diagnostic System

The `doctor` command is a comprehensive diagnostic engine that identifies and repairs environment issues. It operates on a "Check and Report" model [crates/palyra-cli/src/commands/doctor.rs#1-10](http://crates/palyra-cli/src/commands/doctor.rs#1-10).

1. **Check Discovery**: Aggregates checks for filesystem permissions, configuration validity, network connectivity, and security posture [crates/palyra-cli/src/commands/security.rs#118-123](http://crates/palyra-cli/src/commands/security.rs#118-123).
2. **Snapshot Generation**: Captures the current state into a `HealthResponse` [crates/palyra-common/src/health.rs#45-48](http://crates/palyra-common/src/health.rs#45-48).
3. **Repair Logic**: Provides remediation steps or executes automatic repairs when the `--repair` flag is present [crates/palyra-cli/src/args/mod.rs#42](http://crates/palyra-cli/src/args/mod.rs#42).

The `security audit` command extends the Doctor system by ranking findings into `blocking`, `warning`, and `info` severities [crates/palyra-cli/src/commands/security.rs#23-48](http://crates/palyra-cli/src/commands/security.rs#23-48).

Sources: [crates/palyra-cli/src/commands/doctor.rs#1-10](http://crates/palyra-cli/src/commands/doctor.rs#1-10), [crates/palyra-cli/src/commands/security.rs#115-163](http://crates/palyra-cli/src/commands/security.rs#115-163), [crates/palyra-common/src/health.rs#45-48](http://crates/palyra-common/src/health.rs#45-48)

***

### Config and State Commands

The CLI provides tools to inspect and mutate the local environment without manual file editing.

* **Config Validate**: Checks `palyra.toml` against the `RootFileConfig` schema [crates/palyra-cli/tests/config\_validate.rs#37-49](http://crates/palyra-cli/tests/config_validate.rs#37-49), [crates/palyra-common/src/daemon\_config\_schema.rs#142-145](http://crates/palyra-common/src/daemon_config_schema.rs#142-145).
* **Config Set/Unset**: Mutates TOML values at specific paths using the `config_system` utilities [crates/palyra-common/src/config\_system.rs#136-141](http://crates/palyra-common/src/config_system.rs#136-141).
* **State Inspect**: Analyzes the state root for database integrity and disk usage [crates/palyra-cli/src/args/mod.rs#141](http://crates/palyra-cli/src/args/mod.rs#141).

Sources: [crates/palyra-cli/src/commands/config.rs#1-10](http://crates/palyra-cli/src/commands/config.rs#1-10), [crates/palyra-common/src/config\_system.rs#136-141](http://crates/palyra-common/src/config_system.rs#136-141), [crates/palyra-cli/tests/config\_validate.rs#1-10](http://crates/palyra-cli/tests/config_validate.rs#1-10)