Metadata-Version: 2.4
Name: cli-serial-hid-kvm
Version: 0.1.0
Summary: CLI tool for KVM control — thin client for serial-hid-kvm
Project-URL: Homepage, https://github.com/sunasaji/cli-serial-hid-kvm
Project-URL: Repository, https://github.com/sunasaji/cli-serial-hid-kvm
Project-URL: Issues, https://github.com/sunasaji/cli-serial-hid-kvm/issues
Author: sunasaji
License: MIT
License-File: LICENSE.txt
Keywords: cli,kvm,ocr,remote-control
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Hardware
Requires-Python: >=3.10
Requires-Dist: pillow>=10.0.0
Requires-Dist: pytesseract>=0.3.10
Requires-Dist: serial-hid-kvm
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

# cli-serial-hid-kvm

CLI tool for KVM control — thin client for [serial-hid-kvm](https://github.com/sunasaji/serial-hid-kvm).

## Architecture

```
┌──────────┐       TCP        ┌─────────────────┐     USB/HDMI     ┌───────────┐
│  shkvm   │ ──────────────── │ serial-hid-kvm  │ ──────────────── │ Target PC │
│  (CLI)   │    port 9329     │   (server)      │   CH9329 + Cap   │           │
└──────────┘                  └─────────────────┘                  └───────────┘
```

The CLI connects to a running `serial-hid-kvm` server over TCP. The server handles all hardware interaction (USB HID via CH9329 and HDMI capture). OCR is performed locally by the CLI using Tesseract.

## Prerequisites

- **serial-hid-kvm** server running with `--headless --api` (or with GUI + API enabled)
- **Tesseract OCR** installed for `ocr` and `exec` commands
- **Python 3.10+**

## Installation

```bash
pip install cli-serial-hid-kvm
```

Or for development:

```bash
git clone https://github.com/sunasaji/cli-serial-hid-kvm.git
cd cli-serial-hid-kvm
pip install -e .
```

## Quick Start

```bash
# Start the KVM server (on the machine connected to target PC)
serial-hid-kvm --headless --api

# Use shkvm from any machine that can reach the server
shkvm info                          # check connection
shkvm type "ls -la{enter}"          # type on target PC
shkvm capture -o screen.jpg         # take screenshot
shkvm ocr                           # read screen text
shkvm exec "echo hello" -w 2        # run command and read output
```

## Command Reference

### Keyboard

| Command | Description |
|---|---|
| `shkvm type TEXT [-d MS] [-r]` | Type text with optional char delay. Supports inline tags: `{enter}`, `{tab}`, `{ctrl+c}`, `{0xNN}`. Whitelist-based: unknown `{content}` passes through literally. `-r` (raw mode) disables tags, `\n` → Enter |
| `shkvm key KEY [-m MOD]` | Send single key press. `-m` can be repeated: `-m ctrl -m shift` |
| `shkvm keys JSON [-d MS]` | Send key sequence from JSON array |

### Mouse

| Command | Description |
|---|---|
| `shkvm move X Y [-r]` | Move cursor (absolute, or relative with `-r`) |
| `shkvm click [-b BUTTON] [-x X] [-y Y]` | Click (default: left) |
| `shkvm drag X1 Y1 X2 Y2 [-b BUTTON]` | Drag from start to end |
| `shkvm scroll AMOUNT` | Scroll wheel (+up, -down) |

### Screen

| Command | Description |
|---|---|
| `shkvm capture [-o FILE] [--base64]` | Save screenshot or output base64 to stdout |
| `shkvm ocr` | Capture + OCR, print text to stdout |
| `shkvm exec CMD [-w SEC]` | Type command, Enter, wait, then OCR |

### Device Management

| Command | Description |
|---|---|
| `shkvm info` | Show device info (JSON) |
| `shkvm devices` | List capture devices |
| `shkvm set-device DEV` | Switch capture device by index or path |
| `shkvm set-resolution W H` | Set capture resolution |

### Global Options

| Option | Description |
|---|---|
| `-H, --host HOST` | KVM server host (overrides `SHKVM_API_HOST`) |
| `-p, --port PORT` | KVM server port (overrides `SHKVM_API_PORT`) |

## Configuration

All settings can be configured via environment variables:

| Variable | Default | Description |
|---|---|---|
| `SHKVM_API_HOST` | `127.0.0.1` | KVM server host |
| `SHKVM_API_PORT` | `9329` | KVM server port |
| `SHKVM_OCR_CMD` | (auto-detect) | Path to Tesseract binary |
| `SHKVM_CAPTURE_LOG_DIR` | `~/.local/share/cli-serial-hid-kvm/captures` | Capture log directory (set to empty string to disable) |

## License

MIT
