devlift-cli 0.1.0__py3-none-any.whl

devlift_cli/app.py

@@ -0,0 +1,163 @@
+"""Command tree root and process entry point.
+
+    devlift [--profile P] [-o table|json|yaml] [--yes] [--no-input]
+            [--endpoint-url URL] [--debug] <group> <operation> [flags]
+
+Every command receives an Invocation (profile, output format, confirmation
+policy, API client) through ctx.obj, and fails by raising CliError, which
+main() prints once and turns into the documented exit code.
+"""
+
+from __future__ import annotations
+
+import sys
+
+import typer
+from rich.markup import escape
+
+from devlift_cli import __version__
+from devlift_cli.commands import approval as approval_cmds
+from devlift_cli.commands import auth as auth_cmds
+from devlift_cli.commands import catalog as catalog_cmds
+from devlift_cli.commands import clusters as clusters_cmds
+from devlift_cli.commands import deployment as deployment_cmds
+from devlift_cli.commands import dynamodb as dynamodb_cmds
+from devlift_cli.commands import eks as eks_cmds
+from devlift_cli.commands import kong as kong_cmds
+from devlift_cli.commands import languages as languages_cmds
+from devlift_cli.commands import manual as manual_cmds
+from devlift_cli.commands import repositories as repositories_cmds
+from devlift_cli.commands import request as request_cmds
+from devlift_cli.commands import s3 as s3_cmds
+from devlift_cli.commands import sqs as sqs_cmds
+from devlift_cli.config import load_profile
+from devlift_cli.context import Invocation
+from devlift_cli.errors import CliError
+from devlift_cli.render import output
+
+app = typer.Typer(
+    name="devlift",
+    help="DevLift from the terminal: create, change, review and deploy your services and resources.",
+    epilog="Full manual: devlift man (or devlift manual \\[topic]). Start with: devlift configure, devlift login, devlift whoami.",
+    no_args_is_help=True,
+    pretty_exceptions_enable=False,
+    rich_markup_mode="rich",
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+
+
+def _version(value: bool):
+    if value:
+        print(f"devlift {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def root(
+    ctx: typer.Context,
+    profile: str | None = typer.Option(None, "--profile", envvar="DEVLIFT_PROFILE", help="Profile from `devlift configure`."),
+    out: str | None = typer.Option(None, "--output", "-o", help="table | json | yaml (json when piped)."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Answer yes to confirmations."),
+    no_input: bool = typer.Option(False, "--no-input", help="Never prompt; fail when input is missing."),
+    endpoint_url: str | None = typer.Option(None, "--endpoint-url", envvar="DEVLIFT_BASE_URL", help="Override the backend URL for this call."),
+    debug: bool = typer.Option(False, "--debug", help="Log every HTTP call to stderr."),
+    version: bool = typer.Option(False, "--version", "-V", callback=_version, is_eager=True, help="Print the version and exit."),
+):
+    if out and out not in output.FORMATS:
+        raise typer.BadParameter(f"--output must be one of {', '.join(output.FORMATS)}")
+    prof = load_profile(profile, base_url_override=endpoint_url)
+    ctx.obj = Invocation(
+        profile=prof,
+        output=output.resolve_format(out, prof.output),
+        yes=yes,
+        no_input=no_input,
+        debug=debug,
+    )
+    ctx.call_on_close(ctx.obj.close)
+
+
+# ── auth ─────────────────────────────────────────────────────────────────
+app.command("login")(auth_cmds.login)
+app.command("logout")(auth_cmds.logout)
+app.command("whoami")(auth_cmds.whoami)
+app.command("configure")(auth_cmds.configure)
+app.add_typer(auth_cmds.profile_app, name="profile")
+app.command("manual")(manual_cmds.manual)
+# `devlift man` — the name every terminal user reaches for first. Hidden from
+# the command list so the manual appears once there, under its full name.
+app.command("man", hidden=True)(manual_cmds.manual)
+
+# ── catalog ──────────────────────────────────────────────────────────────
+app.add_typer(catalog_cmds.applications_app, name="applications")
+app.add_typer(catalog_cmds.environments_app, name="environments")
+app.add_typer(catalog_cmds.regions_app, name="regions")
+app.add_typer(catalog_cmds.resource_types_app, name="resource-types")
+app.add_typer(catalog_cmds.resource_groups_app, name="resource-groups")
+app.add_typer(catalog_cmds.services_app, name="services")
+app.add_typer(repositories_cmds.repositories_app, name="repositories")
+app.add_typer(languages_cmds.languages_app, name="languages")
+app.add_typer(clusters_cmds.clusters_app, name="clusters")
+
+# ── resources ────────────────────────────────────────────────────────────
+app.add_typer(s3_cmds.s3_app, name="s3")
+app.add_typer(sqs_cmds.sqs_app, name="sqs")
+app.add_typer(dynamodb_cmds.dynamodb_app, name="dynamodb")
+app.add_typer(eks_cmds.eks_app, name="eks")
+app.add_typer(kong_cmds.kong_app, name="kong")
+app.add_typer(request_cmds.request_app, name="request")
+app.add_typer(approval_cmds.approval_app, name="approval")
+app.add_typer(deployment_cmds.deployment_app, name="deployment")
+app.add_typer(deployment_cmds.queue_app, name="queue")
+
+
+_GLOBAL_WITH_VALUE = {"--profile", "--output", "-o", "--endpoint-url"}
+_GLOBAL_FLAGS = {"--yes", "-y", "--no-input", "--debug"}
+
+
+def _hoist_global_options(argv: list[str]) -> list[str]:
+    """Let global options sit anywhere, like `aws s3 ls -o json`.
+
+    Click only reads group options before the subcommand name, so anything
+    from the global set found later in argv is moved to the front. Stops at
+    `--` and leaves everything else in order.
+    """
+    front: list[str] = []
+    rest: list[str] = []
+    i = 0
+    while i < len(argv):
+        arg = argv[i]
+        if arg == "--":
+            rest.extend(argv[i:])
+            break
+        name, eq, _ = arg.partition("=")
+        if name in _GLOBAL_WITH_VALUE:
+            if eq:
+                front.append(arg)
+            elif i + 1 < len(argv):
+                front.extend(argv[i : i + 2])
+                i += 1
+            else:
+                rest.append(arg)
+        elif name in _GLOBAL_FLAGS and not eq:
+            front.append(arg)
+        else:
+            rest.append(arg)
+        i += 1
+    return front + rest
+
+
+def main() -> None:
+    try:
+        app(args=_hoist_global_options(sys.argv[1:]))
+    except CliError as exc:
+        output.err_console.print(f"[red]error:[/red] {escape(exc.message)}")
+        if exc.hint:
+            output.err_console.print(f"[dim]{escape(exc.hint)}[/dim]")
+        sys.exit(exc.code)
+    except KeyboardInterrupt:
+        output.err_console.print("\n[dim]Interrupted.[/dim]")
+        sys.exit(130)
+
+
+if __name__ == "__main__":
+    main()

devlift_cli/auth/oauth.py

@@ -0,0 +1,270 @@
+"""Browser login against DevLift's OAuth 2.1 server.
+
+The server publishes RFC 8414 metadata at
+`{base_url}/.well-known/oauth-authorization-server/devlift-mcp`. The flow is
+the standard native-app one: dynamic client registration (RFC 7591) with a
+loopback redirect, PKCE S256, a short-lived local HTTP server that catches
+the redirect, then the code exchange. Refresh tokens rotate on every use.
+
+The access token is an opaque string that obs_tool's REST API accepts as a
+bearer token, so this is the only login the CLI needs.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import secrets
+import socket
+import threading
+import time
+import webbrowser
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from urllib.parse import parse_qs, urlencode, urlparse
+
+import httpx
+
+from devlift_cli.auth.storage import Credentials
+from devlift_cli.config import OAUTH_METADATA_PATH
+from devlift_cli.errors import AuthError, CliError
+
+CLIENT_NAME = "devlift-cli"
+LOGIN_TIMEOUT_SECONDS = 300
+_TIMEOUT = httpx.Timeout(30.0, connect=10.0)
+
+_SUCCESS_PAGE = """<!doctype html><html><head><meta charset="utf-8"><title>DevLift CLI</title>
+<style>body{font-family:system-ui,sans-serif;display:flex;align-items:center;justify-content:center;height:100vh;margin:0;background:#0f172a;color:#e2e8f0}
+main{text-align:center}h1{font-weight:600}p{color:#94a3b8}</style></head>
+<body><main><h1>Signed in to DevLift</h1><p>You can close this tab and return to the terminal.</p></main></body></html>"""
+
+_FAILURE_PAGE = """<!doctype html><html><head><meta charset="utf-8"><title>DevLift CLI</title>
+<style>body{font-family:system-ui,sans-serif;display:flex;align-items:center;justify-content:center;height:100vh;margin:0;background:#0f172a;color:#e2e8f0}
+main{text-align:center}h1{font-weight:600;color:#f87171}p{color:#94a3b8}</style></head>
+<body><main><h1>Sign-in failed</h1><p>%s</p></main></body></html>"""
+
+
+def _pkce_pair() -> tuple[str, str]:
+    verifier = secrets.token_urlsafe(64)
+    digest = hashlib.sha256(verifier.encode("ascii")).digest()
+    challenge = base64.urlsafe_b64encode(digest).rstrip(b"=").decode("ascii")
+    return verifier, challenge
+
+
+def _free_port() -> int:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("127.0.0.1", 0))
+        return s.getsockname()[1]
+
+
+def _port_is_free(port: int) -> bool:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        try:
+            s.bind(("127.0.0.1", port))
+            return True
+        except OSError:
+            return False
+
+
+def _redirect_uri(port: int) -> str:
+    return f"http://127.0.0.1:{port}/callback"
+
+
+def discover(base_url: str) -> dict:
+    url = base_url.rstrip("/") + OAUTH_METADATA_PATH
+    try:
+        resp = httpx.get(url, timeout=_TIMEOUT)
+        resp.raise_for_status()
+        return resp.json()
+    except httpx.HTTPError as exc:
+        raise CliError(
+            f"Could not read the sign-in configuration from {url}: {exc}",
+            hint="Is the DevLift backend running at that address? Use --endpoint-url or `devlift configure`.",
+        ) from exc
+
+
+def register_client(metadata: dict, port: int) -> tuple[str, str | None]:
+    endpoint = metadata.get("registration_endpoint")
+    if not endpoint:
+        raise CliError("The DevLift server does not offer client registration.")
+    body = {
+        "client_name": CLIENT_NAME,
+        "redirect_uris": [_redirect_uri(port)],
+        "grant_types": ["authorization_code", "refresh_token"],
+        "response_types": ["code"],
+        "token_endpoint_auth_method": "none",
+    }
+    resp = httpx.post(endpoint, json=body, timeout=_TIMEOUT)
+    if resp.status_code >= 300:
+        raise CliError(f"Client registration failed ({resp.status_code}): {resp.text[:300]}")
+    data = resp.json()
+    return data["client_id"], data.get("client_secret")
+
+
+class _CallbackHandler(BaseHTTPRequestHandler):
+    """Catches exactly one redirect and stores its query on the server object."""
+
+    def do_GET(self):  # noqa: N802
+        parsed = urlparse(self.path)
+        if parsed.path != "/callback":
+            self.send_response(404)
+            self.end_headers()
+            return
+        query = {k: v[0] for k, v in parse_qs(parsed.query).items()}
+        self.server.result = query  # type: ignore[attr-defined]
+        if "error" in query:
+            body = _FAILURE_PAGE % (query.get("error_description") or query["error"])
+        else:
+            body = _SUCCESS_PAGE
+        payload = body.encode("utf-8")
+        self.send_response(200)
+        self.send_header("Content-Type", "text/html; charset=utf-8")
+        self.send_header("Content-Length", str(len(payload)))
+        self.end_headers()
+        self.wfile.write(payload)
+
+    def log_message(self, *_args):  # silence the default stderr access log
+        return
+
+
+def _wait_for_callback(port: int, timeout: float) -> dict:
+    server = HTTPServer(("127.0.0.1", port), _CallbackHandler)
+    server.result = None  # type: ignore[attr-defined]
+    server.timeout = 1.0
+    deadline = time.time() + timeout
+    thread = threading.Thread(target=_serve_until, args=(server, deadline), daemon=True)
+    thread.start()
+    thread.join()
+    server.server_close()
+    result = server.result  # type: ignore[attr-defined]
+    if result is None:
+        raise AuthError("Timed out waiting for the browser sign-in.", hint="Run `devlift login` again.")
+    return result
+
+
+def _serve_until(server: HTTPServer, deadline: float) -> None:
+    while server.result is None and time.time() < deadline:  # type: ignore[attr-defined]
+        server.handle_request()
+
+
+def _exchange(metadata: dict, form: dict) -> dict:
+    resp = httpx.post(metadata["token_endpoint"], data=form, timeout=_TIMEOUT)
+    if resp.status_code >= 300:
+        try:
+            detail = resp.json()
+            message = detail.get("error_description") or detail.get("error") or resp.text
+        except ValueError:
+            message = resp.text
+        raise AuthError(f"Token request failed ({resp.status_code}): {str(message)[:300]}", hint="Run `devlift login`.")
+    return resp.json()
+
+
+def _to_credentials(base_url: str, metadata: dict, client_id: str, client_secret: str | None, port: int, token: dict) -> Credentials:
+    expires_in = float(token.get("expires_in") or 3600)
+    scope = token.get("scope") or ""
+    return Credentials(
+        issuer=metadata["issuer"],
+        client_id=client_id,
+        base_url=base_url.rstrip("/"),
+        client_secret=client_secret,
+        redirect_port=port,
+        access_token=token["access_token"],
+        refresh_token=token.get("refresh_token"),
+        expires_at=time.time() + expires_in,
+        scopes=scope.split() if scope else [],
+    )
+
+
+def login(base_url: str, existing: Credentials | None = None, open_browser: bool = True, echo=print) -> Credentials:
+    """Run the whole browser flow and return fresh credentials.
+
+    Reuses the stored client registration when its redirect port is still
+    free, so the server sees one client per machine rather than one per
+    login; otherwise registers a new one.
+    """
+    metadata = discover(base_url)
+
+    client_id = client_secret = None
+    port = 0
+    if existing and existing.issuer == metadata.get("issuer") and existing.redirect_port and _port_is_free(existing.redirect_port):
+        client_id, client_secret, port = existing.client_id, existing.client_secret, existing.redirect_port
+    if not client_id:
+        port = _free_port()
+        client_id, client_secret = register_client(metadata, port)
+
+    verifier, challenge = _pkce_pair()
+    state = secrets.token_urlsafe(24)
+    params = {
+        "response_type": "code",
+        "client_id": client_id,
+        "redirect_uri": _redirect_uri(port),
+        "code_challenge": challenge,
+        "code_challenge_method": "S256",
+        "state": state,
+    }
+    url = metadata["authorization_endpoint"] + "?" + urlencode(params)
+
+    echo("Opening your browser to sign in to DevLift…")
+    echo(f"If it does not open, visit:\n  {url}")
+    if open_browser:
+        try:
+            webbrowser.open(url, new=2)
+        except Exception:
+            pass
+
+    result = _wait_for_callback(port, LOGIN_TIMEOUT_SECONDS)
+    if "error" in result:
+        raise AuthError(f"Sign-in refused: {result.get('error_description') or result['error']}", hint=None)
+    if result.get("state") != state:
+        raise AuthError("Sign-in response did not match this login attempt (state mismatch).", hint="Run `devlift login` again.")
+    code = result.get("code")
+    if not code:
+        raise AuthError("Sign-in response carried no authorization code.", hint="Run `devlift login` again.")
+
+    form = {
+        "grant_type": "authorization_code",
+        "code": code,
+        "redirect_uri": _redirect_uri(port),
+        "client_id": client_id,
+        "code_verifier": verifier,
+    }
+    if client_secret:
+        form["client_secret"] = client_secret
+    token = _exchange(metadata, form)
+    return _to_credentials(base_url, metadata, client_id, client_secret, port, token)
+
+
+def refresh(base_url: str, creds: Credentials) -> Credentials:
+    """Rotate the token pair. Raises AuthError when the refresh token is gone."""
+    if not creds.refresh_token:
+        raise AuthError("Your session has expired.")
+    metadata = discover(base_url)
+    form = {
+        "grant_type": "refresh_token",
+        "refresh_token": creds.refresh_token,
+        "client_id": creds.client_id,
+    }
+    if creds.client_secret:
+        form["client_secret"] = creds.client_secret
+    token = _exchange(metadata, form)
+    fresh = _to_credentials(base_url, metadata, creds.client_id, creds.client_secret, creds.redirect_port, token)
+    if not fresh.refresh_token:
+        fresh.refresh_token = creds.refresh_token
+    return fresh
+
+
+def revoke(base_url: str, creds: Credentials) -> None:
+    """Best effort: tell the server to forget the tokens. Never raises."""
+    try:
+        metadata = discover(base_url)
+        endpoint = metadata.get("revocation_endpoint")
+        if not endpoint:
+            return
+        for token in (creds.refresh_token, creds.access_token):
+            if not token:
+                continue
+            form = {"token": token, "client_id": creds.client_id}
+            if creds.client_secret:
+                form["client_secret"] = creds.client_secret
+            httpx.post(endpoint, data=form, timeout=_TIMEOUT)
+    except Exception:
+        return

devlift_cli/auth/session.py

@@ -0,0 +1,64 @@
+"""The token a command actually sends.
+
+Precedence: DEVLIFT_TOKEN (scripts, CI) → stored credentials for the profile,
+refreshed transparently when expired. A refresh that fails clears nothing;
+the user is told to run `devlift login`.
+"""
+
+from __future__ import annotations
+
+import os
+
+from devlift_cli.auth import oauth, storage
+from devlift_cli.config import Profile
+from devlift_cli.errors import AuthError
+
+
+class TokenSource:
+    def __init__(self, profile: Profile):
+        self.profile = profile
+        self._creds: storage.Credentials | None = None
+        self._env_token = os.environ.get("DEVLIFT_TOKEN") or None
+
+    @property
+    def from_environment(self) -> bool:
+        return self._env_token is not None
+
+    def current(self) -> str:
+        if self._env_token:
+            return self._env_token
+        creds = self._load()
+        if creds.expired:
+            creds = self._refresh(creds)
+        return creds.access_token
+
+    def force_refresh(self) -> str | None:
+        """After a 401: rotate once. None means there is nothing to rotate with."""
+        if self._env_token:
+            return None
+        try:
+            return self._refresh(self._load()).access_token
+        except AuthError:
+            return None
+
+    def _load(self) -> storage.Credentials:
+        if self._creds is None:
+            self._creds = storage.load(self.profile.name)
+        if self._creds is None:
+            raise AuthError(f"Not signed in (profile '{self.profile.name}').")
+        # A token is bound to the backend that issued it. --endpoint-url or
+        # DEVLIFT_BASE_URL can point the same profile elsewhere; never send
+        # one backend's token to another.
+        if self._creds.base_url and self._creds.base_url != self.profile.base_url:
+            raise AuthError(
+                f"Profile '{self.profile.name}' is signed in to {self._creds.base_url}, "
+                f"but this command targets {self.profile.base_url}.",
+                hint="Run `devlift login` for this backend, or drop --endpoint-url / DEVLIFT_BASE_URL.",
+            )
+        return self._creds
+
+    def _refresh(self, creds: storage.Credentials) -> storage.Credentials:
+        fresh = oauth.refresh(self.profile.base_url, creds)
+        storage.save(self.profile.name, fresh)
+        self._creds = fresh
+        return fresh

devlift_cli/auth/storage.py

@@ -0,0 +1,135 @@
+"""Where the credentials live.
+
+Primary: the OS keyring (service "devlift-cli", one entry per profile).
+Fallback: ~/.config/devlift/credentials.json with mode 0600, for machines
+without a keyring backend (headless Linux, CI). Which one is in use is
+reported by `whoami --debug`; the data shape is the same in both.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+
+from devlift_cli.config import CONFIG_DIR
+
+KEYRING_SERVICE = "devlift-cli"
+FALLBACK_FILE = CONFIG_DIR / "credentials.json"
+
+
+@dataclass
+class Credentials:
+    issuer: str
+    client_id: str
+    base_url: str = ""  # the backend this login was made against
+    client_secret: str | None = None
+    redirect_port: int = 0
+    access_token: str = ""
+    refresh_token: str | None = None
+    expires_at: float = 0.0
+    scopes: list[str] = field(default_factory=list)
+
+    @property
+    def expired(self) -> bool:
+        # A minute of slack so a token does not die mid-command.
+        return bool(self.expires_at) and time.time() > self.expires_at - 60
+
+    def to_json(self) -> str:
+        return json.dumps(asdict(self))
+
+    @classmethod
+    def from_json(cls, raw: str) -> "Credentials":
+        data = json.loads(raw)
+        return cls(**{k: v for k, v in data.items() if k in cls.__dataclass_fields__})
+
+
+def _keyring():
+    try:
+        import keyring
+        from keyring.errors import NoKeyringError  # noqa: F401
+    except Exception:
+        return None
+    try:
+        backend = keyring.get_keyring()
+        # The "fail" backend raises on every call; treat it as absent.
+        if backend.__class__.__module__.startswith("keyring.backends.fail"):
+            return None
+        return keyring
+    except Exception:
+        return None
+
+
+def _read_fallback() -> dict:
+    try:
+        return json.loads(FALLBACK_FILE.read_text())
+    except (FileNotFoundError, ValueError):
+        return {}
+
+
+def _write_fallback(data: dict) -> None:
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    tmp = FALLBACK_FILE.with_suffix(".tmp")
+    tmp.write_text(json.dumps(data, indent=2) + "\n")
+    tmp.chmod(0o600)
+    tmp.replace(FALLBACK_FILE)
+
+
+def backend_name() -> str:
+    kr = _keyring()
+    return kr.get_keyring().__class__.__name__ if kr else f"file ({FALLBACK_FILE})"
+
+
+def load(profile: str) -> Credentials | None:
+    kr = _keyring()
+    raw = None
+    if kr:
+        try:
+            raw = kr.get_password(KEYRING_SERVICE, profile)
+        except Exception:
+            raw = None
+    if raw is None:
+        raw = _read_fallback().get(profile)
+        if isinstance(raw, dict):
+            raw = json.dumps(raw)
+    if not raw:
+        return None
+    try:
+        return Credentials.from_json(raw)
+    except (ValueError, TypeError):
+        return None
+
+
+def save(profile: str, creds: Credentials) -> None:
+    kr = _keyring()
+    if kr:
+        try:
+            kr.set_password(KEYRING_SERVICE, profile, creds.to_json())
+            return
+        except Exception:
+            pass
+    data = _read_fallback()
+    data[profile] = json.loads(creds.to_json())
+    _write_fallback(data)
+
+
+def clear(profile: str) -> bool:
+    removed = False
+    kr = _keyring()
+    if kr:
+        try:
+            kr.delete_password(KEYRING_SERVICE, profile)
+            removed = True
+        except Exception:
+            pass
+    data = _read_fallback()
+    if profile in data:
+        del data[profile]
+        _write_fallback(data)
+        removed = True
+    return removed
+
+
+def fallback_path() -> Path:
+    return FALLBACK_FILE

devlift_cli/commands/approval.py

@@ -0,0 +1,51 @@
+"""devlift approval … — the reviewer's side of the review lane."""
+
+from __future__ import annotations
+
+import typer
+
+from devlift_cli.commands.manual import section_command
+from devlift_cli.api import approvals as approvals_api
+from devlift_cli.context import Invocation
+from devlift_cli.ops.approvals import run_verb
+from devlift_cli.render.output import rows_table
+from devlift_cli.resolve.names import Resolver
+
+approval_app = typer.Typer(help="Review change requests: inbox, approve, reject, request changes, revoke.", no_args_is_help=True)
+
+_REF = typer.Argument(..., help="Queue code (queue-…) or service name.")
+_ENV = typer.Option(None, "--env", help="Environment, when the service is configured in several.")
+_REGION = typer.Option(None, "--region", help="Region, when the service runs in several.")
+
+
+@approval_app.command("list")
+def approval_list(ctx: typer.Context):
+    """Services with requests waiting for you (submitted or approved)."""
+    inv: Invocation = ctx.obj
+    rows = approvals_api.services_awaiting(inv.api)
+    inv.emit(rows, lambda d: rows_table(
+        ["Service", "Environment", "Pending", "Approved", "Latest request", "Configuration"],
+        [(r.get("service_name"), r.get("environment"), r.get("pending_count"), r.get("approved_count"),
+          (r.get("latest_requested_at") or "")[:16].replace("T", " "), r.get("resource_code")) for r in d],
+    ))
+
+
+def _verb_command(verb: str, doc: str, comment_required: bool):
+    comment_opt = typer.Option(..., "--comment", help="Why — recorded for the author.") if comment_required else \
+        typer.Option("", "--comment", help="Optional note recorded on the request.")
+
+    def command(ctx: typer.Context, ref: str = _REF, env: str | None = _ENV, region: str | None = _REGION, comment: str = comment_opt):
+        inv: Invocation = ctx.obj
+        result = run_verb(inv, Resolver(inv.api, inv.profile.name), verb, ref, env=env, region=region, comment=comment)
+        inv.emit(result.to_dict(), lambda d: rows_table(["Request", "Kind", "Status"], [(r["code"], r["kind"], r["status"]) for r in d["requests"]], title=f"{d['service']}: {verb}"))
+    command.__doc__ = doc
+    return command
+
+
+approval_app.command("approve")(_verb_command("approve", "Approve a submitted request (settings and routes together). It becomes deployable.", False))
+approval_app.command("request-changes")(_verb_command("request-changes", "Send a submitted request back to its author as a draft, with a comment.", True))
+approval_app.command("reject")(_verb_command("reject", "Reject a submitted request. Terminal — use request-changes unless it should never happen.", True))
+approval_app.command("revoke")(_verb_command("revoke", "Take an approval back; the request waits for a decision again. Not possible once a deploy has started.", False))
+
+
+approval_app.command("manual")(section_command("request, approval"))