labtool-cf 0.1.1__tar.gz

labtool_cf-0.1.1/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,270 @@
+# 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/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "labtool-cf"
+version = "0.1.1"
+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.1/setup.cfg

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

labtool_cf-0.1.1/src/labtool/__main__.py

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