> ## 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 Output, Profiles, and Auxiliary 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/auth.rs
  * crates/palyra-cli/src/args/backup.rs
  * crates/palyra-cli/src/args/patch.rs
  * crates/palyra-cli/src/args/policy.rs
  * crates/palyra-cli/src/args/profile.rs
  * crates/palyra-cli/src/args/reset.rs
  * crates/palyra-cli/src/args/support\_bundle.rs
  * crates/palyra-cli/src/args/uninstall.rs
  * crates/palyra-cli/src/args/update.rs
  * crates/palyra-cli/src/args/workers.rs
  * crates/palyra-cli/src/commands/auth.rs
  * crates/palyra-cli/src/commands/backup.rs
  * crates/palyra-cli/src/commands/pairing.rs
  * crates/palyra-cli/src/commands/patch.rs
  * crates/palyra-cli/src/commands/policy.rs
  * crates/palyra-cli/src/commands/profile.rs
  * crates/palyra-cli/src/commands/support\_bundle.rs
  * crates/palyra-cli/src/commands/update.rs
  * crates/palyra-cli/src/commands/workers.rs
  * crates/palyra-cli/src/output/mod.rs
  * crates/palyra-cli/src/tui/composer.rs
  * crates/palyra-cli/src/tui/rollback.rs
  * crates/palyra-cli/src/tui/slash\_palette\_builders.rs
  * crates/palyra-cli/src/tui/workspace.rs
  * crates/palyra-cli/tests/backup\_cli.rs
  * crates/palyra-cli/tests/help\_snapshots/auth-help.txt
  * crates/palyra-cli/tests/help\_snapshots/browser-console-help.txt
  * crates/palyra-cli/tests/help\_snapshots/config-list-help.txt
  * crates/palyra-cli/tests/help\_snapshots/patch-bundles-help.txt
  * crates/palyra-cli/tests/help\_snapshots/patch-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/support-bundle-export-help.txt
  * crates/palyra-cli/tests/help\_snapshots/update-help.txt
  * crates/palyra-cli/tests/patch\_cli.rs
  * crates/palyra-cli/tests/policy\_explain.rs
  * crates/palyra-common/src/context\_references.rs
  * crates/palyra-common/src/replay\_bundle.rs
  * crates/palyra-control-plane/src/client.rs
  * crates/palyra-control-plane/src/contract.rs
  * crates/palyra-control-plane/src/errors.rs
  * crates/palyra-control-plane/src/lib.rs
  * crates/palyra-control-plane/src/models.rs
  * crates/palyra-control-plane/src/tests.rs
  * crates/palyra-control-plane/src/transport.rs
  * crates/palyra-daemon/src/transport/http/handlers/admin/core.rs
  * crates/palyra-identity/src/pairing/handshake.rs
  * crates/palyra-identity/src/pairing/helpers.rs
  * crates/palyra-identity/src/pairing/persistence.rs
  * crates/palyra-identity/src/pairing/tests.rs
  * crates/palyra-identity/src/store.rs
</details>

The Palyra CLI (`palyra-cli`) is designed with a strict output contract and a robust profile management system that enables multi-environment operations. This page details the technical implementation of the CLI's output formatting, the lifecycle of connection profiles, identity pairing flows, and auxiliary management commands such as backup/restore and support bundle generation.

## CLI Output Contract

The CLI implements a multi-format output system supporting human-readable text, JSON, and NDJSON (Newline Delimited JSON). This contract is pinned by parity tests to ensure stability for operators and automation scripts [crates/palyra-cli/src/output/mod.rs#4-6](http://crates/palyra-cli/src/output/mod.rs#4-6).

### Exit Codes

The CLI maps internal errors to a stable set of process exit codes. These codes are part of the documented operator contract [crates/palyra-cli/src/output/mod.rs#22-38](http://crates/palyra-cli/src/output/mod.rs#22-38).

| Exit Code | Name           | Description                                    |
| :-------- | :------------- | :--------------------------------------------- |
| `0`       | `Success`      | Operation completed successfully.              |
| `1`       | `Internal`     | Unhandled internal error.                      |
| `2`       | `Validation`   | Invalid input or flag combination.             |
| `3`       | `Auth`         | Authentication failure or expired credentials. |
| `4`       | `Connectivity` | Failed to reach the daemon or provider.        |
| `6`       | `Policy`       | Cedar policy engine denied the action.         |
| `130`     | `Cancelled`    | Operation interrupted by user (SIGINT).        |

### Output Formatting and Redaction

Output is routed through the `output` module, which handles serialization and mandatory secret redaction.

* **JSON/NDJSON**: Used for machine-readable automation. Errors are wrapped in a versioned `ErrorEnvelope` [crates/palyra-cli/src/output/mod.rs#95-109](http://crates/palyra-cli/src/output/mod.rs#95-109).
* **Text**: Pretty-printed for terminal use.
* **Redaction**: All diagnostic text is passed through `redact_diagnostic_text` to strip tokens, authorization headers, and secret query parameters before printing [crates/palyra-cli/src/output/mod.rs#151-155](http://crates/palyra-cli/src/output/mod.rs#151-155).

Sources: [crates/palyra-cli/src/output/mod.rs#22-155](http://crates/palyra-cli/src/output/mod.rs#22-155), [crates/palyra-common/src/redaction.rs#10-10](http://crates/palyra-common/src/redaction.rs#10-10)

## Profile Lifecycle and Registry

Profiles allow users to switch between different Palyra environments (e.g., `local`, `production`, `staging`) by isolating connection endpoints, credentials, and state roots.

### Profile Registry Structure

The registry is stored in `cli/profiles.toml` within the CLI state root [crates/palyra-cli/src/app/mod.rs#34-35](http://crates/palyra-cli/src/app/mod.rs#34-35). It is managed via the `CliProfilesDocument` and `CliConnectionProfile` structs [crates/palyra-cli/src/app/mod.rs#140-173](http://crates/palyra-cli/src/app/mod.rs#140-173).

### Profile Operations

The `palyra profile` command family implements the following lifecycle:

1. **Create/Clone**: Initializes a new profile. If `strict_mode` is enabled, the profile enforces higher security guardrails [crates/palyra-cli/src/app/mod.rs#168-169](http://crates/palyra-cli/src/app/mod.rs#168-169).
2. **Use**: Sets the `default_profile` in the registry [crates/palyra-cli/src/app/mod.rs#144-144](http://crates/palyra-cli/src/app/mod.rs#144-144).
3. **Export/Import**: Supports portability. Exports can be plaintext (redacted) or encrypted using AES-256-GCM with a PBKDF2-derived key [crates/palyra-cli/src/commands/profile.rs#31-40](http://crates/palyra-cli/src/commands/profile.rs#31-40).

### Data Flow: Profile Resolution

The `RootCommandContext` resolves the active profile by checking the `--profile` flag, the `PALYRA_CLI_PROFILE` environment variable, or the registry default [crates/palyra-cli/src/app/mod.rs#32-58](http://crates/palyra-cli/src/app/mod.rs#32-58).

```mermaid theme={null}
graph TD
    subgraph "CLI Entry Point"
        A["run_cli()"] --> B["RootOptions"]
    end

    subgraph "Profile Resolution"
        B --> C["RootCommandContext::build()"]
        C --> D{"Profile Source?"}
        D -- "--profile Flag" --> E["Load Named Profile"]
        D -- "ENV: PALYRA_CLI_PROFILE" --> E
        D -- "Registry Default" --> E
        E --> F["CliProfilesDocument"]
    end

    subgraph "Output Context"
        F --> G["CliConnectionProfile"]
        G --> H["HttpConnection"]
        G --> I["ActiveProfileContext"]
    end

    H --> J["Command Execution"]
    I --> K["TUI / Console Display"]
```

Sources: [crates/palyra-cli/src/app/mod.rs#32-173](http://crates/palyra-cli/src/app/mod.rs#32-173), [crates/palyra-cli/src/commands/profile.rs#31-183](http://crates/palyra-cli/src/commands/profile.rs#31-183)

## Identity and Pairing Flows

Palyra uses a pairing handshake to establish trust between a CLI/Device and the Daemon.

### Pairing Handshake

The pairing flow is managed via `PairingCommand`. It supports:

* **Code Minting**: Generating a short-lived pairing code via the admin console [crates/palyra-cli/src/commands/pairing.rs#83-107](http://crates/palyra-cli/src/commands/pairing.rs#83-107).
* **Request Management**: Listing, approving, or rejecting pending pairing requests from other devices [crates/palyra-cli/src/commands/pairing.rs#24-82](http://crates/palyra-cli/src/commands/pairing.rs#24-82).
* **Local Pairing**: A legacy flow that drives the `IdentityManager` directly against an on-disk `SecretStore` [crates/palyra-cli/src/commands/pairing.rs#175-178](http://crates/palyra-cli/src/commands/pairing.rs#175-178).

### Secret Storage

Identity secrets (private keys, CA state) are stored using the `SecretStore` trait.

* **FilesystemSecretStore**: Encrypts payloads with ChaCha20-Poly1305. On Windows, the store key is DPAPI-wrapped [crates/palyra-identity/src/store.rs#3-7](http://crates/palyra-identity/src/store.rs#3-7).
* **Atomic Writes**: Uses temp-file + rename to ensure state integrity [crates/palyra-identity/src/store.rs#4-5](http://crates/palyra-identity/src/store.rs#4-5).

Sources: [crates/palyra-cli/src/commands/pairing.rs#8-178](http://crates/palyra-cli/src/commands/pairing.rs#8-178), [crates/palyra-identity/src/store.rs#1-132](http://crates/palyra-identity/src/store.rs#1-132)

## Auxiliary Commands

### Backup and Restore

The `palyra backup` command creates portable ZIP archives containing configuration, state, and optional workspace data [crates/palyra-cli/src/commands/backup.rs#1-5](http://crates/palyra-cli/src/commands/backup.rs#1-5).

* **Manifest**: Every archive includes a `manifest.json` with SHA-256 hashes of all entries for integrity verification [crates/palyra-cli/src/commands/backup.rs#32-51](http://crates/palyra-cli/src/commands/backup.rs#32-51).
* **Safety**: The command rejects backups targeted inside the live state root to prevent recursive growth or corruption [crates/palyra-cli/src/commands/backup.rs#131-131](http://crates/palyra-cli/src/commands/backup.rs#131-131).

### Support Bundle

The `palyra support-bundle` command generates a diagnostic package for troubleshooting. It aggregates:

* Daemon runtime status snapshots [crates/palyra-daemon/src/transport/http/handlers/admin/core.rs#14-31](http://crates/palyra-daemon/src/transport/http/handlers/admin/core.rs#14-31).
* Redacted logs and configuration.
* System metrics in Prometheus format [crates/palyra-daemon/src/transport/http/handlers/admin/core.rs#127-158](http://crates/palyra-daemon/src/transport/http/handlers/admin/core.rs#127-158).
* Incident replay bundles (if applicable), which capture orchestrator tape events for offline drift detection [crates/palyra-common/src/replay\_bundle.rs#1-7](http://crates/palyra-common/src/replay_bundle.rs#1-7).

### Auth and Policy Diagnostics

* **Auth Profiles**: CRUD operations for the auth registry and model-provider credentials [crates/palyra-cli/src/commands/auth.rs#49-67](http://crates/palyra-cli/src/commands/auth.rs#49-67).
* **Policy Explain**: Evaluates a request against the Cedar engine locally to explain why an action was allowed or denied, overlaying runtime tool approval requirements [crates/palyra-cli/src/commands/policy.rs#1-6](http://crates/palyra-cli/src/commands/policy.rs#1-6).

## Implementation Entity Map

The following diagram bridges the high-level CLI concepts to the specific code entities responsible for their execution.

```mermaid theme={null}
classDiagram
    class RootCommandContext {
        +profile_name: Option~String~
        +output_format: OutputFormatArg
        +state_root: PathBuf
        +resolve_grpc_connection()
    }
    class CliProfilesDocument {
        +default_profile: Option~String~
        +profiles: BTreeMap~String, CliConnectionProfile~
    }
    class SecretStore {
        <<interface>>
        +write_secret(key, value)
        +read_secret(key)
    }
    class FilesystemSecretStore {
        +root: PathBuf
        +encryption_key: [u8; 32]
    }
    class ControlPlaneClient {
        +base_url: Url
        +csrf_token: Option~String~
        +get_session()
        +list_node_pairing_requests()
    }

    RootCommandContext --> CliProfilesDocument : "loads from cli/profiles.toml"
    FilesystemSecretStore ..|> SecretStore : "implements"
    PairingCommand --> ControlPlaneClient : "uses for remote pairing"
    PairingCommand --> SecretStore : "uses for local identity"
```

Sources: [crates/palyra-cli/src/app/mod.rs#45-147](http://crates/palyra-cli/src/app/mod.rs#45-147), [crates/palyra-identity/src/store.rs#41-132](http://crates/palyra-identity/src/store.rs#41-132), [crates/palyra-control-plane/src/client.rs#58-118](http://crates/palyra-control-plane/src/client.rs#58-118), [crates/palyra-cli/src/commands/pairing.rs#23-156](http://crates/palyra-cli/src/commands/pairing.rs#23-156)