From 33845f5a689ee55d8603df8eb7c3179427897d98 Mon Sep 17 00:00:00 2001
From: ysandler <ysandler@beitzah.net>
Date: Tue, 27 Jan 2026 22:03:51 -0600
Subject: [PATCH] add readme

---
 README.md | 117 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 117 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..66208b9
--- /dev/null
+++ b/README.md
@@ -0,0 +1,117 @@
+# klp
+
+A clipboard history manager for Linux (X11 and Wayland).
+
+## Installation
+
+```bash
+./install.sh
+```
+
+This builds the binary, installs it to `~/.local/bin`, and starts the background daemon.
+
+Ensure `~/.local/bin` is in your PATH:
+```bash
+export PATH="$HOME/.local/bin:$PATH"
+```
+
+### Auto-start on Login
+
+**Option 1: systemd (recommended)**
+```bash
+make service-install
+systemctl --user enable --now klp
+```
+
+**Option 2: Desktop autostart**
+```bash
+make autostart-install
+```
+
+## Usage
+
+| Command | Description |
+|---------|-------------|
+| `klp` | Interactive list (navigate with j/k, select with Enter, delete with d) |
+| `klp -l` | Non-interactive list |
+| `klp -l -n 10` | Non-interactive list, 10 entries |
+| `klp --limit 10` | Interactive list, 10 entries |
+| `klp <id>` | Copy entry to clipboard |
+| `klp -s "query"` | Search (interactive) |
+| `klp -s "query" -l` | Search (non-interactive) |
+| `klp -d <id>` | Delete entry |
+| `klp -v` | Print version |
+
+### Service Management
+
+```bash
+klp service start    # Start daemon (backgrounds automatically)
+klp service stop     # Stop daemon
+klp service status   # Check if running
+```
+
+## Configuration
+
+Config file: `~/.config/klp/config.json`
+
+```json
+{
+  "defaultLimit": 20,
+  "dbLocation": "/home/user/.klp.db",
+  "maxEntrySize": 0
+}
+```
+
+- `defaultLimit`: Default number of entries to show
+- `dbLocation`: Path to the clipboard history database
+- `maxEntrySize`: Maximum entry size in bytes (0 = unlimited)
+
+## Development
+
+### Build
+
+```bash
+make build
+```
+
+### Install locally
+
+```bash
+make install
+```
+
+### Project Structure
+
+```
+klp/
+├── main.go
+├── cmd/
+│   ├── root.go      # CLI commands
+│   └── service.go   # Daemon management
+└── internal/
+    ├── config/      # Viper configuration
+    ├── database/    # NDJSON storage
+    ├── clipboard/   # X11/Wayland clipboard access
+    ├── service/     # Clipboard monitoring
+    ├── search/      # Text search
+    └── tui/         # Interactive UI (Bubble Tea)
+```
+
+### Dependencies
+
+- [Cobra](https://github.com/spf13/cobra) - CLI framework
+- [Viper](https://github.com/spf13/viper) - Configuration
+- [Bubble Tea](https://github.com/charmbracelet/bubbletea) - TUI framework
+- [lipgloss](https://github.com/charmbracelet/lipgloss) - Terminal styling
+- [golang.design/x/clipboard](https://golang.design/x/clipboard) - X11 clipboard
+
+### Wayland Requirements
+
+For Wayland support, ensure `wl-paste` and `wl-copy` are installed:
+```bash
+# Fedora
+sudo dnf install wl-clipboard
+
+# Ubuntu/Debian
+sudo apt install wl-clipboard
+```