Metadata-Version: 2.4
Name: cqw
Version: 0.1.0
Summary: Cloudflare Quick Tunnel wrapper with Basic Auth reverse proxy
Project-URL: Documentation, https://github.com/likeablob/cqw
Project-URL: Source, https://github.com/likeablob/cqw
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: httpx>=0.28.1
Requires-Dist: platformdirs>=4.9.0
Requires-Dist: pydantic-settings>=2.14.1
Requires-Dist: qrcode>=8.2
Requires-Dist: rich>=15.0.0
Requires-Dist: starlette>=1.0.0
Requires-Dist: uvicorn>=0.46.0
Requires-Dist: websockets>=16.0
Description-Content-Type: text/markdown

# cqw

Cloudflare Quick Tunnel wrapper with Basic Auth reverse proxy.

```
[Client] -> [Cloudflare Tunnel] -> [cqw Proxy (Basic Auth)] -> [Target Service]
```

## Installation

```bash
uvx cqw
```

Or with uv tool:

```bash
uv tool install cqw
```

## Usage

```bash
# Basic usage: creates tunnel with random credentials
cqw -f localhost:8080
... # QR code with authenticated URL, tunnel URL, credentials

# Custom Basic Auth credentials
cqw -f localhost:8080 --user admin --pass secret

# Direct tunnel to target (bypass proxy and authentication)
# [Cloudflare Tunnel] -> [Target Service]
cqw -f localhost:8080 --no-proxy
```

## CLI Options

| Option                     | Description                                                      |
| -------------------------- | ---------------------------------------------------------------- |
| `-f, --forward`            | Target address to forward (required)                             |
| `--user`                   | Basic auth username (default: env `CQW_USER` or random)          |
| `--pass`                   | Basic auth password (default: env `CQW_PASS` or random)          |
| `--cloudflared`            | Path to cloudflared binary (default: auto-download to cache)     |
| `--update-cloudflared`     | Update cloudflared to latest version                             |
| `--no-qr`                  | Disable QR code display                                          |
| `-v, --verbose`            | Enable verbose logging                                           |
| `--no-proxy`               | Disable proxy and Basic Auth (tunnel only)                       |
| `--quiet`                  | Suppress cloudflared tunnel logs                                 |
| `--cloudflared-extra-args` | Extra arguments passed to cloudflared (e.g., '--protocol http2') |

## Environment Variables

- `CQW_USER`: Basic auth username (fallback: random)
- `CQW_PASS`: Basic auth password (fallback: random)

## `cloudflared` Installation

`cloudflared` is automatically downloaded to the user cache directory on first run:

- Linux: `~/.cache/cqw/cloudflared/`
- macOS: `~/Library/Caches/cqw/cloudflared/`
- Windows: `%LOCALAPPDATA%\cqw\cloudflared\`

To update to the latest version:
```bash
cqw -f localhost:8080 --update-cloudflared
```

Manual download: https://github.com/cloudflare/cloudflared/releases

## Development

```bash
# Install tools
mise trust && mise install

# Install dependencies:
uv sync

# Install pre-commit hooks:
uv run pre-commit install

# Testing
uv run pytest tests/ -v

# Linting
uv run ruff check src/
uv run ruff format src/
uv run ty check src/ tests/
```

## LICENSE

MIT
