labtool-cf 0.1.0__tar.gz

labtool_cf-0.1.0/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.0/PKG-INFO

@@ -0,0 +1,233 @@
+Metadata-Version: 2.4
+Name: labtool-cf
+Version: 0.1.0
+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 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>`. Run commands from the folder that contains `lab.yaml`, or pass `-f path/to/lab.yaml`.
+
+## Quick start
+
+```bash
+labtool install     # 1. install cloudflared for this OS
+labtool login       # 2. authorize with Cloudflare (creates cert.pem)
+labtool init        # 3. create tunnel + DNS records + config.yml
+labtool up          # 4. run the tunnel in the background
+labtool status      # 5. check it
+labtool down        # 6. 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. |
+
+Common option: `-f, --file PATH` (default `lab.yaml`).
+
+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`. |
+| `~/.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 is empty or invalid` | The file is empty or has the wrong format. |
+| `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.0/README.md

@@ -0,0 +1,211 @@
+# 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 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>`. Run commands from the folder that contains `lab.yaml`, or pass `-f path/to/lab.yaml`.
+
+## Quick start
+
+```bash
+labtool install     # 1. install cloudflared for this OS
+labtool login       # 2. authorize with Cloudflare (creates cert.pem)
+labtool init        # 3. create tunnel + DNS records + config.yml
+labtool up          # 4. run the tunnel in the background
+labtool status      # 5. check it
+labtool down        # 6. 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. |
+
+Common option: `-f, --file PATH` (default `lab.yaml`).
+
+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`. |
+| `~/.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 is empty or invalid` | The file is empty or has the wrong format. |
+| `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.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "labtool-cf"
+version = "0.1.0"
+description = "Manage a Cloudflare Tunnel for machines behind NAT"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "Your Name", email = "you@example.com" }]
+keywords = ["cloudflare", "tunnel", "cloudflared", "cli"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Environment :: Console",
+    "Operating System :: OS Independent",
+]
+dependencies = ["click>=8.1", "pyyaml>=6.0"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "build", "twine"]
+
+[project.urls]
+Homepage = "https://github.com/afourteene/labtool"
+
+[project.scripts]
+labtool = "labtool.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

labtool_cf-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

labtool_cf-0.1.0/src/labtool/__main__.py

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

labtool_cf-0.1.0/src/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_cf-0.1.0/src/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}")
+