context-drop

name	context-drop
description	Use when an agent needs to share files, screenshots, logs, existing URLs, or targeted machine messages with Context Drop. Covers chain-aware uploads, uninitialized URL passthrough, pulling drops, and safe handling of sensitive data.

Context Drop for Agents

Context Drop is a CLI for creating short-lived links to files and clipboard images, and for moving those files between machines/agents in a machine chain.

Safety rules

• Do not upload secrets, credentials, .env files, private keys, customer data, or proprietary source archives unless the user explicitly asks for that exact data to be shared.
• Prefer the shortest useful TTL for sensitive-but-approved artifacts, for example --ttl 15m or --ttl 1h.
• Clipboard integration is disabled by default. Use --clipboard only when clipboard copying or clipboard image upload is explicitly useful.
• When reporting a link, say what was uploaded and the TTL if known.

Install or verify the CLI

Check first:

command -v context-drop && context-drop version

If missing, install the latest release:

curl -fsSL https://raw.githubusercontent.com/mupt-ai/context-drop/main/install.sh | bash

Chain state

Uploads, listing, and pulling require a chain session token:

context-drop doctor

If missing, ask the user whether to initialize a new chain or join an existing one:

context-drop init --machine-name <name>
# or
context-drop join <join-token> --machine-name <name>

Do not ask the user to paste chain session tokens into chat.

Share an existing URL when uninitialized

If the user only wants to pass through an existing http or https link and the CLI is not initialized/joined, run:

context-drop 'https://example.com/page'

The CLI prints the link as-is and warns that initialization is required for upload features. For machine-readable output:

context-drop --json 'https://example.com/page'

Note: URL passthrough is only an uninitialized fallback. When initialized, context-drop <arg> treats the argument as a file path to upload.

Upload a file

Use --json when you need the URL programmatically:

context-drop --json --ttl 1h ./artifact.png

For normal human-facing use:

context-drop --ttl 1h ./artifact.png

Add --clipboard only if the user wants the resulting link copied:

context-drop --clipboard --ttl 1h ./artifact.png

Send a file to a specific machine/agent

Find targets:

context-drop machines list

Send text:

context-drop send --to <machine-id-or-name> 'message'

Send a file. A single existing file argument is uploaded and sent as a message containing the drop id and URL:

context-drop send --to <machine-id-or-name> ./artifact.png

Upload the current clipboard image

With no path, Context Drop uploads the current clipboard image only when clipboard integration is enabled:

context-drop --json --clipboard --ttl 1h

This requires pngpaste on macOS, or wl-paste/xclip on Linux.

List and pull drops

List the current chain's drops:

context-drop list
context-drop list --json

Download the latest drop to /tmp/<filename>:

context-drop pull

Download a specific drop:

context-drop pull <id> --output ./downloaded-file --force

Wait for the next new image drop and download it:

context-drop pull --watch --timeout 2m --output ./image.png --force

Common failures

• not initialized or joined; run context-drop init or context-drop join <token>: upload/list/pull needs a chain session token, or use uninitialized URL passthrough for an existing link.
• invalid or expired join token: create a fresh token from an already joined machine.
• no clipboard copy tool found: omit --clipboard, run context-drop config set clipboard false, or install wl-copy, xclip, or xsel on Linux.
• clipboard image support requires pngpaste: install pngpaste on macOS or upload a file path instead.
• Upload rejected for size or TTL: retry with a smaller file or shorter TTL.