deadrop

Passcode-authenticated, ephemeral cloud pipeline file transfer and selective extraction CLI.

deadrop is a fast, zero-configuration command-line tool for sharing files and folders across machines using simple, human-readable keys (3 letters + 4 digits, e.g. abc-1234). It includes built-in archive inspection, selective file extraction, JSON manifest export, automatic unzipping, TTL expiration management, and headless/AI-agent friendly flags.

Features

• Zero Config: No account or login required. Upload and get a short key instantly.
• Human-Readable Keys: Standard format [a-z]{3}-[0-9]{4} (e.g. xyz-9876).
• Selective Extraction: Inspect zip contents before extracting. Download only the specific files you need by index, exact name, or wildcard pattern.
• Remote Inspection (-i see): Preview all files and sizes inside a drop directly in your console without downloading or saving anything to disk.
• JSON Metadata Export (-i getjson): Generate detailed JSON manifests of drop contents.
• Headless & Script Friendly: Explicit flags (-cr, -dl, -cx) eliminate interactive prompts for CI/CD pipelines, shell scripts, and autonomous AI coding agents.
• Auto-Packaging: Automatically packages folders, multi-file arguments, or executable/sensitive scripts into a secure zip archive.
• Auto TTL & Key Management: Configurable time-to-live (-1d, -12h, -30m), rekeying, and deadline extension.
• Path Traversal Protection: Safe extraction prevents zip-slip vulnerabilities.

Installation

Install via pip:

pip install deadrop

Or upgrade to the latest version:

pip install --upgrade deadrop

Requirements: Python 3.7+. Uses standard Python libraries only (zero heavy external dependencies).

Quick Start

1. Upload a File or Folder

# Upload a single file
deadrop up document.pdf

# Upload a folder
deadrop up ./my-project

# Upload with custom key and custom expiration (12 hours)
deadrop up ./src -key dev-4040 -12h

Output:

› staging  my-project.zip
✔ uploaded my-project.zip
· key      pyt-1234
· expires  24h

2. Download or Unpack

# Full download and unpack to current folder (non-interactive)
deadrop down pyt-1234 -uz -cr

# Preview files inside the drop without downloading
deadrop down pyt-1234 -i see

# Selectively extract specific files by name
deadrop down pyt-1234 -i sname "main.py, config.json" -cr

# Interactive file picker
deadrop down pyt-1234 -i

Complete Command Reference

1. deadrop up — Upload Files and Folders

Uploads one or more local files or directories to the gateway.

deadrop up <path> [<path> ...] [-n name] [-e ext] [-key ABC-1234] [-<time_flag>]

Packaging Behavior: Folders, multiple files, or sensitive script/executable types (.py, .sh, .bat, .exe, .js, etc.) are automatically packed into a zip archive for safe staging and staging bypass.

2. deadrop down — Download, Preview & Extract

Downloads a drop from the gateway using its key.

deadrop down <key> [-uz] [-i [subcommand] [args]] [-dl | -cr | -cx [path]]

Destination Flags (Non-Interactive / Headless)

By default, deadrop down prompts you to choose a download location. Pass one of these flags to skip the prompt:

Archive & Extraction Options

Extraction Suffix Protection (-dd)

When extracting a zip archive that contains a top-level directory (e.g. project/), deadrop automatically appends -dd to the extracted root folder (e.g. project-dd/). This prevents accidental overwriting of existing local source folders.

3. deadrop info — Inspect Drop Metadata

Checks if a key is active, displays the files contained, and shows remaining time before expiration without downloading.

deadrop info <key>

Example:

· Drop Tracking Information: pyt-1234
· Active TTL Remaining: 23h 45m
· Trackable Manifest Nodes (1):
  - project.zip

4. deadrop clear — Purge a Drop

Immediately and permanently purges the drop mapping and deletes the file from storage.

deadrop clear <key>

5. deadrop extend — Extend Drop Expiration

Increases the active lifetime of an existing drop.

deadrop extend <key> -<time_flag>

Example:

# Add 2 more days to abc-1234
deadrop extend abc-1234 -2d

6. deadrop rekey — Remap Drop Key

Reassigns an existing drop to a new key.

deadrop rekey <old_key> <new_key>

Example:

deadrop rekey pyt-1234 dev-5678

7. deadrop ping — Health Check

Tests network connectivity, latency, and operational status of the gateway backend.

deadrop ping

8. deadrop version — Check Engine Version

Displays the current version of the CLI client.

deadrop version

AI Agent & Automation Guidelines

If you are an AI coding assistant, subagent, or automation script interacting with deadrop, follow these guidelines to prevent hangs:

1. Avoid Blocking Prompts:
   • Always supply -cr (current directory) or -dl (downloads directory) to avoid interactive destination prompts on stdin.
2. Inspect Before Download:
   • Use deadrop down <key> -i see to preview what files exist inside the drop without downloading anything to disk.
3. Selective Extraction:
   • To extract only relevant source files:

     deadrop down <key> -i spat "*.py,*.json" -cr
     

4. Full Unpack:
   • To fetch and extract all files unattended:

     deadrop down <key> -uz -cr
     

5. Manifest Extraction:
   • To inspect file trees programmatically, run:

     deadrop down <key> -i getjson -cr
     

   • Then parse the generated <name>-dd.json file.

Environment Variables

License

MIT License. See LICENSE for details.