docker-captain 0.0.1__tar.gz

docker_captain-0.0.1/PKG-INFO

@@ -0,0 +1,185 @@
+Metadata-Version: 2.3
+Name: docker-captain
+Version: 0.0.1
+Summary: Add your description here
+Requires-Dist: platformdirs>=4.5.0
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: questionary>=2.1.1
+Requires-Dist: rich>=14.2.0
+Requires-Dist: sh>=2.2.2
+Requires-Dist: typer>=0.19.2
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# ⚓ docker-captain
+
+**docker-captain** is a friendly command-line tool that helps you manage multiple Docker Compose projects under a single folder.  
+
+It's powered by [Typer](https://typer.tiangolo.com/), [Questionary](https://github.com/tmbo/questionary), and [sh](https://amoffat.github.io/sh/).
+
+---
+
+## 🚀 Features
+
+For a quick overview of the available commands, run `docker-captain --help`.
+
+### 🔍 Project Auto-Detection
+`docker-captain` automatically detects any subfolder containing a Docker Compose file — such as `compose.yaml`, `compose.yml`, `docker-compose.yaml`, or `docker-compose.yml`.  
+It scans the folder specified in the configuration file, or passed in the `DOCKER_CAPTAIN_PROJECTS` environment variable, which you can export here:
+
+```bash
+export DOCKER_CAPTAIN_PROJECTS=/path/to/your/deployments  # takes precedence over the config file
+```
+
+Detection is purely based on the file names — if a folder contains one of those Compose files, it’s recognized as a valid “project”, taking its name from the folder.
+
+### ⚙️ Project Management via `manage`
+
+Use the `docker-captain manage` command to interactively select which projects should be considered *active*.
+You’ll see a multi-select list of all detected projects — you can check or uncheck them using the keyboard, then confirm with Enter.
+
+The selected projects become your *active fleet*, used by commands like `rally` and `abandon`.
+
+### 🚢 Easy Interaction with Single Projects
+
+Need to start or stop one project?
+Use these straightforward commands:
+
+```bash
+docker-captain start calibre --detach --remove-orphans
+docker-captain stop calibre --remove-orphans
+docker-captain restart calibre
+```
+
+They’re thin wrappers around standard `docker compose` commands (`up`, `down`, and `restart`), but automatically use the correct compose file and folder context.
+
+Flags:
+
+* `-d` / `--detach`: Run containers in background.
+* `--remove-orphans`: Remove orphaned containers not defined in the compose file.
+
+### 📋 Listing Projects with `list`
+
+See all detected projects neatly formatted in a Rich table:
+
+```bash
+docker-captain list
+```
+
+This shows:
+
+* **Project** name
+* Whether it’s **Active** (selected via `manage`)
+* Whether it’s currently **Running** (`docker compose ls` is checked behind the scenes)
+
+You can also view the compose file paths with `--verbose`:
+
+```bash
+docker-captain list --verbose
+```
+
+### ⚓ Rally and Abandon Your Fleet
+
+Once you’ve marked projects as *active* using `manage`, you can control them all together:
+
+* **Start all active projects:**
+
+  ```bash
+  docker-captain rally --detach
+  ```
+* **Stop all active projects:**
+
+  ```bash
+  docker-captain abandon
+  ```
+
+These commands behave like `start` and `stop`, but apply to every active project in one go — perfect for booting up or shutting down your entire environment.
+
+---
+
+## 📦 Installation
+
+You can install dependencies using `uv`, `pipx`, or plain `pip`.
+
+```bash
+# Install with
+uv tool install docker-captain
+pipx install docker-captain
+
+# or try it out with
+uvx docker-captain
+```
+
+---
+
+## 🗒️ Configuration
+
+`captain-docker` support a simple YAML config file with the following structure:
+
+```yaml
+# ~/.config/docker-captain/config.yaml (on Linux)
+projects_folder: /path/to/your/deployments  # environment variable: DOCKER_CAPTAIN_PROJECTS_FOLDER
+```
+
+---
+
+
+## 🧭 Folder Structure Example
+
+Your deployments might look like this:
+
+```
+~/Deployments/
+├── calibre/
+│   └── compose.yaml
+├── immich/
+│   ├── compose.yaml
+│   └── immich.env
+├── paperless-ngx/
+│   ├── compose.yaml
+│   └── paperless-ngx.env
+└── syncthing/
+    └── compose.yaml
+```
+
+Each subfolder is automatically detected as a project if it has a Compose file.
+
+---
+
+## 🧠 Tech Stack
+
+| Library                                            | Purpose                      |
+| -------------------------------------------------- | ---------------------------- |
+| [Typer](https://typer.tiangolo.com/)               | CLI framework                |
+| [Rich](https://rich.readthedocs.io/)               | Beautiful terminal output    |
+| [Questionary](https://github.com/tmbo/questionary) | Interactive prompts          |
+| [sh](https://amoffat.github.io/sh/)                | Simple subprocess management |
+| [PyYAML](https://pyyaml.org/)                      | YAML parsing                 |
+
+---
+
+## 🐙 Example Workflow
+
+```bash
+# Detect and list all projects
+docker-captain list
+
+# Choose which projects are active
+docker-captain manage
+
+# Start all active projects
+docker-captain rally -d
+```
+
+---
+
+## 💡 Inspiration
+
+I've been using `docker-compose.yaml` files to manage my home server for a while.
+I found the internet is full of tools to observe docker deployments, but I couldn't find one to manage my Docker Compose files.
+I wanted something simple, lightweight, and portable.
+
+I stumbled across [jenssegers/captain](https://github.com/jenssegers/captain/), a Go project with a similar idea - a simple wrapper around `docker compose`, but only acting on one project at a time.
+Given Python is my main language and the project hasn't seen any activity in 3 years, I decided to extend its scope and write `docker-captain`.
+
+Hope this is useful to someone, happy sailing! ⛵

docker_captain-0.0.1/README.md

@@ -0,0 +1,172 @@
+# ⚓ docker-captain
+
+**docker-captain** is a friendly command-line tool that helps you manage multiple Docker Compose projects under a single folder.  
+
+It's powered by [Typer](https://typer.tiangolo.com/), [Questionary](https://github.com/tmbo/questionary), and [sh](https://amoffat.github.io/sh/).
+
+---
+
+## 🚀 Features
+
+For a quick overview of the available commands, run `docker-captain --help`.
+
+### 🔍 Project Auto-Detection
+`docker-captain` automatically detects any subfolder containing a Docker Compose file — such as `compose.yaml`, `compose.yml`, `docker-compose.yaml`, or `docker-compose.yml`.  
+It scans the folder specified in the configuration file, or passed in the `DOCKER_CAPTAIN_PROJECTS` environment variable, which you can export here:
+
+```bash
+export DOCKER_CAPTAIN_PROJECTS=/path/to/your/deployments  # takes precedence over the config file
+```
+
+Detection is purely based on the file names — if a folder contains one of those Compose files, it’s recognized as a valid “project”, taking its name from the folder.
+
+### ⚙️ Project Management via `manage`
+
+Use the `docker-captain manage` command to interactively select which projects should be considered *active*.
+You’ll see a multi-select list of all detected projects — you can check or uncheck them using the keyboard, then confirm with Enter.
+
+The selected projects become your *active fleet*, used by commands like `rally` and `abandon`.
+
+### 🚢 Easy Interaction with Single Projects
+
+Need to start or stop one project?
+Use these straightforward commands:
+
+```bash
+docker-captain start calibre --detach --remove-orphans
+docker-captain stop calibre --remove-orphans
+docker-captain restart calibre
+```
+
+They’re thin wrappers around standard `docker compose` commands (`up`, `down`, and `restart`), but automatically use the correct compose file and folder context.
+
+Flags:
+
+* `-d` / `--detach`: Run containers in background.
+* `--remove-orphans`: Remove orphaned containers not defined in the compose file.
+
+### 📋 Listing Projects with `list`
+
+See all detected projects neatly formatted in a Rich table:
+
+```bash
+docker-captain list
+```
+
+This shows:
+
+* **Project** name
+* Whether it’s **Active** (selected via `manage`)
+* Whether it’s currently **Running** (`docker compose ls` is checked behind the scenes)
+
+You can also view the compose file paths with `--verbose`:
+
+```bash
+docker-captain list --verbose
+```
+
+### ⚓ Rally and Abandon Your Fleet
+
+Once you’ve marked projects as *active* using `manage`, you can control them all together:
+
+* **Start all active projects:**
+
+  ```bash
+  docker-captain rally --detach
+  ```
+* **Stop all active projects:**
+
+  ```bash
+  docker-captain abandon
+  ```
+
+These commands behave like `start` and `stop`, but apply to every active project in one go — perfect for booting up or shutting down your entire environment.
+
+---
+
+## 📦 Installation
+
+You can install dependencies using `uv`, `pipx`, or plain `pip`.
+
+```bash
+# Install with
+uv tool install docker-captain
+pipx install docker-captain
+
+# or try it out with
+uvx docker-captain
+```
+
+---
+
+## 🗒️ Configuration
+
+`captain-docker` support a simple YAML config file with the following structure:
+
+```yaml
+# ~/.config/docker-captain/config.yaml (on Linux)
+projects_folder: /path/to/your/deployments  # environment variable: DOCKER_CAPTAIN_PROJECTS_FOLDER
+```
+
+---
+
+
+## 🧭 Folder Structure Example
+
+Your deployments might look like this:
+
+```
+~/Deployments/
+├── calibre/
+│   └── compose.yaml
+├── immich/
+│   ├── compose.yaml
+│   └── immich.env
+├── paperless-ngx/
+│   ├── compose.yaml
+│   └── paperless-ngx.env
+└── syncthing/
+    └── compose.yaml
+```
+
+Each subfolder is automatically detected as a project if it has a Compose file.
+
+---
+
+## 🧠 Tech Stack
+
+| Library                                            | Purpose                      |
+| -------------------------------------------------- | ---------------------------- |
+| [Typer](https://typer.tiangolo.com/)               | CLI framework                |
+| [Rich](https://rich.readthedocs.io/)               | Beautiful terminal output    |
+| [Questionary](https://github.com/tmbo/questionary) | Interactive prompts          |
+| [sh](https://amoffat.github.io/sh/)                | Simple subprocess management |
+| [PyYAML](https://pyyaml.org/)                      | YAML parsing                 |
+
+---
+
+## 🐙 Example Workflow
+
+```bash
+# Detect and list all projects
+docker-captain list
+
+# Choose which projects are active
+docker-captain manage
+
+# Start all active projects
+docker-captain rally -d
+```
+
+---
+
+## 💡 Inspiration
+
+I've been using `docker-compose.yaml` files to manage my home server for a while.
+I found the internet is full of tools to observe docker deployments, but I couldn't find one to manage my Docker Compose files.
+I wanted something simple, lightweight, and portable.
+
+I stumbled across [jenssegers/captain](https://github.com/jenssegers/captain/), a Go project with a similar idea - a simple wrapper around `docker compose`, but only acting on one project at a time.
+Given Python is my main language and the project hasn't seen any activity in 3 years, I decided to extend its scope and write `docker-captain`.
+
+Hope this is useful to someone, happy sailing! ⛵

docker_captain-0.0.1/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "docker-captain"
+version = "0.0.1"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "platformdirs>=4.5.0",
+    "pyyaml>=6.0.3",
+    "questionary>=2.1.1",
+    "rich>=14.2.0",
+    "sh>=2.2.2",
+    "typer>=0.19.2",
+]
+[dependency-groups]
+dev = [
+    "pyright>=1.1.406",
+    "ruff>=0.14.0",
+]
+
+[project.scripts]
+docker-captain = "docker_captain.main:main"
+
+[build-system]
+requires = ["uv_build>=0.9.2,<0.10.0"]
+build-backend = "uv_build"
+
+[[tool.uv.index]]
+name = "testpypi"
+url = "https://test.pypi.org/simple/"
+publish-url = "https://test.pypi.org/legacy/"
+explicit = true
+
+[tool.uv.workspace]
+members = [
+    "docker-captain",
+]
+
+[tool.ruff]
+line-length = 99

docker_captain-0.0.1/src/docker_captain/config.py

@@ -0,0 +1,100 @@
+"""Module to help manage configuration and data files."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field, fields, is_dataclass
+from pathlib import Path
+from typing import ClassVar, Dict, List, Optional, Type, TypeVar
+
+import yaml
+from platformdirs import user_config_dir, user_data_dir
+from rich.console import Console
+
+console = Console()
+T = TypeVar("T", bound="CaptainFile")
+
+
+@dataclass
+class CaptainFile:
+    """
+    Base class that serialises dataclasses to YAML.
+    Sub‑classes must be dataclasses and provide a ``DEFAULT_PATH``.
+    """
+
+    DEFAULT_PATH: ClassVar[Path]  # overridden by subclasses
+
+    @classmethod
+    def _ensure_dataclass(cls) -> None:
+        if not is_dataclass(cls):
+            raise TypeError(f"{cls.__name__} must be a dataclass")
+
+    @classmethod
+    def load(cls: Type[T], path: Path | None = None) -> T:
+        """
+        Load an instance from *path* (or ``DEFAULT_PATH``).  If the file
+        cannot be read or parsed, a warning is printed and a fresh instance
+        with default values is returned.
+        """
+        cls._ensure_dataclass()
+        path = Path(path) if path is not None else cls.DEFAULT_PATH
+
+        if not path.exists():
+            return cls()
+
+        try:
+            with path.open("r", encoding="utf-8") as f:
+                data = yaml.safe_load(f) or {}
+        except Exception as e:
+            console.print(f"[yellow]Warning: Failed to parse {path}: {e}[/yellow]")
+            return cls()
+
+        # Keep only fields defined on the dataclass
+        field_names = {f.name for f in fields(cls)}
+        filtered = {k: v for k, v in data.items() if k in field_names}
+        return cls(**filtered)
+
+    def save(self, path: Path | None = None) -> None:
+        """
+        Write the instance to *path* (or ``DEFAULT_PATH``) as YAML.
+        The parent directory is created automatically.  Errors are
+        reported with a console warning but not re‑raised.
+        """
+        self.__class__._ensure_dataclass()
+        path = Path(path) if path is not None else self.__class__.DEFAULT_PATH
+        path.parent.mkdir(parents=True, exist_ok=True)
+
+        try:
+            with path.open("w", encoding="utf-8") as f:
+                yaml.safe_dump(
+                    asdict(self),
+                    f,
+                    default_flow_style=False,
+                    allow_unicode=True,
+                )
+        except Exception as e:
+            console.print(f"[yellow]Warning: Failed to write {path}: {e}[/yellow]")
+
+
+@dataclass
+class CaptainConfig(CaptainFile):
+    """Data model of the docker-captain configuration file."""
+
+    DEFAULT_PATH: ClassVar[Path] = (
+        Path(user_config_dir(appname="docker-captain", appauthor=False)) / "config.yaml"
+    )
+    ENVIROMENT: ClassVar[Dict] = {"projects_folder": "DOCKER_CAPTAIN_PROJECTS_FOLDER"}
+
+    projects_folder: Optional[Path] = field(
+        default=None, metadata={"env": "DOCKER_CAPTAIN_PROJECTS_FOLDER"}
+    )
+
+
+@dataclass
+class CaptainData(CaptainFile):
+    """Data model of the docker-captain data."""
+
+    DEFAULT_PATH: ClassVar[Path] = (
+        Path(user_data_dir(appname="docker-captain", appauthor=False)) / "data.yaml"
+    )
+
+    active_projects: List[str] = field(default_factory=list)

docker_captain-0.0.1/src/docker_captain/docker.py

@@ -0,0 +1,118 @@
+"""Module to help wrapping 'docker compose' commands."""
+
+import json
+from pathlib import Path
+from typing import List, Literal
+
+import sh
+from rich.console import Console
+
+console = Console()
+
+
+class DockerCompose:
+    """Wrapper around 'docker compose' commands."""
+
+    @staticmethod
+    def get_running_projects() -> List[str]:
+        """Return a list of running docker compose projects using `docker compose ls`.
+
+        Returns:
+            List[str]: Subset of the passed projects that are currently running.
+        """
+        try:
+            result = sh.docker.compose.ls(format="json", _ok_code=[0, 1])  # pyright: ignore[reportAttributeAccessIssue]
+            data = json.loads(str(result))
+            running = []
+            for item in data:
+                name = item.get("Name")
+                if name and item.get("Status", "").lower().startswith("running"):
+                    running.append(name)
+            return running
+        except sh.CommandNotFound as e:
+            console.print(f"[red][bold]Error:[/bold] '{e}' command not found.[/red]")
+            exit(code=1)
+        except Exception as e:
+            console.print(f"[yellow]Warning: could not determine running projects ({e})[/yellow]")
+            return []
+
+    @staticmethod
+    def up(compose_file: Path, **kwargs) -> int:
+        """Run 'docker compose up' with the specified **kwargs.
+
+        Args:
+            compose_file (Path): Path to the compose YAML file.
+            **kwargs (Dict): Optional arguments to pass directly to docker compose.
+
+        Returns:
+            int: Exit code of the docker command.
+
+        """
+        return DockerCompose._docker_compose_run(compose_file=compose_file, action="up", **kwargs)
+
+    @staticmethod
+    def down(compose_file: Path, **kwargs) -> int:
+        """Run 'docker compose down' with the specified **kwargs.
+
+        Args:
+            compose_file (Path): Path to the compose YAML file.
+            **kwargs (Dict): Optional arguments to pass directly to docker compose.
+
+        Returns:
+            int: Exit code of the docker command.
+
+        """
+        return DockerCompose._docker_compose_run(
+            compose_file=compose_file, action="down", **kwargs
+        )
+
+    @staticmethod
+    def restart(compose_file: Path, **kwargs) -> int:
+        """Run 'docker compose restart' with the specified **kwargs.
+
+        Args:
+            compose_file (Path): Path to the compose YAML file.
+            **kwargs (Dict): Optional arguments to pass directly to docker compose.
+
+        Returns:
+            int: Exit code of the docker command.
+
+        """
+        return DockerCompose._docker_compose_run(
+            compose_file=compose_file, action="restart", **kwargs
+        )
+
+    @staticmethod
+    def _docker_compose_run(
+        compose_file: Path,
+        action: Literal["up", "down", "restart"],
+        **kwargs,
+    ) -> int:
+        """Internal wrapper to run docker compose command via sh.docker.compose.
+
+
+        Args:
+            compose_file (Path): Path to the compose YAML file.
+            action (str): 'up' or 'down', to indicate which docker compose command to run.
+            **kwargs (Dict): Optional arguments to pass directly to docker compose.
+
+        Returns:
+            int: Exit code of the docker command.
+
+        """
+        console.rule(f"[bold blue]{action.upper()} {compose_file.parent.name}[/bold blue]")
+        try:
+            sh.docker.compose(action, file=compose_file, _fg=True, **kwargs)  # pyright: ignore[reportAttributeAccessIssue]
+            console.print(
+                f":white_check_mark: [green]{action} succeeded for {compose_file.parent.name}[/green]"
+            )
+            return 0
+        except sh.CommandNotFound as e:
+            console.print(f"[red]'{e}' command not found.[/red]")
+            return 1
+        except sh.ErrorReturnCode as e:
+            console.print(f"[red]Command failed with exit code {e.exit_code}[/red]")
+            return int(e.exit_code)
+        except Exception as e:
+            console.print(f"[red]Error executing docker compose: {e}[/red]")
+            return 2

docker_captain-0.0.1/src/docker_captain/main.py

@@ -0,0 +1,212 @@
+"""
+A friendly CLI tool for managing multiple Docker Compose projects.
+
+docker-captain detects projects automatically, lets you mark them as active,
+and provides simple commands to start, stop, restart, or list your deployments
+— individually or all at once.
+"""
+
+from __future__ import annotations
+
+from typing import List
+
+import questionary
+import typer
+from questionary import Choice
+from rich import box
+from rich.console import Console
+from rich.table import Table
+
+from docker_captain.config import CaptainData
+from docker_captain.docker import DockerCompose
+from docker_captain.projects import CaptainProject
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+
+app = typer.Typer(no_args_is_help=True)
+console = Console()
+
+# ---------------------------------------------------------------------------
+# Commands
+# ---------------------------------------------------------------------------
+
+
+@app.command()
+def list(
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Show compose file paths."),
+) -> None:
+    """List all discovered projects and show which ones are active and running.
+
+    Args:
+        verbose (bool): If True, also show the compose file path.
+    """
+    projects_folder = CaptainProject.projects_folder()
+    projects = CaptainProject.discover_projects()
+    captain_data: CaptainData = CaptainData.load()
+    running_projects: List[str] = DockerCompose.get_running_projects()
+
+    table = Table(title=f"Projects in {projects_folder}", box=box.SIMPLE_HEAVY)
+    table.add_column("Project", no_wrap=True)
+    table.add_column("Active", justify="center")
+    table.add_column("Running", justify="center")
+
+    if verbose:
+        table.add_column("Compose File")
+
+    for name, compose_path in projects.items():
+        active = "✓" if name in captain_data.active_projects else ""
+        running = "✓" if name in running_projects else ""
+        row = [name, active, running]
+        if verbose:
+            row.append(str(compose_path))
+        table.add_row(*row)
+
+    console.print(table)
+
+
+@app.command()
+def manage() -> None:
+    """Interactively select which projects are active."""
+    projects_folder = CaptainProject.projects_folder()
+    projects = CaptainProject.discover_projects()
+    names = sorted(projects.keys())
+    captain_data: CaptainData = CaptainData.load()
+
+    if not names:
+        console.print(f"[yellow]No projects found in {projects_folder}.[/yellow]")
+        raise typer.Exit(code=1)
+
+    # Build choices with checkmarks for active projects
+    choices = [
+        Choice(title=n, value=n, checked=(n in captain_data.active_projects)) for n in names
+    ]
+
+    answer = questionary.checkbox(
+        "Select active projects (space to toggle, enter to confirm):",
+        choices=choices,
+    ).ask()
+
+    if answer is None:
+        console.print("[yellow]Aborted (no changes made).[/yellow]")
+        raise typer.Exit(code=0)
+
+    captain_data.active_projects = sorted(answer)
+    captain_data.save()
+    console.print(
+        f"[green]Saved {len(captain_data.active_projects)} active project(s) to {captain_data.DEFAULT_PATH}[/green]"
+    )
+
+
+@app.command()
+def start(
+    project: str = typer.Argument(..., help="Project folder name (e.g. calibre)"),
+    detach: bool = typer.Option(False, "-d", "--detach", help="Run `docker compose up --detach`"),
+    remove_orphans: bool = typer.Option(
+        False, "--remove-orphans", help="Include --remove-orphans"
+    ),
+) -> None:
+    """Start a single project using `docker compose up`."""
+    projects = CaptainProject.discover_projects()
+    compose_file = CaptainProject.require_project_exists(project, projects)
+    rc = DockerCompose.up(
+        compose_file=compose_file,
+        detach=detach,
+        remove_orphans=remove_orphans,
+    )
+    raise typer.Exit(code=rc)
+
+
+@app.command()
+def stop(
+    project: str = typer.Argument(..., help="Project folder name (e.g. calibre)"),
+    remove_orphans: bool = typer.Option(
+        False, "--remove-orphans", help="Include --remove-orphans"
+    ),
+) -> None:
+    """Stop a single project using `docker compose down`."""
+    projects = CaptainProject.discover_projects()
+    compose_file = CaptainProject.require_project_exists(project, projects)
+    rc = DockerCompose.down(
+        compose_file=compose_file,
+        remove_orphans=remove_orphans,
+    )
+    raise typer.Exit(code=rc)
+
+
+@app.command()
+def restart(
+    project: str = typer.Argument(..., help="Project folder name (e.g. calibre)"),
+) -> None:
+    """Restart a single project using `docker compose restart`."""
+    projects = CaptainProject.discover_projects()
+    compose_file = CaptainProject.require_project_exists(project, projects)
+    rc = DockerCompose.restart(compose_file=compose_file)
+    raise typer.Exit(code=rc)
+
+
+@app.command()
+def rally(
+    detach: bool = typer.Option(False, "-d", "--detach", help="Run with --detach"),
+    remove_orphans: bool = typer.Option(
+        False, "--remove-orphans", help="Include --remove-orphans"
+    ),
+) -> None:
+    """Start all active projects."""
+    projects = CaptainProject.discover_projects()
+    captain_data = CaptainData.load()
+
+    if not captain_data.active_projects:
+        console.print(
+            f"[yellow]No active projects found in {captain_data.DEFAULT_PATH}. Run `docker-captain manage` first.[/yellow]"
+        )
+        raise typer.Exit(code=0)
+
+    exit_code = 0
+    for name in captain_data.active_projects:
+        if name not in projects:
+            console.print(f"[red]Skipping {name}: project not found.[/red]")
+            exit_code = exit_code or 1
+            continue
+        rc = DockerCompose.up(
+            compose_file=projects[name], detach=detach, remove_orphans=remove_orphans
+        )
+        exit_code = exit_code or rc
+    raise typer.Exit(code=exit_code)
+
+
+@app.command()
+def abandon(
+    remove_orphans: bool = typer.Option(
+        False, "--remove-orphans", help="Include --remove-orphans"
+    ),
+) -> None:
+    """Stop all active projects."""
+    projects = CaptainProject.discover_projects()
+    captain_data = CaptainData.load()
+
+    if not captain_data.active_projects:
+        console.print(
+            f"[yellow]No active projects found in {captain_data.DEFAULT_PATH}. Run `docker-captain manage` first.[/yellow]"
+        )
+        raise typer.Exit(code=0)
+
+    exit_code = 0
+    for name in captain_data.active_projects:
+        if name not in projects:
+            console.print(f"[red]Skipping {name}: project not found.[/red]")
+            exit_code = exit_code or 1
+            continue
+        rc = DockerCompose.down(compose_file=projects[name], remove_orphans=remove_orphans)
+        exit_code = exit_code or rc
+    raise typer.Exit(code=exit_code)
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+
+def main():
+    app()

docker_captain-0.0.1/src/docker_captain/projects.py

@@ -0,0 +1,95 @@
+import os
+from pathlib import Path
+from typing import Dict, List, Optional
+
+import typer
+from rich.console import Console
+
+from docker_captain.config import CaptainConfig
+
+console = Console()
+
+
+class CaptainProject:
+    @staticmethod
+    def projects_folder() -> Path:
+        """Get the root folder of the projects.
+
+        Either parse it from the environment variable (if provided), or from
+        the configuration file.
+        """
+        captain_config = CaptainConfig.load()
+        folder = (
+            os.getenv(CaptainConfig.ENVIROMENT["projects_folder"])
+            or captain_config.projects_folder
+        )
+        if not folder:
+            console.print(
+                f"[bold red]Error:[/bold red] Please set the path containing your Docker Compose projects.\n"
+                f"Either add it to the {CaptainConfig.DEFAULT_PATH} file, or set with:\n\n"
+                f"    export {CaptainConfig.ENVIROMENT['projects_folder']}=/path/to/your/deployments\n"
+            )
+            exit(code=1)
+        folder = Path(folder)
+        if not folder.is_absolute():
+            console.print(
+                f"[bold red]Error:[/bold red] The configured projects folder {folder} "
+                "is not an absolute path."
+            )
+            exit(code=2)
+        if not folder.exists():
+            console.print(
+                f"[bold red]Error:[/bold red] The configured projects folder {folder} "
+                "does not exist."
+            )
+            exit(code=3)
+        return folder
+
+    @staticmethod
+    def discover_projects(root: Optional[Path] = None) -> Dict[str, Path]:
+        """Discover projects that contain a valid docker compose file.
+
+        Args:
+            root (Path): The root directory containing deployment folders.
+
+        Returns:
+            Dict[str, Path]: Mapping from project name to compose file path.
+        """
+        COMPOSE_FILENAMES: List[str] = [
+            "compose.yaml",
+            "compose.yml",
+            "docker-compose.yaml",
+            "docker-compose.yml",
+        ]
+        projects: Dict[str, Path] = {}
+        root = root or CaptainProject.projects_folder()
+        if not root.exists():
+            return projects
+        for child in sorted(root.iterdir()):
+            if not child.is_dir():
+                continue
+            for fname in COMPOSE_FILENAMES:
+                candidate = child / fname
+                if candidate.exists() and candidate.is_file():
+                    projects[child.name] = candidate
+                    break
+        return projects
+
+    @staticmethod
+    def require_project_exists(project: str, projects: Dict[str, Path]) -> Path:
+        """Ensure the given project exists among discovered ones.
+
+        Args:
+            project (str): Project name.
+            projects (Dict[str, Path]): Mapping of available projects.
+
+        Returns:
+            Path: Path to the compose file.
+
+        Raises:
+            typer.Exit: If the project does not exist.
+        """
+        if project not in projects:
+            console.print(f"[red]No such project: {project}[/red]")
+            raise typer.Exit(code=2)
+        return projects[project]