teledrop

File transport that works everywhere - Even behind corporate firewalls, proxies, and locked-down environments.

teledrop uses GitHub releases as a transport layer, allowing you to securely move files between environments using just a memorable phrase.

Why teledrop?

• ✅ Works when everything else is blocked - Email blocked? VPN unavailable? SSH denied? teledrop just needs GitHub.
• 🔐 Encrypted by default - AES-256-CBC with PBKDF2 (600k iterations)
• 🧠 One phrase to rule them all - Same mnemonic to push and pull
• 📦 Multiple files/directories - Package one or many paths at once
• 🌍 Cross-platform - Linux, macOS, Windows (Git Bash)
• 🚀 Dead simple - Two commands, one concept
• 🎯 No authentication needed - Downloads are public URLs (but encrypted)
• 💪 Manual fallback - When npx/curl are blocked, use browser + bash function

Quick Start

🚀 Installation (npx - easiest)

No installation needed! Just use npx:

# Push a single file/folder
npx teledrop "coffee table alpha" ./myproject

# Push multiple items
npx teledrop "alpha beta gamma" ./file1 ./dir1 ./file2

# Use glob patterns!
npx teledrop "figma backup" ~/figma*

# Pull it back
npx teledrop "coffee table alpha"

That's it! The mnemonic is both your encryption key AND your identifier.

🔐 Manual Mode (Locked-Down Environments)

For environments where npm/npx/curl are restricted but you have:

• ✅ Browser access to GitHub
• ✅ Basic shell (bash/zsh)
• ✅ Standard Unix tools (openssl, tar)

See Manual Setup Instructions below.

Setup

1. Create a GitHub Repository for Drops

Create a new GitHub repo (can be public or private) to store your encrypted drops:

# Example
gh repo create my-drops --public

2. Set Environment Variables

Add these to your ~/.bashrc, ~/.zshrc, or ~/.bash_profile:

export TELEDROP_GITHUB_REPO="username/my-drops"
export TELEDROP_GITHUB_BRANCH="main"
export TELEDROP_GITHUB_TOKEN="ghp_your_token_here"  # Only needed for releasing

Note: TELEDROP_GITHUB_TOKEN is only required for releasing (pushing files). Grabbing (pulling) works without it.

3. You're Ready!

# Release one or more items
npx teledrop "project alpha v1" ./important-docs

# Grab it elsewhere
npx teledrop "project alpha v1"

Usage

Release Mode (Push)

Push one or more files/directories to GitHub releases:

teledrop <mnemonic> <path> [path2] [path3] ...

Examples:

Single item:

teledrop "coffee table alpha" ./my-project

Multiple items:

teledrop "alpha beta gamma" ./file1 ./dir1 ./config.json

Glob patterns:

teledrop "figma backup" ~/figma*

This will:

1. Stage all specified paths
2. Compress them into a tarball
3. Encrypt with your mnemonic
4. Derive a unique ID from your mnemonic
5. Create/update a GitHub release with that ID
6. Upload the encrypted file

Grab Mode (Pull)

Pull and decrypt a previously released drop:

teledrop <mnemonic>

Example:

teledrop "coffee table alpha"

This will:

1. Derive the same ID from your mnemonic
2. Download the encrypted file from GitHub releases
3. Decrypt it using your mnemonic
4. Extract all contents to the current directory

The Mnemonic Concept

The brilliance: Your mnemonic serves TWO purposes:

1. Encryption key - Secures your files
2. Drop identifier - Locates your files

Same phrase pushes and pulls. No IDs to remember. Just your phrase.

Handling Multiple Drops

Want different drops? Use different mnemonics:

• "project alpha v1"
• "project alpha v2"
• "backup monday"
• "backup tuesday"

Note: Using the same mnemonic will replace the previous drop. This is by design - think of it as "updating" your drop.

Multiple Files/Directories

Package multiple items in one drop:

# Multiple specific paths
teledrop "important stuff" ~/docs/ ~/configs/ ~/notes.txt

# Glob patterns (shell expands these)
teledrop "all configs" ~/.config/nvim ~/.config/zsh ~/.bashrc

# Mix files and directories
teledrop "project bundle" ./src/ ./package.json ./README.md

On grab: All items extract into the current directory, preserving their names.

Manual Mode Setup

For ultra-restricted environments where npx and curl don't work.

Option 1: Download Script Directly

1. Download the teledrop script from this repo (via browser)
2. Make it executable:

   chmod +x teledrop

3. Move to PATH (optional):

   mv teledrop /usr/local/bin/

Option 2: Bash Function (Recommended for grab-only)

Add this to your ~/.bashrc or ~/.zshrc:

teledrop-manual() {
    if [[ $# -ne 1 ]]; then
        echo "Usage: teledrop-manual <mnemonic>"
        return 1
    fi
    
    local MNEMONIC="$1"
    # Derive ID from mnemonic (same as teledrop does)
    local ID=$(echo -n "$MNEMONIC" | shasum -a 256 | cut -c1-12)
    local ASSET="${ID}.bin"
    
    if [[ ! -f "$ASSET" ]]; then
        echo "Error: ${ASSET} not found in current directory"
        echo ""
        echo "Download it from your GitHub releases:"
        echo "https://github.com/${TELEDROP_GITHUB_REPO:-YOUR_REPO}/releases/tag/drop-${ID}"
        return 1
    fi
    
    echo "Decrypting ${ASSET}..."
    openssl enc -d -aes-256-cbc -pbkdf2 -iter 600000 \
        -in "$ASSET" -out archive.tgz -k "$MNEMONIC"
    
    echo "Extracting..."
    tar -xzf archive.tgz
    rm archive.tgz
    rm "$ASSET"  # Clean up encrypted file
    
    echo "✅ Done! Files extracted."
}

Usage:

1. Browser: Navigate to your GitHub releases and download the .bin file
2. Terminal:

   teledrop-manual "coffee table alpha"

See MANUAL.md for complete manual mode instructions.

Real-World Use Cases

1. Getting Work Files Home

# At work (restricted)
teledrop "q4 report 2024" ./quarterly-report

# At home
teledrop "q4 report 2024"

2. Sharing with Teammates Behind Firewall

# You release
teledrop "sprint 23 build" ./build-artifacts

# They grab (just need repo info + mnemonic via Slack/etc)
teledrop "sprint 23 build"

3. Personal Backup/Sync

# Backup important configs
teledrop "backup dec 2024" ~/.ssh ~/.config ~/.bashrc

# Restore on new machine
teledrop "backup dec 2024"

4. AI Chat Context Transfer

# At home - working on multiple solutions with Claude
teledrop "project phoenix alpha" ./solution1 ./solution2 ./notes.md

# At work - continue the work
teledrop "project phoenix alpha"

5. Multiple Related Projects

# Package all figma-related directories
teledrop "figma backup" ~/figma*

# Restores:
# ./figma/
# ./figma-export-plugin/
# ./figma2html5/

How It Works

1. ID Derivation: Your mnemonic is hashed (SHA-256, first 12 chars) to create a deterministic ID
2. Staging: All paths are copied to a temporary staging directory
3. Compression: Staged files are compressed with tar + gzip
4. Encryption: AES-256-CBC with PBKDF2 (600,000 iterations) using your mnemonic
5. Upload: Encrypted blob is uploaded to a GitHub release tagged with the ID
6. Download: Same mnemonic → same ID → same release → decrypt → extract

Security Notes:

• The mnemonic is your encryption key - keep it safe
• GitHub releases are public URLs (but content is encrypted)
• No plaintext ever touches GitHub
• Use strong, unique mnemonics for sensitive data
• SHA-256 ensures virtually no collision risk (281 trillion possible IDs)

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | TELEDROP_GITHUB_REPO | Yes | GitHub repository (format: owner/repo) | | TELEDROP_GITHUB_BRANCH | Yes | GitHub branch to tag releases on | | TELEDROP_GITHUB_TOKEN | Release only | GitHub personal access token with repo access |

Requirements

For npx mode:

• Node.js 12+
• gh CLI (GitHub CLI)
• openssl, tar, curl

For manual mode:

• openssl, tar, bash
• Browser access to GitHub

FAQ

Q: Is this secure?
A: Yes. Files are encrypted with AES-256-CBC before upload. Only someone with your mnemonic can decrypt them.

Q: What if I use the same mnemonic twice?
A: It will overwrite the previous drop. Think of it as "updating" your drop location.

Q: Can I package multiple files/directories?
A: Yes! Just list them all: teledrop "phrase" ./file1 ./dir1 ./file2 or use globs: teledrop "phrase" ~/docs/*

Q: Can someone guess my drop ID?
A: Even if they could (astronomically unlikely), they still need your mnemonic to decrypt it.

Q: What if I forget the mnemonic?
A: The file is unrecoverable. There's no "forgot password" - that's by design.

Q: Do I need a GitHub account to grab files?
A: No! Grabbing only requires the download URL (public) and the mnemonic.

Q: Can I automate this?
A: Yes! It's just bash - script away. Great for CI/CD, backups, etc.

Q: Why GitHub releases?
A: They're accessible almost everywhere (corporate firewalls rarely block GitHub), they're free, and they're reliable infrastructure.

Q: How many drops can I have?
A: As many as you have unique mnemonics. Each mnemonic = one drop location.

Part of the teleplank Ecosystem

teledrop is part of the teleplank family of tools for working across boundaries.

License

MIT

Contributing

PRs welcome! This tool is built for people in tough situations - let's make it better together.

Issues? Ideas? Found this useful? Let us know!