Metadata-Version: 2.4
Name: clipbox
Version: 0.5.0
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
- **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.

## 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     # run the test suite
make check    # lint and type-check
make format   # apply formatting
```
