> ## Documentation Index
> Fetch the complete documentation index at: https://docs.otter-shell.org/llms.txt
> Use this file to discover all available pages before exploring further.

# otter-clip

> Clipboard manager with searchable history. Access entries via Super+V popup or CLI commands.

otter-clip is Otter Shell's clipboard manager. A long-lived daemon watches the Wayland data-control protocol and keeps a bounded history of text and image entries. Press Super+V to open the launcher popup. The package also ships `otter-copy` and `otter-paste`, native utilities that talk to data-control directly. In packaged installs they shadow `wl-copy` and `wl-paste`, so existing apps and scripts route through Otter's implementation without changes.

## Starting the Daemon

Run the daemon once per session.

```bash theme={null}
otter-clip daemon    # start monitoring clipboard selections
```

<Tip>
  Add `otter-clip daemon` to your compositor's autostart list so history is ready at login. Without the daemon, `otter-clip list`, `search`, and the Super+V popup have nothing to show.
</Tip>

## CLI Commands

| Command                    | Description                                    |
| -------------------------- | ---------------------------------------------- |
| `otter-clip popup`         | Open the Super+V history popup                 |
| `otter-clip popup query`   | Open the popup with a search term pre-filled   |
| `otter-clip list`          | Print all stored history entries               |
| `otter-clip search query`  | Filter history and print matching entries      |
| `otter-clip add some text` | Manually append a text entry to history        |
| `otter-clip clear`         | Delete all history entries                     |
| `otter-clip pin 0`         | Pin an entry by its index so it is not evicted |
| `otter-clip unpin 0`       | Remove the pin from an entry                   |
| `otter-clip select 0`      | Copy a history entry by index to the clipboard |

The `popup` command opens `otter-launcher --query "clip ..."`. Selecting a row calls `otter-clip select INDEX` to copy that item back to the clipboard. Pressing Enter in the popup is the same as running `otter-clip select` on the highlighted entry.

## Copying and Pasting

`otter-copy` and `otter-paste` replace `wl-copy` and `wl-paste`. They communicate with Wayland data-control directly.

```bash theme={null}
otter-copy text                          # copy a text argument
printf 'text' | otter-copy               # copy from stdin
png-tool | otter-copy --type image/png   # copy an image with an explicit MIME type
otter-paste                              # paste the current clipboard contents
otter-paste -n                           # paste without a trailing newline
wl-copy text    # resolved to otter-copy in packaged installs
wl-paste        # resolved to otter-paste in packaged installs
```

Point `otter-copy` and `otter-paste` at a custom history file with `--file /path/to/store` when you want an isolated clipboard store for scripting.

## Configuration

otter-clip reads `~/.config/otter-shell/otter-clip.conf` at daemon startup.

```conf theme={null}
# Optional; empty uses $XDG_CACHE_HOME/otter-shell/otter-clip-history
history_path = ""
```

* `history_path`: absolute path for history storage. Empty uses `$XDG_CACHE_HOME/otter-shell/otter-clip-history`

## Privacy and Password Managers

<Note>
  otter-clip skips clipboard entries that carry password manager or secret MIME hints before reading their data. Credentials copied from password managers do not end up in plain text history. Wayland data-control does not expose the source application ID for copied data, so app-ID filtering only applies when a source ID is available to the caller.
</Note>

## Image Support

otter-clip accepts text offers and common image MIME types from the clipboard. Images are stored as bounded blob files with MIME type and path metadata, not decoded and re-encoded. The otter-launcher popup can show image thumbnails inline when you open clipboard history with Super+V.