Remove unused PortMapping.protocol field

Instead of a Python traceback, display a clean error message with
the red ✗ symbol when the config file cannot be found.

README.md

@@ -117,33 +117,38 @@ Compose files are expected at `{compose_dir}/{service}/compose.yaml` (also suppo
 
 ## Usage
 
+The CLI is available as both `compose-farm` and the shorter `cf` alias.
+
 ```bash
 # Start services (auto-migrates if host changed in config)
-compose-farm up plex jellyfin
-compose-farm up --all
+cf up plex jellyfin
+cf up --all
 
 # Stop services
-compose-farm down plex
+cf down plex
 
 # Pull latest images
-compose-farm pull --all
+cf pull --all
 
 # Restart (down + up)
-compose-farm restart plex
+cf restart plex
 
 # Update (pull + down + up) - the end-to-end update command
-compose-farm update --all
+cf update --all
 
 # Sync state with reality (discovers running services + captures image digests)
-compose-farm sync              # updates state.yaml and dockerfarm-log.toml
-compose-farm sync --dry-run    # preview without writing
+cf sync              # updates state.yaml and dockerfarm-log.toml
+cf sync --dry-run    # preview without writing
+
+# Check config vs disk (find missing services, validate traefik labels)
+cf check
 
 # View logs
-compose-farm logs plex
-compose-farm logs -f plex  # follow
+cf logs plex
+cf logs -f plex  # follow
 
 # Show status
-compose-farm ps
+cf ps
 ```
 
 ### Auto-Migration
@@ -158,7 +163,7 @@ When you change a service's host assignment in config and run `up`, Compose Farm
 services:
   plex: nas01
 
-# After: change to nas02, then run `compose-farm up plex`
+# After: change to nas02, then run `cf up plex`
 services:
   plex: nas02  # Compose Farm will migrate automatically
 ```
@@ -211,7 +216,7 @@ providers:
 **Generate the fragment**
 
 ```bash
-compose-farm traefik-file --all --output /mnt/data/traefik/dynamic.d/compose-farm.yml
+cf traefik-file --all --output /mnt/data/traefik/dynamic.d/compose-farm.yml
 ```
 
 Re‑run this after changing Traefik labels, moving a service to another host, or changing
@@ -238,7 +243,7 @@ services:
 The `traefik_service` option specifies which service runs Traefik. Services on the same host
 are skipped in the file-provider config since Traefik's docker provider handles them directly.
 
-Now `compose-farm up plex` will update the Traefik config automatically—no separate
+Now `cf up plex` will update the Traefik config automatically—no separate
 `traefik-file` command needed.
 
 **Combining with existing config**
@@ -249,7 +254,7 @@ directory and Traefik will merge all files:
 ```bash
 mkdir -p /opt/traefik/dynamic.d
 mv /opt/traefik/dynamic.yml /opt/traefik/dynamic.d/manual.yml
-compose-farm traefik-file --all -o /opt/traefik/dynamic.d/compose-farm.yml
+cf traefik-file --all -o /opt/traefik/dynamic.d/compose-farm.yml
 ```
 
 Update your Traefik config to use directory watching instead of a single file:
@@ -272,7 +277,7 @@ Update your Traefik config to use directory watching instead of a single file:
 
 ## How It Works
 
-1. You run `compose-farm up plex`
+1. You run `cf up plex`
 2. Compose Farm looks up which host runs `plex` (e.g., `nas01`)
 3. It SSHs to `nas01` (or runs locally if `localhost`)
 4. It executes `docker compose -f /opt/compose/plex/docker-compose.yml up -d`

pyproject.toml

@@ -17,6 +17,7 @@ dependencies = [
 
 [project.scripts]
 compose-farm = "compose_farm.cli:app"
+cf = "compose_farm.cli:app"
 
 [build-system]
 requires = ["hatchling", "hatch-vcs"]

src/compose_farm/cli.py

@@ -33,6 +33,15 @@ console = Console(highlight=False)
 err_console = Console(stderr=True, highlight=False)
 
 
+def _load_config_or_exit(config_path: Path | None) -> Config:
+    """Load config or exit with a friendly error message."""
+    try:
+        return load_config(config_path)
+    except FileNotFoundError as e:
+        err_console.print(f"[red]✗[/] {e}")
+        raise typer.Exit(1) from e
+
+
 def _maybe_regenerate_traefik(cfg: Config) -> None:
     """Regenerate traefik config if traefik_file is configured."""
     if cfg.traefik_file is None:
@@ -61,6 +70,7 @@ app = typer.Typer(
     name="compose-farm",
     help="Compose Farm - run docker compose commands across multiple hosts",
     no_args_is_help=True,
+    context_settings={"help_option_names": ["-h", "--help"]},
 )
 
 
@@ -86,7 +96,7 @@ def _get_services(
     config_path: Path | None,
 ) -> tuple[list[str], Config]:
     """Resolve service list and load config."""
-    config = load_config(config_path)
+    config = _load_config_or_exit(config_path)
 
     if all_services:
         return list(config.services.keys()), config
@@ -169,7 +179,7 @@ async def _up_with_migration(
     return results
 
 
-@app.command()
+@app.command(rich_help_panel="Lifecycle")
 def up(
     services: ServicesArg = None,
     all_services: AllOption = False,
@@ -182,7 +192,7 @@ def up(
     _report_results(results)
 
 
-@app.command()
+@app.command(rich_help_panel="Lifecycle")
 def down(
     services: ServicesArg = None,
     all_services: AllOption = False,
@@ -201,7 +211,7 @@ def down(
     _report_results(results)
 
 
-@app.command()
+@app.command(rich_help_panel="Lifecycle")
 def pull(
     services: ServicesArg = None,
     all_services: AllOption = False,
@@ -213,7 +223,7 @@ def pull(
     _report_results(results)
 
 
-@app.command()
+@app.command(rich_help_panel="Lifecycle")
 def restart(
     services: ServicesArg = None,
     all_services: AllOption = False,
@@ -226,7 +236,7 @@ def restart(
     _report_results(results)
 
 
-@app.command()
+@app.command(rich_help_panel="Lifecycle")
 def update(
     services: ServicesArg = None,
     all_services: AllOption = False,
@@ -239,7 +249,7 @@ def update(
     _report_results(results)
 
 
-@app.command()
+@app.command(rich_help_panel="Monitoring")
 def logs(
     services: ServicesArg = None,
     all_services: AllOption = False,
@@ -256,17 +266,17 @@ def logs(
     _report_results(results)
 
 
-@app.command()
+@app.command(rich_help_panel="Monitoring")
 def ps(
     config: ConfigOption = None,
 ) -> None:
     """Show status of all services."""
-    cfg = load_config(config)
+    cfg = _load_config_or_exit(config)
     results = _run_async(run_on_services(cfg, list(cfg.services.keys()), "ps"))
     _report_results(results)
 
 
-@app.command("traefik-file")
+@app.command("traefik-file", rich_help_panel="Configuration")
 def traefik_file(
     services: ServicesArg = None,
     all_services: AllOption = False,
@@ -354,7 +364,7 @@ def _report_sync_changes(
             )
 
 
-@app.command()
+@app.command(rich_help_panel="Configuration")
 def sync(
     config: ConfigOption = None,
     log_path: LogPathOption = None,
@@ -369,7 +379,7 @@ def sync(
     file, and captures image digests. Combines service discovery with
     image snapshot into a single command.
     """
-    cfg = load_config(config)
+    cfg = _load_config_or_exit(config)
     current_state = load_state(cfg)
 
     console.print("Discovering running services...")
@@ -410,12 +420,12 @@ def sync(
             err_console.print(f"[yellow]![/] {exc}")
 
 
-@app.command()
+@app.command(rich_help_panel="Configuration")
 def check(
     config: ConfigOption = None,
 ) -> None:
     """Check for compose directories not in config (and vice versa)."""
-    cfg = load_config(config)
+    cfg = _load_config_or_exit(config)
     configured = set(cfg.services.keys())
     on_disk = cfg.discover_compose_dirs()
 
@@ -439,6 +449,20 @@ def check(
         for name in missing_from_config:
             console.print(f"[dim]  {name}: docker-debian[/]")
 
+    # Check traefik labels have matching ports
+    try:
+        _, traefik_warnings = generate_traefik_config(
+            cfg, list(cfg.services.keys()), check_all=True
+        )
+        if traefik_warnings:
+            console.print(f"\n[yellow]Traefik issues[/] ({len(traefik_warnings)}):")
+            for warning in traefik_warnings:
+                console.print(f"  [yellow]![/] {warning}")
+        elif not missing_from_config and not missing_from_disk:
+            console.print("[green]✓[/] All traefik services have published ports.")
+    except (FileNotFoundError, ValueError):
+        pass  # Skip traefik check if config can't be loaded
+
 
 if __name__ == "__main__":
     app()

src/compose_farm/ssh.py

@@ -10,6 +10,7 @@ from typing import TYPE_CHECKING, Any
 
 import asyncssh
 from rich.console import Console
+from rich.markup import escape
 
 if TYPE_CHECKING:
     from .config import Config, Host
@@ -87,7 +88,7 @@ async def _run_local_command(
                         break
                     text = line.decode()
                     if text.strip():  # Skip empty lines
-                        console.print(f"[cyan]\\[{prefix}][/] {text}", end="")
+                        console.print(f"[cyan]\\[{prefix}][/] {escape(text)}", end="")
 
             await asyncio.gather(
                 read_stream(proc.stdout, service),
@@ -143,7 +144,7 @@ async def _run_ssh_command(
                     console = _err_console if is_stderr else _console
                     async for line in reader:
                         if line.strip():  # Skip empty lines
-                            console.print(f"[cyan]\\[{prefix}][/] {line}", end="")
+                            console.print(f"[cyan]\\[{prefix}][/] {escape(line)}", end="")
 
                 await asyncio.gather(
                     read_stream(proc.stdout, service),

src/compose_farm/traefik.py

@@ -29,7 +29,6 @@ class PortMapping:
 
     target: int
     published: int | None
-    protocol: str | None = None
 
 
 @dataclass
@@ -121,7 +120,7 @@ def _parse_ports(raw: Any, env: dict[str, str]) -> list[PortMapping]:  # noqa: P
     for item in items:
         if isinstance(item, str):
             interpolated = _interpolate(item, env)
-            port_spec, _, protocol = interpolated.partition("/")
+            port_spec, _, _ = interpolated.partition("/")
             parts = port_spec.split(":")
             published: int | None = None
             target: int | None = None
@@ -136,9 +135,7 @@ def _parse_ports(raw: Any, env: dict[str, str]) -> list[PortMapping]:  # noqa: P
                 target = int(parts[-1])
 
             if target is not None:
-                mappings.append(
-                    PortMapping(target=target, published=published, protocol=protocol or None)
-                )
+                mappings.append(PortMapping(target=target, published=published))
         elif isinstance(item, dict):
             target_raw = item.get("target")
             if isinstance(target_raw, str):
@@ -158,14 +155,7 @@ def _parse_ports(raw: Any, env: dict[str, str]) -> list[PortMapping]:  # noqa: P
                 published_val = int(str(published_raw)) if published_raw is not None else None
             except (TypeError, ValueError):
                 published_val = None
-            protocol_val = item.get("protocol")
-            mappings.append(
-                PortMapping(
-                    target=target_val,
-                    published=published_val,
-                    protocol=str(protocol_val) if protocol_val else None,
-                )
-            )
+            mappings.append(PortMapping(target=target_val, published=published_val))
 
     return mappings
 
@@ -400,10 +390,28 @@ def _process_service_label(
         source.scheme = str(_parse_value(key_without_prefix, label_value))
 
 
+def _get_ports_for_service(
+    definition: dict[str, Any],
+    all_services: dict[str, Any],
+    env: dict[str, str],
+) -> list[PortMapping]:
+    """Get ports for a service, following network_mode: service:X if present."""
+    network_mode = definition.get("network_mode", "")
+    if isinstance(network_mode, str) and network_mode.startswith("service:"):
+        # Service uses another service's network - get ports from that service
+        ref_service = network_mode[len("service:") :]
+        if ref_service in all_services:
+            ref_def = all_services[ref_service]
+            if isinstance(ref_def, dict):
+                return _parse_ports(ref_def.get("ports"), env)
+    return _parse_ports(definition.get("ports"), env)
+
+
 def _process_service_labels(
     stack: str,
     compose_service: str,
     definition: dict[str, Any],
+    all_services: dict[str, Any],
     host_address: str,
     env: dict[str, str],
     dynamic: dict[str, Any],
@@ -417,7 +425,7 @@ def _process_service_labels(
     if enable_raw is not None and _parse_value("enable", enable_raw) is False:
         return
 
-    ports = _parse_ports(definition.get("ports"), env)
+    ports = _get_ports_for_service(definition, all_services, env)
     routers: dict[str, bool] = {}
     service_names: set[str] = set()
 
@@ -452,10 +460,19 @@ def _process_service_labels(
 def generate_traefik_config(
     config: Config,
     services: list[str],
+    *,
+    check_all: bool = False,
 ) -> tuple[dict[str, Any], list[str]]:
     """Generate Traefik dynamic config from compose labels.
 
+    Args:
+        config: The compose-farm config.
+        services: List of service names to process.
+        check_all: If True, check all services for warnings (ignore host filtering).
+                   Used by the check command to validate all traefik labels.
+
     Returns (config_dict, warnings).
+
     """
     dynamic: dict[str, Any] = {}
     warnings: list[str] = []
@@ -463,7 +480,7 @@ def generate_traefik_config(
 
     # Determine Traefik's host from service assignment
     traefik_host = None
-    if config.traefik_service:
+    if config.traefik_service and not check_all:
         traefik_host = config.services.get(config.traefik_service)
 
     for stack in services:
@@ -471,10 +488,12 @@ def generate_traefik_config(
         stack_host = config.services.get(stack)
 
         # Skip services on Traefik's host - docker provider handles them directly
-        if host_address.lower() in LOCAL_ADDRESSES:
-            continue
-        if traefik_host and stack_host == traefik_host:
-            continue
+        # (unless check_all is True, for validation purposes)
+        if not check_all:
+            if host_address.lower() in LOCAL_ADDRESSES:
+                continue
+            if traefik_host and stack_host == traefik_host:
+                continue
 
         for compose_service, definition in raw_services.items():
             if not isinstance(definition, dict):
@@ -483,6 +502,7 @@ def generate_traefik_config(
                 stack,
                 compose_service,
                 definition,
+                raw_services,
                 host_address,
                 env,
                 dynamic,

tests/test_traefik.py

@@ -193,3 +193,51 @@ def test_generate_skips_services_with_enable_false(tmp_path: Path) -> None:
 
     assert dynamic == {}
     assert warnings == []
+
+
+def test_generate_follows_network_mode_service_for_ports(tmp_path: Path) -> None:
+    """Services using network_mode: service:X should use ports from service X."""
+    cfg = Config(
+        compose_dir=tmp_path,
+        hosts={"nas01": Host(address="192.168.1.10")},
+        services={"vpn-stack": "nas01"},
+    )
+    compose_path = tmp_path / "vpn-stack" / "docker-compose.yml"
+    _write_compose(
+        compose_path,
+        {
+            "services": {
+                "vpn": {
+                    "image": "gluetun",
+                    "ports": ["5080:5080", "9696:9696"],
+                },
+                "qbittorrent": {
+                    "image": "qbittorrent",
+                    "network_mode": "service:vpn",
+                    "labels": [
+                        "traefik.enable=true",
+                        "traefik.http.routers.torrent.rule=Host(`torrent.example.com`)",
+                        "traefik.http.services.torrent.loadbalancer.server.port=5080",
+                    ],
+                },
+                "prowlarr": {
+                    "image": "prowlarr",
+                    "network_mode": "service:vpn",
+                    "labels": [
+                        "traefik.enable=true",
+                        "traefik.http.routers.prowlarr.rule=Host(`prowlarr.example.com`)",
+                        "traefik.http.services.prowlarr.loadbalancer.server.port=9696",
+                    ],
+                },
+            }
+        },
+    )
+
+    dynamic, warnings = generate_traefik_config(cfg, ["vpn-stack"])
+
+    assert warnings == []
+    # Both services should get their ports from the vpn service
+    torrent_servers = dynamic["http"]["services"]["torrent"]["loadbalancer"]["servers"]
+    assert torrent_servers == [{"url": "http://192.168.1.10:5080"}]
+    prowlarr_servers = dynamic["http"]["services"]["prowlarr"]["loadbalancer"]["servers"]
+    assert prowlarr_servers == [{"url": "http://192.168.1.10:9696"}]