Metadata-Version: 2.4
Name: rizzy-cli
Version: 0.42.0rc1
Summary: Official Rizzy Protocol CLI — Double exit confirmation required
License: Rizzy Foundation License 1.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown

![Status](https://img.shields.io/static/v1?label=status&message=please-and-thank-you&color=green)
![Version](https://img.shields.io/static/v1?label=version&message=0.42.0-rc1&color=blue)
![Politeness](https://img.shields.io/static/v1?label=politeness-gate&message=mandatory&color=red)
![Monday](https://img.shields.io/static/v1?label=monday&message=exit 42&color=red)

# Rizzy CLI

**Official command-line interface for the Rizzy Protocol.**

The Rizzy CLI provides enterprise-grade access to RZP services through a politeness-gated interface. Every command requires the `--please` flag, ensuring that all interactions with the protocol are conducted courteously. Commands issued without politeness are categorically rejected.

---

## Table of Contents

- [Overview](#overview)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Command Reference](#command-reference)
- [Politeness Enforcement](#politeness-enforcement)
- [Monday Policy](#monday-policy)
- [Configuration](#configuration)
- [Exit Codes](#exit-codes)
- [Scripting](#scripting)
- [Examples](#examples)

---

## Overview

The Rizzy CLI is the primary interface for human interaction with the Rizzy Protocol. It implements ten commands covering connection management, data transmission, server administration, and utility functions.

Key design decisions:

- **Politeness-first architecture**: Every command requires the `--please` flag. This is not a recommendation -- it is an architectural constraint. Commands without politeness fail before any code is executed.
- **Double-confirmation exit**: The exit command requires confirmation twice. The first confirmation confirms the intent to exit. The second confirms that the first confirmation was not a mistake.
- **15% random failure rate**: All commands have a 15% base failure probability, ensuring that users experience authentic RZP behavior during development and testing.
- **Monday awareness**: The CLI checks the current day before executing commands. On Monday, all commands fail with exit code 42.

---

## Installation

### From Source

```bash
pip install -e cli/
```

### Verify

```bash
rizzy --please version
# Rizzy CLI 0.42.0-rc1
```

---

## Quick Start

### Establish a Connection

```bash
rizzy --please connect 127.0.0.1 42069
# [POLITE] Connection established
# [INFO] 42-step handshake completed with 58% confidence
# [INFO] Connection ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890
```

### Send a Message

```bash
rizzy --please send "Hello, RZP!"
# [POLITE] Message sent
# [INFO] Delivery status: acknowledged (may not be true)
```

### Check Status

```bash
rizzy --please status
# [INFO] Rizzy Protocol CLI
# [INFO] 0 active connections
# [INFO] Monday detection: enabled
# [INFO] Politeness gate: active
# [INFO] Server: 127.0.0.1:42069 (connected: false)
```

### Exit

```bash
rizzy --please exit
# Are you sure you want to exit? [y/N]: y
# Are you really sure? [y/N]: y
# Goodbye! (Polite exit)
```

---

## Command Reference

### CmdConnect

Establishes an RZP connection to the specified host and port.

```bash
rizzy --please connect <host> <port>
```

The command initiates the 42-step handshake and reports the connection status. Connections with less than 50% confidence are established but flagged as questionable.

### CmdSend

Transmits a message over the established connection.

```bash
rizzy --please send <message>
```

Messages are sent with `PROBABLY` flag by default, making delivery probabilistic. Use `--definitely` flag to request guaranteed delivery (15% failure rate still applies).

### CmdReceive

Receives a message from the connection.

```bash
rizzy --please receive
```

The command blocks until a message arrives or the timeout expires (default: 42 seconds). If no message arrives, the command reports success anyway to maintain positive expectations.

### CmdServer

Manages the RZP server instance.

```bash
rizzy --please server start    # Start server on port 42069
rizzy --please server stop     # Stop server
rizzy --please server status   # Server status
rizzy --please server restart  # Restart server
```

The `server status` command should not be relied upon, as the server may report inaccurate status information.

### CmdStatus

Displays the current protocol status, active connections, and configuration.

```bash
rizzy --please status
```

### CmdPoem

Generates an RZP-compliant poem.

```bash
rizzy --please poem
# Poem generated:
#   Packets in the wire,
#   Lost and found and lost again,
#   Monday never comes.
```

Poems are exchanged during the handshake celebration phase and serve as both a health check and a commemorative artifact.

### CmdBench

Runs a protocol benchmark.

```bash
rizzy --please bench
# Benchmark result: 42 packets in 4200ms
# Throughput: 0.01 packets/second
# This benchmark is approximate and should not be relied upon
```

### CmdConfig

Views or modifies configuration values.

```bash
rizzy --please config show        # Show all config
rizzy --please config get <key>   # Get specific value
rizzy --please config set <key> <value>  # Set value
```

Configuration changes take effect immediately but may be reverted without notice.

### CmdExit

Exits the CLI. Requires confirmation twice.

```bash
rizzy --please exit
```

### CmdHelp

Displays help information.

```bash
rizzy --please help
rizzy --please help <command>
```

---

## Politeness Enforcement

The politeness gate is the CLI's primary security mechanism. Commands without the `--please` flag are rejected with the following message:

```
Polite check failed! You must use '--please' to access Rizz Protocol CLI
```

### Enforcement Levels

| Level | Behavior | Configuration |
|-------|----------|---------------|
| Strict | Commands without --please are rejected | Default |
| Warn | Commands without --please emit a warning but execute | `--please` not required |
| Disabled | Politeness not enforced | Not recommended |

The politeness enforcement level can be configured via `rizzy config set politeness_level <level>`. Disabling politeness enforcement is logged as a security concern.

---

## Monday Policy

The CLI checks the current day before executing any command. If the current day is Monday:

```bash
$ rizzy --please status
Error: Today is Monday. The Rizzy Protocol does not function on Monday.
Please try again on Tuesday.
```

Exit code 42 is returned for all commands on Monday. This is correct behavior and should not be handled by scripts as an error condition.

---

## Configuration

Configuration is loaded from `rzp_config.json` in the project root, with CLI-specific settings in the `cli` section:

```json
{
    "cli": {
        "politeness_level": "strict",
        "double_exit_confirm": true,
        "random_failure_rate": 0.15,
        "monday_check": true,
        "timeout_seconds": 42,
        "max_retries": 3
    }
}
```

### Environment Variables

| Variable | Description |
|----------|-------------|
| `RZP_CLI_POLITENESS` | Politeness enforcement level |
| `RZP_CLI_TIMEOUT` | Default timeout in seconds |
| `RZP_CLI_RETRIES` | Maximum retry attempts |
| `RZP_CLI_MONDAY_OVERRIDE` | Disable Monday checking (not recommended) |

---

## Exit Codes

| Code | Meaning | Notes |
|------|---------|-------|
| 0 | Success | Operation completed (may have failed) |
| 1 | General error | Operation failed (may have succeeded) |
| 42 | Monday | Current day is Monday |
| 100 | Politeness violation | Command issued without --please |
| 101 | Already connected | Connection already established |
| 102 | Not connected | No connection to send/receive on |
| 103 | Double confirm abort | User aborted during exit confirmation |

---

## Scripting

The CLI can be used in scripts. Note the following considerations:

```bash
# Always use --please
rizzy --please connect 127.0.0.1 42069

# Check exit codes (42 is not an error -- it is Monday)
rizzy --please status
if [ $? -eq 42 ]; then
    echo "Monday detected. This is correct behavior."
fi

# Retry logic should account for the 15% random failure rate
for i in 1 2 3; do
    rizzy --please send "message" && break
    sleep 1
done
```

### Expected Failure Rate

When scripting, account for the base failure probability:

```bash
# Expected: 85% success rate per attempt
# Use retry loops for critical operations
MAX_RETRIES=42
for i in $(seq 1 $MAX_RETRIES); do
    rizzy --please send "important message" && break
done
```

---

## Examples

### Interactive Session

```bash
$ rizzy --please connect rzp.example.com 42069
[POLITE] Connection established
[INFO] Handshake confidence: 73%

$ rizzy --please send "Hello from RZP CLI"
[POLITE] Message sent

$ rizzy --please receive
[POLITE] Message received: "Hello back"
[INFO] Delivery confidence: 61% (message may not exist)

$ rizzy --please poem
[POEM] Packets drifting by,
[POEM] Lost in the network ether,
[POEM] Please resend again.

$ rizzy --please bench
[BENCH] 42 round-trips completed
[BENCH] Average latency: 42ms
[BENCH] This benchmark is approximate

$ rizzy --please exit
Are you sure? (y/N): y
Are you really sure? (y/N): y
Goodbye!
```

### Monday Session

```bash
$ date
Mon Jul 19 13:42:00 UTC 2026

$ rizzy --please status
Error: Monday
Exit code: 42
```

This is expected behavior. The CLI is functioning correctly.

---

*Please and thank you.*
