teledrop

Reslilient file transport - 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 mnemonic 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, two simple bash functions

Quick Start

Installation (npx - recommended)

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.

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. Create a GitHub Personal Access Token

You need a fine-grained token with write access to create releases.

1. Go to github.com/settings/tokens?type=beta
2. Click "Generate new token"
3. Configure:
   • Token name: teledrop (or any name)
   • Expiration: your choice
   • Resource owner: your GitHub username
   • Repository access: "Only select repositories" → select your drops repo
4. Under Repository permissions:
   • Contents: Read and write (required for releases)
   • Metadata: Read-only (auto-selected)
5. Click "Generate token" and copy it

3. Set Environment Variables

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

# Format: owner/repo (NOT a git URL!)
export TELEDROP_GITHUB_REPO_SLUG="username/my-drops"
export TELEDROP_GITHUB_BRANCH="main"
export TELEDROP_GITHUB_TOKEN="github_pat_xxxx..."  # Only needed for releasing

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

4. 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

Management Commands

List All Drops

See all drops in your repository:

teledrop list

Output:

Drop ID          Published
------------     ----------
265b68a4918a     Jan 15, 2025
f8c2a91b3d4e     Jan 10, 2025

Note: Only shows drop IDs (hashes), not mnemonics. You need to remember which mnemonic phrase maps to which drop.

Show Drop Info

View details about a specific drop without downloading:

teledrop info "coffee table alpha"

Shows drop ID, creation date, file size, and download URL. Useful for verifying a drop exists before grabbing.

Delete a Drop

Permanently remove a drop:

teledrop delete "coffee table alpha"

Requires: TELEDROP_GITHUB_TOKEN environment variable.

The Mnemonic Concept

The brilliance: Your mnemonic serves TWO purposes:

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

Same mnemonic phrase pushes and pulls. No IDs to remember. Just your mnemonic 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 (When npm is Unavailable)

For environments where npm/npx is blocked (corporate registries, air-gapped systems), use these two bash functions. Copy them to your ~/.bashrc or ~/.zshrc:

Function 1: teledrop-url - Get the download URL

Derives the download URL from repo slug and mnemonic. Copy it to your browser, use with curl, wget, or any download method available to you.

teledrop-url() {
    if [[ $# -ne 2 ]]; then
        echo "Usage: teledrop-url <repo-slug> <mnemonic>"
        echo "Example: teledrop-url \"user/drops\" \"coffee table alpha\""
        return 1
    fi

    local REPO_SLUG="$1"
    local MNEMONIC="$2"

    # Derive ID from mnemonic (SHA-256, first 12 chars)
    local ID=$(echo -n "$MNEMONIC" | shasum -a 256 | cut -c1-12)

    echo "https://github.com/${REPO_SLUG}/releases/download/drop-${ID}/${ID}.bin"
}

Usage:

# Get the URL
teledrop-url "user/drops" "coffee table alpha"
# → https://github.com/user/drops/releases/download/drop-abc123/abc123.bin

# Use with curl (if curl works)
curl -LO "$(teledrop-url "user/drops" "coffee table alpha")"

# Or just copy the URL and paste in your browser

Function 2: teledrop-unpack - Unpack a drop

Once you have the .bin file (via curl, browser, or any other method), unpack it:

teledrop-unpack() {
    if [[ $# -ne 2 ]]; then
        echo "Usage: teledrop-unpack <mnemonic> <file.bin>"
        echo "Example: teledrop-unpack \"coffee table alpha\" ~/Downloads/abc123.bin"
        return 1
    fi

    local MNEMONIC="$1"
    local ENCRYPTED="$2"

    if [[ ! -f "$ENCRYPTED" ]]; then
        echo "Error: File not found: $ENCRYPTED"
        return 1
    fi

    local TMPDIR=$(mktemp -d)
    local ARCHIVE="$TMPDIR/archive.tgz"

    echo "[1/2] Unpacking..."
    if ! openssl enc -d -aes-256-cbc -pbkdf2 -iter 600000 \
        -in "$ENCRYPTED" \
        -out "$ARCHIVE" \
        -k "$MNEMONIC" 2>/dev/null; then
        echo "Error: Unpacking failed. Wrong mnemonic?"
        rm -rf "$TMPDIR"
        return 1
    fi

    echo "[2/2] Extracting to current directory..."
    tar -xzf "$ARCHIVE"
    rm -rf "$TMPDIR"

    echo "Done!"
}

Usage:

teledrop-unpack "coffee table alpha" ~/Downloads/abc123.bin
# → extracts files to current directory

Complete Manual Workflow

# 1. Get the download URL
teledrop-url "user/drops" "my mnemonic phrase"

# 2. Download the .bin file (pick your method)
#    - Paste URL in browser → file saves to ~/Downloads
#    - Or: curl -LO "$(teledrop-url "user/drops" "my mnemonic phrase")"
#    - Or: wget "$(teledrop-url "user/drops" "my mnemonic phrase")"

# 3. Unpack
teledrop-unpack "my mnemonic phrase" ~/Downloads/abc123.bin

Linux Note

On some Linux systems, use sha256sum instead of shasum:

# Replace this line in teledrop-url:
local ID=$(echo -n "$MNEMONIC" | sha256sum | cut -c1-12)

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-post-quantum-security/
# ./figma-plasma-physics/

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_SLUG | 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
• Any way to download files (browser, curl, wget, etc.)

Troubleshooting

"HTTP 403: Resource not accessible by personal access token"

Your token doesn't have the right permissions. Fix:

1. Go to github.com/settings/tokens
2. Edit your token (or create a new one)
3. Ensure Repository permissions → Contents is set to Read and write
4. Ensure the correct repository is selected under "Repository access"

"gh auth login" message appears

The token isn't being passed to the gh CLI. Check:

1. TELEDROP_GITHUB_TOKEN is set in your environment
2. Run echo $TELEDROP_GITHUB_TOKEN to verify it's not empty
3. Make sure you're using teledrop v1.1.1 or later

Wrong repo format

# WRONG - git URL
export TELEDROP_GITHUB_REPO_SLUG="[email protected]:user/repo.git"

# WRONG - https URL
export TELEDROP_GITHUB_REPO_SLUG="https://github.com/user/repo"

# CORRECT - owner/repo format
export TELEDROP_GITHUB_REPO_SLUG="user/repo"

Decryption failed

• Wrong mnemonic: Must match exactly (case-sensitive, spaces matter)
• Corrupted download: Try downloading again
• Wrong file: Make sure you downloaded the correct .bin file for your mnemonic

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 "mnemonic phrase" ./file1 ./dir1 ./file2 or use globs: teledrop "mnemonic 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!