initial commit

interfaces/websocket/client/cmd/README.md

@@ -0,0 +1,136 @@
+# Circles WebSocket Client
+
+A WebSocket client for connecting to Circles servers with authentication support. Available in both CLI and WebAssembly (WASM) versions.
+
+## CLI Usage
+
+### Installation
+
+Build the CLI binary:
+```bash
+cargo build --bin circles_client --release
+```
+
+### Configuration
+
+Create a `.env` file in the `cmd/` directory:
+```bash
+# cmd/.env
+PRIVATE_KEY=your_actual_private_key_hex_here
+```
+
+Or set the environment variable directly:
+```bash
+export PRIVATE_KEY=your_actual_private_key_hex_here
+```
+
+### Usage
+
+```bash
+# Basic usage - connects and enters interactive mode
+circles_client ws://localhost:8080
+
+# Execute a single Rhai script
+circles_client -s "print('Hello from Rhai!')" ws://localhost:8080
+
+# Execute a script from file
+circles_client -f script.rhai ws://localhost:8080
+
+# Increase verbosity (can be used multiple times)
+circles_client -v ws://localhost:8080
+circles_client -vv ws://localhost:8080
+```
+
+### Features
+
+- **Authentication**: Automatically loads private key and completes secp256k1 authentication flow
+- **Script Execution**: Supports both inline scripts (`-s`) and script files (`-f`)
+- **Interactive Mode**: When no script is provided, enters interactive REPL mode
+- **Verbosity Control**: Use `-v` flags to increase logging detail
+- **Cross-platform**: Works on all platforms supported by Rust and tokio-tungstenite
+
+## WebAssembly (WASM) Usage
+
+### Build and Serve
+
+1. Install Trunk:
+```bash
+cargo install trunk
+```
+
+2. Build the WASM version:
+```bash
+trunk build --release
+```
+
+3. Serve the application:
+```bash
+trunk serve
+```
+
+The application will be available at `http://localhost:8080`
+
+### Usage in Browser
+
+1. Open the served page in your browser
+2. Enter the WebSocket server URL
+3. Choose either:
+   - Execute a Rhai script directly
+   - Enter interactive mode (type 'exit' or 'quit' to leave)
+
+### Features
+
+- **Browser Integration**: Uses browser's WebSocket implementation
+- **Interactive Mode**: Browser-based input/output using prompts
+- **Error Handling**: Browser console logging
+- **Cross-browser**: Works in all modern browsers supporting WebAssembly
+
+## Common Features
+
+Both versions share the same core functionality:
+
+- **WebSocket Connection**: Connects to Circles WebSocket server
+- **Authentication**: Handles secp256k1 authentication
+- **Script Execution**: Executes Rhai scripts
+- **Interactive Mode**: Provides REPL-like interface
+- **Error Handling**: Comprehensive error reporting
+- **Logging**: Detailed logging at different verbosity levels
+
+### Interactive Mode
+
+When run without `-s` or `-f` flags, the client enters interactive mode where you can:
+- Enter Rhai scripts line by line
+- Type `exit` or `quit` to close the connection
+- Use Ctrl+C to terminate
+
+### Examples
+
+```bash
+# Connect to local development server
+circles_client ws://localhost:8080
+
+# Connect to secure WebSocket with verbose logging
+circles_client -v wss://circles.example.com/ws
+
+# Execute a simple calculation
+circles_client -s "let result = 2 + 2; print(result);" ws://localhost:8080
+
+# Load and execute a complex script
+circles_client -f examples/complex_script.rhai ws://localhost:8080
+```
+
+### Error Handling
+
+The client provides clear error messages for common issues:
+- Missing or invalid private key
+- Connection failures
+- Authentication errors
+- Script execution errors
+
+### Dependencies
+
+- `tokio-tungstenite`: WebSocket client implementation
+- `secp256k1`: Cryptographic authentication
+- `clap`: Command-line argument parsing
+- `env_logger`: Logging infrastructure
+- `dotenv`: Environment variable loading