Metadata-Version: 2.4
Name: deadrop
Version: 2.4.5
Summary: Passcode-authenticated cloud pipeline file drop, selective extraction, and transfer tool
Home-page: https://github.com/ajinkyadeore/deadrop
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Communications :: File Sharing
Classifier: Topic :: Utilities
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: requires-python
Dynamic: summary

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

[![PyPI version](https://img.shields.io/pypi/v/deadrop.svg)](https://pypi.org/project/deadrop/)
[![Python versions](https://img.shields.io/pypi/pyversions/deadrop.svg)](https://pypi.org/project/deadrop/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

---

## 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`:

```bash
pip install deadrop
```

Or upgrade to the latest version:

```bash
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
```bash
# 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:
```text
› staging  my-project.zip
✔ uploaded my-project.zip
· key      pyt-1234
· expires  24h
```

### 2. Download or Unpack
```bash
# 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.

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

| Option | Description | Example |
|---|---|---|
| `<path> ...` | One or more file or directory paths to upload. | `deadrop up main.py utils.py` |
| `-n <name>` | Custom base filename for the uploaded drop. | `deadrop up data/ -n my_backup` |
| `-e <ext>` | Custom file extension override. | `deadrop up archive -e tar.gz` |
| `-key <key>` | Custom 3-letter + 4-number key (`[a-zA-Z]{3}-\d{4}`). | `deadrop up file.txt -key abc-1234` |
| `-<time_flag>` | Time-to-live expiration flag (`d` = days, `h` = hours, `m` = minutes). Default: 24 hours (`-1d`). | `-2d`, `-12h`, `-30m`, `-1d_12h` |

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

```bash
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:

| Flag | Description |
|---|---|
| `-cr` | Save/extract directly into the **current working directory**. |
| `-dl` | Save/extract into the user's **Downloads folder** (`~/Downloads`). |
| `-cx <path>` | Save/extract into a **custom directory path** (e.g. `-cx /tmp/build`). |

#### Archive & Extraction Options

| Option | Description |
|---|---|
| `-uz` | Unzip the downloaded `.zip` archive automatically upon completion. |
| `-i` | Launch **Interactive Mode**. Automatically enables unzipping. Lists all files alphabetically without parent folder clutter and prompts for selection. |
| `-i see` | **Inspect Only**: Fetches metadata to temp, prints all files and formatted sizes sorted alphabetically in the terminal, cleans up, and exits. Does **not** prompt for a download folder. |
| `-i getjson` | **Export Metadata**: Downloads drop to temp, exports a complete JSON file (`<folder>-dd.json`) listing all file details, and deletes the temporary payload. |
| `-i snum <range>` | **Direct Number Selection**: Extracts files by index or range (e.g. `-i snum "1-3,5"`). |
| `-i sname <names>` | **Direct Name Selection**: Extracts files matching exact names (comma-separated, whitespace-tolerant, e.g. `-i sname "app.py, utils.py"`). |
| `-i spat <patterns>` | **Direct Wildcard Selection**: Extracts files matching glob patterns (e.g. `-i spat "*.py, *.json"`). |

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

```bash
deadrop info <key>
```

Example:
```text
· 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.

```bash
deadrop clear <key>
```

---

### 5. `deadrop extend` — Extend Drop Expiration

Increases the active lifetime of an existing drop.

```bash
deadrop extend <key> -<time_flag>
```

Example:
```bash
# 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.

```bash
deadrop rekey <old_key> <new_key>
```

Example:
```bash
deadrop rekey pyt-1234 dev-5678
```

---

### 7. `deadrop ping` — Health Check

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

```bash
deadrop ping
```

---

### 8. `deadrop version` — Check Engine Version

Displays the current version of the CLI client.

```bash
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:
     ```bash
     deadrop down <key> -i spat "*.py,*.json" -cr
     ```
4. **Full Unpack**:
   - To fetch and extract all files unattended:
     ```bash
     deadrop down <key> -uz -cr
     ```
5. **Manifest Extraction**:
   - To inspect file trees programmatically, run:
     ```bash
     deadrop down <key> -i getjson -cr
     ```
   - Then parse the generated `<name>-dd.json` file.

---

## Environment Variables

| Variable | Default | Description |
|---|---|---|
| `DEADROP_BACKEND_API` | `https://deadrop-kk8h.onrender.com` | URL of the gateway server backend. Can be overridden for private or self-hosted deployments. |

---

## License

MIT License. See [LICENSE](LICENSE) for details.
