mad-cli 0.4.0__py3-none-any.whl

mad_cli/server/auth.py

@@ -0,0 +1,41 @@
+"""Bearer-token authentication for the v1 API.
+
+Every route except ``/health`` requires ``Authorization: Bearer <token>`` where
+``<token>`` matches the auto-generated ``config_root()/api-token`` (created on the
+first ``mad serve``). The comparison is constant-time. A missing or wrong token is
+a 401; a server with no token file configured is a 503.
+"""
+
+from __future__ import annotations
+
+import secrets
+from typing import Annotated
+
+from fastapi import Depends, HTTPException, status
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+
+from mad_cli.core.usecases import service
+
+_bearer = HTTPBearer(auto_error=False, description="The token from config_root()/api-token.")
+
+
+def require_token(
+    credentials: Annotated[HTTPAuthorizationCredentials | None, Depends(_bearer)],
+) -> None:
+    """FastAPI dependency: enforce a valid bearer token or raise 401/503."""
+    expected = service.read_api_token()
+    if expected is None:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="API token is not configured on the server.",
+        )
+    if (
+        credentials is None
+        or credentials.scheme.lower() != "bearer"
+        or not secrets.compare_digest(credentials.credentials, expected)
+    ):
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Missing or invalid bearer token.",
+            headers={"WWW-Authenticate": "Bearer"},
+        )

mad_cli/server/models.py

@@ -0,0 +1,156 @@
+"""Typed request / response models for the v1 HTTP API (OpenAPI for free).
+
+Secret-looking values are only ever carried out masked — the response models are
+populated from the use-case layer's already-masked views, and there is no field
+(and no query flag) that reveals a full secret.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class HealthResponse(BaseModel):
+    status: str = "ok"
+    version: str
+
+
+class InstanceSummaryModel(BaseModel):
+    name: str
+    legacy: bool
+    port: int | None
+    state: str
+    health: str
+    version: str
+
+
+class EnvItemModel(BaseModel):
+    key: str
+    value: str = Field(description="Masked when the key looks like a secret.")
+    secret: bool
+
+
+class InstanceInfoModel(BaseModel):
+    name: str
+    legacy: bool
+    config_dir: str
+    compose_file: str
+    data_path: str | None
+    port: int | None
+    version: str | None
+    env: list[EnvItemModel]
+
+
+class InstallRequest(BaseModel):
+    name: str = "default"
+    port: int = 8080
+    data_path: str
+    timeout_s: int = 600
+    github_token: str
+    git_name: str = ""
+    git_email: str = ""
+    claude_token: str = ""
+    anthropic_api_key: str = ""
+    extra_keys: dict[str, str] = Field(
+        default_factory=dict,
+        description="Extra API keys as {builtin-id-or-VAR: value}; builtins fan out.",
+    )
+    retention_days: str = ""
+    mcp_allowed_hosts: str = ""
+    edge_package: str | None = None
+    edge_version: str = ""
+    start: bool = False
+
+
+class InstallResponse(BaseModel):
+    name: str
+    config_dir: str
+    data_dir: str
+    port: int
+    started: bool
+    healthy: bool | None
+    url: str | None
+
+
+class StartResponse(BaseModel):
+    name: str
+    healthy: bool
+    url: str | None
+
+
+class ActionResponse(BaseModel):
+    name: str
+    action: str
+    ok: bool = True
+
+
+class StatusResponse(BaseModel):
+    name: str
+    health: str
+    url: str | None
+    ps: str
+
+
+class SetConfigRequest(BaseModel):
+    value: str
+
+
+class SetConfigResponse(BaseModel):
+    key: str
+    value: str = Field(description="Masked when the key looks like a secret.")
+    secret: bool
+    compose_baked: bool
+
+
+class BuiltinKeyModel(BaseModel):
+    id: str
+    env_vars: list[str]
+    is_set: bool
+    value: str = Field(description="Masked value, or '-' when unset.")
+
+
+class CustomSecretModel(BaseModel):
+    key: str
+    value: str = Field(description="Masked value.")
+
+
+class KeysResponse(BaseModel):
+    builtins: list[BuiltinKeyModel]
+    custom: list[CustomSecretModel]
+
+
+class SetKeyRequest(BaseModel):
+    value: str
+
+
+class SetKeyResponse(BaseModel):
+    id: str
+    env_vars: list[str]
+    builtin: bool
+    credentials_written: bool
+
+
+class VersionRowModel(BaseModel):
+    name: str
+    legacy: bool
+    pinned: str
+    installed: str
+    latest: str
+    update: str
+
+
+class UpdateRequest(BaseModel):
+    version: str | None = None
+
+
+class UpdateResponse(BaseModel):
+    name: str
+    target: str
+    healthy: bool
+
+
+class AdoptResponse(BaseModel):
+    adopted: bool
+    name: str | None = None
+    target: str | None = None
+    moved: list[str] = Field(default_factory=list)

mad_cli/templates/Dockerfile.tmpl

@@ -0,0 +1,66 @@
+# Mad runtime image — generated by mad-cli (`mad install`). Do not edit by hand.
+# Installs ${edge_package} from PyPI + Claude Code CLI + OpenCode + gh CLI + git.
+# Multi-arch: arm64 (Raspberry Pi) and amd64.
+FROM node:20-slim
+
+# --- system dependencies + gh CLI --------------------------------------------
+RUN set -eux; \
+    apt-get update; \
+    apt-get install -y --no-install-recommends \
+        ca-certificates \
+        curl \
+        git \
+        gnupg \
+        python3 \
+        python3-venv \
+        python3-pip; \
+    mkdir -p -m 755 /etc/apt/keyrings; \
+    curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
+        -o /etc/apt/keyrings/githubcli-archive-keyring.gpg; \
+    chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg; \
+    echo "deb [arch=$$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \
+        > /etc/apt/sources.list.d/github-cli.list; \
+    apt-get update; \
+    apt-get install -y --no-install-recommends gh; \
+    apt-get clean; \
+    rm -rf /var/lib/apt/lists/*
+
+# --- agent CLIs --------------------------------------------------------------
+RUN npm install -g @anthropic-ai/claude-code opencode-ai \
+    && npm cache clean --force
+
+# --- ${edge_package} runtime -------------------------------------------------
+# The version is baked at render time; an empty spec installs the latest release.
+RUN python3 -m venv /opt/venv \
+    && /opt/venv/bin/pip install --no-cache-dir --upgrade pip \
+    && /opt/venv/bin/pip install --no-cache-dir "${edge_package}${edge_version_spec}"
+ENV PATH="/opt/venv/bin:$${PATH}"
+
+# --- non-root user -----------------------------------------------------------
+ARG PUID=${puid}
+ARG PGID=${pgid}
+RUN set -eux; \
+    userdel -r node 2>/dev/null || true; \
+    groupdel node 2>/dev/null || true; \
+    # The host GID may already exist in the base image (e.g. macOS gid 20 is
+    # Debian's dialout); reuse it instead of failing, and allow a duplicate UID.
+    getent group "$${PGID}" >/dev/null || groupadd -g "$${PGID}" mad; \
+    useradd -o -u "$${PUID}" -g "$${PGID}" -m -d /home/mad -s /bin/bash mad; \
+    mkdir -p /workspaces /sessions /home/mad/.claude /home/mad/.aws; \
+    chown -R "$${PUID}:$${PGID}" /workspaces /sessions /home/mad
+
+ENV HOME=/home/mad \
+    MAD_WORKSPACE_DIR=/workspaces
+
+# Entrypoint: authenticate the gh CLI with the token before launching the server.
+COPY --chown=mad:mad entrypoint.sh /home/mad/entrypoint.sh
+RUN chmod +x /home/mad/entrypoint.sh
+
+USER mad
+WORKDIR /home/mad
+EXPOSE 8000
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=30s --retries=3 \
+    CMD curl -fsS http://localhost:8000/openapi.json >/dev/null || exit 1
+
+ENTRYPOINT ["/home/mad/entrypoint.sh"]

mad_cli/templates/__init__.py

@@ -0,0 +1,6 @@
+"""Packaged ``string.Template`` sources for an instance's generated files.
+
+These ``*.tmpl`` files are package data rendered by :mod:`mad_cli.core.templates`.
+Literal ``$`` in the templates is escaped as ``$$``; ``${name}`` placeholders are
+the only render-time substitutions.
+"""

mad_cli/templates/com.mad-core.mad-cli.plist.tmpl

@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>${label}</string>
+    <key>ProgramArguments</key>
+    <array>
+${program_arguments}
+    </array>
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>MAD_CLI_CONFIG_DIR</key>
+        <string>${config_dir}</string>
+    </dict>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <dict>
+        <key>SuccessfulExit</key>
+        <false/>
+    </dict>
+    <key>StandardOutPath</key>
+    <string>${log_path}</string>
+    <key>StandardErrorPath</key>
+    <string>${log_path}</string>
+</dict>
+</plist>

mad_cli/templates/compose.yml.tmpl

@@ -0,0 +1,29 @@
+# Mad — compose generated by mad-cli. Edit .env to change values, not this file.
+services:
+  mad:
+    image: ${edge_package}:${image_tag}
+    build:
+      context: .
+      args:
+        PUID: "$${PUID:-${puid}}"
+        PGID: "$${PGID:-${pgid}}"
+    container_name: mad-${instance}
+    restart: unless-stopped
+    env_file:
+      - .env
+    environment:
+      MAD_WORKSPACE_DIR: /workspaces
+      MAD_SESSIONS_DIR: /sessions
+    ports:
+      - "${host_port}:8000"
+    volumes:
+      - ${data_path}/${instance}/workspaces:/workspaces
+      - ${data_path}/${instance}/sessions:/sessions
+      - ${data_path}/${instance}/claude:/home/mad/.claude
+      - ${data_path}/${instance}/aws:/home/mad/.aws:ro
+    healthcheck:
+      test: ["CMD", "curl", "-fsS", "http://localhost:8000/openapi.json"]
+      interval: 30s
+      timeout: 5s
+      start_period: 30s
+      retries: 3

mad_cli/templates/entrypoint.sh.tmpl

@@ -0,0 +1,11 @@
+#!/bin/bash
+set -e
+
+# Authenticate the gh CLI with the token from the environment so that
+# `gh auth status` shows the account and every git operation (push, PR, …) works.
+if [[ -n "$${GITHUB_TOKEN:-}" ]]; then
+    echo "$$GITHUB_TOKEN" | gh auth login --with-token --hostname github.com 2>/dev/null || true
+    gh auth setup-git 2>/dev/null || true
+fi
+
+exec ${edge_entrypoint} serve --host 0.0.0.0 --port 8000

mad_cli/templates/mad-cli.service.tmpl

@@ -0,0 +1,15 @@
+[Unit]
+Description=Mad operator CLI HTTP API (mad serve)
+Documentation=https://github.com/mad-core/mad-cli
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+ExecStart=${exec_start}
+Environment=MAD_CLI_CONFIG_DIR=${config_dir}
+Restart=on-failure
+RestartSec=3
+
+[Install]
+WantedBy=default.target

mad_cli/ui/__init__.py

@@ -0,0 +1,5 @@
+"""User-facing presentation layer (rich console + prompts).
+
+This package never talks to ``subprocess`` or the filesystem directly — all such
+work goes through ``mad_cli.core`` (see CONTRACTS.md, layering rule).
+"""

mad_cli/ui/console.py

@@ -0,0 +1,65 @@
+"""Shared rich console and consistently-styled status helpers.
+
+The single module-level :data:`console` is the one place output is written, so
+every command shares the same width, theme and capture behaviour. The helpers
+below add a coloured status glyph so ``info``/``ok``/``warn``/``error`` read the
+same everywhere.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TypeVar
+
+from rich.console import Console
+from rich.markup import escape
+
+_T = TypeVar("_T")
+
+# A single shared console. No explicit ``file`` is passed so rich resolves
+# ``sys.stdout`` lazily at print time — this is what lets test runners that
+# redirect stdout (e.g. Typer's CliRunner) capture our output.
+console = Console()
+
+# The message argument to these helpers is plain text (paths, key names,
+# ``pip install 'mad-cli[server]'`` hints, ``[A-Z][A-Z0-9_]*`` patterns …), so it
+# is escaped before printing — only the status glyph carries markup. Otherwise
+# rich would silently swallow any ``[...]`` in the message as a style tag.
+
+
+def info(msg: str) -> None:
+    """Neutral progress message."""
+    console.print(f"[cyan]▸[/cyan] {escape(msg)}", soft_wrap=True)
+
+
+def ok(msg: str) -> None:
+    """Success message."""
+    console.print(f"[green]✓[/green] {escape(msg)}", soft_wrap=True)
+
+
+def warn(msg: str) -> None:
+    """Non-fatal warning."""
+    console.print(f"[yellow]![/yellow] {escape(msg)}", soft_wrap=True)
+
+
+def error(msg: str) -> None:
+    """Error message. Rendering only — callers decide whether to exit."""
+    console.print(f"[red]✗[/red] {escape(msg)}", soft_wrap=True)
+
+
+def header(msg: str) -> None:
+    """Bold section header, preceded by a blank line."""
+    console.print(f"\n[bold]{escape(msg)}[/bold]", soft_wrap=True)
+
+
+def run_step(message: str, func: Callable[[], _T]) -> _T:
+    """Run ``func`` under a spinner on a real terminal, or plainly otherwise.
+
+    Falling back to a plain ``info`` line keeps output deterministic and
+    non-blocking under test runners and redirected pipes (no live display).
+    """
+    if console.is_terminal:
+        with console.status(message, spinner="dots"):
+            return func()
+    info(message)
+    return func()

mad_cli/ui/prompts.py

@@ -0,0 +1,83 @@
+"""Interactive prompt helpers built on ``rich.prompt``.
+
+Contract (CONTRACTS.md):
+
+* ``ask`` re-prompts while ``validator`` raises ``ValueError``; the validator's
+  return value is the normalised answer.
+* In a non-interactive context (stdin is not a TTY) prompts MUST NOT block:
+  ``ask`` returns ``default`` when one exists, otherwise raises
+  ``PromptRequiredError``; ``confirm`` returns its ``default``.
+"""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Callable
+
+from rich.prompt import Confirm, Prompt
+
+from mad_cli.ui.console import console, error
+
+
+class PromptRequiredError(Exception):
+    """A value was required but no default was available and we cannot prompt."""
+
+
+def _stdin_is_tty() -> bool:
+    try:
+        return sys.stdin.isatty()
+    except (ValueError, OSError):  # detached / closed stdin
+        return False
+
+
+def ask(
+    text: str,
+    default: str | None = None,
+    secret: bool = False,
+    validator: Callable[[str], str] | None = None,
+) -> str:
+    """Ask for a single string value.
+
+    ``validator`` receives the raw input and returns the normalised value; it
+    raises ``ValueError`` (whose message is shown) to trigger a re-prompt.
+    """
+    if not _stdin_is_tty():
+        if default is None:
+            raise PromptRequiredError(text)
+        if validator is not None:
+            try:
+                return validator(default)
+            except ValueError as exc:  # a bad default is not recoverable here
+                raise PromptRequiredError(str(exc)) from exc
+        return default
+
+    prompt_text = f"[cyan]?[/cyan] {text}"
+    while True:
+        if default is not None:
+            raw = Prompt.ask(
+                prompt_text,
+                console=console,
+                password=secret,
+                show_default=not secret,
+                default=default,
+            )
+        else:
+            raw = Prompt.ask(
+                prompt_text,
+                console=console,
+                password=secret,
+                show_default=not secret,
+            )
+        if validator is None:
+            return raw
+        try:
+            return validator(raw)
+        except ValueError as exc:
+            error(str(exc))
+
+
+def confirm(text: str, default: bool = True) -> bool:
+    """Yes/no confirmation. Returns ``default`` when stdin is not a TTY."""
+    if not _stdin_is_tty():
+        return default
+    return Confirm.ask(f"[cyan]?[/cyan] {text}", console=console, default=default)

mad_cli-0.4.0.dist-info/METADATA

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: mad-cli
+Version: 0.4.0
+Summary: Operator CLI for Mad — guided install, lifecycle, configuration, keys and version management for mad-edge containers.
+Project-URL: Homepage, https://github.com/mad-core/mad-cli
+Project-URL: Repository, https://github.com/mad-core/mad-cli
+Project-URL: Issues, https://github.com/mad-core/mad-cli/issues
+Author-email: Jose Salamanca <jose.salamancacoy@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Jose Salamanca
+        
+        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.
+License-File: LICENSE
+Keywords: agents,claude,cli,docker,mad,mcp,self-hosted
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Requires-Dist: rich>=13.7
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: fastapi>=0.110; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pip-audit>=2.7; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest-timeout>=2.3; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: python-semantic-release>=10.5.3; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: twine>=5.1; extra == 'dev'
+Requires-Dist: uvicorn>=0.29; extra == 'dev'
+Provides-Extra: server
+Requires-Dist: fastapi>=0.110; extra == 'server'
+Requires-Dist: uvicorn>=0.29; extra == 'server'
+Description-Content-Type: text/markdown
+
+# mad-cli
+
+[![PyPI](https://img.shields.io/pypi/v/mad-cli.svg)](https://pypi.org/project/mad-cli/)
+[![CI](https://github.com/mad-core/mad-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/mad-core/mad-cli/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/pypi/pyversions/mad-cli.svg)](https://pypi.org/project/mad-cli/)
+
+**Operator CLI for [Mad](https://github.com/mad-core).** `mad-cli` installs, runs and
+manages **mad-edge** containers — the Mad runtime that provisions isolated workspaces and
+launches autonomous coding agents (Claude Code, OpenCode, …) against your repositories.
+
+`mad-cli` is the thing an operator installs on a server or a Raspberry Pi. It does **not**
+run agents itself: it generates a `Dockerfile`, a `compose.yml` and a `.env`, builds the
+image and drives the container lifecycle through Docker Compose. The agent runtime lives in
+the [`mad-edge`](https://pypi.org/project/mad-edge/) package, which is installed *inside* the
+container.
+
+> **Alpha (0.x).** Interfaces may change between minor releases. Pin a version in production.
+
+## Quickstart
+
+```bash
+pip install mad-cli
+
+# Guided install: generates the config, builds the image, starts the container.
+mad install
+
+# Day-to-day lifecycle.
+mad start        # build + up (detached)
+mad status       # container state + API health
+mad logs         # follow logs
+mad stop         # stop, keeping workspace data on the host
+```
+
+`mad install` walks you through the instance name, host port, data path, GitHub token,
+git identity and Claude OAuth token, then writes everything under `~/.config/mad` (override
+with `MAD_CLI_CONFIG_DIR`) and starts the container. Once it is healthy the Mad HTTP/MCP API
+is available on the port you chose.
+
+## Commands
+
+The surface grows across the early minor releases; everything below the current line is
+planned.
+
+| Command | Since | What it does |
+|---|---|---|
+| `mad install` | v0.1 | Guided setup: render config, build image, start the container. |
+| `mad start` / `stop` / `restart` | v0.1 | Container lifecycle (`up --build` / `down` / `down`+`up`). |
+| `mad status` | v0.1 | Container state and API health for an instance. |
+| `mad logs` | v0.1 | Follow container logs. |
+| `mad shell` | v0.1 | Open an interactive `bash` shell inside the container. |
+| `mad list` | v0.2 | List every configured instance. |
+| `mad info NAME` | v0.2 | Show one instance's resolved config. |
+| `mad keys` | v0.2 | Set, rotate and mask API keys / tokens in `.env`. |
+| `mad config` | v0.2 | Read and edit `.env` values safely. |
+| `mad versions` / `update` | v0.3 | Show the latest published mad-edge and rebuild onto it. |
+| `mad serve` / `service` | v0.4 | Run the local HTTP API, or install it as a background service. |
+
+Instance-scoped commands take an optional `INSTANCE` argument; when exactly one instance is
+configured it is used by default.
+
+## HTTP API (optional)
+
+Every CLI capability is also exposed over a local HTTP API so a UI/dashboard can build on the
+same logic. It ships as an **optional extra** so the base CLI stays a two-dependency package
+(typer + rich):
+
+```bash
+pip install 'mad-cli[server]'
+
+mad serve                 # foreground API on http://127.0.0.1:7373
+```
+
+The API binds `127.0.0.1` by default and requires a bearer token (auto-generated at
+`~/.config/mad/api-token`, mode 0600) on every request except `/health`. Secret values are
+always masked on reads. OpenAPI is served at `/openapi.json`, docs at `/docs`. See
+[`docs/03-contracts/http-api.md`](docs/03-contracts/http-api.md).
+
+To keep it running across reboots:
+
+```bash
+mad service install       # systemd user unit (Linux) / launchd LaunchAgent (macOS)
+```
+
+If the `server` extra is not installed, `mad service install` **auto-provisions a dedicated
+virtualenv** under `~/.config/mad/server-venv` and installs the API there (use `--wheel PATH`
+to install from a local artifact instead of PyPI), then points the service at it — the base
+CLI never needs FastAPI in its own environment.
+
+> **MVP limitation.** Long operations (install with start, `start`, `update`) run
+> synchronously — the request blocks until the Docker build and health wait finish. Background
+> jobs are a future enhancement.
+
+## How it relates to mad-edge
+
+| | `mad-cli` (this package) | `mad-edge` |
+|---|---|---|
+| Runs on | the operator's host | inside the container |
+| Console script | `mad` | `mad-edge` (server) |
+| Role | install & lifecycle management | the agent runtime / HTTP + MCP API |
+| Talks to | Docker, the filesystem, PyPI | Claude Code, OpenCode, GitHub, workspaces |
+
+`mad-cli` pins or tracks the mad-edge version through the generated `Dockerfile`; the
+container installs `mad-edge` from PyPI at build time. Version bumps follow the mad-edge
+versioning policy.
+
+## License
+
+[MIT](LICENSE).