No description
  • Python 99.2%
  • Dockerfile 0.8%
Find a file
Andrew Phillips 2128c1b12a
Some checks failed
Test / test (3.12) (push) Failing after 30s
Test / test (3.8) (push) Failing after 6s
Test / build (push) Has been skipped
refactor: DRY stdin handling; fix binary read in write mode
2026-06-07 19:53:19 -03:00
.gitea/workflows ci: add 'latest' tag on semver releases 2026-06-07 18:59:27 -03:00
tests fix(test): add from __future__ import annotations for Python 3.8 compatibility 2026-06-07 15:52:38 -03:00
Containerfile feat: add Containerfile and CI build job 2026-06-07 16:45:11 -03:00
px refactor: DRY stdin handling; fix binary read in write mode 2026-06-07 19:53:19 -03:00
pytest.ini test: add pytest suite (89 tests) 2026-06-07 15:38:53 -03:00
README.md initial commit: px clipboard file transfer tool 2026-06-07 14:23:44 -03:00

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 — -C outputs OSC 52 escape sequence (kitty, alacritty, wezterm, foot, …). Falls back to xclip/xsel when DISPLAY is 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