cqw 0.1.0

Cloudflare Quick Tunnel wrapper with Basic Auth reverse proxy

cqw

Cloudflare Quick Tunnel wrapper with Basic Auth reverse proxy.

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

Installation

uvx cqw

Or with uv tool:

uv tool install cqw

Usage

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

cqw -f localhost:8080 --update-cloudflared

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

Development

# 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