drop

简体中文 | English

Share local files, folders, stdin content, and Git diffs through time-limited preview URLs.

drop is a small CLI for turning local content into browser-friendly preview links. It starts a local web server when needed, stores share state under ~/.drop, and renders common developer formats with readable previews.

Why use it?

• Share code, logs, configs, Markdown, CSV, media, or generated artifacts without leaving the terminal.
• Give an AI coding agent a reliable way to show files it created or edited.
• Share a whole project directory with a searchable file tree and split-pane preview UI.
• Turn a Git commit into a readable page with metadata and highlighted diffs.
• Keep access temporary by default with TTL-based links.

At a Glance

Contents

• Quick Start
• How It Works
• For AI Agents
• Install
• Usage
• Commands
• Configuration
• Rendering
• Security Model
• Public Access
• Development

Quick Start

Install the latest release:

curl -fsSL https://raw.githubusercontent.com/junping1/drop/master/install.sh | bash

Share a file:

drop README.md

Share a directory:

drop .

Share piped content:

git diff | drop share --type diff --title "current changes"

Each command prints a URL. Open it in a browser or send it to someone who should be able to preview the content.

How It Works

1. The CLI records an authorization in the local SQLite database.
2. The daemon serves private token URLs from your machine.
3. The browser requests /f/:token, /d/:token, or /git/:token.
4. The server checks expiry, reads local content, and returns a rendered preview or raw file.

Runtime state lives in ~/.drop/:

For AI Agents

Copy this block into your coding agent instructions so it can install and use drop consistently:

Install and use `drop`, a CLI tool for sharing local files through time-limited preview URLs.

Install:
  curl -fsSL https://raw.githubusercontent.com/junping1/drop/master/install.sh | bash

Expose links:
  drop serve
  # If you use an external tunnel, set the public URL:
  drop config set base_url https://your-domain.example

Use:
  drop /path/to/file                           # share a file
  drop /path/to/dir                            # share a browsable directory
  drop /path/to/file --ttl 3600                # custom TTL in seconds
  drop /path/to/file --live                    # auto-refresh when the file changes
  echo "content" | drop share --type markdown  # share piped content
  git diff | drop share --type diff            # share a diff
  drop list                                    # list active shares

Behavior:
  - After creating or editing a file that the user should inspect, run `drop` on it and send the URL.
  - When the user asks to see a file, show a preview, or get a link, use `drop`.
  - For directories, use `drop /path/to/dir` so the user gets the browsable UI.
  - Do not share secrets, `.env` files, API keys, tokens, or credential backups.

AI Decision Rules

Machine-readable summary:

tool: drop
purpose: Share local content through temporary preview URLs.
default_ttl_seconds: 86400
state_dir: ~/.drop
share_file: drop /path/to/file
share_directory: drop /path/to/dir
share_stdin: command | drop share --type text
share_diff: git diff | drop share --type diff
list_shares: drop list
stop_daemon: drop stop
never_share:
  - .env
  - API keys
  - OAuth credentials
  - tokens
  - password files
  - database backups

Install

One-line install for Linux/macOS:

curl -fsSL https://raw.githubusercontent.com/junping1/drop/master/install.sh | bash

Install from a fork or another release repository:

curl -fsSL https://raw.githubusercontent.com/owner/drop/master/install.sh | DROP_REPO=owner/drop bash

Build from source:

git clone https://github.com/junping1/drop.git
cd drop
bun install
bun run build
cp dist/drop-linux-x64 ~/.local/bin/drop

Source builds require Bun v1.0+.

Usage

The allow subcommand is implicit:

drop ~/file.py
drop allow ~/file.py

Both commands share the same file. The daemon starts automatically if it is not already running.

Choosing the right command

Files

drop ~/file.py                     # share a file
drop ~/file.py --ttl 300           # expire in 5 minutes
drop ~/file.py --head 50           # show only the first 50 lines
drop ~/file.py --tail 50           # show only the last 50 lines
drop ~/file.py --live              # reload preview when the file changes

Directories

drop ~/project/                    # share a browsable file tree
drop ~/project/ --ttl 7200         # custom TTL
drop ~/project/ --exclude '*.log'  # add exclude patterns
drop ~/project/ --live             # refresh when the directory changes

Default excludes: .git/, __pycache__/, .env, node_modules/, .DS_Store, *.pyc, .venv/.

Stdin

echo "# Hello" | drop share --type markdown
git diff | drop share --type diff --title "my changes"
drop share --content "print('hi')" --type python

Supported types: markdown, python, javascript, json, yaml, html, css, shell, diff, code, text.

Git Commits

drop allow-git /path/to/repo abc1234
drop allow-git . HEAD

Git commit shares render commit metadata, changed files, and expandable highlighted diffs.

Commands

Configuration

drop config set base_url https://files.example.com
drop config get base_url

Rendering

Security Model

• Nothing is accessible until it is explicitly shared.
• Shares expire automatically according to their TTL.
• File, directory, and Git tokens are at least 32 hex characters (128 bits), and owner keys are 32 hex characters.
• Directory access uses path traversal checks and symlink validation.
• Responses include anti-crawler headers and robots.txt disallows indexing.
• Owner access uses HMAC-signed cookies and timing-safe key comparison.
• Current rate limiting is 300 requests per minute per client identity. Proxy headers are ignored unless DROP_TRUST_PROXY=1 is set for a trusted reverse proxy.
• Markdown raw HTML is escaped, SVG is rendered as an image preview, and template-controlled metadata is HTML-escaped.

Important boundaries:

• Unexpired token URLs are bearer links. Anyone with the URL can access the shared content until it expires or is revoked.
• Markdown raw HTML is escaped, SVG is rendered through an image preview, and template-controlled file metadata is HTML-escaped. Still treat shared files as bearer-link content and avoid sharing untrusted or sensitive material.
• Avoid sharing secrets, .env files, API keys, OAuth credentials, database backups, or directories that may contain them.

Public Access

For local-only use, the default URL is usually enough:

drop README.md

For public sharing, run your preferred tunnel and set base_url:

cloudflared tunnel --url http://localhost:17173
ngrok http 17173
tailscale funnel 17173

drop config set base_url https://your-domain.example

The CLI exposes a drop serve --tunnel option, but verify the current implementation before relying on built-in tunnel behavior in production workflows.

Development

bun install
bun run dev:serve          # start server in foreground
bun run build:web          # build the Svelte directory browser
bun run dev:web            # run the Svelte dev server
bun run build              # compile a standalone binary
bun run verify             # run the project verification entrypoint

License

MIT