Metadata-Version: 2.4
Name: clippy-clipboard
Version: 2.2
Summary: A clipboard manager for the terminal
Author: Ishan Sreejith
License: MIT
Project-URL: Homepage, https://github.com/Parth7864/clippy
Project-URL: Repository, https://github.com/Parth7864/clippy
Keywords: clipboard,manager,history,terminal,tui,gui
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: MacOS X
Classifier: Environment :: Win32 (MS Windows)
Classifier: Environment :: X11 Applications
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Desktop Environment
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# clippy

A clipboard manager for the terminal. It watches your clipboard, keeps a searchable
history of everything you copy, and lets you re-copy, favorite, edit, or export old
items. No dependencies, just the standard library. Works on macOS, Linux, and Windows.

## Install

The quickest way to get a `clippy` command that works from any directory:

```sh
./install.sh
```

This copies the app into `~/.local/lib/clippy` and puts a `clippy` launcher in
`~/.local/bin`. If `~/.local/bin` isn't on your PATH yet, add it:

```sh
echo 'export PATH="$PATH:$HOME/.local/bin"' >> ~/.zshrc
```

### As a Python package

Installable as a normal package, either from source or from PyPI once published:

```sh
pip install .                     # from the repo
pipx install .                    # isolated, via pipx
pip install clippy-clipboard      # from PyPI (name on PyPI is clippy-clipboard)
```

Using it as a library:

```python
from clippy import ClipboardManager, add, search, stats, top

add("hello world")
print(search("hello"))
```

### Other install options

```sh
./install.sh --pip       # install via pip into a private venv
./install.sh --system    # install into /usr/local/bin (run with sudo)
./install.sh --uninstall # remove everything it installed
```

You can also skip installing and run from the repo:

```sh
python -m clippy
```

## Where your history lives

History is stored in one global file, `~/.clippy_history.json`, so it's the same no
matter which directory you're in. If you had an older `data.json` lying around, it gets
copied over automatically the first time you run clippy.

You can point clippy at a different file with the `CLIPPY_DATA` environment variable —
handy for testing:

```sh
CLIPPY_DATA=/tmp/try.json clippy watch
```

Each entry keeps the text, a timestamp, how many times it was copied, and an optional
favorite flag. History is capped at 500 items, dropping the oldest when new copies come
in.

## Using it

Run `clippy` with no arguments to open the interactive menu. Everything you copy while
it's open gets added automatically.

    clippy

To just log copies to the terminal instead of the menu:

    clippy watch

### Commands

| Command | What it does |
| --- | --- |
| `menu` | Interactive menu (this is the default) |
| `watch` | Watch the clipboard and log new copies |
| `history` | List everything you've saved |
| `search <query>` | Search your saved text |
| `top [n]` | Most-copied items, top 10 by default |
| `stats` | Some aggregate stats |
| `favorite <index>` | Toggle the favorite flag on an item |
| `edit <index>` | Open an item in your `$EDITOR` |
| `delete <range>` | Delete by index, e.g. `3`, `3-10`, `1,3,7`, or `all` |
| `truncate <n>` | Keep only the first `n` items |
| `dedupe` | Remove duplicate entries |
| `backup` | Copy the data file with a timestamp |
| `export [json\|txt\|md] [file]` | Write history out to a file |
| `import <file.json>` | Merge entries in from a JSON file |
| `gui` | A small windowed app, if you have tkinter |
| `get <index>` | Print an item's text (1 = most recent). Great for scripts |
| `set <text>` | Add an item to history and copy it to the clipboard |
| `api <path>` | Call the running server's REST API (see below) |
| `serve` | Host a local web page + REST API on localhost |

Every read/write command prints an exit code of `0` on success, and most accept a `--json`
flag that emits machine-parseable JSON instead of human text. Combine this with the global
`CLIPPY_DATA` env var and clippy becomes scriptable:

```sh
clippy history --json                 # full history as JSON
clippy search "deploy" --json         # matching items as JSON
clippy stats --json                   # aggregate stats as JSON
clippy get 1                          # just the most recent item's text
clippy get 3 --json                   # the 4th item's full record
CLIPPY_DATA=/tmp/project.json clippy set "$(pwd)"   # capture cwd
```

For `get`, `set`, and `api`, pass `--json` to force JSON output. For the other commands
`--json` switches their output to JSON.

## Menu keys

```
j/k or arrows   move up/down
f/b or PgUp/Dn  page
g / G           jump to top / bottom
enter           copy the selected item
/               search (Enter to search, n for next match)
e               edit in $EDITOR
f               toggle favorite
F               only show favorites
d               delete the selected item
c               clear the whole history
q               quit
```

## GUI

`clippy gui` opens a frameless, draggable window with a live-updating list, a search
box, and a range-delete field (try `3-10` or `all`). Double-click an item to copy it.

It needs a Python built with tkinter:

- macOS: `brew install python-tk@3.14`
- Debian/Ubuntu: `sudo apt install python3-tk`

If you installed with pipx and `clippy gui` complains about tkinter, reinstall using a
Python that has it:

```sh
pipx install --python /usr/bin/python3 .
```

## Local server & REST API

`clippy serve` starts a small local HTTP server so another program — a script, a browser, a
widget, an editor plugin — can read and drive clippy over HTTP. It has zero dependencies
(built on Python's standard library) and binds to `127.0.0.1` only, so nothing is exposed
to the network.

```sh
clippy serve                     # picks a free port, prints the URL
clippy serve --port 8765         # run on a specific port
clippy serve --host 0.0.0.0      # listen on all interfaces (be careful!)
```

On startup it prints the web dashboard URL, plus three things aimed at developers:

- `http://127.0.0.1:<port>/api/docs`         — human-readable API reference
- `http://127.0.0.1:<port>/api/openapi.json` — machine-readable OpenAPI 3.0 spec
- `http://127.0.0.1:<port>/api/health`       — liveness probe for uptime checks

Visit the printed URL in a browser to get a small dashboard where you can read the current
clipboard, set it, save items, search, and manage history.

### Developer / API endpoints

All endpoints return JSON and accept cross-origin requests, so browser widgets and other
tools can use them directly. The `openapi.json` spec describes the whole surface for
codegen, API clients, and editors.

| Method | Path | What it does |
| --- | --- | --- |
| `GET` | `/` | The web dashboard |
| `GET` | `/api/status` | Server status, version, item count, current clipboard |
| `GET` | `/api/health` | Liveness probe — `{"status":"ok"}` |
| `GET` | `/api/docs` | Human-readable API reference page |
| `GET` | `/api/openapi.json` | Machine-readable OpenAPI 3.0 spec |
| `GET` | `/api/clipboard` | Current clipboard text (`{"clipboard": "..."}`) |
| `POST` | `/api/clipboard` | Set the clipboard. Body: `{"text": "..."}` |
| `GET` | `/api/history` | Full history (`{"items": [{"index", "text", ...}]}`) |
| `POST` | `/api/history` | Add an item. Body: `{"text": "..."}` |
| `DELETE` | `/api/history` | Clear all history |
| `GET` | `/api/history/<i>` | One item |
| `PUT` | `/api/history/<i>` | Update one item. Body: `{"text": "..."}` |
| `DELETE` | `/api/history/<i>` | Delete one item |
| `POST` | `/api/history/<i>/favorite` | Toggle favorite |
| `POST` | `/api/history/<i>/copy` | Copy the item to the clipboard |
| `GET` | `/api/search?q=<query>` | Search history |
| `GET` | `/api/top?n=<count>` | Most-copied items |
| `GET` | `/api/stats` | Aggregate stats |
| `GET` | `/api/favorites` | Favorite items |
| `GET` | `/api/count` | Number of saved items |
| `GET` | `/api/backup` | Create a timestamped backup file |
| `GET` | `/api/export?format=json\|txt\|md` | Export history |

From another program, this makes clippy a small self-hosted clipboard service. For example,
from any language with HTTP:

```sh
curl -s http://127.0.0.1:8765/api/health
curl -s http://127.0.0.1:8765/api/history
curl -s -X POST http://127.0.0.1:8765/api/history -H 'Content-Type: application/json' -d '{"text":"pasted via curl"}'
curl -s -X POST http://127.0.0.1:8765/api/clipboard -H 'Content-Type: application/json' -d '{"text":"new clipboard"}'
```

Handy without a dedicated HTTP client, the `api` command shells out to the running server:

```sh
clippy api /api/history                     # GET, prints pretty JSON
clippy api /api/search?q=deploy
clippy api /api/health                       # liveness probe
clippy api /api/openapi.json                 # machine-readable OpenAPI spec
clippy api /api/docs --json=false            # fetch the reference page as raw HTML
clippy api /api/history --method POST --data '{"text":"hello from a script"}'
clippy api /api/clipboard --method POST --data '{"text":"new clipboard value"}'
clippy api /api/history/3 --method DELETE
clippy api / --json=false                    # vanilla output, no pretty-print
```

`api` talks to `127.0.0.1:8765` by default; point it elsewhere with `--port`.

## Development

```
clippy/          the package
  core.py        history storage and helpers
  clipboard.py   cross-platform clipboard access
  server.py      local HTTP server, REST API, and web page
  cli.py         command-line interface, TUI, and GUI
```

Run the tests:

```sh
python -m pytest
```
