Metadata-Version: 2.4
Name: clipbox
Version: 0.5.1
Summary: Shared clipboard across devices
Requires-Python: >=3.14
Requires-Dist: aiosqlite>=0.20
Requires-Dist: fastapi>=0.110
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: uvicorn>=0.29
Description-Content-Type: text/markdown

# clipbox

A self-hosted shared clipboard for copying text between devices on your local network.

## Features

- **Named buffers** -- create multiple independent text buffers
- **File sharing** -- upload and download files alongside the text buffers
- **Auto-save** -- changes save automatically as you type, with a status indicator
- **Copy button** -- one-tap copy on both desktop and mobile
- **curl-friendly** -- read, write, and delete buffers from the terminal
- **One-line client setup** -- the server hands out its own `cb` and `fb` shell helpers
- **Mobile-friendly** -- responsive UI that works on phones and tablets, installable as a PWA
- **SQLite storage** -- persistent, zero-config database stored in the platform-appropriate data directory

Filenames are kept as sent -- spaces, accents, emoji and macOS screenshot names
all round-trip. Uploads are stored under an opaque name on disk, so nothing in a
filename can reach the filesystem.

## Install

Requires Python 3.14+. Use [uv](https://docs.astral.sh/uv/).

## Usage

```sh
uvx clipbox
```

_OR_

```sh
uvx clipbox --host 0.0.0.0 --port 8080
```

This starts the server on `http://0.0.0.0:8080`. Open it in a browser from any device on your network.

## Shell helpers

`cb` and `fb` wrap the API as shell commands, with tab completion and an
interactive picker. The running server hands them out, so on any machine that
can reach it:

```sh
curl -fsSL http://host:port/cli | sh
```

The server fills in its own address, so `CB_HOST` is already set correctly --
there is nothing to configure. The installer detects your shell, writes the
helpers to `~/.local/share/clipbox/`, adds a marked block to your `.bashrc` or
`.zshrc`, and picks a clipboard command for your platform. It touches nothing
outside your home directory and needs no `sudo`. Re-running it replaces the
block rather than duplicating it, and leaves your settings alone.

```sh
curl -fsSL http://host:port/cli | sh -s -- --print-only   # don't edit any rc file
curl -fsSL http://host:port/cli | sh -s -- --uninstall    # remove it again
curl -fsSL http://host:port/cli | sh -s -- --help         # all options
```

If you would rather nothing the server sends gets executed, fetch the helpers
directly and source them yourself -- the address is baked into this file too:

```sh
mkdir -p ~/.local/share/clipbox
curl -fsSL http://host:port/cli/shell.sh -o ~/.local/share/clipbox/clipbox.sh
echo '. ~/.local/share/clipbox/clipbox.sh' >> ~/.bashrc
```

On zsh, bash-style completion needs to be enabled first; the installer writes
this for you, but add it yourself if you are sourcing manually:

```sh
autoload -Uz compinit bashcompinit
(( $+functions[compdef] )) || compinit
bashcompinit
```

### Commands

```
cb copy [name]           Copy a buffer to the clipboard (omit name to pick one)
cb paste [content]       Write a new buffer, or read stdin
cb rename <name> <new>   Rename a buffer
cb delete [name]         Delete a buffer

fb send <file>...        Upload files
fb get [name]            Download a file (omit name to pick one)
fb delete [name]         Delete a file
```

### Settings

Your settings live in `~/.config/clipbox/config.sh`, which the installer
creates once and never overwrites:

```sh
export CB_HOST=http://host:port
export CB_COPY_CMD='pbcopy'   # wl-copy on Wayland, xclip -selection clipboard on X11
```

`jq` is required. `fzf` is optional -- without it the pickers fall back to a
numbered list.

## curl

### Clipboard operations

```sh
curl http://host:port/my-buffer                         # read a buffer
curl -X PUT -d 'text' http://host:port/my-buffer        # write to a buffer
curl -X PATCH -d 'new-name' http://host:port/my-buffer  # rename a buffer
curl -X DELETE http://host:port/my-buffer               # delete a buffer
curl http://host:port/api/buffers                       # list all buffers (JSON)
```

### File Operations

```sh
curl -F 'file=@photo.jpg' http://host:port/files/   # upload a file
curl http://host:port/files/filename                # download a file
curl -X DELETE http://host:port/files/filename      # delete a file
curl http://host:port/api/files                     # list all files (JSON)
```

### Environment variables

| Variable                | Default       | Description                                     |
| ----------------------- | ------------- | ----------------------------------------------- |
| `CLIPBOX_DATA`          | _(see below)_ | Directory holding the database and uploads      |
| `CLIPBOX_DB`            | _(see below)_ | Path to the SQLite database file                |
| `CLIPBOX_MAX_UPLOAD_MB` | `0`           | Reject uploads above this size (`0` = no limit) |

### Data storage

The database is stored in the platform-appropriate data directory by default,
with uploaded files in a `files/` subdirectory next to it:

| Platform | Path                                               |
| -------- | -------------------------------------------------- |
| Linux    | `~/.local/share/clipbox/clipbox.db`                |
| macOS    | `~/Library/Application Support/clipbox/clipbox.db` |
| Windows  | `%LOCALAPPDATA%\clipbox\clipbox.db`                |

Override with the `CLIPBOX_DB` environment variable.

## Development

```sh
make test              # Python test suite
./tests/test_shell.sh  # cb/fb integration tests (starts its own server)
./tests/test_install.sh # installer tests (installs into a sandboxed HOME)
make check             # lint and type-check
make format            # apply formatting
```
