labtool-cf 0.1.1__py3-none-any.whl

labtool/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

labtool/adapters/cloudflared.py

@@ -0,0 +1,67 @@
+import json
+import subprocess
+from pathlib import Path
+
+import yaml
+
+from ..domain import LabError, Tunnel
+
+CF_DIR = Path.home() / ".cloudflared"
+
+
+def _run(cmd):
+    """Run a command; raise LabError with stderr on failure."""
+    r = subprocess.run(cmd, capture_output=True, text=True)
+    if r.returncode != 0:
+        raise LabError(f"{' '.join(cmd)}\n{r.stderr.strip()}")
+    return r.stdout
+
+
+class CloudflaredGateway:
+    """Talks to Cloudflare through the cloudflared binary."""
+
+    def find(self, name):
+        """Return the Tunnel with this name, or None."""
+        out = _run(["cloudflared", "tunnel", "list", "--output", "json"])
+        for t in json.loads(out) or []:
+            if t["name"] == name:
+                return Tunnel(id=t["id"], name=t["name"])
+        return None
+
+    def create(self, name):
+        _run(["cloudflared", "tunnel", "create", name])
+        return self.find(name)
+
+    def route_dns(self, tunnel_name, hostname):
+        """Create or overwrite the CNAME record for hostname."""
+        _run(["cloudflared", "tunnel", "route", "dns",
+              "--overwrite-dns", tunnel_name, hostname])
+
+    def delete(self, name):
+        """Delete the tunnel; -f also cleans up stale connections."""
+        _run(["cloudflared", "tunnel", "delete", "-f", name])
+
+    def credentials_path(self, tunnel):
+        return str(CF_DIR / f"{tunnel.id}.json")
+
+    def is_logged_in(self):
+        """cert.pem exists only after `cloudflared tunnel login`."""
+        return (CF_DIR / "cert.pem").exists()
+
+    def login(self, log=print):
+        """Run the interactive login; the URL prints straight to the terminal."""
+        log("Open the displayed URL in your browser and click Authorize...")
+        r = subprocess.run(["cloudflared", "tunnel", "login"])
+        if r.returncode != 0:
+            raise LabError("Login failed.")
+
+
+class YamlConfigStore:
+    """Writes the cloudflared config.yml file."""
+
+    def __init__(self, path=CF_DIR / "config.yml"):
+        self.path = path
+
+    def save(self, config):
+        # sort_keys=False: ingress order matters to cloudflared
+        self.path.write_text(yaml.safe_dump(config, sort_keys=False))

labtool/adapters/lab_file.py

@@ -0,0 +1,80 @@
+import yaml
+import os
+from pathlib import Path
+import click
+from ..domain import Lab, LabError, Node
+
+
+APP_NAME = "labtool"
+
+TEMPLATE = """\
+# labtool configuration
+domain: example.com        # a domain that is Active on Cloudflare
+tunnel_name: my-tunnel     # name of the tunnel
+nodes:
+  - name: node1            # becomes node1.example.com
+    ip: 192.168.56.11      # address the tunnel machine can reach
+"""
+
+
+def user_config_path():
+    """Per-user config location (differs per OS)."""
+    return Path(click.get_app_dir(APP_NAME)) / "lab.yaml"
+
+
+def resolve_lab_path(explicit=None):
+    """Find lab.yaml: -f flag, env var, current dir, then user config dir."""
+    if explicit:
+        return Path(explicit)
+
+    env = os.environ.get("LABTOOL_FILE")
+    if env:
+        return Path(env)
+
+    for candidate in (Path("lab.yaml"), user_config_path()):
+        if candidate.exists():
+            return candidate
+
+    raise LabError(
+        "lab.yaml not found. Create one with: labtool config init\n"
+        f"(or pass -f PATH, or set LABTOOL_FILE). Searched: ./lab.yaml, {user_config_path()}"
+    )
+
+
+def write_template(path, force=False):
+    """Write the template; refuse to overwrite unless force=True."""
+    path = Path(path)
+    if path.exists() and not force:
+        raise LabError(f"{path} already exists (use --force to overwrite).")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(TEMPLATE)
+    return path
+
+
+def load_lab(path):
+    """Read and validate the lab file; raise LabError with a clear message."""
+    path = Path(path)
+    try:
+        raw = yaml.safe_load(path.read_text())
+    except FileNotFoundError:
+        raise LabError(f"File {path} not found")
+    except yaml.YAMLError as e:
+        raise LabError(f"{path} is not valid YAML: {e}")
+
+    if not isinstance(raw, dict):
+        raise LabError(f"{path} is empty or has the wrong format")
+
+    for key in ("domain", "tunnel_name", "nodes"):
+        if key not in raw:
+            raise LabError(f"{path}: missing required key '{key}'")
+
+    if not isinstance(raw["nodes"], list) or not raw["nodes"]:
+        raise LabError(f"{path}: 'nodes' must be a non-empty list")
+
+    try:
+        nodes = tuple(Node(**n) for n in raw["nodes"])
+        return Lab(domain=raw["domain"], tunnel_name=raw["tunnel_name"], nodes=nodes)
+    except (TypeError, ValueError) as e:
+        # TypeError: unknown/missing node field, ValueError: invalid IP, duplicate names
+        raise LabError(f"{path}: invalid node definition: {e}")
+    

labtool/adapters/runner.py

@@ -0,0 +1,67 @@
+import os
+import signal
+import subprocess
+import time
+from pathlib import Path
+
+from ..domain import LabError, RunState
+
+STATE_DIR = Path.home() / ".labtool"
+
+
+class ProcessRunner:
+    """Runs cloudflared in the background and tracks it via a PID file."""
+
+    def __init__(self, state_dir=STATE_DIR):
+        self.dir = Path(state_dir)
+        self.pid_file = self.dir / "tunnel.pid"
+        self.log_path = self.dir / "tunnel.log"
+
+    def _read_pid(self):
+        try:
+            return int(self.pid_file.read_text())
+        except (FileNotFoundError, ValueError):
+            return None
+
+    def _alive(self, pid):
+        """Signal 0 sends nothing; it only checks that the process exists."""
+        try:
+            os.kill(pid, 0)
+            return True
+        except ProcessLookupError:
+            return False
+        except PermissionError:
+            return True  # exists, but owned by another user
+
+    def state(self):
+        """A stale PID file (dead process) counts as not running."""
+        pid = self._read_pid()
+        if pid and self._alive(pid):
+            return RunState(True, pid)
+        return RunState(False)
+
+    def start(self, tunnel_name):
+        self.dir.mkdir(parents=True, exist_ok=True)
+        log = open(self.log_path, "ab")
+        proc = subprocess.Popen(
+            ["cloudflared", "tunnel", "run", tunnel_name],
+            stdout=log, stderr=log,
+            start_new_session=True,  # detach so it survives closing the terminal/SSH
+        )
+        self.pid_file.write_text(str(proc.pid))
+        time.sleep(1)  # if it dies immediately, report it instead of hiding it
+        if proc.poll() is not None:
+            self.pid_file.unlink(missing_ok=True)
+            raise LabError(f"cloudflared exited immediately. Log: {self.log_path}")
+        return proc.pid
+
+    def stop(self):
+        """Send SIGTERM and wait up to 5 seconds for a clean exit."""
+        pid = self._read_pid()
+        if pid and self._alive(pid):
+            os.kill(pid, signal.SIGTERM)
+            for _ in range(50):
+                if not self._alive(pid):
+                    break
+                time.sleep(0.1)
+        self.pid_file.unlink(missing_ok=True)

labtool/adapters/system.py

@@ -0,0 +1,29 @@
+import platform
+import shutil
+import subprocess
+
+from ..domain import LabError, Platform
+
+
+def detect_platform():
+    system = platform.system().lower()          # darwin | linux | windows
+    machine = platform.machine().lower()
+    arch = "arm64" if machine in ("arm64", "aarch64") else "amd64"
+    return Platform(
+        system=system,
+        arch=arch,
+        has_apt=shutil.which("apt-get") is not None,
+        has_brew=shutil.which("brew") is not None,
+    )
+
+
+def is_installed():
+    return shutil.which("cloudflared") is not None
+
+
+def run_commands(commands, log=print):
+    for cmd in commands:
+        log("$ " + " ".join(cmd))
+        r = subprocess.run(cmd)
+        if r.returncode != 0:
+            raise LabError(f"دستور شکست خورد: {' '.join(cmd)}")

labtool/cli.py

@@ -0,0 +1,145 @@
+import click
+import sys
+from pathlib import Path
+from labtool.adapters import system
+from labtool.services import install_cloudflared
+from importlib.metadata import version
+from labtool.adapters.cloudflared import CloudflaredGateway, YamlConfigStore
+from labtool.adapters.lab_file import load_lab
+from labtool.adapters.runner import ProcessRunner
+from labtool.domain import LabError
+from labtool.services import (
+    delete_tunnel,
+    down_tunnel,
+    ensure_login,
+    init_tunnel,
+    tunnel_status,
+    up_tunnel,
+)
+from . import ui
+from .adapters.lab_file import load_lab, resolve_lab_path, user_config_path, write_template
+
+
+
+
+
+CONTEXT = {"help_option_names": ["-h", "--help"]}
+
+
+@click.group(context_settings=CONTEXT)
+@click.version_option(version("labtool-cf"), "-v", "--version", prog_name="labtool-cf")
+def cli():
+    """labtool: manage a Cloudflare tunnel for your lab nodes.
+
+    \b
+    Typical flow:
+      labtool install    install cloudflared
+      labtool login      authorize with Cloudflare
+      labtool init       create tunnel, DNS and config.yml
+      labtool up         run the tunnel in the background
+      labtool status     check whether it is running
+      labtool down       stop it
+    """
+    
+    
+@cli.command(context_settings=CONTEXT)
+@click.option("-f", "--file", default=None, show_default=True)
+def init(file):
+    """Create the tunnel, DNS records and config.yml."""
+    lab = load_lab(resolve_lab_path(file))
+    init_tunnel(lab, CloudflaredGateway(), YamlConfigStore(), log=ui.smart_log)
+
+
+@cli.command(context_settings=CONTEXT)
+def install():
+    """Install cloudflared on this system."""
+    install_cloudflared(system.detect_platform, system.is_installed,
+                        system.run_commands, log=ui.smart_log)          
+
+@cli.command(context_settings=CONTEXT)
+def status():
+    """Show whether the tunnel is running."""
+    state = tunnel_status(ProcessRunner())
+    if state.running:
+        ui.success(f"Running (PID {state.pid})")
+    else:
+        ui.warn("Stopped")
+
+
+@cli.command(context_settings=CONTEXT)
+@click.option("-f", "--file", default=None, show_default=True)
+@click.option("-y", "--yes", is_flag=True, help="Skip the confirmation prompt.")
+def delete(file, yes):
+    """Delete the tunnel from Cloudflare (irreversible)."""
+    lab = load_lab(resolve_lab_path(file))
+    if not yes:
+        click.confirm(
+            click.style(f"Delete tunnel '{lab.tunnel_name}'?", fg="red", bold=True),
+            abort=True,
+        )
+    delete_tunnel(lab, CloudflaredGateway(), ProcessRunner(), log=ui.smart_log)
+    
+@cli.command(context_settings=CONTEXT)
+@click.option("-f", "--file", default=None, show_default=True,
+              help="Path to the lab definition file.")
+def up(file):
+    """Run the tunnel in the background."""
+    lab = load_lab(resolve_lab_path(file))
+    up_tunnel(lab, CloudflaredGateway(), ProcessRunner(), log=ui.smart_log)
+
+
+@cli.command(context_settings=CONTEXT)
+def down():
+    """Stop the running tunnel."""
+    down_tunnel(ProcessRunner(), log=ui.smart_log)
+
+
+@cli.command(context_settings=CONTEXT)
+def login():
+    """Log in to Cloudflare (creates cert.pem)."""
+    ensure_login(CloudflaredGateway(), log=ui.smart_log)
+    
+    
+    
+@cli.group(context_settings=CONTEXT)
+def config():
+    """Manage the lab.yaml configuration file."""
+
+
+@config.command("init", context_settings=CONTEXT)
+@click.option("--local", is_flag=True, help="Create ./lab.yaml instead of the user config dir.")
+@click.option("--force", is_flag=True, help="Overwrite an existing file.")
+def config_init(local, force):
+    """Create a template lab.yaml and show where it is."""
+    path = Path("lab.yaml") if local else user_config_path()
+    write_template(path, force)
+    ui.success(f"Created {path}")
+    ui.info("Edit it (domain, tunnel_name, nodes), then run: labtool init")
+
+
+@config.command("path", context_settings=CONTEXT)
+def config_path():
+    """Print the config file that would be used."""
+    click.echo(resolve_lab_path())
+
+    
+    
+    
+def main():
+    """Entry point: turn errors and Ctrl+C into clean, colored messages."""
+    try:
+        cli(standalone_mode=False)
+    except click.exceptions.Abort:
+        ui.warn("Cancelled.")
+        sys.exit(130)                     # 130 = conventional exit code for Ctrl+C
+    except KeyboardInterrupt:
+        ui.warn("Cancelled (Ctrl+C).")
+        sys.exit(130)
+    except click.ClickException as e:
+        ui.error(e.format_message())
+        sys.exit(e.exit_code)
+    except click.exceptions.Exit as e:
+        sys.exit(e.exit_code)
+    except LabError as e:
+        ui.error(str(e))
+        sys.exit(1)

labtool/config_builder.py

@@ -0,0 +1,11 @@
+def build_tunnel_config(lab, tunnel, credentials_path):
+    ingress = [
+        {"hostname": lab.hostname(n), "service": n.service}
+        for n in lab.nodes
+    ]
+    ingress.append({"service": "http_status:404"})  # The final mandatory rule
+    return {
+        "tunnel": tunnel.id,
+        "credentials-file": credentials_path,
+        "ingress": ingress,
+    }

labtool/domain.py

@@ -0,0 +1,80 @@
+import ipaddress
+from dataclasses import dataclass
+
+
+class LabError(Exception):
+    """A user-facing error."""
+
+
+@dataclass(frozen=True)
+class Node:
+    name: str
+    ip: str
+    port: int = 22
+
+    def __post_init__(self):
+        ipaddress.ip_address(self.ip)  # An invalid IP triggers an error here.
+
+    @property
+    def service(self):
+        return f"ssh://{self.ip}:{self.port}"
+
+
+@dataclass(frozen=True)
+class Lab:
+    domain: str
+    tunnel_name: str
+    nodes: tuple
+
+    def __post_init__(self):
+        names = [n.name for n in self.nodes]
+        if len(names) != len(set(names)):
+            raise LabError("The node names are duplicated.")
+
+    def hostname(self, node):
+        return f"{node.name}.{self.domain}"
+
+
+@dataclass(frozen=True)
+class Tunnel:
+    id: str
+    name: str
+    
+@dataclass(frozen=True)
+class Platform:
+    system: str   # "darwin" | "linux" | "windows"
+    arch: str     # "amd64" | "arm64"
+    has_apt: bool = False
+    has_brew: bool = False
+
+@dataclass(frozen=True)
+class RunState:
+    """Whether the tunnel process is running, and its PID if so."""
+    running: bool
+    pid: int | None = None
+    
+    
+def plan_install(p):
+    """List of commands required to install cloudflared on this platform."""
+    if p.system == "darwin":
+        if not p.has_brew:
+            raise LabError("brew is required to install cloudflared on macOS")
+        return [["brew", "install", "cloudflared"]]
+
+    if p.system == "linux":
+        url = ("https://github.com/cloudflare/cloudflared/releases/latest/download/"
+               f"cloudflared-linux-{p.arch}")
+        if p.has_apt:
+            return [
+                ["curl", "-fsSL", "-o", "/tmp/cloudflared.deb", url + ".deb"],
+                ["sudo", "dpkg", "-i", "/tmp/cloudflared.deb"],
+            ]
+        return [
+            ["curl", "-fsSL", "-o", "/tmp/cloudflared", url],
+            ["sudo", "install", "/tmp/cloudflared", "/usr/local/bin/cloudflared"],
+        ]
+
+    if p.system == "windows":
+        return [["winget", "install", "--id", "Cloudflare.cloudflared", "-e"]]
+
+    raise LabError(f"Unsupported operating system: {p.system}")

labtool/labtool.py

@@ -0,0 +1,39 @@
+import ipaddress
+
+import click
+import yaml
+
+
+def load_lab(path):
+    with open(path) as f:
+        lab = yaml.safe_load(f)
+    for node in lab["nodes"]:
+        ipaddress.ip_address(node["ip"])
+    return lab
+
+
+@click.group()
+def cli():
+    """lab tool management"""
+
+
+@cli.command()
+@click.option("--file", "-f", default="lab.yaml")
+@click.option("--tunnel-id", required=True)
+@click.option("--creds", default="~/.cloudflared/TUNNEL_ID.json")
+def render(file, tunnel_id, creds):
+    """print tunnel config.yml"""
+    lab = load_lab(file)
+    ingress = []
+    for node in lab["nodes"]:
+        ingress.append({
+            "hostname": f"{node['name']}.{lab['domain']}",
+            "service": f"ssh://{node['ip']}:22",
+        })
+    ingress.append({"service": "http_status:404"})
+    config = {"tunnel": tunnel_id, "credentials-file": creds, "ingress": ingress}
+    click.echo(yaml.safe_dump(config, sort_keys=False))
+
+
+if __name__ == "__main__":
+    cli()

labtool/ports.py

@@ -0,0 +1,12 @@
+from typing import Protocol
+
+
+class TunnelGateway(Protocol):
+    def find(self, name): ...
+    def create(self, name): ...
+    def route_dns(self, tunnel_name, hostname): ...
+    def credentials_path(self, tunnel): ...
+
+
+class ConfigStore(Protocol):
+    def save(self, config): ...

labtool/services.py

@@ -0,0 +1,94 @@
+from .config_builder import build_tunnel_config
+from .domain import plan_install
+from .domain import LabError
+
+
+
+
+
+
+def init_tunnel(lab, gateway, store, log=print):
+    ensure_login(gateway, log)
+    tunnel = gateway.find(lab.tunnel_name)
+    if tunnel:
+        log(f"tunnel {lab.tunnel_name} already exists.")
+    else:
+        tunnel = gateway.create(lab.tunnel_name)
+        log(f"tunnel {lab.tunnel_name} created.")
+
+    for node in lab.nodes:
+        host = lab.hostname(node)
+        gateway.route_dns(lab.tunnel_name, host)
+        log(f"DNS: {host}")
+
+    config = build_tunnel_config(lab, tunnel, gateway.credentials_path(tunnel))
+    store.save(config)
+    return tunnel
+
+
+def ensure_login(gateway, log=print):
+    """Start the interactive login only if cert.pem is missing."""
+    if gateway.is_logged_in():
+        log("Already logged in.")
+        return False
+    gateway.login(log)
+    return True
+
+
+def up_tunnel(lab, gateway, runner, log=print):
+    """Run the tunnel in the background (no-op if already running)."""
+    state = runner.state()
+    if state.running:
+        log(f"The tunnel is already running (PID {state.pid}).")
+        return state
+
+    tunnel = gateway.find(lab.tunnel_name)
+    if not tunnel:
+        raise LabError(f"The tunnel {lab.tunnel_name} does not exist. First run: labtool init")
+
+    pid = runner.start(lab.tunnel_name)
+    log(f"The tunnel is running (PID {pid}). Log: {runner.log_path}")
+    return runner.state()
+
+
+def down_tunnel(runner, log=print):
+    """Stop the running tunnel. Returns True if something was stopped."""
+    state = runner.state()
+    if not state.running:
+        log("The tunnel is not running.")
+        return False
+    runner.stop()
+    log(f"The tunnel has been stopped (PID {state.pid}).")
+    return True
+
+
+def tunnel_status(runner):
+    """Return the current RunState."""
+    return runner.state()
+
+
+def delete_tunnel(lab, gateway, runner, log=print):
+    """Stop the tunnel, then delete it from Cloudflare."""
+    tunnel = gateway.find(lab.tunnel_name)
+    if not tunnel:
+        log(f"Tunnel {lab.tunnel_name} does not exist.")
+        return False
+
+    down_tunnel(runner, log)  # a running tunnel cannot be deleted
+    gateway.delete(lab.tunnel_name)
+    log(f"Tunnel {lab.tunnel_name} has been deleted.")
+    return True
+
+
+
+
+def install_cloudflared(detect, installed, run, log=print):
+    if installed():
+        log("cloudflared is already installed.")
+        return False
+    commands = plan_install(detect())
+    run(commands, log)
+    log("cloudflared installed.")
+    return True
+
+

labtool/ui.py

@@ -0,0 +1,34 @@
+import click
+
+
+def success(msg):
+    click.echo(click.style("✔ ", fg="green", bold=True) + msg)
+
+
+def info(msg):
+    click.echo(click.style("ℹ ", fg="cyan") + msg)
+
+
+def warn(msg):
+    click.echo(click.style("! ", fg="yellow", bold=True) + click.style(msg, fg="yellow"))
+
+
+def error(msg):
+    click.echo(click.style("✖ ", fg="red", bold=True) + click.style(msg, fg="red"), err=True)
+
+
+def step(msg):
+    """A command being run, shown dimmed."""
+    click.echo(click.style(f"$ {msg}", dim=True))
+
+
+def smart_log(msg):
+    """Pick a color by message content so services stay UI-agnostic."""
+    if "created" in msg or "started" in msg or "stopped" in msg or "deleted" in msg:
+        success(msg)
+    elif "already exists" in msg or "does not exist" in msg or "not found" in msg:
+        warn(msg)
+    elif msg.startswith("$"):
+        step(msg[2:])
+    else:
+        info(msg)

labtool_cf-0.1.1.dist-info/METADATA

@@ -0,0 +1,292 @@
+Metadata-Version: 2.4
+Name: labtool-cf
+Version: 0.1.1
+Summary: Manage a Cloudflare Tunnel for machines behind NAT
+Author-email: Your Name <you@example.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/afourteene/labtool
+Keywords: cloudflare,tunnel,cloudflared,cli
+Classifier: Programming Language :: Python :: 3
+Classifier: Environment :: Console
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# labtool
+
+A small CLI that sets up and manages a Cloudflare Tunnel (`cloudflared`) for machines behind NAT, so they can be reached over the internet without opening any ports.
+
+Everything is described in one file, `lab.yaml`. The tool turns it into a tunnel, DNS records and a `cloudflared` `config.yml`.
+
+## Requirements
+
+- Python 3.10+
+- A domain managed by Cloudflare (status: Active)
+- A Cloudflare account (used once for `labtool login`)
+- `cloudflared` (the tool can install it for you: `labtool install`)
+
+## Using your domain with Cloudflare
+
+`labtool` creates DNS records such as `node1.example.com`, so your domain must be managed by Cloudflare (its nameservers must point to Cloudflare). You only do this once per domain.
+
+### Option A: you already own a domain at another registrar
+
+1. Create a free account at [dash.cloudflare.com](https://dash.cloudflare.com).
+2. Go to **Domains** and click **Add domain**. Enter your domain (for example `example.com`) and choose the **Free** plan.
+3. Cloudflare scans your existing DNS records. Review them and continue. Keep any records you still need (website, mail).
+4. Cloudflare shows you two nameservers, for example `xxx.ns.cloudflare.com` and `yyy.ns.cloudflare.com`.
+5. Log in to your registrar (where you bought the domain), open the domain's nameserver settings, and replace the current nameservers with the two from Cloudflare.
+6. Wait until the domain shows **Active** in the Cloudflare dashboard. This usually takes minutes, but can take up to 24 hours.
+
+Check from the terminal:
+
+```bash
+dig +short NS example.com
+```
+
+The output should list the two `*.ns.cloudflare.com` servers.
+
+### Option B: buy the domain from Cloudflare
+
+In the dashboard choose **Domains**, then **Buy domain**. A domain bought there is managed by Cloudflare right away; there is nothing to move.
+
+### Authorize labtool for that domain
+
+Run:
+
+```bash
+labtool login
+```
+
+Open the printed URL, log in, and **select your domain** on the authorization page. Cloudflare saves a `cert.pem` that lets `labtool` create tunnels and DNS records for that domain only. If you own several domains, pick the one set as `domain:` in `lab.yaml`.
+
+### What `labtool init` does to your DNS
+
+For every node in `lab.yaml` it creates a proxied `CNAME` record that points to the tunnel:
+
+| Record | Type | Points to |
+|---|---|---|
+| `node1.example.com` | CNAME (proxied) | `<TUNNEL_ID>.cfargotunnel.com` |
+
+Notes:
+
+- No server IP is stored in DNS, and no port has to be opened on your machines.
+- If a record with the same name already exists, `init` overwrites it. Do not reuse a hostname that serves something else.
+- To use a subdomain only for this tool, set `domain: lab.example.com` in `lab.yaml`; nodes then become `node1.lab.example.com`.
+- After `labtool delete`, the CNAME records stay in DNS. Remove them in the dashboard under **DNS > Records**.
+- The free plan is enough. No payment method is needed for DNS and tunnels.
+
+### Troubleshooting the domain
+
+| Problem | Fix |
+|---|---|
+| Domain stays **Pending** | Nameservers at the registrar are not changed yet, or have not propagated. Re-check step 5 and wait. |
+| `labtool init` cannot create DNS records | The domain is not Active, or you selected a different domain during `labtool login`. Delete `~/.cloudflared/cert.pem` and run `labtool login` again. |
+| `node1.example.com` does not resolve | The record is missing. Run `labtool init` again and check the dashboard under **DNS > Records**. |
+
+## Installation
+
+### From PyPI (recommended)
+
+```bash
+pipx install labtool-cf
+labtool -h
+```
+
+`pipx` installs the tool in its own isolated environment, so it does not clash with system Python packages. You can also use `pip install labtool-cf` inside a virtual environment. The package is called `labtool-cf`; the command it installs is `labtool`.
+
+Upgrade with `pipx upgrade labtool-cf`.
+
+### From source (development)
+
+From the project root (the folder containing `pyproject.toml`):
+
+```bash
+python3 -m venv venv
+source venv/bin/activate
+pip install -e .
+labtool -h
+```
+
+For development (tests):
+
+```bash
+pip install pytest
+pytest -v
+```
+
+You can also run it as a module: `python -m labtool -h`.
+
+## Configuration: `lab.yaml`
+
+```yaml
+domain: example.com        # a domain active on Cloudflare
+tunnel_name: my-tunnel     # name of the tunnel
+nodes:
+  - name: node1            # becomes node1.example.com
+    ip: 192.168.56.11      # address the tunnel machine can reach
+  - name: node2
+    ip: 192.168.56.12
+```
+
+Each node is exposed as `ssh://<ip>:22` under `<name>.<domain>`.
+
+### Creating the file
+
+The easiest way is to let the tool create a template for you:
+
+```bash
+labtool config init          # creates the file in your user config directory
+labtool config path          # shows which file will be used
+```
+
+Then edit the file it printed (set `domain`, `tunnel_name` and `nodes`). Useful options:
+
+- `labtool config init --local` creates `./lab.yaml` in the current folder instead.
+- `labtool config init --force` overwrites an existing file (without it, an existing file is never touched).
+
+User config directory:
+
+| System | Path |
+|---|---|
+| Linux | `~/.config/labtool/lab.yaml` |
+| macOS | `~/Library/Application Support/labtool/lab.yaml` |
+| Windows | `%APPDATA%\labtool\lab.yaml` |
+
+### Where the tool looks for the file
+
+The first match wins:
+
+1. The `-f PATH` option
+2. The `LABTOOL_FILE` environment variable
+3. `./lab.yaml` in the current folder
+4. The user config directory (table above)
+
+If none exists, the command stops and tells you to run `labtool config init`.
+
+You can keep one `lab.yaml` per project (use option 3 or `-f`), or one global file for everything (option 4). For scripts and CI, set `LABTOOL_FILE`:
+
+```bash
+export LABTOOL_FILE=/path/to/lab.yaml
+labtool init
+```
+
+## Quick start
+
+```bash
+labtool install      # 1. install cloudflared for this OS
+labtool config init  # 2. create a template lab.yaml, then edit it
+labtool login        # 3. authorize with Cloudflare (creates cert.pem)
+labtool init         # 4. create tunnel + DNS records + config.yml
+labtool up           # 5. run the tunnel in the background
+labtool status       # 6. check it
+labtool down         # 7. stop it
+```
+
+## How it works
+
+1. **You describe the lab** in `lab.yaml`: a domain, a tunnel name and a list of nodes (name + IP).
+2. **`labtool init`** talks to Cloudflare through the `cloudflared` binary. It creates the tunnel (once), adds a DNS record `<node>.<domain>` for every node, and writes a `config.yml` whose `ingress` rules map each hostname to `ssh://<ip>:22`. A last catch-all rule (`http_status:404`) is added automatically, because `cloudflared` requires it.
+3. **`labtool up`** starts `cloudflared tunnel run` in the background and remembers its PID. The tunnel connects *outward* to Cloudflare, so no inbound port is opened.
+4. **A client** connects to `node1.example.com`. The request reaches Cloudflare, travels through the tunnel to your machine, and is forwarded to the node's IP.
+5. **`labtool down`** stops the process; the hostnames stop working until you run `up` again.
+
+```
+client ──ssh──► Cloudflare ──► tunnel (cloudflared on your machine) ──► node IP:22
+```
+
+## Commands
+
+Every command supports `-h` / `--help`. `labtool -v` prints the version.
+
+| Command | What it does |
+|---|---|
+| `install` | Installs `cloudflared` (Homebrew on macOS, `.deb` or binary on Linux, `winget` on Windows). Skips if already installed. |
+| `login` | Runs `cloudflared tunnel login`. Prints a URL; open it in any browser and click Authorize. Skips if `cert.pem` already exists. |
+| `init` | Logs in if needed, creates the tunnel if missing, routes DNS for every node, and writes `~/.cloudflared/config.yml`. This is the only command that creates the tunnel. |
+| `up` | Starts `cloudflared tunnel run` in the background. Does nothing if already running. |
+| `down` | Stops the running tunnel. |
+| `status` | Shows whether the tunnel is running (and its PID). |
+| `delete` | Stops and deletes the tunnel from Cloudflare. Asks for confirmation; `-y` skips the prompt. Irreversible. |
+
+| `config init` | Creates a template `lab.yaml` in the user config directory. Options: `--local` (use `./lab.yaml`), `--force` (overwrite). |
+| `config path` | Prints the `lab.yaml` that would be used. |
+
+`init`, `up` and `delete` accept `-f, --file PATH` to choose the lab file (see "Where the tool looks for the file" above). The other commands do not read it.
+
+All commands are safe to run more than once (idempotent).
+
+## Files used
+
+| Path | Purpose |
+|---|---|
+| `~/.cloudflared/cert.pem` | Result of `login`. Admin access to your domain; treat it like a password. |
+| `~/.cloudflared/<TUNNEL_ID>.json` | Tunnel credentials, needed on any machine that runs the tunnel. |
+| `~/.cloudflared/config.yml` | Generated by `init`. |
+| `lab.yaml` | Your configuration (see "Configuration" above). Not stored inside the package. |
+| `~/.labtool/tunnel.pid` | PID of the background tunnel. |
+| `~/.labtool/tunnel.log` | `cloudflared` output (check here if `up` fails). |
+
+## Connecting to a node
+
+Install `cloudflared` on the client machine, then:
+
+```bash
+ssh -i ~/.ssh/id_rsa \
+  -o ProxyCommand="cloudflared access ssh --hostname %h" \
+  user@node1.example.com
+```
+
+## Running the tunnel on another machine
+
+- `cert.pem` is only needed for management commands (`init`, `delete`). Running a tunnel (`up`) needs only `<TUNNEL_ID>.json` and `config.yml`.
+- The credentials file exists only on the machine where the tunnel was created. Either copy it to the other machine, or set a different `tunnel_name` in that machine's `lab.yaml` and run `labtool init` there to create a separate tunnel.
+- Do not run the same tunnel on two machines at once unless you want traffic split between them. Stop one with `labtool down` (or `Ctrl+C`).
+- `init` overwrites existing DNS records, so they will point to the tunnel you just initialised.
+
+## Troubleshooting
+
+| Message | Cause and fix |
+|---|---|
+| `Cannot determine default origin certificate path` | No `cert.pem`. Run `labtool login`. |
+| `Tunnel credentials file ... doesn't exist` | Credentials are missing on this machine. Copy the `.json`, or create a tunnel here. |
+| `cloudflared exited immediately` | Check `~/.labtool/tunnel.log` (bad config or missing credentials). |
+| `You have an existing certificate ... which login would overwrite` | You are already logged in. Nothing to do. |
+| `lab.yaml not found` | No file in any searched location. Run `labtool config init`, or pass `-f PATH`. |
+| `... is empty or has the wrong format` / `missing required key` | The file is empty or incomplete. It needs `domain`, `tunnel_name` and a non-empty `nodes` list. |
+| `No module named labtool.cli` | `cli.py` must be in `src/labtool/`; then run `pip install -e .` again. |
+
+`Ctrl+C` cancels any command cleanly (exit code 130).
+
+## Project layout
+
+```
+labtool/
+├── pyproject.toml
+├── lab.yaml
+├── src/labtool/
+│   ├── cli.py            # click commands only (wiring)
+│   ├── ui.py             # colored output
+│   ├── services.py       # use cases: init, up, down, delete, ...
+│   ├── domain.py         # models and pure rules, no I/O
+│   ├── config_builder.py # pure function: Lab -> tunnel config
+│   ├── ports.py          # interfaces
+│   └── adapters/         # cloudflared, process runner, system, lab file
+└── tests/                # run with pytest, using fakes (no Cloudflare needed)
+```
+
+Dependencies point inward: `cli -> services -> domain`, and adapters implement the interfaces in `ports`. Services never import `click` or `subprocess`, which is why they can be tested with fakes.
+
+## Security notes
+
+- Never commit `cert.pem`, `<TUNNEL_ID>.json`, SSH private keys, or tokens. Add them to `.gitignore` (`venv/`, `.labtool/`, `*.json`, `ssh-keys/`).
+- Use key-only SSH on the nodes (`PasswordAuthentication no`).
+- A tunnel hostname is public while the tunnel runs. Stop it with `labtool down` when you are not using it.

labtool_cf-0.1.1.dist-info/RECORD

@@ -0,0 +1,20 @@
+labtool/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+labtool/__main__.py,sha256=VlwlDPUFQme_ppKS7d1cN-_ww3xpMR2WGOPVqVUcMZo,29
+labtool/cli.py,sha256=8EZF-6aCKVxLVJv6qY4YuQU27FKZTSTiXygJyncMslY,4636
+labtool/config_builder.py,sha256=S5UOq1ixG7Ai_veN93cBFJqbYqjM0ZwQh0r13fHEnPg,365
+labtool/domain.py,sha256=EJ-_q416I9p30XCQcVBJTmnuU9V8pioGhh31B8Vt9jQ,2139
+labtool/labtool.py,sha256=sfP4JcPS0bHBrznBMLzA4KNl6IZuAiq2Ph2_prORPhI,957
+labtool/ports.py,sha256=F5RhcIRii8Pw5EDMT1MQhT1Ab7r51g7PtAUl3jWdL7A,281
+labtool/services.py,sha256=AXoBF3haW_1Vc5lFkyfdQWpwlhvoxNZk9rxyds_rZLo,2575
+labtool/ui.py,sha256=o9dXK0eU2qKLUKxjE55_jtMiywt_HNfnl42OsPaPKpo,881
+labtool/adapters/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+labtool/adapters/cloudflared.py,sha256=Qpj-70ymjG3X3hA-QjbwAMEq4cOQhwy7nWphjV6UNj8,2177
+labtool/adapters/lab_file.py,sha256=fzT67fOVRZooDtl_SI4-iIpT8FvWICyxmSLlOS-567I,2523
+labtool/adapters/runner.py,sha256=wHMBTKTIWZKZ5Bhp7xm88vJu2W0dibttpNLPCcgQK1o,2196
+labtool/adapters/system.py,sha256=0xZGJDGlnsqsf6SL6M_GsqwozubsSUoH5DV8cOtZk3M,781
+labtool_cf-0.1.1.dist-info/licenses/LICENSE,sha256=z0vVDrwjw-5LNq0_xqmIcfPcWIOABEklibuYrvt1WnQ,1074
+labtool_cf-0.1.1.dist-info/METADATA,sha256=-bAF-rADrRN0HgvdQ8Lwu8XqtgOns6qKINljktMaLG0,12777
+labtool_cf-0.1.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+labtool_cf-0.1.1.dist-info/entry_points.txt,sha256=WFTkfNwQ5QB1K0WqMIdiftxY2XI8XxZ1dNDgtvFKDP4,45
+labtool_cf-0.1.1.dist-info/top_level.txt,sha256=tB36FzMvBypIGqfkSHKb-Bgf0Ta6oJJDtVtm8baSm5M,8
+labtool_cf-0.1.1.dist-info/RECORD,,

labtool_cf-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

labtool_cf-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+labtool = labtool.cli:main

labtool_cf-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amirhossein Ziaee
+
+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.

labtool_cf-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+labtool