Metadata-Version: 2.4
Name: clippy-clipboard
Version: 2.1
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 |

## 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 .
```

## Development

```
clippy/          the package
  core.py        history storage and helpers
  clipboard.py   cross-platform clipboard access
  cli.py         command-line interface, TUI, and GUI
```

Run the tests:

```sh
python -m pytest
```
