suxitunnel 0.1.2__py3-none-any.whl → 0.1.3__py3-none-any.whl

PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: suxitunnel
-Version: 0.1.2
+Version: 0.1.3
 Summary: A simple Python library to expose local servers using Cloudflare Tunnel
 Project-URL: Homepage, https://github.com/sadwx/suxitunnel
 Project-URL: Repository, https://github.com/sadwx/suxitunnel
@@ -35,6 +35,21 @@ pip install suxitunnel
 
 ## Quick Start
 
+### Command Line
+
+```bash
+# Expose local port 8000 (random URL)
+suxitunnel --port 8000
+
+# Or use short form
+suxitunnel -p 8000
+
+# Use a named tunnel with dedicated URL (requires Cloudflare account)
+suxitunnel --port 8000 --tunnel-token YOUR_TOKEN
+```
+
+### Python API
+
 ```python
 from suxitunnel import Tunnel
 
@@ -57,6 +72,8 @@ That's it! No configuration, no authentication, no manual setup.
 - 🌍 **Global CDN** - Fast access from anywhere in the world
 - 📦 **Auto-install** - Automatically downloads cloudflared if needed
 - 🐍 **Simple API** - Clean, Pythonic interface
+- 💻 **CLI Support** - Use from command line or as a library
+- 🏷️ **Named Tunnels** - Support for dedicated URLs with tunnel tokens
 
 ## Usage
 
@@ -162,7 +179,31 @@ tunnel = Tunnel(8000, auto_download=False)
 
 ## API Reference
 
-### `Tunnel(port, host="localhost", cloudflared_path=None, auto_download=True)`
+### Command Line Interface
+
+```bash
+suxitunnel [-h] -p PORT [--tunnel-token TUNNEL_TOKEN] [--local-https]
+```
+
+**Arguments:**
+- `-p, --port PORT`: Local port to expose (required)
+- `--tunnel-token TOKEN`: Cloudflare tunnel token for named tunnels (optional)
+- `--local-https`: Connect to local server via HTTPS (for self-signed certs)
+- `-h, --help`: Show help message
+
+**Examples:**
+```bash
+# Quick tunnel with random URL
+suxitunnel --port 8000
+
+# Named tunnel with dedicated URL
+suxitunnel --port 8000 --tunnel-token eyJhIjoiNz...
+
+# Local HTTPS server (e.g., .NET Core with HTTPS)
+suxitunnel --port 5001 --local-https
+```
+
+### `Tunnel(port, host="localhost", cloudflared_path=None, auto_download=True, tunnel_token=None, local_https=False)`
 
 Create a tunnel to expose a local port.
 
@@ -171,19 +212,28 @@ Create a tunnel to expose a local port.
 - `host` (str): Local hostname (default: "localhost")
 - `cloudflared_path` (str): Path to cloudflared binary (auto-detected if None)
 - `auto_download` (bool): Auto-download cloudflared if not found (default: True)
+- `tunnel_token` (str): Cloudflare tunnel token for named tunnels (optional)
+- `local_https` (bool): Set to True if local server uses HTTPS (default: False)
 
 **Attributes:**
 - `url` (str): Public HTTPS URL for the tunnel
 - `port` (int): Local port being exposed
 - `host` (str): Local hostname
+- `tunnel_token` (str): Tunnel token if using named tunnel
 - `is_alive()` (bool): Check if tunnel is running
 - `close()`: Close the tunnel
 
 **Example:**
 ```python
+# Quick tunnel (random URL)
 tunnel = Tunnel(8000)
 print(tunnel.url)  # https://abc123.trycloudflare.com
 tunnel.close()
+
+# Named tunnel (dedicated URL)
+tunnel = Tunnel(8000, tunnel_token="your-token")
+print(tunnel.url)  # https://your-configured-domain.com
+tunnel.close()
 ```
 
 ### `open_tunnel(port, host="localhost")`
@@ -237,12 +287,18 @@ Supported platforms:
 
 ## Limitations
 
-1. **Random URLs**: Each tunnel gets a random `*.trycloudflare.com` URL (no custom domains)
+**Quick Tunnels (default):**
+1. **Random URLs**: Each tunnel gets a random `*.trycloudflare.com` URL
 2. **Temporary**: Tunnels are meant for development/testing, not production
 3. **No persistence**: URL changes each time you create a new tunnel
 4. **Rate limits**: Subject to Cloudflare's fair use policy
 
-For production use with custom domains, see the full [cloudflared documentation](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/).
+**Named Tunnels (with `--tunnel-token`):**
+- Requires a free Cloudflare account
+- Provides persistent, dedicated URLs
+- Better suited for staging/production environments
+
+For setting up named tunnels, see the [Cloudflare Tunnel documentation](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/).
 
 ## Security Considerations
 

README.md

@@ -12,6 +12,21 @@ pip install suxitunnel
 
 ## Quick Start
 
+### Command Line
+
+```bash
+# Expose local port 8000 (random URL)
+suxitunnel --port 8000
+
+# Or use short form
+suxitunnel -p 8000
+
+# Use a named tunnel with dedicated URL (requires Cloudflare account)
+suxitunnel --port 8000 --tunnel-token YOUR_TOKEN
+```
+
+### Python API
+
 ```python
 from suxitunnel import Tunnel
 
@@ -34,6 +49,8 @@ That's it! No configuration, no authentication, no manual setup.
 - 🌍 **Global CDN** - Fast access from anywhere in the world
 - 📦 **Auto-install** - Automatically downloads cloudflared if needed
 - 🐍 **Simple API** - Clean, Pythonic interface
+- 💻 **CLI Support** - Use from command line or as a library
+- 🏷️ **Named Tunnels** - Support for dedicated URLs with tunnel tokens
 
 ## Usage
 
@@ -139,7 +156,31 @@ tunnel = Tunnel(8000, auto_download=False)
 
 ## API Reference
 
-### `Tunnel(port, host="localhost", cloudflared_path=None, auto_download=True)`
+### Command Line Interface
+
+```bash
+suxitunnel [-h] -p PORT [--tunnel-token TUNNEL_TOKEN] [--local-https]
+```
+
+**Arguments:**
+- `-p, --port PORT`: Local port to expose (required)
+- `--tunnel-token TOKEN`: Cloudflare tunnel token for named tunnels (optional)
+- `--local-https`: Connect to local server via HTTPS (for self-signed certs)
+- `-h, --help`: Show help message
+
+**Examples:**
+```bash
+# Quick tunnel with random URL
+suxitunnel --port 8000
+
+# Named tunnel with dedicated URL
+suxitunnel --port 8000 --tunnel-token eyJhIjoiNz...
+
+# Local HTTPS server (e.g., .NET Core with HTTPS)
+suxitunnel --port 5001 --local-https
+```
+
+### `Tunnel(port, host="localhost", cloudflared_path=None, auto_download=True, tunnel_token=None, local_https=False)`
 
 Create a tunnel to expose a local port.
 
@@ -148,19 +189,28 @@ Create a tunnel to expose a local port.
 - `host` (str): Local hostname (default: "localhost")
 - `cloudflared_path` (str): Path to cloudflared binary (auto-detected if None)
 - `auto_download` (bool): Auto-download cloudflared if not found (default: True)
+- `tunnel_token` (str): Cloudflare tunnel token for named tunnels (optional)
+- `local_https` (bool): Set to True if local server uses HTTPS (default: False)
 
 **Attributes:**
 - `url` (str): Public HTTPS URL for the tunnel
 - `port` (int): Local port being exposed
 - `host` (str): Local hostname
+- `tunnel_token` (str): Tunnel token if using named tunnel
 - `is_alive()` (bool): Check if tunnel is running
 - `close()`: Close the tunnel
 
 **Example:**
 ```python
+# Quick tunnel (random URL)
 tunnel = Tunnel(8000)
 print(tunnel.url)  # https://abc123.trycloudflare.com
 tunnel.close()
+
+# Named tunnel (dedicated URL)
+tunnel = Tunnel(8000, tunnel_token="your-token")
+print(tunnel.url)  # https://your-configured-domain.com
+tunnel.close()
 ```
 
 ### `open_tunnel(port, host="localhost")`
@@ -214,12 +264,18 @@ Supported platforms:
 
 ## Limitations
 
-1. **Random URLs**: Each tunnel gets a random `*.trycloudflare.com` URL (no custom domains)
+**Quick Tunnels (default):**
+1. **Random URLs**: Each tunnel gets a random `*.trycloudflare.com` URL
 2. **Temporary**: Tunnels are meant for development/testing, not production
 3. **No persistence**: URL changes each time you create a new tunnel
 4. **Rate limits**: Subject to Cloudflare's fair use policy
 
-For production use with custom domains, see the full [cloudflared documentation](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/).
+**Named Tunnels (with `--tunnel-token`):**
+- Requires a free Cloudflare account
+- Provides persistent, dedicated URLs
+- Better suited for staging/production environments
+
+For setting up named tunnels, see the [Cloudflare Tunnel documentation](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/).
 
 ## Security Considerations
 

__init__.py

@@ -3,7 +3,7 @@ suxitunnel
 A simple Python library to expose local servers using Cloudflare Tunnel
 """
 
-from .suxitunnel import Tunnel, TunnelError, open_tunnel
+from suxitunnel import Tunnel, TunnelError, open_tunnel
 
 __version__ = "0.1.0"
 __all__ = ["Tunnel", "TunnelError", "open_tunnel"]

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "suxitunnel"
-version = "0.1.2"
+version = "0.1.3"
 description = "A simple Python library to expose local servers using Cloudflare Tunnel"
 readme = "README.md"
 license = "MIT"
@@ -22,6 +22,9 @@ dependencies = [
     "requests>=2.32.0",
 ]
 
+[project.scripts]
+suxitunnel = "suxitunnel:main"
+
 [project.urls]
 Homepage = "https://github.com/sadwx/suxitunnel"
 Repository = "https://github.com/sadwx/suxitunnel"
@@ -49,6 +52,7 @@ dev = [
     "build>=1.4.0",
     "fastapi>=0.128.0",
     "flask>=3.1.2",
+    "pytest>=9.0.2",
     "twine>=6.2.0",
     "uvicorn>=0.40.0",
 ]

{suxitunnel-0.1.2.dist-info → suxitunnel-0.1.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: suxitunnel
-Version: 0.1.2
+Version: 0.1.3
 Summary: A simple Python library to expose local servers using Cloudflare Tunnel
 Project-URL: Homepage, https://github.com/sadwx/suxitunnel
 Project-URL: Repository, https://github.com/sadwx/suxitunnel
@@ -35,6 +35,21 @@ pip install suxitunnel
 
 ## Quick Start
 
+### Command Line
+
+```bash
+# Expose local port 8000 (random URL)
+suxitunnel --port 8000
+
+# Or use short form
+suxitunnel -p 8000
+
+# Use a named tunnel with dedicated URL (requires Cloudflare account)
+suxitunnel --port 8000 --tunnel-token YOUR_TOKEN
+```
+
+### Python API
+
 ```python
 from suxitunnel import Tunnel
 
@@ -57,6 +72,8 @@ That's it! No configuration, no authentication, no manual setup.
 - 🌍 **Global CDN** - Fast access from anywhere in the world
 - 📦 **Auto-install** - Automatically downloads cloudflared if needed
 - 🐍 **Simple API** - Clean, Pythonic interface
+- 💻 **CLI Support** - Use from command line or as a library
+- 🏷️ **Named Tunnels** - Support for dedicated URLs with tunnel tokens
 
 ## Usage
 
@@ -162,7 +179,31 @@ tunnel = Tunnel(8000, auto_download=False)
 
 ## API Reference
 
-### `Tunnel(port, host="localhost", cloudflared_path=None, auto_download=True)`
+### Command Line Interface
+
+```bash
+suxitunnel [-h] -p PORT [--tunnel-token TUNNEL_TOKEN] [--local-https]
+```
+
+**Arguments:**
+- `-p, --port PORT`: Local port to expose (required)
+- `--tunnel-token TOKEN`: Cloudflare tunnel token for named tunnels (optional)
+- `--local-https`: Connect to local server via HTTPS (for self-signed certs)
+- `-h, --help`: Show help message
+
+**Examples:**
+```bash
+# Quick tunnel with random URL
+suxitunnel --port 8000
+
+# Named tunnel with dedicated URL
+suxitunnel --port 8000 --tunnel-token eyJhIjoiNz...
+
+# Local HTTPS server (e.g., .NET Core with HTTPS)
+suxitunnel --port 5001 --local-https
+```
+
+### `Tunnel(port, host="localhost", cloudflared_path=None, auto_download=True, tunnel_token=None, local_https=False)`
 
 Create a tunnel to expose a local port.
 
@@ -171,19 +212,28 @@ Create a tunnel to expose a local port.
 - `host` (str): Local hostname (default: "localhost")
 - `cloudflared_path` (str): Path to cloudflared binary (auto-detected if None)
 - `auto_download` (bool): Auto-download cloudflared if not found (default: True)
+- `tunnel_token` (str): Cloudflare tunnel token for named tunnels (optional)
+- `local_https` (bool): Set to True if local server uses HTTPS (default: False)
 
 **Attributes:**
 - `url` (str): Public HTTPS URL for the tunnel
 - `port` (int): Local port being exposed
 - `host` (str): Local hostname
+- `tunnel_token` (str): Tunnel token if using named tunnel
 - `is_alive()` (bool): Check if tunnel is running
 - `close()`: Close the tunnel
 
 **Example:**
 ```python
+# Quick tunnel (random URL)
 tunnel = Tunnel(8000)
 print(tunnel.url)  # https://abc123.trycloudflare.com
 tunnel.close()
+
+# Named tunnel (dedicated URL)
+tunnel = Tunnel(8000, tunnel_token="your-token")
+print(tunnel.url)  # https://your-configured-domain.com
+tunnel.close()
 ```
 
 ### `open_tunnel(port, host="localhost")`
@@ -237,12 +287,18 @@ Supported platforms:
 
 ## Limitations
 
-1. **Random URLs**: Each tunnel gets a random `*.trycloudflare.com` URL (no custom domains)
+**Quick Tunnels (default):**
+1. **Random URLs**: Each tunnel gets a random `*.trycloudflare.com` URL
 2. **Temporary**: Tunnels are meant for development/testing, not production
 3. **No persistence**: URL changes each time you create a new tunnel
 4. **Rate limits**: Subject to Cloudflare's fair use policy
 
-For production use with custom domains, see the full [cloudflared documentation](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/).
+**Named Tunnels (with `--tunnel-token`):**
+- Requires a free Cloudflare account
+- Provides persistent, dedicated URLs
+- Better suited for staging/production environments
+
+For setting up named tunnels, see the [Cloudflare Tunnel documentation](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/).
 
 ## Security Considerations
 

suxitunnel-0.1.3.dist-info/RECORD

@@ -0,0 +1,17 @@
+./.gitignore,sha256=Zj2M7GCQqPm6hifX5LW6RkR6DYgZUaz9a4oYrGtoqWM,477
+./LICENSE,sha256=1QbfFX4K5Hc9fT1l8GK3N8RQEXz4L9HfZKdd8HKthPQ,1053
+./PKG-INFO,sha256=vVIi4gqQVz5UOjTDily1X35GfJzutQZMkiH4ZLMLW8Y,11976
+./README.md,sha256=8bFGdLIP9zXOtRoF2kU7VJ3OXqcUDAu18GloEsje0OI,10979
+./__init__.py,sha256=kdD8ohA_FzNpfe3tH_afXQZmCs4XPE8Z4-0sTbIL1as,222
+./pyproject.toml,sha256=GG2AVGsbo6CQaXv3vawscZoP0kPoCf_kF7dg5VIkMRk,1436
+./suxitunnel.py,sha256=QJNgxPnefV90Lk2LYxMDxmcRiAnhE6c_NC8yTj_NSS4,12267
+./examples/basic_example.py,sha256=H3pYsBoliHwevU07Pgd91mZXEQRII2mwoSzTAso3LXo,1025
+./examples/context_manager.py,sha256=0uWx04VN_7kPwOiMnMuhWA3MCl5kIW-cAV4c7cJov1o,2808
+./examples/fastapi_example.py,sha256=zG4dN7O4DgZr9KLs-xP2PWE1vCBQDd7CRWlaioa85Fw,1353
+./examples/flask_example.py,sha256=aRmfRqGxzp41scbIgRQb3BOj3oa1KKarSYsSHLJCgms,1243
+./examples/multiple_tunnels.py,sha256=6lamM7g0nYKvxwWD5bTcnvVfXg_19eZ_np0bYt5neZA,3228
+suxitunnel-0.1.3.dist-info/METADATA,sha256=vVIi4gqQVz5UOjTDily1X35GfJzutQZMkiH4ZLMLW8Y,11976
+suxitunnel-0.1.3.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+suxitunnel-0.1.3.dist-info/entry_points.txt,sha256=Y4OF_5gQ2TtS7cJuxBUa04uTb1JGvT7jHsRXARLZKXU,47
+suxitunnel-0.1.3.dist-info/licenses/LICENSE,sha256=1QbfFX4K5Hc9fT1l8GK3N8RQEXz4L9HfZKdd8HKthPQ,1053
+suxitunnel-0.1.3.dist-info/RECORD,,

suxitunnel-0.1.3.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+suxitunnel = suxitunnel:main

suxitunnel.py

@@ -51,19 +51,25 @@ class Tunnel:
         port: int,
         host: str = "localhost",
         cloudflared_path: Optional[str] = None,
-        auto_download: bool = True
+        auto_download: bool = True,
+        tunnel_token: Optional[str] = None,
+        local_https: bool = False
     ):
         """
         Create a tunnel to expose a local port.
-        
+
         Args:
             port: Local port to expose (e.g., 8000)
             host: Local host (default: "localhost")
             cloudflared_path: Path to cloudflared binary (auto-detected if None)
             auto_download: Automatically download cloudflared if not found
+            tunnel_token: Cloudflare tunnel token for named tunnels (optional)
+            local_https: Set to True if local server uses HTTPS (default: False)
         """
         self.port = port
         self.host = host
+        self.tunnel_token = tunnel_token
+        self.local_https = local_https
         self.url: Optional[str] = None
         self._process: Optional[subprocess.Popen] = None
         self._ready = threading.Event()
@@ -203,14 +209,29 @@ class Tunnel:
     
     def _start(self):
         """Start the cloudflared tunnel"""
-        local_url = f"http://{self.host}:{self.port}"
-        
-        # Use Cloudflare Quick Tunnels (no authentication required!)
-        cmd = [
-            self.cloudflared_path,
-            "tunnel",
-            "--url", local_url
-        ]
+        protocol = "https" if self.local_https else "http"
+        local_url = f"{protocol}://{self.host}:{self.port}"
+
+        if self.tunnel_token:
+            # Named tunnel with token
+            cmd = [
+                self.cloudflared_path,
+                "tunnel",
+                "--url", local_url,
+                "run",
+                "--token", self.tunnel_token
+            ]
+        else:
+            # Quick tunnel (no authentication required)
+            cmd = [
+                self.cloudflared_path,
+                "tunnel",
+                "--url", local_url
+            ]
+
+        # Add --no-tls-verify for local HTTPS servers with self-signed certs
+        if self.local_https:
+            cmd.append("--no-tls-verify")
         
         try:
             self._process = subprocess.Popen(
@@ -291,19 +312,77 @@ class Tunnel:
         return f"<Tunnel port={self.port} url={self.url} status={status}>"
 
 
+def parse_args(args: list[str] | None = None):
+    """Parse command line arguments for the CLI."""
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        prog="suxitunnel",
+        description="Expose local servers via Cloudflare Tunnel"
+    )
+    parser.add_argument(
+        "-p", "--port",
+        type=int,
+        required=True,
+        help="Local port to expose"
+    )
+    parser.add_argument(
+        "--tunnel-token",
+        type=str,
+        default=None,
+        help="Cloudflare tunnel token for named tunnels (optional)"
+    )
+    parser.add_argument(
+        "--local-https",
+        action="store_true",
+        default=False,
+        help="Use HTTPS to connect to local server (for servers with self-signed certs)"
+    )
+
+    return parser.parse_args(args)
+
+
 def open_tunnel(port: int, host: str = "localhost") -> Tunnel:
     """
     Convenience function to create a tunnel.
-    
+
     Args:
         port: Local port to expose
         host: Local host (default: "localhost")
-    
+
     Returns:
         Tunnel instance
-    
+
     Example:
         tunnel = open_tunnel(8000)
         print(f"Public URL: {tunnel.url}")
     """
     return Tunnel(port=port, host=host)
+
+
+def main(args: list[str] | None = None) -> None:
+    """CLI entry point for suxitunnel."""
+    parsed = parse_args(args)
+
+    tunnel = Tunnel(
+        port=parsed.port,
+        tunnel_token=parsed.tunnel_token,
+        local_https=parsed.local_https
+    )
+
+    print(f"Tunnel URL: {tunnel.url}")
+    print("Press Ctrl+C to stop the tunnel")
+
+    try:
+        while tunnel.is_alive():
+            time.sleep(1)
+    except KeyboardInterrupt:
+        pass
+    finally:
+        tunnel.close()
+
+    raise SystemExit(0)
+
+
+if __name__ == "__main__":
+    main()

suxitunnel-0.1.2.dist-info/RECORD

@@ -1,16 +0,0 @@
-./.gitignore,sha256=Zj2M7GCQqPm6hifX5LW6RkR6DYgZUaz9a4oYrGtoqWM,477
-./LICENSE,sha256=1QbfFX4K5Hc9fT1l8GK3N8RQEXz4L9HfZKdd8HKthPQ,1053
-./PKG-INFO,sha256=-VEXmZc6Fp7x2KoA2Al1Z4GDUgs20zBLH49NaW8R7z4,10338
-./README.md,sha256=OCBSHbI1lbi9uAPzoejKcGpj6QEw8Y9CqLfHFp8D328,9341
-./__init__.py,sha256=b37S0Mt7B88CPV2j_xJ5VLSqrvMvF-_K-vuSpdmGWFo,223
-./pyproject.toml,sha256=VEOdkiwYsvv2PDvKScFRyyIFhRIcKfapA__OGeceX38,1365
-./suxitunnel.py,sha256=a5pULsz7kBz1nclGoz9fchL6xABLcg3BJ_f1ZgwU0zo,10126
-./examples/basic_example.py,sha256=H3pYsBoliHwevU07Pgd91mZXEQRII2mwoSzTAso3LXo,1025
-./examples/context_manager.py,sha256=0uWx04VN_7kPwOiMnMuhWA3MCl5kIW-cAV4c7cJov1o,2808
-./examples/fastapi_example.py,sha256=zG4dN7O4DgZr9KLs-xP2PWE1vCBQDd7CRWlaioa85Fw,1353
-./examples/flask_example.py,sha256=aRmfRqGxzp41scbIgRQb3BOj3oa1KKarSYsSHLJCgms,1243
-./examples/multiple_tunnels.py,sha256=6lamM7g0nYKvxwWD5bTcnvVfXg_19eZ_np0bYt5neZA,3228
-suxitunnel-0.1.2.dist-info/METADATA,sha256=-VEXmZc6Fp7x2KoA2Al1Z4GDUgs20zBLH49NaW8R7z4,10338
-suxitunnel-0.1.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-suxitunnel-0.1.2.dist-info/licenses/LICENSE,sha256=1QbfFX4K5Hc9fT1l8GK3N8RQEXz4L9HfZKdd8HKthPQ,1053
-suxitunnel-0.1.2.dist-info/RECORD,,