multicloud-cli 0.1.0__py3-none-any.whl

multicloud_cli/cloud_account.py

@@ -0,0 +1,401 @@
+"""``mctl cloud-account``: connect an AWS account to an organization.
+
+These commands call the Multicloud API (``/api/v1/orgs/{slug}/cloud-accounts``) with an API key that
+holds the ``infra`` scope. The key comes from
+``mctl auth`` (or ``MULTICLOUD_API_KEY``); org and URL from ``--org``/``MULTICLOUD_ORG``/``MULTICLOUD_API_URL``
+or the saved config.
+The connect token is printed only by ``token`` (to stderr). ``apply`` hands it to tofu/terraform through the
+child environment variable ``TF_VAR_multicloud_connect_token``: never argv, never a file.
+"""
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import time
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+import click
+import requests  # noqa: F401  (tests patch cloud_account.requests.request)
+
+from . import api, exitcodes
+from .output import run
+from .duration import duration_option, interval_option
+from .orgopt import org_group
+
+TOKEN_VARIABLE = "multicloud_connect_token"
+TOKEN_ENV = "TF_VAR_" + TOKEN_VARIABLE
+TF_FILE = "multicloud.tf"
+PLAN_PLACEHOLDER = "plan-placeholder"
+_sleep = time.sleep  # tests patch this name
+
+
+def _stdin_is_tty() -> bool:
+    return sys.stdin.isatty()
+
+
+class CloudAccountError(exitcodes.CliError):
+    pass
+
+
+def call(method: str, org: Optional[str], tail: str = "", *, body: Optional[Dict[str, Any]] = None,
+         headers: Optional[Dict[str, str]] = None, accept=(200, 201, 202)) -> Dict[str, Any]:
+    """One API call. Returns the JSON body with ``_status`` added; raises on other statuses."""
+    try:
+        return api.call(method, org, "/cloud-accounts" + tail, body=body, headers=headers, accept=accept,
+                        pass_codes=("VERIFY_FAILED",))
+    except api.ApiError as ex:
+        raise CloudAccountError(str(ex), ex.exit_code)
+
+
+def describe_verify(answer: Dict[str, Any]) -> str:
+    """The text for a connect or verify answer, including the missing permissions of a 422."""
+    detail = answer.get("detail")
+    if isinstance(detail, dict) and detail.get("code") == "VERIFY_FAILED":
+        info = detail.get("details") or {}
+        lines = [f"Verification failed: {detail.get('message', '')}".rstrip()]
+        if info.get("reason"):
+            lines.append(f"Reason: {info['reason']}")
+        missing = info.get("missing") or []
+        if missing:
+            lines.append("Missing permissions:")
+            lines += [f"  {m}" for m in missing]
+        return "\n".join(lines)
+    status = answer.get("status", "unknown")
+    out = f"Cloud account {answer.get('id', '')}: {status}"
+    if answer.get("status_reason"):
+        out += f" ({answer['status_reason']})"
+    return out
+
+
+def terraform_outputs() -> Dict[str, Any]:
+    """``role_arn``, ``policy_version`` and ``module_version`` from ``tofu output -json`` in the cwd
+    (``terraform`` when ``tofu`` is not on the PATH, as for ``apply``)."""
+    try:
+        tool = next((t for t in ("tofu", "terraform") if shutil.which(t)), None)  # the order of apply
+        if tool is None:
+            raise CloudAccountError("Neither 'tofu' nor 'terraform' is on the PATH.")
+        done = subprocess.run([tool, "output", "-json"], capture_output=True, text=True, check=True)
+        outputs = json.loads(done.stdout)
+    except (OSError, subprocess.CalledProcessError, ValueError) as ex:
+        raise CloudAccountError(f"Could not read 'terraform output -json' in this directory: {ex}")
+    values = {}
+    for name in ("role_arn", "policy_version", "module_version"):
+        item = outputs.get(name)
+        if not isinstance(item, dict) or item.get("value") in (None, ""):
+            raise CloudAccountError(f"The Terraform output '{name}' is missing. Run terraform apply first.")
+        values[name] = item["value"]
+    try:
+        values["policy_version"] = int(values["policy_version"])
+    except (TypeError, ValueError):
+        raise CloudAccountError("The Terraform output 'policy_version' is not a number.")
+    values["module_version"] = str(values["module_version"])
+    return values
+
+
+def format_table(accounts, headers: bool = True) -> str:
+    rows = ([("ID", "CLOUD", "STATUS", "ACCOUNT")] if headers else []) + [
+        (str(a.get("id")), str(a.get("cloud")), str(a.get("status")), str(a.get("expected_native_id")))
+        for a in accounts]
+    if not rows:
+        return ""
+    widths = [max(len(r[i]) for r in rows) for i in range(4)]
+    return "\n".join("  ".join(c.ljust(w) for c, w in zip(r, widths)).rstrip() for r in rows)
+
+
+def _dump(data: Dict[str, Any]) -> None:
+    data = dict(data)
+    data.pop("_status", None)
+    click.echo(json.dumps(data, indent=2, sort_keys=True))
+
+
+json_option = click.option("--json", "as_json", is_flag=True, help="Print the raw JSON")
+
+
+def _tf_file_exists():
+    click.echo(f"Error: {TF_FILE} exists in this directory. Move it, or run again with --force to "
+               f"overwrite it. A new file holds a new external id, and 'terraform apply' would cut "
+               f"off a connected account.", err=True)
+    sys.exit(1)
+
+
+@click.group(name="cloud-account", cls=org_group("cloud_account_org"))
+@click.option("--org", default=None, help="Organization slug (default: MULTICLOUD_ORG)")
+@click.pass_context
+def cloud_account(ctx, org):
+    """Connect a customer AWS account (sign in first: mctl auth login)."""
+    ctx.ensure_object(dict)
+    ctx.obj["cloud_account_org"] = org
+
+
+def _run(ctx, fn):
+    return run(ctx.obj.get("cloud_account_org"), fn, (CloudAccountError,))
+
+
+@cloud_account.command()
+@click.option("--cloud", required=True, type=click.Choice(["AWS"], case_sensitive=False))
+@click.option("--account", required=True, help="The 12-digit AWS account id")
+@click.option("--region", "regions", multiple=True, help="Region to allow; repeat for several")
+@click.option("--force", is_flag=True, help="Overwrite an existing multicloud.tf")
+@json_option
+@click.pass_context
+def create(ctx, cloud, account, regions, force, as_json):
+    """Register an account and write multicloud.tf. No token is printed.
+
+    An existing multicloud.tf is kept: a new external id in it would cut off a connected account."""
+    if Path(TF_FILE).exists() and not force:
+        _tf_file_exists()
+    body = {"cloud": cloud.upper(), "expected_native_id": account}
+    if regions:
+        body["regions"] = list(regions)
+    made = _run(ctx, lambda org: call("POST", org, body=body))
+    try:
+        with open(TF_FILE, "w" if force else "x") as f:
+            f.write(made["terraform"])
+    except FileExistsError:  # created after the check above
+        _tf_file_exists()
+    acct_id = made["account"]["id"]
+    if as_json:  # the created account; the Terraform file is in multicloud.tf
+        _dump(made["account"])
+    say = lambda text: click.echo(text, err=as_json)  # noqa: E731
+    say(f"Cloud account {acct_id} created for AWS account {account}. Wrote {TF_FILE}.")
+    say(f"Next: mctl cloud-account apply {acct_id}")
+    say(f"By hand: mctl cloud-account token {acct_id}, then tofu apply (or terraform apply).")
+
+
+@cloud_account.command()
+@click.argument("account_id", type=int)
+@click.pass_context
+def token(ctx, account_id):
+    """Issue a new connect token (the old one stops working). The token goes to stderr only."""
+    made = _run(ctx, lambda org: call("POST", org, f"/{account_id}/connect-token"))
+    click.echo(f"export {TOKEN_ENV}={made['connect_token']}", err=True)
+    click.echo(f"New connect token for cloud account {account_id}, valid until "
+               f"{made.get('connect_token_expires_at')}. The old token no longer works. "
+               f"Run the export line in this shell, then tofu apply.")
+
+
+@cloud_account.command(name="list")
+@json_option
+@click.option("-q", "--quiet", is_flag=True, help="Print only the IDs, one per line")
+@click.option("--no-headers", is_flag=True, help="Leave the header line out of the table")
+@click.pass_context
+def list_(ctx, as_json, quiet, no_headers):
+    """List the cloud accounts of the organization."""
+    data = _run(ctx, lambda org: call("GET", org))
+    if as_json:
+        return _dump(data)
+    if quiet:
+        for a in data.get("cloud_accounts", []):
+            click.echo(a.get("id"))
+        return
+    click.echo(format_table(data.get("cloud_accounts", []), not no_headers))
+
+
+def _readable(data: Dict[str, Any]) -> str:
+    status = str(data.get("status", "unknown"))
+    if status == "verified":
+        status += " (Ready)"
+    regions = data.get("regions")
+    lines = [
+        f"Cloud account {data.get('id')} ({data.get('cloud')})",
+        f"Status: {status}",
+        ("Account", data.get("native_id") or data.get("expected_native_id")),
+        ("Regions", ", ".join(regions) if regions else "all"),
+        ("Role", data.get("role_arn")),
+        ("Policy version", data.get("policy_version")),
+        ("Module version", data.get("module_version")),
+        ("Connected", data.get("connected_on")),
+        ("Verified", data.get("verified_on")),
+        ("Last check", data.get("last_probe_on")),
+        ("Reason", data.get("status_reason")),
+    ]
+    return "\n".join(l if isinstance(l, str) else f"{l[0]}: {l[1]}"
+                     for l in lines if isinstance(l, str) or l[1] not in (None, ""))
+
+
+@cloud_account.command()
+@click.argument("account_id", type=int)
+@json_option
+@click.pass_context
+def show(ctx, account_id, as_json):
+    """Show one cloud account."""
+    data = _run(ctx, lambda org: call("GET", org, f"/{account_id}"))
+    data.pop("_status", None)
+    if as_json:
+        click.echo(json.dumps(data, indent=2, sort_keys=True))
+    else:
+        click.echo(_readable(data))
+
+
+def _verify_loop(org, account_id: int, wait: bool, timeout: int, interval: int, as_json: bool = False) -> int:
+    """Verify; with ``wait`` repeat while the answer is 202. Returns the exit code.
+
+    Notes about waiting go to stderr. With ``as_json`` the last answer is the only thing on stdout."""
+    say = lambda text, err=as_json: click.echo(text, err=err)  # noqa: E731
+    note = lambda text: click.echo(text, err=True)  # noqa: E731
+    waited = 0
+    while True:
+        data = call("POST", org, f"/{account_id}/verify")
+        status = data.pop("_status", 200)
+        if status == 422:
+            if as_json:
+                _dump(data)
+            say(describe_verify(data))
+            say(f"Fix: apply the module again (mctl cloud-account apply {account_id}), then verify.")
+            return exitcodes.ERROR
+        if status != 202 and data.get("status") != "verified":
+            if as_json:
+                _dump(data)
+            say(f"Not ready: {describe_verify(data)}")
+            return exitcodes.ERROR
+        if status != 202:
+            if as_json:
+                _dump(data)
+            native = data.get("native_id") or data.get("expected_native_id")
+            say(f"Ready: {data.get('cloud', 'AWS')} account {native} is connected "
+                f"(policy version {data.get('policy_version')}).")
+            return exitcodes.OK
+        note(f"Pending: the role is not usable yet ({data.get('status_reason') or 'no reason given'}). "
+             f"AWS can take up to 15 minutes to apply IAM changes.")
+        if not wait or waited >= timeout:
+            if as_json:
+                _dump(data)
+            if wait:
+                note(f"Still pending after {waited}s. Run again later: "
+                     f"mctl cloud-account verify {account_id} --wait")
+            return exitcodes.PENDING
+        step = max(1, min(interval, timeout - waited))
+        note(f"Checking again in {step}s ...")
+        _sleep(step)
+        waited += step
+
+
+@cloud_account.command()
+@click.argument("account_id", type=int)
+@click.option("-w", "--wait", is_flag=True, help="Check again while the role is not usable yet")
+@click.option("-t", "--timeout", default="15m", show_default=True, callback=duration_option,
+              help="How long to wait with --wait (90, 90s, 15m, 1h)")
+@click.option("--interval", default="30s", show_default=True, callback=interval_option,
+              help="Time between checks with --wait (90, 90s, 15m, 1h)")
+@json_option
+@click.pass_context
+def verify(ctx, account_id, wait, timeout, interval, as_json):
+    """Probe the account again. Exit 1 when verification fails, 5 while pending."""
+    code = _run(ctx, lambda org: _verify_loop(org, account_id, wait, timeout, interval, as_json))
+    sys.exit(code)
+
+
+def _find_tool(requested: Optional[str]) -> str:
+    if requested:
+        if not shutil.which(requested):
+            raise CloudAccountError(f"'{requested}' is not on the PATH.")
+        return requested
+    tool = next((t for t in ("tofu", "terraform") if shutil.which(t)), None)
+    if tool is None:
+        raise CloudAccountError("Neither 'tofu' nor 'terraform' is on the PATH. Install OpenTofu or Terraform.")
+    return tool
+
+
+def _tool_run(tool: str, args, cwd: str, env: Dict[str, str]) -> int:
+    """Run the tool with inherited stdout/stderr. The environment carries the only copy of any token."""
+    try:
+        return subprocess.run([tool, *args], cwd=cwd, env=env).returncode
+    except OSError as ex:
+        raise CloudAccountError(f"Could not run {tool}: {ex}")
+
+
+@cloud_account.command()
+@click.argument("account_id", type=int)
+@click.option("--dir", "directory", default=".", type=click.Path(file_okay=False), help="Folder with multicloud.tf")
+@click.option("--tool", type=click.Choice(["tofu", "terraform"]), default=None, help="Default: tofu, then terraform")
+@click.option("--plan-only", is_flag=True, help="Show the plan and stop; no token is issued")
+@click.option("-y", "--yes", is_flag=True, help="Apply without asking")
+@click.option("-t", "--timeout", default="15m", show_default=True, callback=duration_option,
+              help="How long to wait for the account to verify (90, 90s, 15m, 1h)")
+@click.option("--interval", default="30s", show_default=True, callback=interval_option,
+              help="Time between checks (90, 90s, 15m, 1h)")
+@click.pass_context
+def apply(ctx, account_id, directory, tool, plan_only, yes, timeout, interval):
+    """Plan, apply multicloud.tf with a fresh connect token, then wait until the account verifies.
+
+    The token reaches tofu/terraform only through the environment of that one process."""
+    tf = Path(directory) / TF_FILE
+    if not tf.is_file():
+        click.echo(f"Error: {tf} does not exist. Run: mctl cloud-account create", err=True)
+        sys.exit(1)
+    found = re.search(r"account_row_id\s*=\s*(\d+)", tf.read_text())
+    if found and int(found.group(1)) != account_id:
+        click.echo(f"Error: {TF_FILE} in {directory} is for cloud account {found.group(1)}, not {account_id}.",
+                   err=True)
+        sys.exit(1)
+    tool = _run(ctx, lambda org: _find_tool(tool))
+    # Terraform, its providers and the module's curl see this environment: no API key, no old token,
+    # and no TF_LOG (a debug log could record the token).
+    base_env = {k: v for k, v in os.environ.items()
+                if k not in (TOKEN_ENV, "MULTICLOUD_API_KEY") and not k.startswith("TF_LOG")}
+
+    def step(args, env, what):
+        code = _run(ctx, lambda org: _tool_run(tool, args, directory, env))
+        if code != 0:
+            click.echo(f"Error: {tool} {what} failed (exit {code}).", err=True)
+            sys.exit(1)
+
+    step(["init", "-input=false"], base_env, "init")
+    click.echo("The plan uses a placeholder connect token. The real token is issued only for the apply.")
+    step(["plan", "-input=false"], {**base_env, TOKEN_ENV: PLAN_PLACEHOLDER}, "plan")
+    if plan_only:
+        click.echo(f"Plan only: no token issued. To apply: mctl cloud-account apply {account_id} --yes")
+        return
+    if not yes:
+        if not _stdin_is_tty():
+            click.echo("Error: Refusing to apply without confirmation. Review the plan, then run again "
+                       "with --yes.", err=True)
+            sys.exit(1)
+        if not click.confirm("Apply this plan to your AWS account?", default=False):
+            click.echo("Nothing applied.", err=True)
+            sys.exit(exitcodes.ERROR)
+    made = _run(ctx, lambda org: call("POST", org, f"/{account_id}/connect-token"))
+    code = _run(ctx, lambda org: _tool_run(
+        tool, ["apply", "-input=false", "-auto-approve"], directory,
+        {**base_env, TOKEN_ENV: made["connect_token"]}))
+    if code != 0:
+        click.echo(f"Error: {tool} apply failed (exit {code}).", err=True)
+        try:
+            state = _run(ctx, lambda org: call("GET", org, f"/{account_id}"))
+            state.pop("_status", None)
+            click.echo(f"Account status after the failed apply: {describe_verify(state)}", err=True)
+        except SystemExit:
+            pass
+        sys.exit(1)
+    sys.exit(_run(ctx, lambda org: _verify_loop(org, account_id, True, timeout, interval)))
+
+
+@cloud_account.command()
+@click.argument("account_id", type=int)
+@click.option("--from-terraform-output", "from_tf", is_flag=True,
+              help="Read role_arn, policy_version and module_version from 'terraform output -json' "
+                   "(the only input; this is the default)")
+@click.pass_context
+def connect(ctx, account_id, from_tf):
+    """Report the role Terraform created. The token comes from TF_VAR_multicloud_connect_token."""
+    token = os.environ.get(TOKEN_ENV)
+    if not token:
+        click.echo(f"Error: set {TOKEN_ENV} to a connect token: run 'mctl cloud-account token {account_id}'.", err=True)
+        sys.exit(1)
+
+    def post(org):
+        return call("POST", org, f"/{account_id}/connect", body=terraform_outputs(),
+                    headers={"X-Multicloud-Connect-Token": token})
+    _finish(_run(ctx, post))
+
+
+def _finish(data: Dict[str, Any]) -> None:
+    status = data.pop("_status", 200)
+    click.echo(describe_verify(data))
+    if status == 422:
+        sys.exit(1)
+    if status == 202:
+        sys.exit(exitcodes.PENDING)

multicloud_cli/config.py

@@ -0,0 +1,114 @@
+"""Settings: the config directory, ``cli.json`` (org and API URL) and their precedence."""
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any, Dict, Optional
+from urllib.parse import urlparse
+
+import click
+
+DEFAULT_API_URL = "https://api.multicloud.io"
+DEFAULT_ISSUER = "https://auth.multicloud.io/realms/multicloud"
+_LOCAL_HOSTS = ("localhost", "127.0.0.1", "::1")
+
+
+class ConfigError(Exception):
+    pass
+
+
+def config_dir() -> Path:
+    base = os.environ.get("XDG_CONFIG_HOME")
+    root = Path(base) if base else Path.home() / ".config"
+    return root / "multicloud"
+
+
+_warned = set()
+
+
+def warn_once(text: str) -> None:
+    """A warning on stderr, once per process: the mode checks run on every refresh."""
+    if text not in _warned:
+        _warned.add(text)
+        print(f"Warning: {text}", file=sys.stderr)
+
+
+def ensure_private_dir(strict: bool = False) -> Path:
+    """Create the config directory with access for the user only, and narrow an existing one to 0700.
+    ``strict`` (the credentials file) raises when the mode cannot be set; otherwise a warning goes to stderr,
+    because the directory may be a link or belong to another account, and the lock and settings hold no secret."""
+    directory = config_dir()
+    directory.mkdir(parents=True, exist_ok=True, mode=0o700)
+    try:
+        os.chmod(directory, 0o700)
+    except OSError as ex:
+        if strict:
+            raise
+        warn_once(f"cannot set {directory} to 0700 ({type(ex).__name__}).")
+    return directory
+
+
+def config_file() -> Path:
+    return config_dir() / "cli.json"
+
+
+def load() -> Dict[str, Any]:
+    try:
+        data = json.loads(config_file().read_text())
+    except (OSError, ValueError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def save(org: Optional[str] = None, api_url: Optional[str] = None, issuer: Optional[str] = None) -> None:
+    data = load()
+    if org:
+        data["org"] = org
+    if api_url:
+        data["api_url"] = api_url
+    if issuer:
+        data["issuer"] = issuer
+    ensure_private_dir()
+    config_file().write_text(json.dumps(data, indent=2, sort_keys=True) + "\n")
+
+
+def _root_option(key: str) -> Optional[str]:
+    """The value of a root option (``mctl --org acme ...``) in the running command, or None."""
+    ctx = click.get_current_context(silent=True)
+    obj = ctx.find_root().obj if ctx is not None else None
+    return obj.get(key) if isinstance(obj, dict) else None
+
+
+def get_org(option: Optional[str] = None) -> Optional[str]:
+    """--org after the group or subcommand (the most specific wins), then --org before the command,
+    then MULTICLOUD_ORG, then the config file."""
+    return option or _root_option("root_org") or os.environ.get("MULTICLOUD_ORG") or load().get("org") or None
+
+
+def org_is_explicit(option: Optional[str] = None) -> bool:
+    """Whether the organization came from --org or MULTICLOUD_ORG, not from the saved config."""
+    return bool(option or _root_option("root_org") or os.environ.get("MULTICLOUD_ORG"))
+
+
+def get_api_url() -> str:
+    """--api-url before the command, then MULTICLOUD_API_URL, then the config file, then the public API."""
+    url = (_root_option("root_api_url") or os.environ.get("MULTICLOUD_API_URL") or load().get("api_url")
+           or DEFAULT_API_URL)
+    return check_api_url(url)
+
+
+def get_issuer() -> str:
+    """MULTICLOUD_ISSUER_URL, then the config file, then the public Keycloak realm."""
+    url = os.environ.get("MULTICLOUD_ISSUER_URL") or load().get("issuer") or DEFAULT_ISSUER
+    return check_api_url(url, "issuer URL")
+
+
+def check_api_url(url: str, what: str = "API URL") -> str:
+    """The key or token travels in a header or a form, so the URL must be https (plain http only to this machine)."""
+    url = url.rstrip("/")
+    parsed = urlparse(url)
+    if parsed.scheme == "https" and parsed.hostname:
+        return url
+    if parsed.scheme == "http" and parsed.hostname in _LOCAL_HOSTS:
+        return url
+    raise ConfigError(f"The {what} must start with https:// (got {url!r}).")

multicloud_cli/duration.py

@@ -0,0 +1,30 @@
+"""Durations for ``--timeout`` and ``--interval``: ``90``, ``90s``, ``15m`` or ``1h``."""
+import re
+
+import click
+
+_DURATION = re.compile(r"^\s*(\d+)\s*([smh]?)\s*$")
+_UNITS = {"s": 1, "m": 60, "h": 3600}
+
+
+def parse_duration(text: str) -> int:
+    """``90``, ``90s``, ``15m`` or ``1h`` in seconds."""
+    m = _DURATION.match(text or "")
+    if not m:
+        raise ValueError(f"Invalid duration '{text}'. Use a number with s, m or h, for example 15m.")
+    return int(m.group(1)) * _UNITS[m.group(2) or "s"]
+
+
+def duration_option(ctx, param, value):
+    try:
+        return parse_duration(value)
+    except ValueError as ex:
+        raise click.BadParameter(str(ex))
+
+
+def interval_option(ctx, param, value):
+    """Like ``duration_option``, and at least one second."""
+    seconds = duration_option(ctx, param, value)
+    if seconds < 1:
+        raise click.BadParameter("Must be at least 1 second.")
+    return seconds

multicloud_cli/exitcodes.py

@@ -0,0 +1,30 @@
+"""The exit codes of ``mctl``: one map, used by every command (see docs/reference.md).
+
+0 success. 1 error, refusal, or a declined prompt. 2 usage error (click's own). 3 not signed in, or the API
+answered 401 or 403. 4 not found (API 404, unknown pool name). 5 not done yet: still pending, or a --wait
+ran out of time. 6 gone: the pool is deleting or deleted. 130 Ctrl-C."""
+from typing import Optional
+
+OK, ERROR, USAGE, AUTH, NOT_FOUND, PENDING, GONE, INTERRUPTED = 0, 1, 2, 3, 4, 5, 6, 130
+BROKEN_PIPE = 141  # 128 + SIGPIPE, as a shell shows a process that wrote into a closed pipe
+
+
+def for_status(status: Optional[int]) -> int:
+    """The exit code for an HTTP status of the API (1 when there was none or it has no code of its own)."""
+    if status in (401, 403):
+        return AUTH
+    if status == 404:
+        return NOT_FOUND
+    return ERROR
+
+
+class CliError(Exception):
+    """An error a command reports as ``Error: <text>`` and ends with ``exit_code``."""
+
+    def __init__(self, message: str, exit_code: int = ERROR):
+        super().__init__(message)
+        self.exit_code = exit_code
+
+
+def of(ex: Exception) -> int:
+    return getattr(ex, "exit_code", ERROR)

multicloud_cli/main.py

@@ -0,0 +1,90 @@
+"""``mctl``: the customer command line."""
+import os
+import sys
+
+import click
+
+from . import __version__, exitcodes
+from .auth import auth
+from .catalog import catalog
+from .cloud_account import cloud_account
+from .pool import pool
+
+
+def _broken_pipe() -> int:
+    """The reader of stdout left (``mctl pool list | head -1``). Point stdout at /dev/null, so the flush at exit
+    does not print a traceback, and give 141 (128 + SIGPIPE), the code a shell shows for this."""
+    try:
+        os.dup2(os.open(os.devnull, os.O_WRONLY), sys.stdout.fileno())
+    except (OSError, ValueError, AttributeError):
+        pass
+    return exitcodes.BROKEN_PIPE
+
+
+class Root(click.Group):
+    def invoke(self, ctx):
+        # click itself turns EPIPE into exit 1, so this catches it first.
+        try:
+            return super().invoke(ctx)
+        except BrokenPipeError:
+            sys.exit(_broken_pipe())
+
+
+@click.group(cls=Root, context_settings={"help_option_names": ["-h", "--help"]})
+@click.version_option(__version__, prog_name="mctl")
+@click.option("--org", default=None, help="Organization slug (env: MULTICLOUD_ORG)")
+@click.option("--api-url", default=None, help="API URL (env: MULTICLOUD_API_URL)")
+@click.pass_context
+def mctl(ctx, org, api_url):
+    """Sign in to Multicloud, connect your cloud account and manage CI pools and find servers.
+
+    --org and --api-url work here and after a command. The one after the command wins, then the one
+    here, then the environment variable, then the saved setting."""
+    ctx.ensure_object(dict)
+    ctx.obj["root_org"] = org
+    ctx.obj["root_api_url"] = api_url
+
+
+mctl.add_command(auth)
+mctl.add_command(cloud_account)
+mctl.add_command(pool)
+mctl.add_command(catalog)
+
+
+def _run() -> int:
+    # click's own error handling would make Ctrl-C "Aborted!" with exit 1, so it runs here.
+    try:
+        code = mctl(standalone_mode=False)
+    except click.exceptions.Abort as ex:
+        if isinstance(ex.__cause__, KeyboardInterrupt):
+            return exitcodes.INTERRUPTED
+        click.echo("Aborted!", err=True)
+        return exitcodes.ERROR
+    except click.ClickException as ex:
+        ex.show()
+        return ex.exit_code
+    except KeyboardInterrupt:
+        return exitcodes.INTERRUPTED
+    except BrokenPipeError:
+        return _broken_pipe()
+    except SystemExit as ex:
+        if ex.code is None:
+            return exitcodes.OK
+        if isinstance(ex.code, int):
+            return ex.code
+        click.echo(str(ex.code), err=True)
+        return exitcodes.ERROR
+    return code if isinstance(code, int) else exitcodes.OK
+
+
+def main():
+    code = _run()
+    try:
+        sys.stdout.flush()  # a closed pipe shows here, when the output was small and buffered
+    except BrokenPipeError:
+        code = _broken_pipe()
+    sys.exit(code)
+
+
+if __name__ == "__main__":
+    main()