| name | zerobin |
| description | Create, read, and delete zero-knowledge encrypted pastes on ZeroBin or PrivateBin v2 instances. Use when the user wants to share sensitive text, code snippets, secrets, logs, or temporary data with end-to-end encryption — the server never sees plaintext. Triggers on requests like "share this securely", "encrypt and paste", "create a private paste", "burn after reading", or any mention of zerobin, privatebin, or encrypted pastebin. |
| license | Apache-2.0 |
| compatibility | Requires Node.js 18+ to run the zerobin CLI via npx. Default server is https://zerobin.cc but any PrivateBin v2 compatible instance works. |
| metadata | {"author":"zerobin","version":"1.0"} |
ZeroBin
Encrypt content client-side with AES-256-GCM, upload only ciphertext, and share a URL whose decryption key lives in the URL fragment (never sent to the server). The recipient pastes the URL — the browser or CLI decrypts locally.
Quick reference
| Goal | Command |
|---|
| Create a paste | echo "secret" | npx zerobin-cli create |
| Create from file | npx zerobin-cli create --file ./notes.md |
| Read a paste | npx zerobin-cli read "<url>" |
| Delete a paste | npx zerobin-cli delete "<url>" <deletetoken> |
The default server is https://zerobin.cc. Override with --server <url> or set ZEROBIN_SERVER.
Prerequisites
Verify the CLI is reachable before running operations:
npx zerobin-cli --version
If that fails with "command not found" or a registry error, run scripts/zerobin-check.sh for a friendly install hint, or instruct the user to install Node.js 18+ and retry.
Create a paste
The CLI reads plaintext from stdin (preferred) or a file. It generates a random 256-bit key, encrypts locally, uploads only ciphertext, and prints the share URL.
From stdin:
echo "my secret note" | npx zerobin-cli create
From a file:
npx zerobin-cli create --file ./secrets.txt
Common options:
--burn — paste self-destructs on first read--password <pass> — adds a second factor (recipient also needs the password)--expire <when> — 5min, 10min, 1hour, 1day, 1week (default), 1month, 1year, never--discussion — allow encrypted comments--format <fmt> — plaintext (default), syntaxhighlighting, markdown--server <url> — target a different ZeroBin/PrivateBin instance--json — emit { url, id, deletetoken, server, key } instead of just the URL
Important: create writes the share URL to stdout and the delete token to stderr. If the user wants to delete the paste later, capture both:
output=$(echo "data" | npx zerobin-cli create --json)
url=$(echo "$output" | jq -r .url)
token=$(echo "$output" | jq -r .deletetoken)
Read a paste
The decryption key lives in the URL fragment (#...). Always quote URLs in shell so the fragment is preserved:
npx zerobin-cli read "https://zerobin.cc/?abc123def4567890#3F4xK..."
If the paste is password-protected, pass --password. If the paste was created with --burn, the first read deletes it server-side.
Delete a paste
Requires the original URL and the delete token captured at creation time:
npx zerobin-cli delete "https://zerobin.cc/?abc...#key..." <deletetoken>
Configuration
| Variable | Effect |
|---|
ZEROBIN_SERVER | Default server URL (overridden by --server) |
Security notes
- The decryption key is generated locally and never transmitted to the server. It travels in the URL fragment, which browsers do not include in HTTP requests.
- Anyone with the full URL (including
#key) can decrypt the paste. Treat the share URL like a password.
--password adds a layer beyond the URL key. Useful when the URL might be observed (e.g., shoulder-surfing a chat log).--burn is best-effort: the server deletes after the first successful read, but the recipient could screenshot the result before the burn completes.
Error handling
| Symptom | Likely cause | Fix |
|---|
Paste not found or expired | Burn-after-reading already triggered, expired, or wrong ID | Confirm the URL; pastes cannot be recovered after expiry |
Invalid base58 character | URL fragment was mangled or unquoted | Re-paste the full URL inside quotes |
URL is missing decryption key fragment | The #... portion was stripped | Ensure the entire URL including the hash was preserved |
400 / Invalid data | Server rejected payload (size, format) | Check paste size limit; default cap is 10 MB |
| Network/DNS error | Server unreachable | Verify --server value or network |
When NOT to use
- Storing the only copy of important data — pastes expire and can be deleted by anyone with the URL.
- Compliance scenarios requiring audit logs of who accessed data — the server has no view into reads.
- Real-time secure messaging — Signal or similar tools are the right shape for that.
See also
references/api-reference.md — raw HTTP API for agents that prefer not to use the CLIreferences/examples.md — runnable example commands and shell snippets
