remote-docker-cli 0.2.0__py3-none-any.whl

remote_docker/cli.py

@@ -0,0 +1,986 @@
+#!/usr/bin/env python3
+"""
+rdocker — Docker-like CLI that proxies pull/save/load to a remote SSH host via skopeo.
+
+Architecture:
+    Local Machine                          Remote Machine (SSH)
+    ┌──────────────────┐                   ┌──────────────────────────────┐
+    │ docker-compose   │                   │  /tmp/rdocker/<name>/       │
+    │       .yml       │                   │   ├── nginx_latest.tar      │
+    └────────┬─────────┘                   │   ├── redis_7-alpine.tar    │
+             │ parse + 补全 latest         │   └── ...                   │
+             ▼                             │   └── <name>.tar.gz  ← 产物 │
+    │  images list    │  ──ssh+skopeo──▶  │  skopeo copy docker://...   │
+    │  (in memory)    │                    │  docker-archive:xx.tar      │
+    └─────────────────┘                    └──────────────┬─────────────┘
+                                                         │
+                                                         │ scp
+                                                         ▼
+                                            ./<name>.tar.gz  ← 本地最终产物
+
+Config file: ~/.config/rdocker/config.yml
+"""
+
+import getpass
+import os
+import platform
+import re
+import shlex
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+from typing import Optional
+from remote_docker import __version__
+
+import click
+import yaml
+
+
+# ─────────────────────────────────────────────
+# 配置层
+# ─────────────────────────────────────────────
+CONFIG_DIR = Path(os.path.expanduser("~/.config/rdocker"))
+CONFIG_FILE = CONFIG_DIR / "config.yml"
+
+DEFAULT_REMOTE_DIR = "/tmp/rdocker"
+DEFAULT_SSH_PORT = 22
+
+
+# ── 配置读写 ────────────────────────────────
+
+def load_config_file() -> dict:
+    """从 ~/.config/rdocker/config.yml 读取配置，不存在返回空 dict"""
+    if not CONFIG_FILE.exists():
+        return {}
+    try:
+        data = yaml.safe_load(CONFIG_FILE.read_text(encoding="utf-8"))
+        return data or {}
+    except yaml.YAMLError as e:
+        click.echo(f"⚠️  Config file parse error: {e}", err=True)
+        return {}
+
+
+def save_config_file(config: dict):
+    """写入配置文件"""
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    # 保留注释友好：用 yaml 写，排序 keys
+    yaml_text = yaml.dump(
+        config,
+        default_flow_style=False,
+        sort_keys=False,
+        allow_unicode=True,
+        indent=2,
+    )
+    CONFIG_FILE.write_text(yaml_text, encoding="utf-8")
+    os.chmod(CONFIG_FILE, 0o600)
+    click.echo(f"✅ Config saved to {CONFIG_FILE}")
+
+
+def get_config_value(key: str, default: str = "") -> str:
+    """
+    优先级：环境变量 rdocker_<KEY> > 配置文件 > default
+    """
+    env_val = os.getenv(f"rdocker_{key.upper()}")
+    if env_val:
+        return env_val
+    cfg = load_config_file()
+    return cfg.get(key, default)
+
+
+# ─────────────────────────────────────────────
+# 工具函数
+# ─────────────────────────────────────────────
+
+def parse_compose_images(compose_file: Path) -> list[str]:
+    """
+    解析 docker-compose.yml，提取所有 service.image，
+    没有 tag 的自动补全为 :latest，
+    正确区分 registry:port 与 :tag 的情况。
+    """
+    data = yaml.safe_load(compose_file.read_text(encoding="utf-8"))
+    images: set[str] = set()
+
+    services = data.get("services") or {}
+    for svc_name, svc_cfg in services.items():
+        img = (svc_cfg or {}).get("image")
+        if not img:
+            click.echo(f"⚠️  Service '{svc_name}' has no image field, skipping.", err=True)
+            continue
+
+        parts = img.split("/")
+        first = parts[0]
+
+        # registry:port 形式（如 registry:5000/app:v1）
+        if ":" in first and re.match(r"^[^:]+:\d+$", first):
+            rest = "/".join(parts[1:])
+            if ":" in rest and not re.search(r":\d+$", img):
+                pass  # 已有 tag
+            else:
+                img = img + ":latest"
+        elif re.match(r"^[^:]+:\d+$", img):
+            img = img + ":latest"
+        elif ":" not in img:
+            img = img + ":latest"
+
+        images.add(img)
+
+    return sorted(images)
+
+
+def build_ssh_cmd(host: str, user: str, key: str, port: int, remote_cmd: str) -> list[str]:
+    cmd = [
+        "ssh",
+        "-o", "StrictHostKeyChecking=no",
+        "-o", "ConnectTimeout=30",
+        "-o", "ServerAliveInterval=60",
+        "-p", str(port),
+    ]
+    if key:
+        cmd.extend(["-i", os.path.expanduser(key)])
+    cmd += [f"{user}@{host}", remote_cmd]
+    return cmd
+
+
+def build_scp_cmd(host: str, user: str, key: str, port: int, src: str, dst: str) -> list[str]:
+    cmd = [
+        "scp",
+        "-o", "StrictHostKeyChecking=no",
+        "-o", "ConnectTimeout=30",
+        "-P", str(port),
+    ]
+    if key:
+        cmd.extend(["-i", os.path.expanduser(key)])
+    cmd += [f"{user}@{host}:{src}", dst]
+    return cmd
+
+
+def run_local(cmd: list[str], check: bool = True, capture: bool = False) -> subprocess.CompletedProcess:
+    click.echo(f"  $ {' '.join(shlex.quote(c) for c in cmd)}", err=True)
+    if capture:
+        result = subprocess.run(cmd, capture_output=True, text=True)
+    else:
+        result = subprocess.run(cmd)
+    if check and result.returncode != 0:
+        err_msg = result.stderr.strip() if capture else ""
+        raise click.ClickException(
+            f"Command failed (exit {result.returncode}): "
+            f"{' '.join(shlex.quote(c) for c in cmd)}"
+            + (f"\n{err_msg}" if err_msg else "")
+        )
+    return result
+
+
+def run_ssh(host: str, user: str, key: str, port: int, remote_cmd: str, capture: bool = False) -> subprocess.CompletedProcess:
+    cmd = build_ssh_cmd(host, user, key, port, remote_cmd)
+    return run_local(cmd, check=True, capture=capture)
+
+
+def run_scp_download(host: str, user: str, key: str, port: int, remote_src: str, local_dst: str) -> subprocess.CompletedProcess:
+    cmd = build_scp_cmd(host, user, key, port, remote_src, local_dst)
+    return run_local(cmd, check=True, capture=False)
+
+
+# ─────────────────────────────────────────────
+# 核心动作
+# ─────────────────────────────────────────────
+
+def local_arch() -> str:
+    """Return the Docker/OCI architecture name for the local machine."""
+    machine = platform.machine().lower()
+    mapping = {
+        "x86_64": "amd64",
+        "amd64": "amd64",
+        "aarch64": "arm64",
+        "arm64": "arm64",
+        "armv7l": "arm",
+        "armv6l": "arm",
+        "i386": "386",
+        "i686": "386",
+        "ppc64le": "ppc64le",
+        "s390x": "s390x",
+    }
+    return mapping.get(machine, machine)
+
+
+def image_short_name(image: str) -> str:
+    """Return the last path segment of an image reference, with any :tag stripped.
+
+    Examples:
+        nginx                       -> nginx
+        nginx:1.25-alpine           -> nginx
+        library/nginx               -> nginx
+        library/nginx:1.25          -> nginx
+        registry:5000/app:v1        -> app
+        harbor.example.com/team/app -> app
+        harbor.example.com/team/app:1.0 -> app
+    """
+    last = image.rsplit("/", 1)[-1]
+    if ":" in last:
+        last = last.split(":", 1)[0]
+    return last or image
+
+
+def default_bundle_name(mode: str, ref: str = "") -> str:
+    """Default bundle name for commands.
+
+    mode='compose' → current directory's last short name
+    mode='image'   → image reference's last segment, tag stripped
+    """
+    if mode == "image" and ref:
+        return image_short_name(ref)
+    return Path.cwd().name or "rdocker"
+
+
+def do_pull(host, user, key, port, images, name, registry_auth):
+    remote_dir = f"{DEFAULT_REMOTE_DIR}/{name}"
+    click.echo(f"📁 Creating remote directory: {remote_dir}")
+    run_ssh(host, user, key, port, f"mkdir -p {remote_dir}")
+
+    arch_flag = f"--override-arch {shlex.quote(local_arch())}"
+    auth_flag = ""
+    if registry_auth:
+        auth_flag = f"--src-creds {shlex.quote(registry_auth)}"
+
+    failed = []
+    for img in images:
+        safe_name = img.replace("/", "_").replace(":", "_")
+        tar_path = f"{remote_dir}/{safe_name}.tar"
+        click.echo(f"⬇️  Pulling ({local_arch()}): {img}  →  {tar_path}")
+
+        skopeo_cmd = (
+            f"skopeo copy {arch_flag} {auth_flag} "
+            f"docker://{shlex.quote(img)} "
+            f"docker-archive:{shlex.quote(tar_path)}:{shlex.quote(img)}"
+        )
+        try:
+            run_ssh(host, user, key, port, skopeo_cmd)
+        except click.ClickException as e:
+            click.echo(f"   ❌ Failed: {img} — {e}", err=True)
+            failed.append(img)
+            continue
+
+    click.echo("")
+    click.echo(f"✅ Pull complete. ({len(images) - len(failed)}/{len(images)} succeeded)")
+    if failed:
+        click.echo(f"❌ Failed images:", err=True)
+        for f in failed:
+            click.echo(f"   - {f}", err=True)
+        raise click.ClickException(f"{len(failed)} image(s) failed to pull")
+
+
+def do_save(host, user, key, port, name):
+    remote_dir = f"{DEFAULT_REMOTE_DIR}/{name}"
+    tarball = f"/tmp/{name}.tar.gz"
+
+    click.echo(f"📦 Packing remote tars into {tarball} ...")
+    check_cmd = f"ls {remote_dir}/*.tar >/dev/null 2>&1 && echo OK || echo EMPTY"
+    result = run_ssh(host, user, key, port, check_cmd, capture=True)
+    if "EMPTY" in result.stdout:
+        raise click.ClickException(f"No tar files found in {remote_dir}")
+
+    tar_cmd = f"cd {remote_dir} && tar -czf {tarball} ."
+    run_ssh(host, user, key, port, tar_cmd)
+    click.echo(f"✅ Remote bundle created: {tarball}")
+
+
+def do_fetch(host, user, key, port, name, output_dir) -> str:
+    remote_tarball = f"/tmp/{name}.tar.gz"
+    local_path = os.path.join(output_dir, f"{name}.tar.gz")
+    click.echo(f"⬇️  Downloading {remote_tarball} → {local_path} ...")
+    run_scp_download(host, user, key, port, remote_tarball, local_path)
+    click.echo(f"✅ Downloaded: {local_path}")
+    return local_path
+
+
+def do_load(local_tarball: str):
+    tarball = Path(local_tarball)
+    if not tarball.exists():
+        raise click.ClickException(f"File not found: {tarball}")
+
+    if not shutil.which("docker"):
+        raise click.ClickException("docker command not found on local machine")
+
+    click.echo(f"📂 Extracting {tarball} ...")
+    with tempfile.TemporaryDirectory() as tmp:
+        subprocess.run(["tar", "-xzf", str(tarball), "-C", tmp], check=True)
+
+        tar_files = sorted(Path(tmp).glob("*.tar"))
+        if not tar_files:
+            raise click.ClickException(f"No .tar files found in {tarball}")
+
+        click.echo(f"🔄 Loading {len(tar_files)} image(s) into local Docker ...")
+        for tar in tar_files:
+            click.echo(f"   Loading {tar.name} ...")
+            result = subprocess.run(
+                ["docker", "load", "-i", str(tar)],
+                capture_output=True, text=True,
+            )
+            if result.returncode != 0:
+                click.echo(f"   ❌ docker load failed for {tar.name}: {result.stderr}", err=True)
+            else:
+                click.echo(f"   ✅ {result.stdout.strip()}")
+
+    click.echo("✅ All images loaded into local Docker daemon")
+
+
+def do_cleanup(host, user, key, port, name):
+    remote_dir = f"{DEFAULT_REMOTE_DIR}/{name}"
+    remote_tarball = f"/tmp/{name}.tar.gz"
+    click.echo(f"🧹 Cleaning up remote files ...")
+    cleanup_cmd = f"rm -rf {remote_dir} {remote_tarball}"
+    try:
+        run_ssh(host, user, key, port, cleanup_cmd)
+        click.echo("✅ Remote cleanup done")
+    except click.ClickException:
+        click.echo("⚠️  Remote cleanup failed (non-fatal)", err=True)
+
+
+# ── 干跑计划（不执行，仅打印） ─────────────────
+
+def cmd_to_str(cmd: list[str]) -> str:
+    """Quote a command list as a printable shell string."""
+    return " ".join(shlex.quote(c) for c in cmd)
+
+
+def print_save_plan(host, user, key, port, name):
+    """Print the save command without executing."""
+    remote_dir = f"{DEFAULT_REMOTE_DIR}/{name}"
+    tarball = f"/tmp/{name}.tar.gz"
+    click.echo(f"🔍 Dry-run: no commands will be executed")
+    click.echo("")
+    check_cmd = build_ssh_cmd(
+        host, user, key, port,
+        f"ls {remote_dir}/*.tar >/dev/null 2>&1 && echo OK || echo EMPTY",
+    )
+    click.echo(f"  {cmd_to_str(check_cmd)}")
+    tar_cmd = build_ssh_cmd(host, user, key, port, f"cd {remote_dir} && tar -czf {tarball} .")
+    click.echo(f"  {cmd_to_str(tar_cmd)}")
+    click.echo("")
+    click.echo(f"  Remote bundle would be: {tarball}")
+
+
+def print_fetch_plan(host, user, key, port, name, local_dst):
+    """Print the fetch command without executing."""
+    remote_tarball = f"/tmp/{name}.tar.gz"
+    click.echo(f"🔍 Dry-run: no commands will be executed")
+    click.echo("")
+    cmd = build_scp_cmd(host, user, key, port, remote_tarball, local_dst)
+    click.echo(f"  {cmd_to_str(cmd)}")
+
+
+def print_load_plan(host, user, key, port, name, file, output_dir="."):
+    """Print what load would execute; if remote fallback applies, print scp too."""
+    if file:
+        tarball = file
+    elif name:
+        tarball = f"{name}.tar.gz"
+    else:
+        raise click.ClickException("Must specify --name or --file")
+
+    click.echo(f"🔍 Dry-run: no commands will be executed")
+    click.echo("")
+
+    would_fetch = False
+    if not Path(tarball).exists() and name and host:
+        would_fetch = True
+        local_dst = os.path.join(output_dir or ".", f"{name}.tar.gz")
+        click.echo(f"  # Local '{tarball}' not found, would fetch from remote:")
+        cmd = build_scp_cmd(host, user, key, port, f"/tmp/{name}.tar.gz", local_dst)
+        click.echo(f"  {cmd_to_str(cmd)}")
+        click.echo("")
+        local_tarball = local_dst
+    else:
+        local_tarball = tarball
+
+    click.echo(f"  # Extract and load:")
+    click.echo(f"  tar -xzf {shlex.quote(local_tarball)} -C <tmpdir>")
+    click.echo(f"  docker load -i <each.tar in tmpdir>")
+
+
+def print_cleanup_plan(host, user, key, port, name):
+    """Print the cleanup command without executing."""
+    remote_dir = f"{DEFAULT_REMOTE_DIR}/{name}"
+    remote_tarball = f"/tmp/{name}.tar.gz"
+    click.echo(f"🔍 Dry-run: no commands will be executed")
+    click.echo("")
+    cleanup_cmd = f"rm -rf {remote_dir} {remote_tarball}"
+    cmd = build_ssh_cmd(host, user, key, port, cleanup_cmd)
+    click.echo(f"  {cmd_to_str(cmd)}")
+
+
+# ─────────────────────────────────────────────
+# Click CLI
+# ─────────────────────────────────────────────
+
+@click.group(
+    context_settings={"help_option_names": ["-h", "--help"]},
+    help=(
+        "rdocker — Docker-like CLI that proxies pull/save/load to a remote SSH host via skopeo.\n\n"
+        "Config priority: CLI flag > env var > config file > default\n"
+        "Config file: ~/.config/rdocker/config.yml"
+    ),
+)
+@click.option("--host", default=lambda: get_config_value("host", ""), help="Remote SSH host")
+@click.option("--user", default=lambda: get_config_value("user", getpass.getuser()), help="SSH user (default: current system username)")
+@click.option("--port", default=lambda: int(get_config_value("port", str(DEFAULT_SSH_PORT))), type=int, help="SSH port")
+@click.option("--key", default=lambda: get_config_value("key", ""), help="SSH private key path (default: use ssh-agent / ~/.ssh/id_*)")
+@click.pass_context
+def cli(ctx: click.Context, host: str, user: str, port: int, key: str):
+    ctx.ensure_object(dict)
+    ctx.obj["host"] = host
+    ctx.obj["user"] = user
+    ctx.obj["port"] = port
+    ctx.obj["key"] = key
+
+
+def _require_host(ctx: click.Context) -> str:
+    host = ctx.obj.get("host", "")
+    if not host:
+        raise click.ClickException(
+            "Remote host not specified.\n"
+            "  → Use --host flag, set rdocker_HOST env var, or run: rdocker config init"
+        )
+    return host
+
+
+# ── config 命令组 ────────────────────────────
+
+@cli.group(help="Manage rdocker configuration (~/.config/rdocker/config.yml)")
+def config():
+    pass
+
+
+@config.command("init", help="Interactively create or overwrite the config file")
+@click.option("--force", "-f", is_flag=True, help="Overwrite existing config without prompting")
+def config_init(force: bool):
+    """
+    交互式引导用户填写 SSH 远程主机配置，写入 ~/.config/rdocker/config.yml
+    """
+    if CONFIG_FILE.exists() and not force:
+        click.confirm(
+            f"⚠️  Config file already exists at {CONFIG_FILE}.\n"
+            f"   Overwrite?",
+            abort=True,
+            default=False,
+        )
+
+    click.echo("")
+    click.echo("🔧 rdocker Config Init")
+    click.echo("─" * 50)
+    click.echo("Enter remote SSH connection details (press Enter to use [default]):")
+    click.echo("")
+
+    # host（必填）
+    host = click.prompt("  Remote host (IP or domain)", type=str, default="").strip()
+    while not host:
+        click.echo("  ❌ Host cannot be empty", err=True)
+        host = click.prompt("  Remote host (IP or domain)", type=str, default="").strip()
+
+    # user
+    user = click.prompt("  SSH user", type=str, default=getpass.getuser()).strip()
+    if not user:
+        user = getpass.getuser()
+
+    # port
+    port_str = click.prompt("  SSH port", type=str, default=str(DEFAULT_SSH_PORT)).strip()
+    try:
+        port = int(port_str)
+    except ValueError:
+        click.echo(f"  ⚠️  Invalid port '{port_str}', using default {DEFAULT_SSH_PORT}", err=True)
+        port = DEFAULT_SSH_PORT
+
+    # key (empty = use system default: ssh-agent / ~/.ssh/id_*)
+    key = click.prompt("  SSH private key path (empty = system default)", type=str, default="").strip()
+
+    # registry auth（可选）
+    registry_auth = click.prompt(
+        "  Registry auth (user:pass, leave empty if none)",
+        type=str, default="",
+    ).strip()
+
+    # remote dir
+    remote_dir = click.prompt(
+        "  Remote working directory",
+        type=str, default=DEFAULT_REMOTE_DIR,
+    ).strip()
+    if not remote_dir:
+        remote_dir = DEFAULT_REMOTE_DIR
+
+    # 组装配置
+    config_data = {
+        "host": host,
+        "user": user,
+        "port": port,
+        "key": key,
+        "remote_dir": remote_dir,
+    }
+    if registry_auth:
+        config_data["registry_auth"] = registry_auth
+
+    # 写入
+    save_config_file(config_data)
+
+    # 验证 SSH 连通性
+    click.echo("")
+    click.echo("🔍 Testing SSH connection ...")
+    ssh_key_path = os.path.expanduser(key)
+    test_cmd = [
+        "ssh",
+        "-i", ssh_key_path,
+        "-o", "StrictHostKeyChecking=no",
+        "-o", "ConnectTimeout=10",
+        "-p", str(port),
+        f"{user}@{host}",
+        "echo 'SSH OK' && which skopeo || echo 'WARN: skopeo not found on remote'",
+    ]
+    try:
+        result = subprocess.run(test_cmd, capture_output=True, text=True, timeout=20)
+        if result.returncode == 0:
+            click.echo(f"  ✅ SSH connection successful")
+            if "skopeo not found" in result.stdout:
+                click.echo(f"  ⚠️  skopeo is NOT installed on remote host. Install it first!", err=True)
+            else:
+                click.echo(f"  ✅ skopeo is available on remote")
+        else:
+            click.echo(f"  ❌ SSH connection failed:\n  {result.stderr.strip()}", err=True)
+    except subprocess.TimeoutExpired:
+        click.echo(f"  ❌ SSH connection timeout (10s)", err=True)
+    except Exception as e:
+        click.echo(f"  ❌ SSH test error: {e}", err=True)
+
+    click.echo("")
+    click.echo("🎉 Config initialized! You can now run:")
+    click.echo(f"   rdocker all docker-compose.yml --name myapp")
+
+
+@config.command("show", help="Display current configuration")
+def config_show():
+    """查看当前配置（脱敏显示密码）"""
+    cfg = load_config_file()
+
+    click.echo("")
+    click.echo("📋 rdocker Configuration")
+    click.echo("─" * 50)
+
+    if not cfg:
+        click.echo(f"  (no config file found at {CONFIG_FILE})")
+        click.echo(f"  Run: rdocker config init")
+        return
+
+    click.echo(f"  Config file: {CONFIG_FILE}")
+    click.echo(f"  Permissions: {oct(os.stat(CONFIG_FILE).st_mode)[-3:]}")
+    click.echo("")
+    for key in ("host", "user", "port", "key", "remote_dir", "registry_auth"):
+        val = cfg.get(key, "<not set>")
+        # 脱敏 registry_auth
+        if key == "registry_auth" and val and ":" in str(val):
+            parts = str(val).split(":", 1)
+            masked = f"{parts[0]}:***"
+            click.echo(f"  {key:15s} = {masked}")
+        else:
+            click.echo(f"  {key:15s} = {val}")
+
+    click.echo("")
+    click.echo("  Priority: CLI flag > env var (rdocker_*) > config file > default")
+
+
+@config.command("set", help="Set a single config key-value pair")
+@click.argument("key", type=click.Choice([
+    "host", "user", "port", "key", "remote_dir", "registry_auth"
+]))
+@click.argument("value")
+def config_set(key: str, value: str):
+    """修改配置中的单个字段"""
+    cfg = load_config_file()
+
+    # 类型转换
+    if key == "port":
+        try:
+            value = int(value)
+        except ValueError:
+            raise click.ClickException(f"port must be an integer, got '{value}'")
+
+    cfg[key] = value
+    save_config_file(cfg)
+
+    # 脱敏显示
+    display_val = value
+    if key == "registry_auth" and ":" in str(value):
+        parts = str(value).split(":", 1)
+        display_val = f"{parts[0]}:***"
+
+    click.echo(f"   {key} = {display_val}")
+
+
+@config.command("unset", help="Remove a config key")
+@click.argument("key", type=click.Choice([
+    "host", "user", "port", "key", "remote_dir", "registry_auth"
+]))
+def config_unset(key: str):
+    """删除配置中的某个字段"""
+    cfg = load_config_file()
+    if key in cfg:
+        del cfg[key]
+        save_config_file(cfg)
+        click.echo(f"   removed: {key}")
+    else:
+        click.echo(f"   key '{key}' not in config, nothing to do")
+
+
+@config.command("path", help="Print the config file path")
+def config_path():
+    """打印配置文件路径"""
+    click.echo(str(CONFIG_FILE))
+
+
+# ── pull ──────────────────────────────────────
+
+@cli.command()
+@click.argument("compose_file", type=click.Path(exists=True, dir_okay=False))
+@click.option("--name", "-n", default="", help="Bundle name (default: current directory short name)")
+@click.option("--registry-auth", "-a", default=lambda: get_config_value("registry_auth", ""), help="Registry credentials (user:pass)")
+@click.option("--try", "dry_run", is_flag=True, help="Dry-run: print commands without executing")
+@click.pass_context
+def pull(ctx: click.Context, compose_file: str, name: str, registry_auth: str, dry_run: bool):
+    """Parse docker-compose.yml and pull all images to remote host via skopeo."""
+    host = _require_host(ctx)
+    user = ctx.obj["user"]
+    port = ctx.obj["port"]
+    key = ctx.obj["key"]
+
+    if not name:
+        name = default_bundle_name("compose")
+    click.echo(f"📦 Bundle name: {name}")
+
+    compose_path = Path(compose_file)
+    click.echo(f"📄 Parsing: {compose_path}")
+    images = parse_compose_images(compose_path)
+
+    if not images:
+        raise click.ClickException("No images found in compose file")
+
+    click.echo(f"📋 Found {len(images)} image(s):")
+    for img in images:
+        click.echo(f"   - {img}")
+
+    click.echo("")
+    auth = registry_auth or None
+    if dry_run:
+        print_pull_plan(host, user, key, port, images, name, auth)
+        return
+    do_pull(host, user, key, port, images, name, auth)
+
+
+def print_pull_plan(host, user, key, port, images, name, registry_auth):
+    """Print the commands that would be executed, without running them."""
+    remote_dir = f"{DEFAULT_REMOTE_DIR}/{name}"
+    arch_flag = f"--override-arch {shlex.quote(local_arch())} "
+    click.echo(f"🔍 Dry-run: no commands will be executed")
+    click.echo("")
+    click.echo(f"  ssh {user}@{host} 'mkdir -p {remote_dir}'")
+
+    auth_flag = ""
+    if registry_auth:
+        auth_flag = f"--src-creds {shlex.quote(registry_auth)} "
+
+    for img in images:
+        safe_name = img.replace("/", "_").replace(":", "_")
+        tar_path = f"{remote_dir}/{safe_name}.tar"
+        skopeo_cmd = (
+            f"skopeo copy {arch_flag}{auth_flag}"
+            f"docker://{shlex.quote(img)} "
+            f"docker-archive:{shlex.quote(tar_path)}:{shlex.quote(img)}"
+        )
+        click.echo(f"  ssh {user}@{host} '{skopeo_cmd}'")
+
+    click.echo("")
+    click.echo(f"  ({len(images)} image(s) would be pulled)")
+
+
+# ── spull ─────────────────────────────────────
+
+@cli.command()
+@click.argument("image")
+@click.option("--name", "-n", default="", help="Bundle name (default: current directory short name)")
+@click.option("--registry-auth", "-a", default=lambda: get_config_value("registry_auth", ""), help="Registry credentials (user:pass)")
+@click.option("--try", "dry_run", is_flag=True, help="Dry-run: print commands without executing")
+@click.pass_context
+def spull(ctx: click.Context, image: str, name: str, registry_auth: str, dry_run: bool):
+    """Pull a single image to remote host via skopeo (no compose parsing)."""
+    host = _require_host(ctx)
+    user = ctx.obj["user"]
+    port = ctx.obj["port"]
+    key = ctx.obj["key"]
+
+    if not name:
+        name = default_bundle_name("image", image)
+    click.echo(f"📦 Bundle name: {name}")
+    click.echo(f"🐳 Image: {image}")
+
+    images = [image]
+    auth = registry_auth or None
+    if dry_run:
+        print_pull_plan(host, user, key, port, images, name, auth)
+        return
+    do_pull(host, user, key, port, images, name, auth)
+
+
+# ── save ──────────────────────────────────────
+
+@cli.command()
+@click.option("--name", "-n", default="", help="Bundle name (default: current directory short name)")
+@click.option("--try", "dry_run", is_flag=True, help="Dry-run: print commands without executing")
+@click.pass_context
+def save(ctx: click.Context, name: str, dry_run: bool):
+    """Package all remote tar files into a single tar.gz."""
+    if not name:
+        name = default_bundle_name("compose")
+    click.echo(f"📦 Bundle name: {name}")
+    host = _require_host(ctx)
+    user = ctx.obj["user"]
+    port = ctx.obj["port"]
+    key = ctx.obj["key"]
+    if dry_run:
+        print_save_plan(host, user, key, port, name)
+        return
+    do_save(host, user, key, port, name)
+
+
+# ── fetch ─────────────────────────────────────
+
+@cli.command()
+@click.option("--name", "-n", default="", help="Bundle name (default: current directory short name)")
+@click.option("--output-dir", "-o", default=".", help="Local output directory (default: current dir)")
+@click.option("--try", "dry_run", is_flag=True, help="Dry-run: print commands without executing")
+@click.pass_context
+def fetch(ctx: click.Context, name: str, output_dir: str, dry_run: bool):
+    """Download the tar.gz bundle from remote host to local."""
+    if not name:
+        name = default_bundle_name("compose")
+    click.echo(f"📦 Bundle name: {name}")
+    host = _require_host(ctx)
+    user = ctx.obj["user"]
+    port = ctx.obj["port"]
+    key = ctx.obj["key"]
+
+    local_dst = os.path.join(output_dir, f"{name}.tar.gz")
+    if dry_run:
+        print_fetch_plan(host, user, key, port, name, local_dst)
+        return
+
+    os.makedirs(output_dir, exist_ok=True)
+    do_fetch(host, user, key, port, name, output_dir)
+
+
+# ── load ──────────────────────────────────────
+
+@cli.command()
+@click.option("--name", "-n", help="Bundle name (downloads <name>.tar.gz from remote)")
+@click.option("--file", "-f", help="Local tar.gz file to load (alternative to --name)")
+@click.option("--try", "dry_run", is_flag=True, help="Dry-run: print commands without executing")
+@click.pass_context
+def load(ctx: click.Context, name: str, file: Optional[str], dry_run: bool):
+    """Load images from tar.gz into local Docker daemon."""
+    host = ctx.obj.get("host", "")
+    user = ctx.obj.get("user", "")
+    port = ctx.obj.get("port", 22)
+    key = ctx.obj.get("key", "")
+
+    if dry_run:
+        print_load_plan(host, user, key, port, name, file)
+        return
+
+    tarball = None
+
+    if file:
+        tarball = file
+    elif name:
+        tarball = f"{name}.tar.gz"
+    else:
+        raise click.ClickException("Must specify --name or --file")
+
+    if not Path(tarball).exists():
+        if name and host:
+            click.echo(f"📥 Local file not found, fetching from remote ...")
+            tarball = do_fetch(host, user, key, port, name, ".")
+        else:
+            raise click.ClickException(f"File not found: {tarball}")
+
+    do_load(tarball)
+
+
+# ── cleanup ───────────────────────────────────
+
+@cli.command()
+@click.option("--name", "-n", default="", help="Bundle name (default: current directory short name)")
+@click.option("--try", "dry_run", is_flag=True, help="Dry-run: print commands without executing")
+@click.pass_context
+def cleanup(ctx: click.Context, name: str, dry_run: bool):
+    """Remove remote temporary files."""
+    if not name:
+        name = default_bundle_name("compose")
+    click.echo(f"📦 Bundle name: {name}")
+    host = _require_host(ctx)
+    user = ctx.obj["user"]
+    port = ctx.obj["port"]
+    key = ctx.obj["key"]
+    if dry_run:
+        print_cleanup_plan(host, user, key, port, name)
+        return
+    do_cleanup(host, user, key, port, name)
+
+
+# ── all ───────────────────────────────────────
+
+@cli.command()
+@click.argument("compose_file", type=click.Path(exists=True, dir_okay=False))
+@click.option("--name", "-n", default="", help="Bundle name (default: current directory short name)")
+@click.option("--registry-auth", "-a", default=lambda: get_config_value("registry_auth", ""), help="Registry credentials (user:pass)")
+@click.option("--output-dir", "-o", default=".", help="Local output directory")
+@click.option("--no-cleanup", is_flag=True, help="Do not remove remote temp files")
+@click.option("--no-load", is_flag=True, help="Do not docker load after download")
+@click.option("--try", "dry_run", is_flag=True, help="Dry-run: print commands without executing")
+@click.pass_context
+def all_cmd(
+    ctx: click.Context,
+    compose_file: str,
+    name: str,
+    registry_auth: str,
+    output_dir: str,
+    no_cleanup: bool,
+    no_load: bool,
+    dry_run: bool,
+):
+    """
+    One-shot: parse compose → remote pull → remote pack → download → local load.
+
+    Equivalent to running: pull → save → fetch → load
+    """
+    if not name:
+        name = default_bundle_name("compose")
+    click.echo(f"📦 Bundle name: {name}")
+
+    host = ctx.obj["host"]
+    user = ctx.obj["user"]
+    port = ctx.obj["port"]
+    key = ctx.obj["key"]
+
+    if dry_run:
+        click.echo("🔍 Dry-run: no commands will be executed")
+        click.echo("")
+
+        # Step 1
+        click.echo("=" * 60)
+        click.echo("STEP 1/4: Parse compose & pull images on remote")
+        click.echo("=" * 60)
+        compose_path = Path(compose_file)
+        images = parse_compose_images(compose_path)
+        if not images:
+            raise click.ClickException("No images found in compose file")
+        click.echo(f"📋 Found {len(images)} image(s):")
+        for img in images:
+            click.echo(f"   - {img}")
+        click.echo("")
+        auth = registry_auth or None
+        print_pull_plan(host, user, key, port, images, name, auth)
+
+        # Step 2
+        click.echo("")
+        click.echo("=" * 60)
+        click.echo("STEP 2/4: Pack tar.gz on remote")
+        click.echo("=" * 60)
+        print_save_plan(host, user, key, port, name)
+
+        # Step 3
+        click.echo("")
+        click.echo("=" * 60)
+        click.echo("STEP 3/4: Download bundle to local")
+        click.echo("=" * 60)
+        local_dst = os.path.join(output_dir, f"{name}.tar.gz")
+        print_fetch_plan(host, user, key, port, name, local_dst)
+
+        # Step 4
+        if not no_load:
+            click.echo("")
+            click.echo("=" * 60)
+            click.echo("STEP 4/4: Load images into local Docker")
+            click.echo("=" * 60)
+            print_load_plan(host, user, key, port, name, None, output_dir=output_dir)
+        else:
+            click.echo("")
+            click.echo("⏭️  Skipping docker load (--no-load)")
+
+        # Cleanup
+        if not no_cleanup:
+            click.echo("")
+            click.echo("=" * 60)
+            click.echo("Cleanup remote temp files")
+            click.echo("=" * 60)
+            print_cleanup_plan(host, user, key, port, name)
+        else:
+            click.echo("⏭️  Skipping remote cleanup (--no-cleanup)")
+        return
+
+    # Step 1: Parse + Pull
+    click.echo("=" * 60)
+    click.echo("STEP 1/4: Parse compose & pull images on remote")
+    click.echo("=" * 60)
+    compose_path = Path(compose_file)
+    images = parse_compose_images(compose_path)
+    if not images:
+        raise click.ClickException("No images found in compose file")
+    click.echo(f"📋 Found {len(images)} image(s):")
+    for img in images:
+        click.echo(f"   - {img}")
+
+    auth = registry_auth or None
+    do_pull(host, user, key, port, images, name, auth)
+
+    # Step 2: Save
+    click.echo("")
+    click.echo("=" * 60)
+    click.echo("STEP 2/4: Pack tar.gz on remote")
+    click.echo("=" * 60)
+    do_save(host, user, key, port, name)
+
+    # Step 3: Fetch
+    click.echo("")
+    click.echo("=" * 60)
+    click.echo("STEP 3/4: Download bundle to local")
+    click.echo("=" * 60)
+    os.makedirs(output_dir, exist_ok=True)
+    local_tarball = do_fetch(host, user, key, port, name, output_dir)
+
+    # Step 4: Load (optional)
+    if not no_load:
+        click.echo("")
+        click.echo("=" * 60)
+        click.echo("STEP 4/4: Load images into local Docker")
+        click.echo("=" * 60)
+        do_load(local_tarball)
+    else:
+        click.echo("⏭️  Skipping docker load (--no-load)")
+
+    # Cleanup
+    if not no_cleanup:
+        do_cleanup(host, user, key, port, name)
+    else:
+        click.echo("⏭️  Skipping remote cleanup (--no-cleanup)")
+
+    click.echo("")
+    click.echo("🎉 All done!")
+    click.echo(f"   Bundle: {local_tarball}")
+
+
+# ─────────────────────────────────────────────
+# 入口
+# ─────────────────────────────────────────────
+def main():
+    """Console script entry point (referenced by pyproject.toml)."""
+    cli()
+
+
+if __name__ == "__main__":
+    main()