clipboard-history

# clipboard-history

CLI tool for persistent clipboard history with search and restore.

## Quick Start

```bash
# Start the background daemon
clp daemon start

# List recent history
clp list

# Search history
clp search "function fetch"

# Restore item to clipboard
clp get 1041 --copy

# Interactive picker
clp pick
```

## Daemon

The daemon runs in the background and polls the clipboard every 500ms. It must be running to capture new entries.

```bash
clp daemon start       # start background daemon
clp daemon stop        # stop daemon
clp daemon status      # check if running
```

Add `clp daemon start` to your shell profile to start automatically.

## List History

```bash
clp list                    # last 20 entries
clp list --limit 50         # show more
clp list --today            # today only
clp list --type url         # filter by type: url, code, email, text
```

## Search

```bash
clp search "error message"       # full-text search
clp search "function fetch"      # multi-word search
clp search '"exact phrase"'      # phrase search
```

## Get and Restore

```bash
clp get 1041                # show full content of entry
clp get 1041 --copy         # copy to clipboard
clp pick                    # interactive numbered picker
```

## Delete

```bash
clp delete 1041             # delete with confirmation
clp delete 1041 --yes       # delete without prompt
clp clear                   # clear all history (prompts)
clp clear --yes             # clear without prompt
```

## Statistics

```bash
clp stats                   # total entries, type breakdown, DB size
clp config                  # database path, limits, poll interval
```

## Content Types

| Type | Detection Rule |
|---|---|
| `url` | Starts with http:// or https:// |
| `email` | Matches email address pattern |
| `code` | Has newlines + programming syntax |
| `text` | Everything else |

## Environment Variables

| Variable | Default | Description |
|---|---|---|
| `CLP_DB_PATH` | `~/.local/share/clipboard-history/db.sqlite` | Database path |
| `CLP_MAX_ENTRIES` | `10000` | Maximum entries before pruning oldest |
| `CLP_POLL_MS` | `500` | Daemon polling interval (milliseconds) |
| `CLP_NO_COLOR` | `0` | Disable ANSI color (1 to disable) |
| `CLP_DEBUG` | `0` | Enable debug logging (1 to enable) |

## Exit Codes

| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | No results / empty history |
| 2 | Daemon error |
| 3 | Runtime error |