dropby

Ephemeral file drops from your terminal — push an .html or .md file, get a short-lived, self-destructing link.

dropby is the CLI companion to dropby. Drop a file, get a link, share it — it deletes itself when the timer runs out (or on first read, if you arm burn mode). No account, no config required.

$ dropby push report.md --ttl 1h --burn

  ✓ dropped report.md (8.4 KB)
    slug      falcon
    link      https://site.sachinthapa.tech/falcon
    expires   in 60:00 · burn-after-reading armed

Install

# with bun
bun add -g @sachinthapa/dropby

# or npm / pnpm
npm install -g @sachinthapa/dropby

The dropby command is installed. Requires Node ≥ 18 or Bun (uses the platform fetch/FormData).

Or for development/testing, install by bun link

Standalone binary (no Node/Bun required)

bun run build:compile   # → dist/dropby (single self-contained executable)
./dist/dropby push report.md --ttl 1h

build:compile uses bun build --compile to embed the Bun runtime, producing a single native binary for the current platform — handy for GitHub release artifacts or machines without a JS runtime. The npm package itself ships the lightweight dist/cli.js (runs on both Node and Bun); the compiled binary is opt-in.

Usage

dropby <command> [options]

push <file>

Drop an .html, .htm, or .md file (max 512 KB).

| Option | Alias | Description | | ----------------- | ----- | ---------------------------------------------------- | | --ttl <dur> | -t | Lifetime: 15m, 30m, or 1h (default 30m) | | --burn | -b | Self-destruct after the first read by anyone but you | | --encrypt | -e | End-to-end encrypt; prompt for a passphrase | | --password <pw> | -p | Encrypt with this passphrase (no prompt) | | --slug <name> | -s | Custom URL slug (a–z, 0–9, -) | | --host <url> | -H | dropby server origin | | --copy | -c | Copy the resulting link to the clipboard | | --open | -o | Open the link in your browser | | --json | | Print the raw JSON response (good for scripts) | | --no-color | | Disable coloured output |

dropby push index.html --slug launch --copy
dropby push notes.md --ttl 15m --json
dropby push secret.md --encrypt        # prompts for a passphrase

paste

Drop HTML piped in on stdin.

cat page.html | dropby paste --ttl 1h --slug preview
echo '<h1>hi</h1>' | dropby paste --burn

Password-protected drops

--encrypt (or --password) encrypts the content in the CLI before upload — AES-GCM with a key derived from your passphrase (PBKDF2, 600k iterations). The server only ever stores ciphertext; it never sees the passphrase or the plaintext. Recipients open the link and enter the passphrase to decrypt it in their browser.

Passphrase source, in order: --password <pw> → DROPBY_PASSWORD env → hidden interactive prompt (read from the terminal, so it works even when piping into paste). A lost passphrase is unrecoverable. The drop shows a 🔒 flag in dropby list.

dropby push secret.md --encrypt                       # hidden prompt (+ confirmation)
DROPBY_PASSWORD=hunter2 dropby push notes.md --encrypt # from env (scripts/CI)
cat report.html | dropby paste --encrypt --slug q3     # encrypt piped HTML

Encryption is offline-brute-forceable against the delivered ciphertext, so the passphrase's strength is the only protection — choose a strong one.

view <slug>

View a drop's content directly in the terminal. Markdown drops are rendered with syntax highlighting; HTML drops print their source. For encrypted drops, the passphrase is prompted in the terminal and decryption happens locally (zero-knowledge — the server only ever sees ciphertext).

dropby view falcon-otter                          # render markdown in terminal
dropby view secret-note                           # prompts for passphrase
dropby view notes --raw > notes.md                # save raw plaintext to file
DROPBY_PASSWORD=hunter2 dropby view secret-note    # passphrase from env

| Option | Alias | Description | | ----------------- | ----- | -------------------------------------------------------- | | --password <pw> | -p | Passphrase for an encrypted drop (no prompt) | | --host <url> | -H | dropby server origin | | --raw | | Print the plaintext without rendering (great for piping) | | --json | | Print the raw JSON response (good for scripts) | | --no-color | | Disable coloured output |

config

The target host is resolved as: --host flag → DROPBY_HOST env → config file → built-in default.

dropby config                       # show effective host + config path
dropby config set host http://localhost:8788
dropby config get host
dropby config unset host            # revert to default

completion

Shell completion for bash, zsh, and fish — tab-complete commands, flags, and flag values.

# auto-detect shell and install to XDG paths
dropby completion install

# or print the script for a specific shell
dropby completion bash   > /etc/bash_completion.d/dropby
dropby completion zsh    > /usr/local/share/zsh/site-functions/_dropby
dropby completion fish   > ~/.config/fish/completions/dropby.fish

After install, restart your shell or source the file:

• bash: source "$(dropby completion bash | head -1)"
• zsh: autoload -Uz compinit && compinit
• fish: works immediately (fish sources ~/.config/fish/completions/ automatically)

Install paths follow XDG Base Directory (2026 standard):

| Shell | Default path | | ----- | ------------ | | bash | $XDG_DATA_HOME/bash-completion/completions/dropby | | zsh | $XDG_DATA_HOME/zsh/site-functions/_dropby | | fish | $XDG_CONFIG_HOME/fish/completions/dropby.fish |

The completion script calls dropby completion suggest at runtime — completions are always in sync with the installed CLI. Supports subcommands (push, paste, config, etc.), flags (--ttl, --burn, --slug, …), and common flag values.

Scripting

--json writes a clean object to stdout (status chatter goes to stderr):

url=$(dropby push build/index.html --ttl 1h --json | jq -r .url)

Development

This package uses Bun as its package manager, bundler, and test runner.

bun install
bun run dev -- push README.md --host http://localhost:8788   # run from source
bun test                                                     # unit tests
bun run typecheck                                            # tsc --noEmit
bun run build                                                # bundle to dist/cli.js

License

MIT