No description
- Python 99.2%
- Dockerfile 0.8%
| .gitea/workflows | ||
| tests | ||
| Containerfile | ||
| px | ||
| pytest.ini | ||
| README.md | ||
px — Terminal Clipboard File Transfer
Compress, integrity-protect, and base64-encode files into a single string for clipboard transfer between terminals.
Format
PX01.b64.<compress>.<type>:<data_b64>.<integrity_b64>.<size>
| Segment | Description |
|---|---|
PX01 |
Version identifier |
b64 |
Encoding (base64) |
<compress> |
xz | lz4 | gz | bz2 | zstd |
<type> |
sha256 | sha384 | sha512 | hmac-sha256 | hmac-sha384 | hmac-sha512 |
<data_b64> |
Compressed payload, base64-encoded |
<integrity_b64> |
Hash or HMAC of PX01.b64.<compress>.<type>:<data_b64> |
<size> |
Character length of PX01.b64.<compress>.<type>:<data_b64>.<integrity_b64> |
The : delimiter separates header from data. Both hash and HMAC cover the encoded message (header:data_b64) — HMAC adds authentication with a secret key. The <size> field covers the integrity value, catching truncation before any verification.
Usage
# Encode (hash integrity, default sha256):
./px file.txt
# Encode with HMAC:
./px -t hmac-sha256 -k "secret" file.txt
# Decode:
./px -w output.txt # reads from stdin
# Full roundtrip:
./px file.txt | ./px -w output.txt
# With HMAC:
./px -t hmac-sha256 -k "secret" file.txt | ./px -w output.txt -k "secret"
# Copy directly to clipboard (OSC 52):
./px -C file.txt
# Different compression:
./px -c lz4 file.txt
# HMAC key via environment:
PX_HMAC_KEY="secret" ./px -t hmac-sha256 file.txt
Features
- Zero dependencies — Python 3 stdlib only
- Compression — xz, lz4, gzip, bzip2, zstd (system binaries)
- Integrity — SHA-256/384/512 hashing or HMAC-SHA-256/384/512
- Clipboard —
-Coutputs OSC 52 escape sequence (kitty, alacritty, wezterm, foot, …). Falls back toxclip/xselwhenDISPLAYis set. - Copy/paste tolerant — all whitespace stripped before parsing
- Streaming decompression — hash verified during write, not after buffering
- Compact metadata — decimal size, single integrity field