141 lines
4.1 KiB
Markdown
141 lines
4.1 KiB
Markdown
|
|
# rklipd
|
|
|
|
A lightweight clipboard history manager for Linux — daemon + TUI client.
|
|
|
|
|
|
|
|
|
|
|
|
## Features
|
|
|
|
- Captures text and images automatically (X11 polling & Wayland events)
|
|
- SQLite storage — images saved as JPEG (quality 70)
|
|
- Fuzzy search (`~`), regex search (`/pattern`), date filters (`after:2025-01` `before:2025-06-01`)
|
|
- Type filter: All / Text / Image (`t`)
|
|
- Per-entry AES-256-GCM encryption with Argon2 password (`e`)
|
|
- Syntax highlighting in preview (300+ languages via syntect)
|
|
- Image preview in terminal (sixel / kitty / halfblocks via ratatui-image)
|
|
- Undo last delete (`u`)
|
|
- IPC Unix socket — fully scriptable
|
|
|
|
## Architecture
|
|
|
|
```
|
|
rklipd (daemon) rklip (TUI client)
|
|
┌─────────────────────┐ ┌──────────────────────┐
|
|
│ monitor (X11/Wayland│──────────▶│ app.rs (state) │
|
|
│ database.rs (SQLite)│◀──IPC────▶│ ui.rs (ratatui) │
|
|
│ ipc.rs (Unix sock) │ │ ipc.rs (client) │
|
|
│ crypto.rs (AES-GCM) │ │ crypto.rs (Argon2) │
|
|
└─────────────────────┘ └──────────────────────┘
|
|
|
|
~/.local/share/com.zefad.rklipd/
|
|
├── clipboard.db # SQLite history
|
|
├── images/ # JPEG images
|
|
├── master.key # Machine key (enc:)
|
|
├── crypto2.salt # Argon2 salt (enc2:)
|
|
└── rklip.sock # IPC socket
|
|
```
|
|
|
|
## Build & Install
|
|
|
|
**Dependencies:** `libxcb` (X11) or Wayland libs, `libsqlite3`
|
|
|
|
```bash
|
|
# X11
|
|
cargo build --release --features x11 -p rklipd
|
|
cargo build --release -p rklip
|
|
|
|
# Wayland
|
|
cargo build --release --features wayland -p rklipd
|
|
cargo build --release -p rklip
|
|
|
|
# Install
|
|
sudo cp target/release/rklipd /usr/local/bin/
|
|
sudo cp target/release/rklip /usr/local/bin/
|
|
```
|
|
|
|
**Autostart (systemd user):**
|
|
|
|
```ini
|
|
# ~/.config/systemd/user/rklipd.service
|
|
[Unit]
|
|
Description=rklipd clipboard daemon
|
|
|
|
[Service]
|
|
ExecStart=/usr/local/bin/rklipd
|
|
Restart=on-failure
|
|
|
|
[Install]
|
|
WantedBy=default.target
|
|
```
|
|
|
|
```bash
|
|
systemctl --user enable --now rklipd
|
|
```
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
rklipd [OPTIONS] # start daemon
|
|
rklip # open TUI
|
|
|
|
Options:
|
|
--max-entries <N> Max history entries (default: 500)
|
|
--max-entry-size-kb <N> Max text entry size in KB (default: 512)
|
|
--expiry-days <N> Auto-delete entries > N days
|
|
```
|
|
|
|
## Keybindings
|
|
|
|
| Key | Action |
|
|
|-----|--------|
|
|
| `j` / `↓` | Next entry |
|
|
| `k` / `↑` | Previous entry |
|
|
| `Enter` | Paste selected & quit |
|
|
| `/` | Fuzzy search mode |
|
|
| `t` | Cycle type filter (All → Text → Image) |
|
|
| `e` | Encrypt / Decrypt selected entry |
|
|
| `dd` | Delete selected (confirm) |
|
|
| `u` | Undo last delete |
|
|
| `gg` / `G` | Jump to top / bottom |
|
|
| `Ctrl+j/k` | Scroll preview |
|
|
| `:clear` | Clear entire history |
|
|
| `:p` | Set session password |
|
|
| `q` / `:q` | Quit |
|
|
|
|
**Search syntax:**
|
|
|
|
```
|
|
rust # fuzzy match
|
|
/fn\s+\w+\( # regex (prefix with /)
|
|
after:2025-01 before:2025-06 config # date filters + text
|
|
```
|
|
|
|
## Encryption
|
|
|
|
Two independent layers:
|
|
|
|
| Prefix | Method | Key source | Use case |
|
|
|--------|--------|-----------|----------|
|
|
| `enc:` | AES-256-GCM | Machine key (`master.key`) | Legacy / auto |
|
|
| `enc2:` | Argon2 + AES-256-GCM | User password | Sensitive entries |
|
|
|
|
Press `e` on any entry to encrypt/decrypt with a password. Encrypted entries show as `🔒 [Chiffré]` and require your password to paste.
|
|
|
|
## IPC (scripting)
|
|
|
|
The daemon exposes a JSON Unix socket. Example with `socat`:
|
|
|
|
```bash
|
|
# Fetch last 5 entries
|
|
echo '{"GetHistory":{"limit":5}}' | socat - UNIX-CONNECT:~/.local/share/com.zefad.rklipd/rklip.sock
|
|
|
|
# Set clipboard content
|
|
echo '{"SetClipboard":{"content":"hello"}}' | socat - UNIX-CONNECT:...
|
|
|
|
# Clear history
|
|
echo '"ClearHistory"' | socat - UNIX-CONNECT:...
|
|
```
|