> ## 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 (palyra-cli)

<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/mod.rs
  * crates/palyra-cli/src/args/profile.rs
  * crates/palyra-cli/src/args/tests.rs
  * crates/palyra-cli/src/commands/mod.rs
  * crates/palyra-cli/src/commands/profile.rs
  * crates/palyra-cli/src/lib.rs
  * crates/palyra-cli/tests/cli\_parity\_matrix.toml
  * crates/palyra-cli/tests/cli\_parity\_report.md
  * crates/palyra-cli/tests/help\_snapshots.rs
  * 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
</details>

The `palyra-cli` crate provides the primary command-line interface for operators to manage both local and remote Palyra runtimes [crates/palyra-cli/src/lib.rs#1-5](http://crates/palyra-cli/src/lib.rs#1-5). It serves as a unified entry point for administrative tasks, agent interaction, and system diagnostics.

The CLI is built using a strict output contract where all user-visible strings and JSON field names are pinned by parity and snapshot tests [crates/palyra-cli/src/lib.rs#23-25](http://crates/palyra-cli/src/lib.rs#23-25).

## Architecture Overview

The CLI follows a dispatch lifecycle managed by the `RootCommandContext`. It parses global options to establish the environment before executing specific subcommand logic.

### CLI Execution Lifecycle

The following diagram illustrates how a command moves from the shell into the internal execution logic.

**CLI Dispatch Pipeline**

```mermaid theme={null}
graph TD
    subgraph "Natural Language Space"
        A["Shell Command (e.g., 'palyra --profile prod gateway status')"]
    end

    subgraph "Code Entity Space"
        B["args::Cli (Parser)"]
        C["app::RootCommandContext"]
        D["commands::*::run_* (Handlers)"]
        E["output::print_json / print_text"]
    end

    A -->|"argv"| B
    B -->|"RootOptions"| C
    C -->|"Context + Subcommand"| D
    D -->|"Payload"| E
```

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

### Key Components

| Component              | Role                                                            | Code Reference                                                                              |
| :--------------------- | :-------------------------------------------------------------- | :------------------------------------------------------------------------------------------ |
| `Cli`                  | Top-level `clap` derive structure for argument parsing.         | [crates/palyra-cli/src/args/mod.rs#12](http://crates/palyra-cli/src/args/mod.rs#12)         |
| `RootCommandContext`   | Resolves profiles, state roots, and connection endpoints.       | [crates/palyra-cli/src/app/mod.rs#45](http://crates/palyra-cli/src/app/mod.rs#45)           |
| `CliConnectionProfile` | Named configuration for targeting specific environments.        | [crates/palyra-cli/src/app/mod.rs#153](http://crates/palyra-cli/src/app/mod.rs#153)         |
| `OutputFormatArg`      | Global flag for switching between `Text`, `JSON`, and `NDJSON`. | [crates/palyra-cli/src/args/mod.rs#97-101](http://crates/palyra-cli/src/args/mod.rs#97-101) |

Sources: [crates/palyra-cli/src/app/mod.rs#45-153](http://crates/palyra-cli/src/app/mod.rs#45-153), [crates/palyra-cli/src/args/mod.rs#1-153](http://crates/palyra-cli/src/args/mod.rs#1-153)

## Command Families

The CLI is organized into functional groups, often referred to as "command families" [crates/palyra-cli/src/args/mod.rs#154-191](http://crates/palyra-cli/src/args/mod.rs#154-191).

**Command Hierarchy Mapping**

```mermaid theme={null}
graph LR
    subgraph "CLI Root"
        Root["palyra"]
    end

    subgraph "Architecture & Core"
        Root -->|"setup / init"| Core
        Root -->|"gateway / daemon"| Core
        Root -->|"doctor"| Core
    end

    subgraph "Agent & Session"
        Root -->|"agent / acp"| Agents
        Root -->|"tui"| Agents
        Root -->|"mcp"| Agents
    end

    subgraph "Auxiliary & Output"
        Root -->|"profile"| Aux
        Root -->|"auth"| Aux
        Root -->|"backup"| Aux
    end
```

Sources: [crates/palyra-cli/tests/help\_snapshots/root-help-unix.txt#5-66](http://crates/palyra-cli/tests/help_snapshots/root-help-unix.txt#5-66), [crates/palyra-cli/src/commands/mod.rs#4-67](http://crates/palyra-cli/src/commands/mod.rs#4-67)

### CLI Architecture and Core Commands

This group handles the fundamental lifecycle of the Palyra installation. It includes `setup` (the preferred bootstrap workflow), `gateway` (admin and runtime diagnostics), and the `doctor` diagnostic system for environment repair [crates/palyra-cli/src/args/mod.rs#175-179](http://crates/palyra-cli/src/args/mod.rs#175-179).
For details, see [CLI Architecture and Core Commands](/cli_palyra-cli/cli_architecture_and_core_commands).

### Agent and Session Commands

These commands facilitate interaction with agents. The `acp` command provides the Agent Control Protocol bridge, while `agent` allows for interactive or one-off sessions [crates/palyra-cli/src/args/mod.rs#71-75](http://crates/palyra-cli/src/args/mod.rs#71-75). This family also includes the `tui` (Terminal User Interface) and the `mcp` (Model Context Protocol) facade [crates/palyra-cli/src/args/mod.rs#110-148](http://crates/palyra-cli/src/args/mod.rs#110-148).
For details, see [Agent and Session Commands](/cli_palyra-cli/agent_and_session_commands).

### CLI Output, Profiles, and Auxiliary Commands

This family manages the operator's local environment. The `profile` command manages a registry of connection profiles (local, remote, or custom) with isolated state roots [crates/palyra-cli/src/args/profile.rs#10-27](http://crates/palyra-cli/src/args/profile.rs#10-27). It also covers `auth` for credential management and `backup` for portable system snapshots [crates/palyra-cli/src/args/mod.rs#81-85](http://crates/palyra-cli/src/args/mod.rs#81-85).
For details, see [CLI Output, Profiles, and Auxiliary Commands](/cli_palyra-cli/cli_output_profiles_and_auxiliary_commands).

## Design Patterns

### Profile Isolation

The CLI enforces isolation by assigning per-profile state roots and config snapshots [crates/palyra-cli/src/args/profile.rs#25-27](http://crates/palyra-cli/src/args/profile.rs#25-27). When a profile is created via `palyra profile create`, it typically resides in a subdirectory of the global state root [crates/palyra-cli/src/app/mod.rs#34-39](http://crates/palyra-cli/src/app/mod.rs#34-39).

### Global Guardrails

* **`--expect-profile`**: Ensures the command only runs if the resolved profile matches the operator's expectation [crates/palyra-cli/tests/help\_snapshots/root-help-unix.txt#79-80](http://crates/palyra-cli/tests/help_snapshots/root-help-unix.txt#79-80).
* **`--allow-strict-profile-actions`**: A safety gate required for destructive actions like `reset` when targeting production profiles [crates/palyra-cli/src/app/mod.rs#57](http://crates/palyra-cli/src/app/mod.rs#57), [crates/palyra-cli/tests/help\_snapshots/root-help-unix.txt#131](http://crates/palyra-cli/tests/help_snapshots/root-help-unix.txt#131).

### Parity Testing

The CLI maintains a `CliParityMatrix` to ensure feature parity across platforms and consistent help output [crates/palyra-cli/tests/cli\_parity\_matrix.toml#1-15](http://crates/palyra-cli/tests/cli_parity_matrix.toml#1-15). Help snapshots are pinned for every command to prevent accidental UX regressions [crates/palyra-cli/tests/help\_snapshots.rs#1-8](http://crates/palyra-cli/tests/help_snapshots.rs#1-8).

Sources: [crates/palyra-cli/src/app/mod.rs#32-58](http://crates/palyra-cli/src/app/mod.rs#32-58), [crates/palyra-cli/src/args/profile.rs#10-27](http://crates/palyra-cli/src/args/profile.rs#10-27), [crates/palyra-cli/tests/cli\_parity\_matrix.toml#1-15](http://crates/palyra-cli/tests/cli_parity_matrix.toml#1-15), [crates/palyra-cli/tests/help\_snapshots.rs#1-8](http://crates/palyra-cli/tests/help_snapshots.rs#1-8)

## Child Pages

* [CLI Architecture and Core Commands](/cli_palyra-cli/cli_architecture_and_core_commands)
* [Agent and Session Commands](/cli_palyra-cli/agent_and_session_commands)
* [CLI Output, Profiles, and Auxiliary Commands](/cli_palyra-cli/cli_output_profiles_and_auxiliary_commands)