Metadata-Version: 2.4
Name: ptn
Version: 0.2.1
Summary: Web-based terminal accessible from phone via Cloudflare Tunnel
Project-URL: Homepage, https://github.com/lyehe/porterminal
Project-URL: Repository, https://github.com/lyehe/porterminal
Project-URL: Documentation, https://github.com/lyehe/porterminal/tree/main/docs
Project-URL: Issues, https://github.com/lyehe/porterminal/issues
Author: Porterminal Contributors
Maintainer: Porterminal Contributors
License: AGPL-3.0-or-later
License-File: LICENSE
Keywords: cloudflare,mobile,pty,terminal,tunnel,web,websocket,xterm
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: System :: Shells
Classifier: Topic :: Terminals :: Terminal Emulators/X Terminals
Requires-Python: >=3.12
Requires-Dist: fastapi>=0.104.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pywinpty>=2.0.0; sys_platform == 'win32'
Requires-Dist: pyyaml>=6.0
Requires-Dist: qrcode>=7.4
Requires-Dist: rich>=13.0
Requires-Dist: uvicorn[standard]>=0.24.0
Provides-Extra: dev
Requires-Dist: watchfiles>=0.21.0; extra == 'dev'
Description-Content-Type: text/markdown

<p align="center">
  <a href="https://github.com/lyehe/porterminal">
    <img src="assets/banner.jpg" alt="Porterminal - Vibe Code From Anywhere" width="600">
  </a>
</p>

<p align="center">
  <a href="https://pypi.org/project/ptn/">
    <img src="https://img.shields.io/pypi/v/ptn?style=flat-square&logo=pypi&logoColor=white&label=PyPI" alt="PyPI">
  </a>
  <a href="https://pypi.org/project/ptn/">
    <img src="https://img.shields.io/pypi/pyversions/ptn?style=flat-square&logo=python&logoColor=white" alt="Python">
  </a>
  <a href="https://pypi.org/project/ptn/">
    <img src="https://img.shields.io/pypi/dm/ptn?style=flat-square&label=Downloads" alt="Downloads">
  </a>
  <a href="https://github.com/lyehe/porterminal/blob/main/LICENSE">
    <img src="https://img.shields.io/github/license/lyehe/porterminal?style=flat-square" alt="License">
  </a>
</p>



<p align="center">
  <b>1.</b> <code>uvx ptn</code><br>
  <b>2.</b> Scan the QR<br>
  <b>3.</b> Access your terminal from your phone<br>
</p>

<p align="center">
  <video src="assets/demo.mp4" width="600" controls></video>
</p>

---

## Why

I wanted to vibe code from bed. ngrok requires registration and the free tier sucks. Cloudflare Quick Tunnel works great but is hard to use directly on the phone. Termius works after complicated setup: port forwarding, firewall rules, key management... I just wanted something simpler: run a command, scan a QR, start typing.

## Features

- **One command, instant access** - No SSH, no port forwarding, no config files. Cloudflare tunnel + QR code.
- **Actually usable on mobile** - + Essential buttons and gestures for everyday terminals use for vibe coding and mroe.
- **Multi-tab shared sessions** - Run builds in one tab, tail logs in another. Sessions persist across reconnects.
- **Cross-platform** - Windows (PowerShell, CMD, WSL), Linux/macOS (Bash, Zsh, Fish). Auto-detects your shells.

## Install

| Method | Install | Update |
|--------|---------|--------|
| **uvx** (no install) | `uvx ptn` | `uvx --refresh ptn` |
| **uv tool** | `uv tool install ptn` | `uv tool upgrade ptn` |
| **pipx** | `pipx install ptn` | `pipx upgrade ptn` |
| **pip** | `pip install ptn` | `pip install -U ptn` |

Requires Python 3.12+ and [cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/) (auto-installed if missing).

## Usage

```bash
ptn                    # Start in current directory
ptn ~/projects/myapp   # Start in specific folder
ptn --no-tunnel        # Local network only
ptn -b                 # Run in background
ptn -v                 # Verbose logs
```

## Configuration

Create `ptn.yaml` in your working directory, `.ptn/ptn.yaml`, or `~/.ptn/ptn.yaml` (optional):

```yaml
terminal:
  default_shell: bash
  cols: 120
  rows: 30

buttons:
  - label: "git"
    send: "git status\r"
  - label: "build"
    send: "npm run build\r"
```

## Security

> **Warning:** The URL is the only authentication. Anyone with the link has full terminal access.

- Don't share the URL
- Stop the server when not in use (`Ctrl+C`)
- Use `--no-tunnel` for local network only
- Environment variables are sanitized (API keys, tokens stripped)

## Contributing

Issues and PRs welcome.

```bash
git clone https://github.com/lyehe/porterminal
cd porterminal
uv sync
uv run ptn
```

## License

[AGPL-3.0](LICENSE)
