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.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.| 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 theoutput module, which handles serialization and mandatory secret redaction.
- JSON/NDJSON: Used for machine-readable automation. Errors are wrapped in a versioned
ErrorEnvelopecrates/palyra-cli/src/output/mod.rs#95-109. - Text: Pretty-printed for terminal use.
- Redaction: All diagnostic text is passed through
redact_diagnostic_textto strip tokens, authorization headers, and secret query parameters before printing crates/palyra-cli/src/output/mod.rs#151-155.
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 incli/profiles.toml within the CLI state root 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.
Profile Operations
Thepalyra profile command family implements the following lifecycle:
- Create/Clone: Initializes a new profile. If
strict_modeis enabled, the profile enforces higher security guardrails crates/palyra-cli/src/app/mod.rs#168-169. - Use: Sets the
default_profilein the registry crates/palyra-cli/src/app/mod.rs#144-144. - 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.
Data Flow: Profile Resolution
TheRootCommandContext 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.
Sources: crates/palyra-cli/src/app/mod.rs#32-173, 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 viaPairingCommand. It supports:
- Code Minting: Generating a short-lived pairing code via the admin console 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.
- Local Pairing: A legacy flow that drives the
IdentityManagerdirectly against an on-diskSecretStorecrates/palyra-cli/src/commands/pairing.rs#175-178.
Secret Storage
Identity secrets (private keys, CA state) are stored using theSecretStore trait.
- FilesystemSecretStore: Encrypts payloads with ChaCha20-Poly1305. On Windows, the store key is DPAPI-wrapped 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.
Auxiliary Commands
Backup and Restore
Thepalyra backup command creates portable ZIP archives containing configuration, state, and optional workspace data crates/palyra-cli/src/commands/backup.rs#1-5.
- Manifest: Every archive includes a
manifest.jsonwith SHA-256 hashes of all entries for integrity verification 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.
Support Bundle
Thepalyra 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.
- Redacted logs and configuration.
- System metrics in Prometheus format 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.
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.
- 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.