clipto 0.1.0__tar.gz

clipto-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install .[dev]
+      - name: Run tests
+        run: |
+          pytest

clipto-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,45 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Build distribution 📦
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install pypa/build
+        run: python3 -m pip install build --user
+      - name: Build a binary wheel and a source tarball
+        run: python3 -m build
+      - name: Store the distribution packages
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-to-pypi:
+    name: Publish to PyPI 🚀
+    needs:
+      - build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/clipto
+    permissions:
+      id-token: write # Mandatory for PyPI Trusted Publishing
+    steps:
+      - name: Download distribution packages
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish distribution to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

clipto-0.1.0/.gitignore

@@ -0,0 +1,27 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# IDE & OS
+.DS_Store
+.idea/
+.vscode/
+*.swp
+
+# Testing & coverage
+.pytest_cache/
+.coverage
+htmlcov/

clipto-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

clipto-0.1.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.5
+Name: clipto
+Version: 0.1.0
+Summary: Instant clipboard, screenshot, and file bridge from your browser to your terminal/remote server.
+Project-URL: Homepage, https://github.com/mattintech/clipto
+Project-URL: Repository, https://github.com/mattintech/clipto
+Project-URL: Issues, https://github.com/mattintech/clipto/issues
+Author-email: Matt <matt@example.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-tools,cli,clipboard,developer-tools,remote-transfer,screenshot,upload
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Utilities
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: build>=1.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: twine>=5.0.0; extra == 'dev'
+Provides-Extra: qr
+Requires-Dist: segno>=1.6.0; extra == 'qr'
+Description-Content-Type: text/markdown
+
+# 📎 Clipto
+
+[![PyPI](https://img.shields.io/pypi/v/clipto.svg)](https://pypi.org/project/clipto/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![CI](https://github.com/mattintech/clipto/actions/workflows/ci.yml/badge.svg)](https://github.com/mattintech/clipto/actions/workflows/ci.yml)
+
+> **Instant clipboard, screenshot, and file bridge from your browser to your terminal or remote server.**
+
+Ever run an AI agent, Docker container, or SSH session on a remote server, but need to get a screenshot or log file from your local machine to that server? 
+
+**Clipto** solves this. Run `clipto` in any directory on your machine or remote server, open the link in your browser, and hit **Cmd+V / Ctrl+V**. Your screenshot or clipboard contents are immediately saved right into that folder.
+
+---
+
+## ✨ Features
+
+- **⚡ Zero-Click Paste:** Open the page and press `Cmd+V` or `Ctrl+V` anywhere. No buttons or input selection required.
+- **🎯 Drag & Drop:** Drop multiple files, images, or documents straight onto the window.
+- **📝 Text & Note Box:** Paste stack traces, error logs, or notes to save directly as `.txt` files.
+- **🤖 AI Agent Friendly (`--once`):** One-shot mode spins up the server, waits for an upload, writes the file, prints the saved path to `stdout`, and exits cleanly.
+- **🔀 Smart Port Hunting:** Automatically picks the next free port (`8765`, `8766`, etc.) so multiple instances never collide.
+- **🏷️ Multi-Instance Context:** The UI prominently shows the host machine, target directory, and optional custom `--title`.
+- **🪶 Zero Dependencies:** Powered purely by Python's standard library. Installs in milliseconds with zero dependency conflicts.
+
+---
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+pip install clipto
+```
+
+### Basic Usage
+
+Run `clipto` in whichever directory you want files to land:
+
+```bash
+clipto
+```
+
+You'll see a clean terminal banner with the local and LAN URLs:
+
+```text
+┌──────────────────────────────────────────────────────────┐
+│  📎 Clipto v0.1.0                                        │
+│  Saving to: /Users/matt/code/my-project                  │
+│  Local:     http://localhost:8765                        │
+│  Network:   http://192.168.1.50:8765                     │
+└──────────────────────────────────────────────────────────┘
+```
+
+1. Open the URL in your browser (or pass `-o / --open` to auto-open).
+2. Hit `Cmd+V` to paste a screenshot, or drag files onto the page.
+3. The files are instantly written to your current directory!
+
+---
+
+## 🤖 Using with AI Agents & Scripts
+
+Clipto is built from the ground up to integrate cleanly into automated agent workflows (Antigravity, Claude Code, Aider, OpenHands, etc.).
+
+### One-Shot Mode (`--once`)
+
+When run with `--once` (or `-1`), Clipto waits for a single upload batch, saves the file(s), prints the resolved absolute path to `stdout`, and shuts down:
+
+```bash
+# Agent or script runs this:
+FILE_PATH=$(clipto --once --title "Submit login bug screenshot" --timeout 120)
+
+echo "Agent received file at: $FILE_PATH"
+```
+
+The agent gets the exact file path back into its visual/multimodal context!
+
+---
+
+## ⚙️ CLI Reference
+
+```text
+usage: clipto [-h] [-v] [-p PORT] [--no-hunt] [-d DIR] [-1] [-t TITLE] [-o] [--host HOST] [--timeout TIMEOUT]
+
+Instant clipboard, screenshot, and file bridge from browser to terminal.
+
+options:
+  -h, --help            show this help message and exit
+  -v, --version         show program's version number and exit
+  -p PORT, --port PORT  Port to listen on (default: 8765; use 0 for random).
+  --no-hunt             Disable automatic port hunting if port is busy.
+  -d DIR, --dir DIR     Target directory to save files (default: .).
+  -1, --once            One-shot mode: exit after upload and print file path(s).
+  -t TITLE, --title TITLE
+                        Custom session title or prompt shown in the UI header.
+  -o, --open            Automatically open web UI in default browser on launch.
+  --host HOST           Host to bind to (default: 0.0.0.0).
+  --timeout TIMEOUT     Timeout in seconds (useful with --once).
+```
+
+---
+
+## 🛠️ Multi-Instance Support
+
+You can run multiple `clipto` instances simultaneously across different projects or terminals:
+* Each instance automatically detects occupied ports and claims the next available one.
+* Each browser tab displays its target folder path and optional session title so you always know where your file is landing.
+
+---
+
+## 🔒 Security
+
+* By default, Clipto binds to `0.0.0.0` for convenience across local networks (e.g. testing with phone/laptop).
+* If you only want local machine access, pass `--host 127.0.0.1`.
+* Filenames are strictly sanitized to prevent directory traversal attacks.
+
+---
+
+## 📄 License
+
+MIT © Matt

clipto-0.1.0/README.md

@@ -0,0 +1,120 @@
+# 📎 Clipto
+
+[![PyPI](https://img.shields.io/pypi/v/clipto.svg)](https://pypi.org/project/clipto/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![CI](https://github.com/mattintech/clipto/actions/workflows/ci.yml/badge.svg)](https://github.com/mattintech/clipto/actions/workflows/ci.yml)
+
+> **Instant clipboard, screenshot, and file bridge from your browser to your terminal or remote server.**
+
+Ever run an AI agent, Docker container, or SSH session on a remote server, but need to get a screenshot or log file from your local machine to that server? 
+
+**Clipto** solves this. Run `clipto` in any directory on your machine or remote server, open the link in your browser, and hit **Cmd+V / Ctrl+V**. Your screenshot or clipboard contents are immediately saved right into that folder.
+
+---
+
+## ✨ Features
+
+- **⚡ Zero-Click Paste:** Open the page and press `Cmd+V` or `Ctrl+V` anywhere. No buttons or input selection required.
+- **🎯 Drag & Drop:** Drop multiple files, images, or documents straight onto the window.
+- **📝 Text & Note Box:** Paste stack traces, error logs, or notes to save directly as `.txt` files.
+- **🤖 AI Agent Friendly (`--once`):** One-shot mode spins up the server, waits for an upload, writes the file, prints the saved path to `stdout`, and exits cleanly.
+- **🔀 Smart Port Hunting:** Automatically picks the next free port (`8765`, `8766`, etc.) so multiple instances never collide.
+- **🏷️ Multi-Instance Context:** The UI prominently shows the host machine, target directory, and optional custom `--title`.
+- **🪶 Zero Dependencies:** Powered purely by Python's standard library. Installs in milliseconds with zero dependency conflicts.
+
+---
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+pip install clipto
+```
+
+### Basic Usage
+
+Run `clipto` in whichever directory you want files to land:
+
+```bash
+clipto
+```
+
+You'll see a clean terminal banner with the local and LAN URLs:
+
+```text
+┌──────────────────────────────────────────────────────────┐
+│  📎 Clipto v0.1.0                                        │
+│  Saving to: /Users/matt/code/my-project                  │
+│  Local:     http://localhost:8765                        │
+│  Network:   http://192.168.1.50:8765                     │
+└──────────────────────────────────────────────────────────┘
+```
+
+1. Open the URL in your browser (or pass `-o / --open` to auto-open).
+2. Hit `Cmd+V` to paste a screenshot, or drag files onto the page.
+3. The files are instantly written to your current directory!
+
+---
+
+## 🤖 Using with AI Agents & Scripts
+
+Clipto is built from the ground up to integrate cleanly into automated agent workflows (Antigravity, Claude Code, Aider, OpenHands, etc.).
+
+### One-Shot Mode (`--once`)
+
+When run with `--once` (or `-1`), Clipto waits for a single upload batch, saves the file(s), prints the resolved absolute path to `stdout`, and shuts down:
+
+```bash
+# Agent or script runs this:
+FILE_PATH=$(clipto --once --title "Submit login bug screenshot" --timeout 120)
+
+echo "Agent received file at: $FILE_PATH"
+```
+
+The agent gets the exact file path back into its visual/multimodal context!
+
+---
+
+## ⚙️ CLI Reference
+
+```text
+usage: clipto [-h] [-v] [-p PORT] [--no-hunt] [-d DIR] [-1] [-t TITLE] [-o] [--host HOST] [--timeout TIMEOUT]
+
+Instant clipboard, screenshot, and file bridge from browser to terminal.
+
+options:
+  -h, --help            show this help message and exit
+  -v, --version         show program's version number and exit
+  -p PORT, --port PORT  Port to listen on (default: 8765; use 0 for random).
+  --no-hunt             Disable automatic port hunting if port is busy.
+  -d DIR, --dir DIR     Target directory to save files (default: .).
+  -1, --once            One-shot mode: exit after upload and print file path(s).
+  -t TITLE, --title TITLE
+                        Custom session title or prompt shown in the UI header.
+  -o, --open            Automatically open web UI in default browser on launch.
+  --host HOST           Host to bind to (default: 0.0.0.0).
+  --timeout TIMEOUT     Timeout in seconds (useful with --once).
+```
+
+---
+
+## 🛠️ Multi-Instance Support
+
+You can run multiple `clipto` instances simultaneously across different projects or terminals:
+* Each instance automatically detects occupied ports and claims the next available one.
+* Each browser tab displays its target folder path and optional session title so you always know where your file is landing.
+
+---
+
+## 🔒 Security
+
+* By default, Clipto binds to `0.0.0.0` for convenience across local networks (e.g. testing with phone/laptop).
+* If you only want local machine access, pass `--host 127.0.0.1`.
+* Filenames are strictly sanitized to prevent directory traversal attacks.
+
+---
+
+## 📄 License
+
+MIT © Matt

clipto-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "clipto"
+version = "0.1.0"
+description = "Instant clipboard, screenshot, and file bridge from your browser to your terminal/remote server."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [
+    { name = "Matt", email = "matt@example.com" }
+]
+keywords = [
+    "clipboard",
+    "screenshot",
+    "upload",
+    "cli",
+    "developer-tools",
+    "ai-tools",
+    "remote-transfer"
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Utilities",
+]
+dependencies = []
+
+[project.optional-dependencies]
+qr = ["segno>=1.6.0"]
+dev = [
+    "pytest>=8.0.0",
+    "build>=1.0.0",
+    "twine>=5.0.0",
+]
+
+[project.scripts]
+clipto = "clipto.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/mattintech/clipto"
+Repository = "https://github.com/mattintech/clipto"
+Issues = "https://github.com/mattintech/clipto/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/clipto"]

clipto-0.1.0/src/clipto/__init__.py

@@ -0,0 +1,4 @@
+"""Clipto: Instant clipboard, screenshot, and file bridge from browser to terminal."""
+
+__version__ = "0.1.0"
+__all__ = ["__version__"]

clipto-0.1.0/src/clipto/__main__.py

@@ -0,0 +1,4 @@
+from clipto.cli import main
+
+if __name__ == "__main__":
+    main()

clipto-0.1.0/src/clipto/cli.py

@@ -0,0 +1,174 @@
+import argparse
+import os
+import sys
+import threading
+import time
+import webbrowser
+from pathlib import Path
+from typing import Optional
+
+from clipto import __version__
+from clipto.server import CliptoHTTPServer, CliptoRequestHandler
+from clipto.utils import (
+    find_available_port,
+    get_local_ip,
+    get_tailscale_ip,
+    terminal_hyperlink,
+)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="clipto",
+        description="Instant clipboard, screenshot, and file bridge from browser to terminal.",
+    )
+    parser.add_argument(
+        "-v", "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    parser.add_argument(
+        "-p", "--port",
+        type=int,
+        default=8765,
+        help="Port to listen on (default: 8765, auto-increments if occupied; use 0 for random).",
+    )
+    parser.add_argument(
+        "--no-hunt",
+        action="store_true",
+        help="Disable automatic port hunting if specified port is in use.",
+    )
+    parser.add_argument(
+        "-d", "--dir",
+        type=Path,
+        default=Path("."),
+        help="Target directory where files will be saved (default: current directory).",
+    )
+    parser.add_argument(
+        "-1", "--once",
+        action="store_true",
+        help="One-shot mode: exit immediately after receiving an upload and print saved file path(s).",
+    )
+    parser.add_argument(
+        "-t", "--title",
+        type=str,
+        default=None,
+        help="Custom session title or prompt shown in the web UI header.",
+    )
+    parser.add_argument(
+        "-o", "--open",
+        action="store_true",
+        help="Automatically open the web UI in the default browser on launch.",
+    )
+    parser.add_argument(
+        "--host",
+        type=str,
+        default="0.0.0.0",
+        help="Host address to bind to (default: 0.0.0.0).",
+    )
+    parser.add_argument(
+        "--timeout",
+        type=int,
+        default=None,
+        help="Timeout in seconds (useful with --once to prevent hanging indefinitely).",
+    )
+    return parser
+
+
+def print_banner(
+    port: int,
+    target_dir: Path,
+    title: Optional[str] = None,
+    once: bool = False,
+):
+    local_url = f"http://localhost:{port}"
+    lan_ip = get_local_ip()
+    tailscale_ip = get_tailscale_ip()
+
+    lines = [
+        f"📎 Clipto v{__version__}" + (" [ONE-SHOT MODE]" if once else ""),
+        f"Saving to: {target_dir.resolve()}",
+    ]
+    if title:
+        lines.append(f"Session:   {title}")
+
+    lines.append(f"Local:     {terminal_hyperlink(local_url)}")
+    if lan_ip and lan_ip != "127.0.0.1":
+        lines.append(f"Network:   {terminal_hyperlink(f'http://{lan_ip}:{port}')}")
+    if tailscale_ip:
+        lines.append(f"Tailscale: {terminal_hyperlink(f'http://{tailscale_ip}:{port}')}")
+
+    max_len = max(len(line) for line in lines)
+    border = "─" * (max_len + 4)
+
+    print(f"\n┌{border}┐", file=sys.stderr)
+    for line in lines:
+        padding = " " * (max_len - len(line))
+        print(f"│  {line}{padding}  │", file=sys.stderr)
+    print(f"└{border}┘\n", file=sys.stderr)
+    print("Press Cmd+V or drag files into the browser tab. Press Ctrl+C to stop.\n", file=sys.stderr)
+
+
+def main():
+    parser = build_parser()
+    args = parser.parse_args()
+
+    target_dir = args.dir.resolve()
+    target_dir.mkdir(parents=True, exist_ok=True)
+
+    # Determine port
+    if args.no_hunt:
+        port = args.port
+    else:
+        try:
+            port = find_available_port(args.port)
+        except RuntimeError as e:
+            print(f"Error: {e}", file=sys.stderr)
+            sys.exit(1)
+
+    try:
+        server = CliptoHTTPServer(
+            (args.host, port),
+            CliptoRequestHandler,
+            upload_dir=target_dir,
+            title=args.title,
+            once=args.once,
+        )
+    except OSError as e:
+        print(f"Error binding to port {port}: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    print_banner(port, target_dir, title=args.title, once=args.once)
+
+    if args.open:
+        webbrowser.open(f"http://localhost:{port}")
+
+    # Start server thread
+    server_thread = threading.Thread(target=server.serve_forever, daemon=True)
+    server_thread.start()
+
+    start_time = time.time()
+
+    try:
+        while not server.shutdown_event.is_set():
+            if args.timeout and (time.time() - start_time) > args.timeout:
+                print("\nOperation timed out.", file=sys.stderr)
+                server.shutdown()
+                sys.exit(124)
+            time.sleep(0.1)
+
+        # Shutdown triggered (in once mode)
+        server.shutdown()
+
+        # In once mode, output the uploaded file path(s) to stdout
+        for file_path in server.uploaded_files:
+            print(str(file_path.resolve()))
+
+    except KeyboardInterrupt:
+        print("\nStopping Clipto server...", file=sys.stderr)
+        server.shutdown()
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()