exedev 0.2.0__py3-none-any.whl

exedev/_async.py

@@ -0,0 +1,2707 @@
+# Code generated by "go run ./cmd/gensdkpy" in the exe.dev repository. DO NOT EDIT.
+
+"""The asynchronous API: AsyncClient and AsyncVM."""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import contextlib
+import errno
+import functools
+import inspect
+import os
+import secrets
+import shlex
+import signal
+import stat
+from collections.abc import Awaitable, Callable, Mapping, Sequence
+from datetime import datetime
+from pathlib import Path, PurePosixPath
+from time import monotonic
+from types import TracebackType
+from typing import Any, Literal
+from urllib.parse import urlsplit, urlunsplit
+
+import httpx
+
+from . import types as t
+from ._errors import (
+    APIError,
+    CommandError,
+    CommandInterruptedError,
+    CommandTimeoutError,
+    ExeError,
+    NetworkError,
+    NotFoundError,
+    OutputLimitError,
+    PermissionDeniedError,
+    ProcessLostError,
+    ProtocolError,
+    VMReadyError,
+    VMSetupError,
+    api_error,
+    is_error_document,
+    parse_documents,
+    ssh_error,
+)
+from ._wire import (
+    DEFAULT_BASE_URL,
+    DOWNLOAD_SCRIPT,
+    HEADERS,
+    IS_DIRECTORY,
+    KILL_SCRIPT,
+    LIST_SCRIPT,
+    LOGS_SCRIPT,
+    MAX_OUTPUT,
+    MISSING,
+    PARALLEL,
+    PART_SCRIPT,
+    PART_SIZE,
+    READ_SCRIPT,
+    RETRYABLE,
+    RUN_SCRIPT,
+    RUNNING,
+    SETUP_PROBE,
+    SPAWN_SCRIPT,
+    STATE_SCRIPT,
+    TIMEOUT,
+    UNLIMITED,
+    UNTAR_SCRIPT,
+    UPLOADED_COMMAND,
+    WAIT_SCRIPT,
+    WRITE_SCRIPT,
+    Arg,
+    CommandResult,
+    Flag,
+    Logs,
+    Output,
+    ProcessState,
+    SetupFailure,
+    Stream,
+    VMInfo,
+    check_ready,
+    command_line,
+    creates,
+    env_flags,
+    file_mode,
+    fits,
+    is_ndjson,
+    on_off,
+    pack,
+    process_name,
+    process_state,
+    ready_timeout,
+    remote_path,
+    required,
+    retry_delay,
+    rm_result,
+    setup_state,
+    sh,
+    signal_name,
+    ssh_command,
+    stream_timeout,
+    tar_directory,
+    untar,
+    vm_info,
+    vm_list,
+    vm_name,
+)
+
+__all__ = ["AsyncClient", "AsyncProcess", "AsyncVM"]
+
+OutputCallback = Callable[[str], object]
+"""Called with each line of output as it arrives, decoded as UTF-8, without its line ending. May be a coroutine function."""
+
+WaitUntil = Literal["ssh", "setup", "created"]
+
+
+class _AsyncTransport:
+    """Runs exe.dev commands over HTTPS: POST /exec with the command line as the body."""
+
+    def __init__(self, token: str, base_url: str, http_client: httpx.AsyncClient | None, max_retries: int) -> None:
+        if not isinstance(max_retries, int) or isinstance(max_retries, bool) or max_retries < 0:
+            raise TypeError("max_retries must be a nonnegative int")
+        self._url = base_url.rstrip("/") + "/exec"
+        self._headers = {**HEADERS, "Authorization": f"Bearer {token}"}
+        self._owned = http_client is None
+        self._http = http_client if http_client is not None else httpx.AsyncClient(timeout=TIMEOUT)
+        self._retries = max_retries
+
+    async def aclose(self) -> None:
+        if self._owned:
+            await self._http.aclose()
+
+    async def _send(self, command: str, timeout: httpx.Timeout = TIMEOUT, stream: bool = False) -> httpx.Response:
+        """POST command, retrying while the server says 429 (before running anything)."""
+        attempt = 0
+        while True:
+            request = self._http.build_request(
+                "POST", self._url, content=command.encode(), headers=self._headers, timeout=timeout
+            )
+            response = await self._http.send(request, stream=stream)
+            if response.status_code != 429 or attempt >= self._retries:
+                return response
+            await response.aclose()
+            await asyncio.sleep(retry_delay(response, attempt))
+            attempt += 1
+
+    async def documents(
+        self, path: str, args: Sequence[Arg] = (), flags: Sequence[Flag] = ()
+    ) -> tuple[int, str, list[Any] | None]:
+        """A successful response's status, body, and JSON documents, including in-band error documents."""
+        try:
+            response = await self._send(command_line(path, args, flags))
+        except httpx.RequestError as err:
+            raise NetworkError(path, err) from err
+        body = response.text
+        if not response.is_success:
+            raise api_error(path, response.status_code, body)
+        return response.status_code, body, parse_documents(body)
+
+    async def call(self, path: str, args: Sequence[Arg] = (), flags: Sequence[Flag] = (), json: bool = False) -> Any:
+        """Run a command: its JSON document, or its text output if it is not JSON and json is false."""
+        status, body, docs = await self.documents(path, args, flags)
+        if docs is None:
+            if json:
+                raise ProtocolError(path)
+            return body
+        if any(is_error_document(d) for d in docs):
+            raise api_error(path, status, body)
+        return docs[0] if len(docs) == 1 else docs
+
+    async def ssh(
+        self,
+        vm: str,
+        command: str,
+        *,
+        capture: bool = True,
+        max_output: int = MAX_OUTPUT,
+        on_stdout: OutputCallback | None = None,
+        on_stderr: OutputCallback | None = None,
+        timeout: float | None = None,
+    ) -> CommandResult:
+        output = Output(capture, max_output)
+        if timeout is not None and (isinstance(timeout, bool) or not isinstance(timeout, (int, float)) or timeout <= 0):
+            raise ValueError("timeout must be a positive number of seconds")
+        deadline = None if timeout is None else monotonic() + timeout
+        callbacks = {"stdout": on_stdout, "stderr": on_stderr}
+
+        def expired() -> bool:
+            return deadline is not None and monotonic() >= deadline
+
+        def timed_out() -> CommandInterruptedError:
+            return output.interrupted(CommandTimeoutError, "the command did not finish within its timeout")
+
+        try:
+            response = await self._send(
+                f"ssh {shlex.quote(vm)} {shlex.quote(command)}", stream_timeout(timeout), stream=True
+            )
+        except httpx.RequestError as err:
+            # The request may have reached the VM: whether the command ran is unknown.
+            raise (timed_out() if expired() else output.interrupted()) from err
+        try:
+            if not response.is_success:
+                try:
+                    await response.aread()
+                except httpx.RequestError as err:
+                    raise NetworkError("ssh", err) from err
+                raise ssh_error(vm, response.status_code, response.text)
+            if not is_ndjson(response):
+                # An older server may be streaming the command's raw output, which
+                # can be endless: do not read it as an error, or claim the command
+                # did not run.
+                raise ProtocolError("ssh")
+            chunks = response.aiter_bytes()
+            while True:
+                try:
+                    chunk = await anext(chunks)
+                except StopAsyncIteration:
+                    break
+                except httpx.RequestError as err:
+                    raise (timed_out() if expired() else output.interrupted()) from err
+                for stream, data in output.feed(chunk):
+                    await _deliver(callbacks[stream], output, stream, data)
+                if expired():
+                    raise timed_out()
+            for stream, data in output.finish():
+                await _deliver(callbacks[stream], output, stream, data)
+            for stream in ("stdout", "stderr"):
+                await _deliver(callbacks[stream], output, stream, b"", final=True)
+            return output.result()
+        finally:
+            # Before the end of the body, this ends the command.
+            await response.aclose()
+
+
+async def _deliver(
+    callback: OutputCallback | None, output: Output, stream: Stream, data: bytes, final: bool = False
+) -> None:
+    """Call callback with each line that data completes."""
+    if callback is None:
+        return
+    for line in output.lines(stream, data, final):
+        result = callback(line)
+        if inspect.isawaitable(result):
+            await result
+
+
+class AsyncVM:
+    """A VM on exe.dev.
+
+    Get one from AsyncClient.new(), AsyncClient.vms(), AsyncClient.vm(), or
+    AsyncVM.copy(). Its attributes are a snapshot: the SDK's own operations
+    keep them current, and refresh() fetches the rest.
+
+    A VM made by new() or copy() is a context manager that deletes it on
+    exit::
+
+        async with exe.new() as vm:
+            await vm.run("make test", check=True)
+    """
+
+    def __init__(self, transport: _AsyncTransport, info: VMInfo, *, owned: bool = False) -> None:
+        self._t = transport
+        self._info = info
+        self._owned = owned
+        self.domain = _AsyncVMDomain(self)
+        self.share = _AsyncVMShare(self)
+        self.shelley = _AsyncVMShelley(self)
+
+    @property
+    def name(self) -> str:
+        return self._info.name
+
+    @property
+    def status(self) -> str:
+        """Such as "starting", "running", or "paused", when last seen."""
+        return self._info.status
+
+    @property
+    def ssh_dest(self) -> str:
+        """The SSH destination, such as "myvm.exe.xyz"."""
+        return self._info.ssh_dest
+
+    @property
+    def https_url(self) -> str:
+        """The VM's web URL, such as "https://myvm.exe.xyz/". url() makes others."""
+        return self._info.https_url
+
+    @property
+    def tags(self) -> tuple[str, ...]:
+        return self._info.tags
+
+    @property
+    def comment(self) -> str:
+        """The VM's comment; "" when it has none."""
+        return self._info.comment
+
+    @property
+    def region(self) -> str | None:
+        """The VM's region; None until listed (see refresh())."""
+        return self._info.region
+
+    @property
+    def created_at(self) -> datetime | None:
+        """When the VM was created; None until listed (see refresh())."""
+        return self._info.created_at
+
+    @property
+    def prompt_error(self) -> str | None:
+        """Why new(prompt=...) did not reach Shelley, when it did not."""
+        return self._info.prompt_error
+
+    def url(self, port: int | None = None, path: str = "/") -> str:
+        """A URL that reaches the VM through exe.dev's HTTPS proxy.
+
+        Without a port, it is https_url, which reaches the VM's default port
+        (see share.port()). With one, it reaches that port; the proxy serves
+        ports 3000 to 9999. Who may visit depends on how the VM is shared.
+        """
+        if port is not None and (not isinstance(port, int) or isinstance(port, bool) or not 0 < port < 65536):
+            raise ValueError("port must be an int from 1 to 65535")
+        if not isinstance(path, str) or not path.startswith("/"):
+            raise ValueError("path must be a str starting with /")
+        url = urlsplit(self.https_url)
+        netloc = url.netloc if port is None else f"{url.hostname}:{port}"
+        return urlunsplit((url.scheme, netloc, path, "", ""))
+
+    def __repr__(self) -> str:
+        return f"<{type(self).__name__} {self.name!r} status={self.status!r}>"
+
+    async def __aenter__(self) -> AsyncVM:
+        if not self._owned:
+            raise TypeError("only a VM made by new() or copy() deletes itself at the end of a with block")
+        return self
+
+    async def __aexit__(
+        self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None
+    ) -> None:
+        with contextlib.suppress(NotFoundError):
+            await self.delete()
+
+    def _absorb(self, result: object) -> None:
+        """Take the status, comment, and tags a command reports for this VM into the snapshot."""
+        if not isinstance(result, dict) or result.get("vm_name") != self.name:
+            return
+        if isinstance(status := result.get("status"), str):
+            self._info.status = status
+        if isinstance(comment := result.get("comment"), str):
+            self._info.comment = comment
+        tags = result.get("tags")
+        if isinstance(tags, list) and all(isinstance(tag, str) for tag in tags):
+            self._info.tags = tuple(tags)
+
+    def _renamed(self, result: Mapping[str, object]) -> None:
+        """Take a new name, and the destinations that change with it."""
+        ssh_dest, https_url = result.get("ssh_dest"), result.get("https_url")
+        if not isinstance(ssh_dest, str) or not ssh_dest or not isinstance(https_url, str) or not https_url:
+            raise ProtocolError("rename")
+        self._info.name = vm_name(result["new_name"])
+        self._info.ssh_dest = ssh_dest
+        self._info.https_url = https_url
+
+    async def run(
+        self,
+        command: str | Sequence[str],
+        *,
+        check: bool = False,
+        timeout: float | None = None,
+        cwd: str | os.PathLike[str] | None = None,
+        env: Mapping[str, str] | None = None,
+        on_stdout: OutputCallback | None = None,
+        on_stderr: OutputCallback | None = None,
+        capture: bool = True,
+        max_output: int = MAX_OUTPUT,
+    ) -> CommandResult:
+        """Run a command on the VM, once, and return how it ended.
+
+        A string is a shell command line, which the VM user's login shell
+        runs as a login shell, so PATH is as in a terminal. A sequence of
+        strings is an argument list, which is quoted for you:
+        ``vm.run(["cat", path])``.
+
+        Like subprocess.run, a nonzero exit status is a result, not an
+        exception, unless check is true; then it raises CommandError.
+
+        cwd is the directory to run it in, and env variables to set for it.
+
+        on_stdout and on_stderr are called with each line of output, without
+        its line ending, as it arrives; ``on_stdout=print`` works. They are
+        called one at a time, and may be coroutine functions. An exception
+        from one stops the command and propagates.
+        Output is also captured, up to max_output bytes in all (8 MiB by
+        default; more raises OutputLimitError). For long or large output,
+        pass capture=False and stream it.
+
+        timeout is in seconds; a command still running then is stopped,
+        with every process it started, and CommandTimeoutError raised.
+        Without a timeout, a command may run for as long as it likes.
+
+        run() returns once the command has exited and its output has
+        closed, so a process left running in the background with stdout or
+        stderr open keeps it waiting. Start those with spawn().
+
+        If the connection breaks first, CommandInterruptedError: whether the
+        command finished is unknown. A command line too long for one request
+        is uploaded as a file first. Requires ssh permission.
+        """
+        script = await self._fit(ssh_command(command, cwd, env), lambda line: sh(RUN_SCRIPT, line))
+        result = await self._t.ssh(
+            self.name,
+            script,
+            capture=capture,
+            max_output=max_output,
+            on_stdout=on_stdout,
+            on_stderr=on_stderr,
+            timeout=timeout,
+        )
+        if check and result.exit_code != 0:
+            raise CommandError(result)
+        return result
+
+    async def _fit(self, line: str, make: Callable[[str], str]) -> str:
+        """make(line), or if that does not fit in a request, make() of a
+        command line that runs line from a file uploaded first."""
+        command = make(line)
+        if fits(self.name, command):
+            return command
+        path = f"/tmp/.exedev-command-{secrets.token_hex(8)}"
+        await self.write_file(path, line)
+        return make(UPLOADED_COMMAND.format(path=path))
+
+    async def _script(self, command: str, max_output: int = MAX_OUTPUT, ok: Sequence[int] = ()) -> CommandResult:
+        """Run one of the SDK's scripts. An exit status other than 0 or those in ok raises CommandError."""
+        result = await self._t.ssh(self.name, command, max_output=max_output)
+        if result.exit_code != 0 and result.exit_code not in ok:
+            raise CommandError(result)
+        return result
+
+    async def _parallel(self, jobs: Sequence[Callable[[], Awaitable[object]]]) -> None:
+        """Run jobs, PARALLEL at a time. The first to fail stops the rest."""
+        semaphore = asyncio.Semaphore(PARALLEL)
+
+        async def one(job: Callable[[], Awaitable[object]]) -> None:
+            async with semaphore:
+                await job()
+
+        tasks = [asyncio.ensure_future(one(job)) for job in jobs]
+        try:
+            await asyncio.gather(*tasks)
+        finally:
+            for task in tasks:
+                task.cancel()
+            await asyncio.gather(*tasks, return_exceptions=True)
+
+    def _file_error(self, exit_code: int, path: object) -> None:
+        if exit_code == MISSING:
+            raise FileNotFoundError(errno.ENOENT, f"No such file or directory on VM {self.name}", str(path))
+        if exit_code == IS_DIRECTORY:
+            raise IsADirectoryError(errno.EISDIR, f"Is a directory on VM {self.name}", str(path))
+
+    async def write_file(self, path: str | PurePosixPath, data: str | bytes, *, mode: int | None = None) -> None:
+        """Write a file on the VM, replacing it, and making its directory if need be.
+
+        path is relative to the home directory unless it is absolute. A str
+        is written as UTF-8. mode, such as 0o755, sets the file's permissions.
+
+        A request carries at most 64 KB, so a large file goes in parts,
+        several at a time. The VM needs base64, and gzip for a large file.
+        Requires ssh permission.
+        """
+        remote = remote_path(path)
+        packed, gz = pack(data)
+        encoded = base64.b64encode(packed).decode()
+        options = (file_mode(mode), "gz" if gz else "")
+        command = sh(WRITE_SCRIPT, remote, encoded, *options, "")
+        if fits(self.name, command):
+            await self._script(command)
+            return
+        parts = f"/tmp/.exedev-upload-{secrets.token_hex(8)}"
+        try:
+            await self._parallel(
+                [
+                    functools.partial(self._script, sh(PART_SCRIPT, parts, f"{i:06d}", encoded[start : start + PART_SIZE]))
+                    for i, start in enumerate(range(0, len(encoded), PART_SIZE))
+                ]
+            )
+        except Exception:
+            with contextlib.suppress(ExeError):
+                await self._t.ssh(self.name, f"rm -rf {parts}", capture=False, timeout=30)
+            raise
+        await self._script(sh(WRITE_SCRIPT, remote, "", *options, parts))
+
+    async def read_file(self, path: str | PurePosixPath) -> bytes:
+        """The contents of a file on the VM, which raises FileNotFoundError if
+        there is none. path is relative to the home directory unless it is
+        absolute. Requires ssh permission."""
+        result = await self._script(sh(READ_SCRIPT, remote_path(path)), UNLIMITED, ok=(MISSING, IS_DIRECTORY))
+        self._file_error(result.exit_code, path)
+        return result.stdout_bytes
+
+    async def upload(
+        self, local: str | os.PathLike[str], remote: str | PurePosixPath, *, exclude: Sequence[str] = ()
+    ) -> None:
+        """Copy a local file or directory to the VM.
+
+        A file is written to remote, with its permissions. A directory's
+        contents are copied into remote, which is made if need be; exclude
+        leaves out files and directories whose names match any of its
+        patterns, such as ``[".git", "node_modules", "*.pyc"]``. The VM needs
+        tar for a directory. Requires ssh permission.
+        """
+        source = Path(local)
+        destination = remote_path(remote)
+        if source.is_dir():
+            archive = await asyncio.to_thread(tar_directory, source, exclude)
+            temporary = f"/tmp/.exedev-upload-{secrets.token_hex(8)}.tgz"
+            await self.write_file(temporary, archive)
+            await self._script(sh(UNTAR_SCRIPT, temporary, destination))
+        else:
+            await self.write_file(destination, source.read_bytes(), mode=stat.S_IMODE(source.stat().st_mode))
+
+    async def download(self, remote: str | PurePosixPath, local: str | os.PathLike[str]) -> None:
+        """Copy a file or directory from the VM.
+
+        A file is written to local. A directory's contents are copied into
+        local, which is made if need be. A path on the VM that does not
+        exist raises FileNotFoundError. The VM needs tar for a directory.
+        Requires ssh permission.
+        """
+        result = await self._script(sh(DOWNLOAD_SCRIPT, remote_path(remote)), UNLIMITED, ok=(MISSING,))
+        self._file_error(result.exit_code, remote)
+        kind, data = result.stdout_bytes[:1], result.stdout_bytes[1:]
+        destination = Path(local)
+        if kind == b"D":
+            await asyncio.to_thread(untar, data, destination)
+        elif kind == b"F":
+            destination.write_bytes(data)
+        else:
+            raise ProtocolError("download")
+
+    @creates
+    async def spawn(
+        self,
+        command: str | Sequence[str],
+        *,
+        name: str | None = None,
+        cwd: str | os.PathLike[str] | None = None,
+        env: Mapping[str, str] | None = None,
+    ) -> AsyncProcess:
+        """Start a command in the background, and return at once.
+
+        The command runs as run() runs it, but on its own: until it exits,
+        or is killed, whatever becomes of this program or its connection.
+        Its output goes to files on the VM; see AsyncProcess.logs().
+
+        name identifies the process, so that process() finds it again
+        later, from anywhere; by default, it is random. It must not be the
+        name of a process still running. A process is a context manager that
+        kills it on exit::
+
+            async with vm.spawn("python3 -m http.server 8000") as server:
+                ...
+
+        Requires ssh permission, and setsid on the VM.
+        """
+        name = process_name(name if name is not None else secrets.token_hex(4))
+        script = await self._fit(ssh_command(command, cwd, env), lambda line: sh(SPAWN_SCRIPT, name, line))
+        result = await self._script(script, ok=(RUNNING,))
+        if result.exit_code == RUNNING:
+            raise ExeError(f"a process named {name} is already running on VM {self.name}")
+        try:
+            pid = int(result.stdout)
+        except ValueError:
+            raise ProtocolError("spawn") from None
+        return AsyncProcess(self, name, ProcessState(pid))
+
+    async def process(self, name: str) -> AsyncProcess:
+        """The process that spawn() started with this name, running or not.
+        ProcessLookupError if there is none. Requires ssh permission."""
+        result = await self._script(sh(STATE_SCRIPT, process_name(name)), ok=(MISSING,))
+        if result.exit_code == MISSING:
+            raise ProcessLookupError(f"no process {name} on VM {self.name}")
+        return AsyncProcess(self, name, process_state(result.stdout))
+
+    async def processes(self) -> list[AsyncProcess]:
+        """The processes spawn() has started, running or not. Requires ssh permission."""
+        result = await self._script(sh(LIST_SCRIPT))
+        processes = []
+        for line in result.stdout.splitlines():
+            name, _, state = line.partition(" ")
+            processes.append(AsyncProcess(self, process_name(name), process_state(state)))
+        return processes
+
+    async def refresh(self) -> None:
+        """Fetch the VM's attributes. Requires ls permission."""
+        self._info = await _find(self._t, self.name)
+
+    async def wait_until_ready(self, until: Literal["ssh", "setup"] = "ssh", *, timeout: float | None = None) -> None:
+        """Wait until the VM runs commands.
+
+        It probes SSH with ``true`` until it succeeds. With until="setup", it
+        then waits for the VM's setup script (exeuntu's exe-setup.service) to
+        finish, raising VMSetupError if it failed. A script on an image
+        without that unit (anything not built on exeuntu) never runs: that is
+        a VMSetupError too, with result "unsupported". This does not wait for
+        servers the VM starts.
+
+        timeout is in seconds, by default 60, or 600 for setup. Raises
+        VMReadyError. Requires ssh permission.
+        """
+        seconds = ready_timeout(until, timeout)
+        await self._wait(until, seconds)
+
+    async def _wait(self, until: str, timeout: float) -> None:
+        deadline = monotonic() + timeout
+        backoff = 0.1
+        probe = SETUP_PROBE if until == "setup" else "true"
+        last: BaseException | None = None
+        while (remaining := deadline - monotonic()) > 0:
+            try:
+                result = await self._t.ssh(
+                    self.name, probe, capture=until == "setup", max_output=1 << 20, timeout=remaining
+                )
+                if result.exit_code != 0:
+                    raise ProtocolError("ssh readiness probe")
+                state = setup_state(result.stdout) if until == "setup" else "done"
+                if state == "done":
+                    # It answered over SSH, so it is running, whatever new or cp said then.
+                    self._info.status = "running"
+                    return
+                if isinstance(state, SetupFailure):
+                    raise VMSetupError(self, state.result, state.exit_code, state.signal, state.output)
+                backoff = max(backoff, 1.0)
+            except CommandTimeoutError as err:
+                last = err
+                break
+            except (OutputLimitError, ProtocolError) as err:
+                raise VMReadyError(self, "is not SSH-ready") from err
+            except CommandInterruptedError as err:
+                # The probe is safe to rerun after a lost connection.
+                last = err
+            except PermissionDeniedError as err:
+                raise VMReadyError(
+                    self,
+                    "is not known to be ready: this token may not run ssh, "
+                    'which readiness needs (use wait_until="created")',
+                ) from err
+            except APIError as err:
+                # /exec reports these before a remote command starts. Others (not
+                # found, no SSH configured) fail fast.
+                if err.status != 422 or not RETRYABLE.search(err.body):
+                    raise VMReadyError(self, "is not SSH-ready") from err
+                last = err
+            except NetworkError as err:
+                last = err
+            await asyncio.sleep(max(0.0, min(backoff, deadline - monotonic())))
+            backoff = min(backoff * 2, 2.0)
+        what = "setup did not finish in time" if until == "setup" else "SSH readiness timed out"
+        raise VMReadyError(self, f"is not ready: {what}") from last
+
+    async def _ready(self, wait_until: WaitUntil, timeout: float | None) -> None:
+        if wait_until != "created":
+            await self._wait(wait_until, ready_timeout(wait_until, timeout))
+
+    async def _created(self, wait_until: WaitUntil, timeout: float | None, keep_on_failure: bool) -> AsyncVM:
+        """Wait until a VM that new() or copy() made is ready. If that fails,
+        or is interrupted, delete it: the caller never received it."""
+        try:
+            await self._ready(wait_until, timeout)
+        except BaseException as err:
+            if not (keep_on_failure and isinstance(err, VMReadyError)):
+                with contextlib.suppress(Exception):
+                    await self.delete()
+            raise
+        return self
+
+    async def _flush(self) -> None:
+        """Flush the VM's recent writes to its disk, if it is running. Best effort."""
+        with contextlib.suppress(ExeError):
+            await self._t.ssh(self.name, "sync", capture=False, timeout=60)
+
+    async def delete(self) -> None:
+        """Delete the VM. A VM that does not exist raises NotFoundError.
+
+        CLI: ``rm <vmname>...``
+
+        Tag-scoped API keys may run this command.
+        """
+        _, body, docs = await self._t.documents("rm", [self.name])
+        summary = rm_result(docs)
+        if summary["failed"] or len(summary["deleted"]) != 1:
+            raise api_error("rm", 404 if summary.get("not_found") else 422, body)
+
+    async def restart(self, *, wait_until: WaitUntil = "ssh", timeout: float | None = None) -> t.RestartResponse:
+        """Restart a VM.
+
+        CLI: ``restart <vmname>``
+
+        Tag-scoped API keys may run this command.
+
+        Args:
+            wait_until: "ssh" (the default) returns once the VM runs commands; "setup"
+                also waits for its setup script to finish, and succeed; "created"
+                returns at once. Waiting needs ssh permission, and raises VMReadyError
+                if the VM does not become ready.
+            timeout: seconds to wait for readiness; by default 60, or 600 for "setup".
+        """
+        check_ready(wait_until, timeout)
+        result: t.RestartResponse = await self._t.call("restart", [self.name], json=True)
+        await self._ready(wait_until, timeout)
+        return result
+
+    async def pause(self) -> t.PauseResponse:
+        """Pause a VM (snapshot RAM to disk, free its CPU and memory).
+
+        CLI: ``pause <vmname>``
+
+        Tag-scoped API keys may run this command.
+        """
+        result: t.PauseResponse = await self._t.call("pause", [self.name], json=True)
+        self._absorb(result)
+        return result
+
+    async def resume(self, *, wait_until: WaitUntil = "ssh", timeout: float | None = None) -> t.ResumeResponse:
+        """Resume a paused VM (restore RAM from disk).
+
+        CLI: ``resume <vmname>``
+
+        Tag-scoped API keys may run this command.
+
+        Args:
+            wait_until: "ssh" (the default) returns once the VM runs commands; "setup"
+                also waits for its setup script to finish, and succeed; "created"
+                returns at once. Waiting needs ssh permission, and raises VMReadyError
+                if the VM does not become ready.
+            timeout: seconds to wait for readiness; by default 60, or 600 for "setup".
+        """
+        check_ready(wait_until, timeout)
+        result: t.ResumeResponse = await self._t.call("resume", [self.name], json=True)
+        self._absorb(result)
+        await self._ready(wait_until, timeout)
+        return result
+
+    async def rename(self, new_name: str) -> t.RenameResponse:
+        """Rename the VM. Its ssh_dest and https_url change with its name.
+
+        CLI: ``rename <oldname> <newname>``
+
+        Tag-scoped API keys may run this command.
+        """
+        result: t.RenameResponse = await self._t.call("rename", [self.name, new_name], json=True)
+        if not isinstance(result, dict) or result.get("old_name") != self.name or result.get("new_name") != new_name:
+            raise ProtocolError("rename")
+        self._renamed(result)
+        return result
+
+    async def tag(self, *tag_names: str) -> t.TagResponse:
+        """Add tags to the VM.
+
+        CLI: ``tag [-d] <vm> <tag-name> [tag-name...]``
+
+        Tag-scoped API keys may run this command.
+        """
+        result: t.TagResponse = await self._t.call("tag", [self.name, required("tag name", tag_names)], json=True)
+        self._absorb(result)
+        return result
+
+    async def untag(self, *tag_names: str) -> t.TagResponse:
+        """Remove tags from the VM.
+
+        CLI: ``tag [-d] <vm> <tag-name> [tag-name...]``
+
+        Tag-scoped API keys may run this command.
+        """
+        result: t.TagResponse = await self._t.call(
+            "tag",
+            [self.name, required("tag name", tag_names)],
+            [("d", "bool", True)],
+            json=True,
+        )
+        self._absorb(result)
+        return result
+
+    @creates
+    async def copy(
+        self,
+        name: str | None = None,
+        *,
+        copy_tags: bool = True,
+        cpu: int | None = None,
+        disk: int | str | None = None,
+        memory: int | str | None = None,
+        pool: str | None = None,
+        standalone: bool = False,
+        flush: bool = True,
+        wait_until: WaitUntil = "ssh",
+        timeout: float | None = None,
+        keep_on_failure: bool = False,
+    ) -> AsyncVM:
+        """Copy the VM: a new VM with a copy of its disk, and by default its tags.
+
+        CLI: ``cp <source-vm> [new-name] [--pool=<name>] [--memory=<size>] [--cpu=<count>] [--disk=<size>]``
+
+        Tag-scoped API keys may run this command.
+
+        Args:
+            copy_tags: copy tags from source VM (use ``copy_tags=False`` to disable)
+            cpu: number of CPUs
+            disk: disk size (e.g., 20, 20GB, 50G)
+            memory: memory allocation (e.g., 4, 4GB, 8G)
+            pool: create the copy in one of your team's pools (see ``exe.pool.list()``)
+            standalone: create the copy as a standalone VM with its own reserved
+                capacity (requires a plan with standalone VMs and team approval)
+            flush: first flush the VM's recent writes to its disk, so that the copy has
+                them. Best effort: it needs ssh permission, and a running VM.
+            wait_until: "ssh" (the default) returns once the VM runs commands; "setup"
+                also waits for its setup script to finish, and succeed; "created"
+                returns at once. Waiting needs ssh permission, and raises VMReadyError
+                if the VM does not become ready.
+            timeout: seconds to wait for readiness; by default 60, or 600 for "setup".
+            keep_on_failure: keep a VM that does not become ready, for debugging:
+                VMReadyError.vm is it. By default, it is deleted, as it is when the wait
+                is interrupted.
+        """
+        check_ready(wait_until, timeout)
+        if flush:
+            await self._flush()
+        result = await self._t.call(
+            "cp",
+            [self.name, name],
+            [
+                ("copy-tags", "bool", None if copy_tags else False),
+                ("cpu", "number", cpu),
+                ("disk", "string", disk),
+                ("memory", "string", memory),
+                ("pool", "string", pool),
+                ("standalone", "bool", standalone or None),
+            ],
+            json=True,
+        )
+        vm = AsyncVM(self._t, vm_info(result, "cp"), owned=True)
+        return await vm._created(wait_until, timeout, keep_on_failure)
+
+    async def resize(
+        self,
+        *,
+        cpu: int | None = None,
+        disk: int | str | None = None,
+        memory: int | str | None = None,
+        restart: bool = False,
+    ) -> t.ResizeResponse:
+        """Resize the VM's memory, CPUs, or disk. Memory and CPU changes take effect when it restarts.
+
+        CLI: ``resize <vmname> [--memory=<size>] [--cpu=<count>] [--disk=<size>]``
+
+        Tag-scoped API keys may run this command.
+
+        Args:
+            cpu: number of CPUs
+            disk: new total disk size (e.g., 25, 25GB) - disk size can only increase;
+                billed by usage above your plan's included disk, not by size
+            memory: memory allocation (e.g., 4, 4GB, 8G)
+            restart: restart the VM afterwards, so that memory and cpu changes take
+                effect, and wait until it runs commands.
+        """
+        result: t.ResizeResponse = await self._t.call(
+            "resize",
+            [self.name],
+            [
+                ("cpu", "number", cpu),
+                ("disk", "string", disk),
+                ("memory", "string", memory),
+            ],
+            json=True,
+        )
+        if restart:
+            await self.restart()
+        return result
+
+    async def set_comment(self, text: str) -> t.CommentResponse:
+        """Set or clear a short comment on a VM.
+
+        CLI: ``comment <hostname> <text>``
+
+        Tag-scoped API keys may run this command.
+        """
+        result: t.CommentResponse = await self._t.call("comment", [self.name, text], json=True)
+        self._absorb(result)
+        return result
+
+    async def grant_support_root(self, enabled: bool) -> Any:
+        """Allow exe.dev support to log in to a VM.
+
+        CLI: ``grant-support-root <vmname> on|off``
+
+        Tag-scoped API keys may run this command.
+        """
+        return await self._t.call("grant-support-root", [self.name, on_off(enabled)])
+
+    async def stats(self, *, range: str | None = None) -> t.StatResponse:
+        """Show vCPU, disk, IO, and network (RX/TX) metrics for a VM.
+
+        CLI: ``stat <vm-name> [--range=24h|7d|30d]``
+
+        Tag-scoped API keys may run this command.
+
+        Args:
+            range: time range: 24h, 7d, or 30d (server default: 24h)
+        """
+        result: t.StatResponse = await self._t.call("stat", [self.name], [("range", "string", range)], json=True)
+        return result
+
+
+async def _find(transport: _AsyncTransport, name: str) -> VMInfo:
+    result = await transport.call("ls", [name], json=True)
+    for info in vm_list(result):
+        if info.name == name:
+            return info
+    raise NotFoundError("ls", 404, f'{{"error": "VM {name} not found"}}')
+
+
+class AsyncProcess:
+    """A process that AsyncVM.spawn() started on a VM.
+
+    Like subprocess.Popen, but the process does not depend on this program:
+    it runs until it exits or is killed. Find it again later with
+    AsyncVM.process(name). Its attributes are a snapshot; poll() and wait()
+    update them.
+
+    As a context manager, it kills the process at the end of the block.
+    """
+
+    def __init__(self, vm: AsyncVM, name: str, state: ProcessState) -> None:
+        self.vm = vm
+        """The VM it runs on."""
+        self.name = name
+        """Its name, which AsyncVM.process() finds it by."""
+        self._state = state
+
+    @property
+    def pid(self) -> int:
+        """Its process ID on the VM, which is also its process group's."""
+        return self._state.pid
+
+    @property
+    def exit_code(self) -> int | None:
+        """Its exit status, or None if it was running when last seen.
+        A process killed by a signal has 128 plus the signal's number."""
+        return self._state.exit_code
+
+    def __repr__(self) -> str:
+        state = "lost" if self._state.lost else "running" if self.exit_code is None else f"exit_code={self.exit_code}"
+        return f"<{type(self).__name__} {self.name!r} on {self.vm.name!r} pid={self.pid} {state}>"
+
+    async def __aenter__(self) -> AsyncProcess:
+        return self
+
+    async def __aexit__(
+        self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None
+    ) -> None:
+        with contextlib.suppress(NotFoundError, ProcessLookupError):
+            await self.kill()
+
+    def _check(self) -> int | None:
+        if self._state.lost:
+            raise ProcessLostError(self)
+        return self._state.exit_code
+
+    async def poll(self) -> int | None:
+        """Its exit status, or None if it is still running. Raises
+        ProcessLostError if it ended without one."""
+        result = await self.vm._script(sh(STATE_SCRIPT, self.name), ok=(MISSING,))
+        if result.exit_code == MISSING:
+            raise ProcessLookupError(f"no process {self.name} on VM {self.vm.name}")
+        self._state = process_state(result.stdout)
+        return self._check()
+
+    async def wait(
+        self, *, timeout: float | None = None, check: bool = False, capture: bool = True, max_output: int = MAX_OUTPUT
+    ) -> CommandResult:
+        """Wait for it to exit, and return how it ended, with its output.
+
+        A lost connection does not matter: wait() reconnects until it knows.
+        timeout is in seconds: TimeoutError if it is still running then
+        (which it still is). check, capture, and max_output are as for
+        AsyncVM.run(); with capture=False, the result has no output.
+        Raises ProcessLostError if it ended without an exit status.
+        """
+        deadline = None if timeout is None else monotonic() + timeout
+        nonce = secrets.token_hex(8)
+        backoff = 0.1
+        while True:
+            remaining = None if deadline is None else deadline - monotonic()
+            if remaining is not None and remaining <= 0:
+                raise TimeoutError(f"process {self.name} on VM {self.vm.name} is still running")
+            try:
+                command = sh(WAIT_SCRIPT, self.name, nonce, "1" if capture else "")
+                result = await self.vm._t.ssh(self.vm.name, command, max_output=max_output, timeout=remaining)
+                break
+            except CommandTimeoutError:
+                continue
+            except (CommandInterruptedError, NetworkError) as err:
+                if isinstance(err, OutputLimitError):
+                    raise
+                await asyncio.sleep(backoff)
+                backoff = min(backoff * 2, 2.0)
+        if result.exit_code == 0 and result.stdout == f"{nonce} missing":
+            raise ProcessLookupError(f"no process {self.name} on VM {self.vm.name}")
+        if result.exit_code == 0 and result.stdout == f"{nonce} lost":
+            self._state.lost = True
+            raise ProcessLostError(self)
+        self._state.exit_code = result.exit_code
+        if check and result.exit_code != 0:
+            raise CommandError(result)
+        return result
+
+    async def logs(self, *, tail: int | None = None) -> Logs:
+        """Its output so far; with tail, at most that many lines of each stream."""
+        if tail is not None and (not isinstance(tail, int) or isinstance(tail, bool) or tail < 0):
+            raise ValueError("tail must be a nonnegative int")
+        result = await self.vm._script(
+            sh(LOGS_SCRIPT, self.name, "" if tail is None else str(tail)), UNLIMITED, ok=(MISSING,)
+        )
+        if result.exit_code == MISSING:
+            raise ProcessLookupError(f"no process {self.name} on VM {self.vm.name}")
+        return Logs(result.stdout, result.stderr)
+
+    async def send_signal(self, sig: int | str) -> None:
+        """Send a signal, such as signal.SIGTERM or "HUP", to the process and
+        everything it started, if it is running."""
+        result = await self.vm._script(sh(KILL_SCRIPT, self.name, signal_name(sig)), ok=(MISSING,))
+        if result.exit_code == MISSING:
+            raise ProcessLookupError(f"no process {self.name} on VM {self.vm.name}")
+
+    async def terminate(self) -> None:
+        """Send SIGTERM to the process and everything it started."""
+        await self.send_signal(signal.SIGTERM)
+
+    async def kill(self) -> None:
+        """Send SIGKILL to the process and everything it started."""
+        await self.send_signal(signal.SIGKILL)
+
+
+class AsyncClient:
+    """An exe.dev API client.
+
+    token is an exe.dev API token; by default, the EXE_TOKEN environment
+    variable. Create one with ``ssh exe.dev ssh-key generate-api-key``. Its
+    permissions decide which methods work.
+
+    http_client is an httpx.AsyncClient to send requests with, for proxies,
+    custom TLS, or tests. The SDK does not close a client it was given.
+
+    A request refused for exceeding the rate limit, which runs nothing, is
+    retried up to max_retries times, with backoff.
+
+    Use it as a context manager, or call aclose(), to release connections.
+    """
+
+    def __init__(
+        self,
+        token: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        http_client: httpx.AsyncClient | None = None,
+        max_retries: int = 5,
+    ) -> None:
+        token = token if token is not None else os.environ.get("EXE_TOKEN")
+        if not token:
+            raise ExeError("an exe.dev API token is required: pass token= or set EXE_TOKEN")
+        self._t = _AsyncTransport(token, base_url, http_client, max_retries)
+        self.domain = _AsyncDomain(self._t)
+        self.ssh_key = _AsyncSshKey(self._t)
+        self.integrations = _AsyncIntegrations(self._t)
+        self.team = _AsyncTeam(self._t)
+        self.pool = _AsyncPool(self._t)
+        self.billing = _AsyncBilling(self._t)
+        self.invite = _AsyncInvite(self._t)
+
+    def __repr__(self) -> str:
+        return f"<{type(self).__name__} {self._t._url.removesuffix('/exec')!r}>"
+
+    async def aclose(self) -> None:
+        """Close the HTTP client this client made, if it made one."""
+        await self._t.aclose()
+
+    async def __aenter__(self) -> AsyncClient:
+        return self
+
+    async def __aexit__(
+        self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None
+    ) -> None:
+        await self.aclose()
+
+    async def vm(self, name: str) -> AsyncVM:
+        """The VM with this name. NotFoundError if there is none. Requires ls permission."""
+        return AsyncVM(self._t, await _find(self._t, vm_name(name)))
+
+    async def vms(self, pattern: str | None = None) -> list[AsyncVM]:
+        """Your VMs; with a pattern such as ``"web-*"``, those it matches. Requires ls permission."""
+        result = await self._t.call("ls", [pattern], json=True)
+        return [AsyncVM(self._t, info) for info in vm_list(result)]
+
+    async def delete(self, *vms: str | AsyncVM) -> t.RmResponse:
+        """Delete VMs in one request.
+
+        Unlike AsyncVM.delete(), VMs that were missing or could not be
+        deleted do not raise: they are listed in failed, with reasons in
+        errors. Requires rm permission.
+        """
+        names = list(dict.fromkeys(vm.name if isinstance(vm, AsyncVM) else vm_name(vm) for vm in vms))
+        if not names:
+            return {"deleted": [], "failed": [], "not_found": [], "errors": {}}
+        _, _, docs = await self._t.documents("rm", [names])
+        return rm_result(docs)
+
+    async def doc(self, *queries: str) -> Any:
+        """Browse documentation.
+
+        CLI: ``doc [slug-or-query...]``
+
+        Tag-scoped API keys may run this command.
+        """
+        return await self._t.call("doc", [queries])
+
+    @creates
+    async def new(
+        self,
+        *,
+        comment: str | None = None,
+        cpu: int | None = None,
+        disk: int | str | None = None,
+        env: Mapping[str, str] | None = None,
+        image: str | None = None,
+        integrations: Sequence[str] | None = None,
+        memory: int | str | None = None,
+        name: str | None = None,
+        no_pool: bool = False,
+        pool: str | None = None,
+        prompt: str | None = None,
+        registry_auth: str | None = None,
+        setup_script: str | None = None,
+        standalone: bool = False,
+        tags: Sequence[str] | None = None,
+        email: bool = False,
+        wait_until: WaitUntil = "ssh",
+        timeout: float | None = None,
+        keep_on_failure: bool = False,
+    ) -> AsyncVM:
+        """Create a VM. By default, it returns once the VM runs commands.
+
+        Tag-scoped API keys may run this command.
+
+        Args:
+            comment: short note about the VM (max 200 bytes)
+            cpu: number of CPUs (default 2; run 'billing plan' for plan limits)
+            disk: disk size (e.g., 20, 20GB, 50G)
+            env: environment variable in KEY=VALUE format (can be specified multiple
+                times)
+            image: container image (server default: exeuntu)
+            integrations: integration name to attach
+            memory: memory allocation (e.g., 4, 4GB, 8G)
+            name: VM name (auto-generated if not specified)
+            no_pool: use ordinary placement (not available on plans that place new VMs
+                in pools)
+            pool: create the VM in one of your team's pools (see ``exe.pool.list()``)
+            prompt: initial prompt to send to Shelley after VM creation (requires an
+                image with Shelley, like exeuntu)
+            registry_auth: private container registry credentials as USERNAME:PASSWORD
+                (e.g. octocat:ghp_xxx) for the registry hosting ``image``
+            setup_script: setup script to run on first boot (max 10KiB)
+            standalone: create a standalone VM with its own reserved capacity (requires
+                a plan with standalone VMs and team approval)
+            tags: tag to add to the VM
+            email: email you about the VM, as the command line does. By default, it does
+                not.
+            wait_until: "ssh" (the default) returns once the VM runs commands; "setup"
+                also waits for its setup script to finish, and succeed; "created"
+                returns at once. Waiting needs ssh permission, and raises VMReadyError
+                if the VM does not become ready.
+            timeout: seconds to wait for readiness; by default 60, or 600 for "setup".
+            keep_on_failure: keep a VM that does not become ready, for debugging:
+                VMReadyError.vm is it. By default, it is deleted, as it is when the wait
+                is interrupted.
+        """
+        check_ready(wait_until, timeout)
+        result = await self._t.call(
+            "new",
+            [],
+            [
+                ("comment", "string", comment),
+                ("cpu", "number", cpu),
+                ("disk", "string", disk),
+                ("env", "repeated", env_flags(env)),
+                ("image", "string", image),
+                ("integration", "repeated", integrations),
+                ("memory", "string", memory),
+                ("name", "string", name),
+                ("no-pool", "bool", no_pool or None),
+                ("pool", "string", pool),
+                ("prompt", "string", prompt),
+                ("registry-auth", "string", registry_auth),
+                ("setup-script", "string", setup_script.replace("\\", "\\\\") if setup_script is not None else None),
+                ("standalone", "bool", standalone or None),
+                ("tag", "repeated", tags),
+                ("no-email", "bool", None if email else True),
+            ],
+            json=True,
+        )
+        vm = AsyncVM(self._t, vm_info(result, "new"), owned=True)
+        return await vm._created(wait_until, timeout, keep_on_failure)
+
+    async def whoami(self) -> t.WhoamiResponse:
+        """Show user information (email, keys, etc).
+
+        CLI: ``whoami``
+
+        Tag-scoped API keys may run this command.
+        """
+        result: t.WhoamiResponse = await self._t.call("whoami", [], json=True)
+        return result
+
+    async def set_region(self, region_code: str) -> Any:
+        """Set your preferred region for new VMs.
+
+        CLI: ``set-region <region-code>``
+        """
+        return await self._t.call("set-region", [region_code])
+
+    async def browser(self, *, qr: bool = False) -> Any:
+        """Generate a magic link to log in to the website.
+
+        CLI: ``browser``
+
+        Args:
+            qr: show QR code for the URL
+        """
+        return await self._t.call("browser", [], [("qr", "bool", qr or None)])
+
+
+class _AsyncDomain:
+    """``domain`` commands."""
+
+    def __init__(self, t: _AsyncTransport) -> None:
+        self._t = t
+
+    async def ls(self, *args: str, all: bool = False) -> Any:
+        """List custom domains for a VM (or -a for all your VMs).
+
+        CLI: ``domain ls <vm> | domain ls -a``
+
+        Args:
+            all: list domains across all your VMs
+        """
+        return await self._t.call("domain ls", [args], [("a", "bool", all or None)])
+
+
+class _AsyncSshKey:
+    """``ssh-key`` commands."""
+
+    def __init__(self, t: _AsyncTransport) -> None:
+        self._t = t
+
+    async def list(self) -> Any:
+        """List all SSH keys associated with your account.
+
+        CLI: ``ssh-key list``
+
+        Tag-scoped API keys may run this command.
+        """
+        return await self._t.call("ssh-key list", [])
+
+    async def add(self, public_key: str, *, tag: str | None = None) -> Any:
+        """Add a new SSH key to your account.
+
+        CLI: ``ssh-key add [--tag=TAG] <public-key>``
+
+        Tag-scoped API keys may run this command.
+
+        Args:
+            tag: scope key to VMs with this tag
+        """
+        return await self._t.call("ssh-key add", [public_key], [("tag", "string", tag)])
+
+    async def remove(self, key: str) -> Any:
+        """Remove an SSH key from your account.
+
+        CLI: ``ssh-key remove <name|fingerprint|public-key>``
+
+        Tag-scoped API keys may run this command.
+        """
+        return await self._t.call("ssh-key remove", [key])
+
+    async def rename(self, old_name: str, new_name: str) -> Any:
+        """Rename an SSH key.
+
+        CLI: ``ssh-key rename <old-name> <new-name>``
+
+        Tag-scoped API keys may run this command.
+        """
+        return await self._t.call("ssh-key rename", [old_name, new_name])
+
+    async def generate_api_key(
+        self,
+        *,
+        cmds: str | None = None,
+        exp: str | None = None,
+        label: str | None = None,
+        vm: str | None = None,
+    ) -> Any:
+        """Generate an API key for the exe.dev HTTPS API or for a specific VM.
+
+        CLI: ``ssh-key generate-api-key [--label=NAME] [--vm=VMNAME] [--cmds=CMD1,CMD2] [--exp=30d]``
+
+        Tag-scoped API keys may run this command.
+
+        Args:
+            cmds: comma-separated list of allowed commands (empty = defaults)
+            exp: expiry duration (e.g. 30d, 1y) or 'never'
+            label: label for this token's SSH key
+            vm: scope key to a VM (authenticates to its HTTPS endpoints instead of
+                exe.dev commands)
+        """
+        return await self._t.call(
+            "ssh-key generate-api-key",
+            [],
+            [
+                ("cmds", "string", cmds),
+                ("exp", "string", exp),
+                ("label", "string", label),
+                ("vm", "string", vm),
+            ],
+        )
+
+
+class _AsyncIntegrations:
+    """``integrations`` commands."""
+
+    def __init__(self, t: _AsyncTransport) -> None:
+        self._t = t
+        self.setup = _AsyncIntegrationsSetup(self._t)
+
+    async def list(self, *, usage: bool = False) -> Any:
+        """List your integrations.
+
+        CLI: ``integrations list [--json [--usage]]``
+
+        Tag-scoped API keys may run this command.
+
+        Args:
+            usage: include per-VM usage (lastUsedAt, usedByVMs); JSON only
+        """
+        return await self._t.call("integrations list", [], [("usage", "bool", usage or None)])
+
+    async def add(
+        self,
+        type: str,
+        *,
+        act_as_user: bool = False,
+        attach: Sequence[str] | None = None,
+        bearer: str | None = None,
+        comment: str | None = None,
+        default: bool = False,
+        fields: str | None = None,
+        for_: str | None = None,
+        headers: Sequence[str] | None = None,
+        host_keys: Sequence[str] | None = None,
+        name: str | None = None,
+        no_auth: bool = False,
+        peer: bool = False,
+        readonly: bool = False,
+        repository: str | None = None,
+        strip_prefix: str | None = None,
+        target: str | None = None,
+        team: bool = False,
+    ) -> Any:
+        """Add a new integration.
+
+
+
+        CLI: ``integrations add <type> [--default | --name=<name> [--team] [args...]]``
+
+        Args:
+            act_as_user: authenticate as your GitHub user instead of the exe.dev app
+                (github only); pushes and API calls are attributed to your GitHub
+                account
+            attach: attach to a spec (vm:<name>, tag:<name>, or auto:all)
+            bearer: bearer token (shorthand for ``headers=["Authorization:Bearer
+                TOKEN"]``; combines with ``headers``)
+            comment: optional free-form comment stored with the integration
+            default: install the canonical reflection integration with all fields;
+                attaches to auto:all unless ``attach=["vm:<name>"]`` is supplied; no
+                other customization
+            fields: comma-separated reflection fields to expose (email, integrations,
+                tags, comment, default_port); 'all' exposes every field including ones
+                added in the future; 'none' disables every field (server default: all)
+            for_: time-box every ``attach`` to a duration from now (e.g. 2h, 45m);
+                access lapses automatically
+            headers: header to inject (e.g. X-Auth:secret)
+            host_keys: host keys for ssh-key: authorized_keys or known_hosts lines
+                (hostnames are ignored), or '*' for any
+            name: integration name (required unless ``default=True``)
+            no_auth: create an endpoint integration with no injected authentication
+            peer: authenticate with a generated API key scoped to the target VM;
+                combines with ``headers``/``bearer``
+            readonly: restrict the integration to read access (github only); git push
+                and write API calls are rejected
+            repository: GitHub repository in owner/repo format (required for github)
+            strip_prefix: path prefix to strip from each request before forwarding
+                (http-proxy only; e.g. /api/v3 makes /api/v3/users reach the target as
+                /users)
+            target: target URL (required for http-proxy)
+            team: create as a team integration
+        """
+        return await self._t.call(
+            "integrations add",
+            [type],
+            [
+                ("act-as-user", "bool", act_as_user or None),
+                ("attach", "repeated", attach),
+                ("bearer", "string", bearer),
+                ("comment", "string", comment),
+                ("default", "bool", default or None),
+                ("fields", "string", fields),
+                ("for", "string", for_),
+                ("header", "repeated", headers),
+                ("host-key", "repeated", host_keys),
+                ("name", "string", name),
+                ("no-auth", "bool", no_auth or None),
+                ("peer", "bool", peer or None),
+                ("readonly", "bool", readonly or None),
+                ("repository", "string", repository),
+                ("strip-prefix", "string", strip_prefix),
+                ("target", "string", target),
+                ("team", "bool", team or None),
+            ],
+        )
+
+    async def remove(self, name: str, *, team: bool = False) -> Any:
+        """Remove an integration.
+
+        CLI: ``integrations remove <name> [--team]``
+
+        Args:
+            team: operate on a team integration
+        """
+        return await self._t.call("integrations remove", [name], [("team", "bool", team or None)])
+
+    async def test(self, name: str, *, team: bool = False) -> Any:
+        """Test an integration's credential (connection check).
+
+        CLI: ``integrations test <name> [--team]``
+
+        Args:
+            team: operate on a team integration
+        """
+        return await self._t.call("integrations test", [name], [("team", "bool", team or None)])
+
+    async def edit(
+        self,
+        name: str,
+        *args: str,
+        act_as_user: bool = False,
+        bearer: str | None = None,
+        clear_header: bool = False,
+        comment: str | None = None,
+        fields: str | None = None,
+        headers: Sequence[str] | None = None,
+        host_keys: Sequence[str] | None = None,
+        no_auth: bool = False,
+        readonly: bool = False,
+        repository: str | None = None,
+        strip_prefix: str | None = None,
+        target: str | None = None,
+        team: bool = False,
+        webhook_url: str | None = None,
+    ) -> Any:
+        """Edit an integration.
+
+
+
+        CLI: ``integrations edit <name> [--team] [args...]``
+
+        Args:
+            act_as_user: authenticate as your GitHub user instead of the exe.dev app
+                (github only)
+            bearer: bearer token (shorthand for ``headers=["Authorization:Bearer
+                TOKEN"]``; combines with ``headers``)
+            clear_header: remove injected headers for http-proxy
+            comment: free-form comment stored with the integration
+            fields: comma-separated reflection fields to expose (email, integrations,
+                tags, comment, default_port); 'all' exposes every field including ones
+                added in the future; 'none' disables every field
+            headers: header to inject for http-proxy; replaces all existing headers
+            host_keys: replacement host keys for ssh-key; replaces the whole list; one -
+                reads them piped in
+            no_auth: remove injected authentication for http-proxy
+            readonly: restrict the integration to read access (github only)
+            repository: GitHub repository in owner/repo format
+            strip_prefix: path prefix to strip from each request before forwarding
+                (http-proxy only; e.g. /api/v3; empty clears it)
+            target: target URL for http-proxy
+            team: edit a team integration
+            webhook_url: replacement Slack or Discord webhook URL
+        """
+        return await self._t.call(
+            "integrations edit",
+            [name, args],
+            [
+                ("act-as-user", "bool", act_as_user or None),
+                ("bearer", "string", bearer),
+                ("clear-header", "bool", clear_header or None),
+                ("comment", "string", comment),
+                ("fields", "string", fields),
+                ("header", "repeated", headers),
+                ("host-key", "repeated", host_keys),
+                ("no-auth", "bool", no_auth or None),
+                ("readonly", "bool", readonly or None),
+                ("repository", "string", repository),
+                ("strip-prefix", "string", strip_prefix),
+                ("target", "string", target),
+                ("team", "bool", team or None),
+                ("webhook-url", "string", webhook_url),
+            ],
+        )
+
+    async def attach(
+        self,
+        name: str,
+        spec: str,
+        *,
+        for_: str | None = None,
+        team: bool = False,
+        until: str | None = None,
+    ) -> Any:
+        """Attach an integration to a VM, tag, or all VMs.
+
+        A <spec> controls where the integration is mounted:
+          vm:<vm-name>   attach to a specific VM (personal only)
+          tag:<tag-name> attach to every VM with the given tag
+          auto:all       attach to all current and future VMs (personal only)
+
+        You can attach the same integration multiple times with different specs.
+        Team integrations only support tag:<tag-name>.
+
+        A grant can be time-boxed with ``for_=<duration>`` or ``until=<RFC3339>``;
+        when it lapses, access stops immediately, with nothing to revoke.
+        Re-attaching the same spec with a new ``for_``/``until`` extends or shortens it.
+
+        CLI: ``integrations attach <name> <spec> [--team] [--for <duration> | --until <time>]``
+
+        Args:
+            for_: time-box the attachment to a duration from now (e.g. 2h, 45m); access
+                lapses automatically
+            team: operate on a team integration
+            until: time-box the attachment until an RFC3339 instant (e.g.
+                2026-08-03T20:00:00Z)
+        """
+        return await self._t.call(
+            "integrations attach",
+            [name, spec],
+            [
+                ("for", "string", for_),
+                ("team", "bool", team or None),
+                ("until", "string", until),
+            ],
+        )
+
+    async def detach(self, name: str, spec: str, *, team: bool = False) -> Any:
+        """Detach an integration from a VM, tag, or all VMs.
+
+        CLI: ``integrations detach <name> <spec> [--team]``
+
+        Args:
+            team: operate on a team integration
+        """
+        return await self._t.call("integrations detach", [name, spec], [("team", "bool", team or None)])
+
+    async def rename(self, name: str, new_name: str, *, team: bool = False) -> Any:
+        """Rename an integration.
+
+        CLI: ``integrations rename <name> <new-name> [--team]``
+
+        Args:
+            team: operate on a team integration
+        """
+        return await self._t.call(
+            "integrations rename",
+            [name, new_name],
+            [("team", "bool", team or None)],
+        )
+
+    async def catalog(self, query: str | None = None) -> Any:
+        """Browse the catalog of ready-made service integrations.
+
+        CLI: ``integrations catalog [service-or-search-term]``
+        """
+        return await self._t.call("integrations catalog", [query])
+
+
+class _AsyncIntegrationsSetup:
+    """``integrations setup`` commands."""
+
+    def __init__(self, t: _AsyncTransport) -> None:
+        self._t = t
+
+    async def github(self, *, delete: bool = False, list: bool = False, verify: bool = False) -> Any:
+        """Set up GitHub integration.
+
+        CLI: ``integrations setup github [--list|--verify|-d]``
+
+        Args:
+            delete: disconnect GitHub account
+            list: list connected GitHub accounts
+            verify: verify GitHub connections are working
+        """
+        return await self._t.call(
+            "integrations setup github",
+            [],
+            [
+                ("delete", "bool", delete or None),
+                ("list", "bool", list or None),
+                ("verify", "bool", verify or None),
+            ],
+        )
+
+    async def chatgpt(
+        self,
+        *,
+        delete: bool = False,
+        list: bool = False,
+        name: str | None = None,
+        verify: bool = False,
+    ) -> Any:
+        """Set up ChatGPT account access for LLM integrations.
+
+        CLI: ``integrations setup chatgpt [--name=<account-name>|--list|--verify|-d]``
+
+        Args:
+            delete: disconnect ChatGPT account
+            list: list connected ChatGPT accounts
+            name: local ChatGPT account name (default chatgpt)
+            verify: verify ChatGPT connections are working
+        """
+        return await self._t.call(
+            "integrations setup chatgpt",
+            [],
+            [
+                ("delete", "bool", delete or None),
+                ("list", "bool", list or None),
+                ("name", "string", name),
+                ("verify", "bool", verify or None),
+            ],
+        )
+
+
+class _AsyncTeam:
+    """``team`` commands."""
+
+    def __init__(self, t: _AsyncTransport) -> None:
+        self._t = t
+        self.billing = _AsyncTeamBilling(self._t)
+        self.auth = _AsyncTeamAuth(self._t)
+        self.settings = _AsyncTeamSettings(self._t)
+        self.vm = _AsyncTeamVm(self._t)
+
+    async def __call__(self) -> Any:
+        """View and manage your team."""
+        return await self._t.call("team", [])
+
+    async def disable(self, *, yes: bool = False) -> Any:
+        """Disband your team.
+
+        CLI: ``team disable``
+
+        Args:
+            yes: skip the confirmation prompt (required for non-interactive use, e.g.
+                the web UI)
+        """
+        return await self._t.call("team disable", [], [("yes", "bool", yes or None)])
+
+    async def members(self) -> Any:
+        """List team members.
+
+        CLI: ``team members``
+        """
+        return await self._t.call("team members", [])
+
+    async def usage(self) -> Any:
+        """Show team pool, disk, and bandwidth usage for the billing period.
+
+        CLI: ``team usage``
+        """
+        return await self._t.call("team usage", [])
+
+    async def add(self, email: str, role: Literal["user", "admin", "billing_owner"] | None = None) -> Any:
+        """Add a user to the team.
+
+        CLI: ``team add <email> [<user|admin|billing_owner>]``
+        """
+        return await self._t.call("team add", [email, role])
+
+    async def remove(self, email: str, *, transfer_vms_to: str | None = None) -> Any:
+        """Remove a user from the team.
+
+        CLI: ``team remove <email> [--transfer-vms-to <email>]``
+
+        Args:
+            transfer_vms_to: transfer the member's VMs to this team member before
+                removing them
+        """
+        return await self._t.call(
+            "team remove",
+            [email],
+            [("transfer-vms-to", "string", transfer_vms_to)],
+        )
+
+    async def role(self, email: str, role: Literal["user", "admin", "billing_owner"]) -> Any:
+        """Change a team member's role.
+
+        CLI: ``team role <email> <user|admin|billing_owner>``
+        """
+        return await self._t.call("team role", [email, role])
+
+    async def rename(self, name: str) -> Any:
+        """Rename your team.
+
+        CLI: ``team rename <name>``
+        """
+        return await self._t.call("team rename", [name])
+
+    async def transfer(self, vm_name: str, target_email: str) -> Any:
+        """Transfer a VM to another team member.
+
+        CLI: ``team transfer <vm_name> <target_email>``
+        """
+        return await self._t.call("team transfer", [vm_name, target_email])
+
+
+class _AsyncTeamBilling:
+    """``team billing`` commands."""
+
+    def __init__(self, t: _AsyncTransport) -> None:
+        self._t = t
+
+    async def plan(self, *, all: bool = False) -> Any:
+        """Show your team's plan.
+
+        CLI: ``team billing plan [--all]``
+
+        Args:
+            all: list the plans you can switch to
+        """
+        return await self._t.call("team billing plan", [], [("all", "bool", all or None)])
+
+    async def update(
+        self,
+        *,
+        address_city: str | None = None,
+        address_country: str | None = None,
+        address_line1: str | None = None,
+        address_line2: str | None = None,
+        address_postal_code: str | None = None,
+        address_state: str | None = None,
+        business_name: str | None = None,
+        email: str | None = None,
+        name: str | None = None,
+        phone: str | None = None,
+        tax_id_type: str | None = None,
+        tax_id_value: str | None = None,
+    ) -> Any:
+        """Update team billing information.
+
+        CLI: ``team billing update [--email=<email>] [--name=<name>] [--business-name=<name>] [--phone=<phone>] [--address-line1=<line>] [--address-line2=<line>] [--address-city=<city>] [--address-state=<state>] [--address-postal-code=<code>] [--address-country=<country>] [--tax-id-type=<type>] [--tax-id-value=<value>]``
+
+        Args:
+            address_city: billing address city
+            address_country: billing address country code
+            address_line1: billing address line 1
+            address_line2: billing address line 2
+            address_postal_code: billing address postal code
+            address_state: billing address state or province
+            business_name: business name shown on invoices
+            email: billing email shown on invoices
+            name: customer name shown on invoices
+            phone: phone number shown on invoices
+            tax_id_type: tax ID type shown on invoices (e.g. eu_vat, pl_nip, us_ein)
+            tax_id_value: tax ID value shown on invoices
+        """
+        return await self._t.call(
+            "team billing update",
+            [],
+            [
+                ("address-city", "string", address_city),
+                ("address-country", "string", address_country),
+                ("address-line1", "string", address_line1),
+                ("address-line2", "string", address_line2),
+                ("address-postal-code", "string", address_postal_code),
+                ("address-state", "string", address_state),
+                ("business-name", "string", business_name),
+                ("email", "string", email),
+                ("name", "string", name),
+                ("phone", "string", phone),
+                ("tax-id-type", "string", tax_id_type),
+                ("tax-id-value", "string", tax_id_value),
+            ],
+        )
+
+
+class _AsyncTeamAuth:
+    """``team auth`` commands."""
+
+    def __init__(self, t: _AsyncTransport) -> None:
+        self._t = t
+
+    async def __call__(self) -> Any:
+        """View and manage team auth settings.
+
+        CLI: ``team auth``
+        """
+        return await self._t.call("team auth", [])
+
+    async def require_oidc(self, mode: Literal["web", "off"]) -> Any:
+        """Require OIDC for web login (web|off).
+
+        CLI: ``team auth require-oidc <web|off>``
+        """
+        return await self._t.call("team auth require-oidc", [mode])
+
+    async def set(
+        self,
+        provider: Literal["default", "google", "oidc"],
+        *,
+        client_id: str | None = None,
+        client_secret: str | None = None,
+        display_name: str | None = None,
+        issuer_url: str | None = None,
+    ) -> Any:
+        """Set the team auth provider (default, google, oidc).
+
+        CLI: ``team auth set <default|google|oidc> [--issuer-url=<url> --client-id=<id> --client-secret=<secret>]``
+
+        Args:
+            client_id: OIDC client ID
+            client_secret: OIDC client secret
+            display_name: display name for the SSO provider
+            issuer_url: OIDC issuer URL (e.g. https://accounts.google.com)
+        """
+        return await self._t.call(
+            "team auth set",
+            [provider],
+            [
+                ("client-id", "string", client_id),
+                ("client-secret", "string", client_secret),
+                ("display-name", "string", display_name),
+                ("issuer-url", "string", issuer_url),
+            ],
+        )
+
+
+class _AsyncTeamSettings:
+    """``team settings`` commands."""
+
+    def __init__(self, t: _AsyncTransport) -> None:
+        self._t = t
+        self.vm_placement = _AsyncTeamSettingsVmPlacement(self._t)
+
+    async def __call__(self) -> Any:
+        """View and manage team settings.
+
+        CLI: ``team settings``
+        """
+        return await self._t.call("team settings", [])
+
+    async def standalone(self, who: Literal["off", "admins-only", "all-users"]) -> Any:
+        """Set who can create standalone VMs.
+
+        CLI: ``team settings standalone <off|admins-only|all-users>``
+        """
+        return await self._t.call("team settings standalone", [who])
+
+    async def llm_gateway(self, enabled: bool) -> Any:
+        """Allow or block the exe.dev LLM gateway (your own API keys are unaffected).
+
+        CLI: ``team settings llm-gateway <on|off>``
+        """
+        return await self._t.call("team settings llm-gateway", [on_off(enabled)])
+
+    async def core_sharing(self, enabled: bool) -> Any:
+        """Allow team VMs to share CPU cores with each other.
+
+        CLI: ``team settings core-sharing <on|off>``
+        """
+        return await self._t.call("team settings core-sharing", [on_off(enabled)])
+
+    async def vm_sharing(self, who: Literal["admins-only", "all-members"]) -> Any:
+        """Set who can share team VMs.
+
+        CLI: ``team settings vm-sharing <admins-only|all-members>``
+        """
+        return await self._t.call("team settings vm-sharing", [who])
+
+    async def session_length(self, length: str) -> Any:
+        """Set how long members stay signed in on the web and mobile apps.
+
+        CLI: ``team settings session-length <length>``
+        """
+        return await self._t.call("team settings session-length", [length])
+
+    async def auto_join(self, enabled: bool) -> Any:
+        """Allow users from your email domain to join this team on signup.
+
+        CLI: ``team settings auto-join <on|off>``
+        """
+        return await self._t.call("team settings auto-join", [on_off(enabled)])
+
+
+class _AsyncTeamSettingsVmPlacement:
+    """``team settings vm-placement`` commands."""
+
+    def __init__(self, t: _AsyncTransport) -> None:
+        self._t = t
+
+    async def __call__(self) -> Any:
+        """View and manage automatic VM placement.
+
+        CLI: ``team settings vm-placement``
+        """
+        return await self._t.call("team settings vm-placement", [])
+
+    async def default(self) -> Any:
+        """Use ordinary VM placement.
+
+        CLI: ``team settings vm-placement default``
+        """
+        return await self._t.call("team settings vm-placement default", [])
+
+    async def pool(self, name: str) -> Any:
+        """Send bare new commands to a shared team pool.
+
+        CLI: ``team settings vm-placement pool <name>``
+        """
+        return await self._t.call("team settings vm-placement pool", [name])
+
+    async def member_pool(self, *, cpus: int | None = None, max_vms: int | None = None) -> Any:
+        """Create or reuse one team pool per member for bare new commands.
+
+        CLI: ``team settings vm-placement member-pool --cpus=N [--max-vms=N]``
+
+        Args:
+            cpus: CPUs to reserve for each member pool (required)
+            max_vms: maximum VMs in each member pool (Work defaults to 25 per vCPU, up
+                to 1000) (server default: 100)
+        """
+        return await self._t.call(
+            "team settings vm-placement member-pool",
+            [],
+            [("cpus", "number", cpus), ("max-vms", "number", max_vms)],
+        )
+
+    async def poolless(self) -> Any:
+        """Keep bare new commands outside pools while migrating (legacy).
+
+        CLI: ``team settings vm-placement poolless``
+        """
+        return await self._t.call("team settings vm-placement poolless", [])
+
+
+class _AsyncTeamVm:
+    """``team vm`` commands."""
+
+    def __init__(self, t: _AsyncTransport) -> None:
+        self._t = t
+
+    async def ls(
+        self,
+        value: str | None = None,
+        *,
+        group: Literal["none", "tag", "region", "type", "user", "access"] | None = None,
+        long: bool = False,
+    ) -> Any:
+        """List all VMs across your team.
+
+        CLI: ``team vm ls [-l] [--group=tag|region|type|user|access] [name|pattern]``
+
+        Tag-scoped API keys may run this command.
+
+        Args:
+            group: group VMs by none|tag|region|type|user|access (server default: none)
+            long: show detailed information
+        """
+        return await self._t.call(
+            "team vm ls",
+            [value],
+            [("group", "string", group), ("l", "bool", long or None)],
+        )
+
+
+class _AsyncPool:
+    """``pool`` commands."""
+
+    def __init__(self, t: _AsyncTransport) -> None:
+        self._t = t
+
+    async def new(
+        self,
+        name: str,
+        *,
+        cpus: int | None = None,
+        max_vms: int | None = None,
+        region: str | None = None,
+    ) -> Any:
+        """Create a pool: reserved capacity for your team's VMs.
+
+        CLI: ``pool new <name> --cpus=N [--region=<region>] [--max-vms=M]``
+
+        Args:
+            cpus: number of CPUs reserved for the pool (required; an even number of
+                vCPUs from 2 through 512 (2, 4, 6, and so on; memory is 2 GiB per vCPU))
+            max_vms: maximum VMs in the pool (Work defaults to the size limit of up to
+                25 VMs per vCPU, capped at 1000 VMs) (server default: 100)
+            region: region code for the pool (required unless your team has dedicated
+                hosts, which decide the region)
+        """
+        return await self._t.call(
+            "pool new",
+            [name],
+            [
+                ("cpus", "number", cpus),
+                ("max-vms", "number", max_vms),
+                ("region", "string", region),
+            ],
+        )
+
+    async def hosts(self) -> Any:
+        """Show your team's dedicated hosts, where its new pools are placed.
+
+        CLI: ``pool hosts``
+        """
+        return await self._t.call("pool hosts", [])
+
+    async def list(self, pool_name: str | None = None, *, range: str | None = None, usage: bool = False) -> Any:
+        """List your team's pools, or show live or historical usage with ``usage=True``.
+
+        CLI: ``pool list [pool-name] [--usage [--range=live|24h|7d|30d]]``
+
+        Args:
+            range: statistics range: live, 24h, 7d, or 30d (requires ``usage=True``)
+                (server default: live)
+            usage: show live or historical CPU and starvation statistics
+        """
+        return await self._t.call(
+            "pool list",
+            [pool_name],
+            [("range", "string", range), ("usage", "bool", usage or None)],
+        )
+
+    async def adopt(self, *, pool: str | None = None, vm: str | None = None) -> Any:
+        """Adopt a VM into a pool; this can take several minutes.
+
+        CLI: ``pool adopt --vm=<vm-name> --pool=<pool-name>``
+
+        Args:
+            pool: pool to adopt into (required)
+            vm: VM to adopt (required)
+        """
+        return await self._t.call("pool adopt", [], [("pool", "string", pool), ("vm", "string", vm)])
+
+    async def detach(self, *, poolless: bool = False, vm: str | None = None) -> Any:
+        """Detach a VM from its pool into its own standalone capacity (``poolless=True`` leaves it outside any pool).
+
+        CLI: ``pool detach --vm=<vm-name> [--poolless]``
+
+        Args:
+            poolless: leave the VM outside any pool instead of making it standalone
+                (only while your team has poolless VMs)
+            vm: VM to detach from its pool (required)
+        """
+        return await self._t.call(
+            "pool detach",
+            [],
+            [("poolless", "bool", poolless or None), ("vm", "string", vm)],
+        )
+
+    async def resize(
+        self,
+        *args: str,
+        cpus: int | None = None,
+        force: bool = False,
+        max_vms: str | None = None,
+    ) -> Any:
+        """Change a pool's CPU capacity or VM cap.
+
+        CLI: ``pool resize <name> --cpus=N | pool resize <name> --max-vms=N [--force]``
+
+        Args:
+            cpus: new pool size in vCPUs (required unless ``max_vms`` is set; even, from
+                2 up to the placement limit)
+            force: allow ``max_vms`` below the current VM count (does not stop or evict
+                VMs)
+            max_vms: maximum VMs in the pool (Work: at most 25 per vCPU, up to 1000)
+        """
+        return await self._t.call(
+            "pool resize",
+            [args],
+            [
+                ("cpus", "number", cpus),
+                ("force", "bool", force or None),
+                ("max-vms", "string", max_vms),
+            ],
+        )
+
+    async def rename(self, old_name: str, new_name: str) -> Any:
+        """Rename a pool without changing its capacity or VMs.
+
+        CLI: ``pool rename <old-name> <new-name>``
+        """
+        return await self._t.call("pool rename", [old_name, new_name])
+
+    async def delete(self, name: str) -> Any:
+        """Delete a pool (refused while it has VMs; ``force`` detaches them).
+
+        CLI: ``pool delete <name> [--force]``
+        """
+        return await self._t.call("pool delete", [name])
+
+
+class _AsyncBilling:
+    """``billing`` commands."""
+
+    def __init__(self, t: _AsyncTransport) -> None:
+        self._t = t
+        self.credits = _AsyncBillingCredits(self._t)
+        self.payment = _AsyncBillingPayment(self._t)
+        self.invoices = _AsyncBillingInvoices(self._t)
+        self.provider = _AsyncBillingProvider(self._t)
+
+    async def plan(self, *, all: bool = False) -> Any:
+        """Show your current plan and resource limits.
+
+        CLI: ``billing plan [--all]``
+
+        Args:
+            all: list the plans you can switch to
+        """
+        return await self._t.call("billing plan", [], [("all", "bool", all or None)])
+
+    async def usage(self, *, group: str | None = None, range: str | None = None) -> Any:
+        """Show VM resource usage against your plan quotas.
+
+        CLI: ``billing usage [--range=cycle|24h|7d|30d] [--group=vm]``
+
+        Args:
+            group: group usage by: vm
+            range: time range: cycle (current billing cycle), 24h, 7d, or 30d (server
+                default: cycle)
+        """
+        return await self._t.call(
+            "billing usage",
+            [],
+            [("group", "string", group), ("range", "string", range)],
+        )
+
+    async def rewards(self) -> Any:
+        """Show invite rewards you've earned.
+
+        CLI: ``billing rewards``
+        """
+        return await self._t.call("billing rewards", [])
+
+    async def capacity(self, *, cpu: int | None = None, yes: bool = False) -> Any:
+        """Change your subscription capacity.
+
+        CLI: ``billing capacity [--cpu=N] [--yes]``
+
+        Args:
+            cpu: Personal capacity in vCPUs: 2, 4, 8, or 16
+            yes: skip interactive confirmation (required for non-interactive changes)
+        """
+        return await self._t.call(
+            "billing capacity",
+            [],
+            [("cpu", "number", cpu), ("yes", "bool", yes or None)],
+        )
+
+    async def manage(self) -> Any:
+        """Open the billing management page.
+
+        CLI: ``billing manage``
+        """
+        return await self._t.call("billing manage", [])
+
+    async def activate(self) -> Any:
+        """Open the personal plan activation page.
+
+        CLI: ``billing activate``
+        """
+        return await self._t.call("billing activate", [])
+
+    async def update(
+        self,
+        *,
+        address_city: str | None = None,
+        address_country: str | None = None,
+        address_line1: str | None = None,
+        address_line2: str | None = None,
+        address_postal_code: str | None = None,
+        address_state: str | None = None,
+        business_name: str | None = None,
+        email: str | None = None,
+        name: str | None = None,
+        phone: str | None = None,
+        tax_id_type: str | None = None,
+        tax_id_value: str | None = None,
+    ) -> Any:
+        """Update your billing contact information.
+
+        CLI: ``billing update [--email=<email>] [--name=<name>] [--business-name=<name>] [--phone=<phone>] [--address-line1=<line>] [--address-line2=<line>] [--address-city=<city>] [--address-state=<state>] [--address-postal-code=<code>] [--address-country=<country>] [--tax-id-type=<type>] [--tax-id-value=<value>]``
+
+        Args:
+            address_city: billing address city
+            address_country: billing address country code
+            address_line1: billing address line 1
+            address_line2: billing address line 2
+            address_postal_code: billing address postal code
+            address_state: billing address state or province
+            business_name: business name shown on invoices
+            email: billing email shown on invoices
+            name: customer name shown on invoices
+            phone: phone number shown on invoices
+            tax_id_type: tax ID type shown on invoices (e.g. eu_vat, pl_nip, us_ein)
+            tax_id_value: tax ID value shown on invoices
+        """
+        return await self._t.call(
+            "billing update",
+            [],
+            [
+                ("address-city", "string", address_city),
+                ("address-country", "string", address_country),
+                ("address-line1", "string", address_line1),
+                ("address-line2", "string", address_line2),
+                ("address-postal-code", "string", address_postal_code),
+                ("address-state", "string", address_state),
+                ("business-name", "string", business_name),
+                ("email", "string", email),
+                ("name", "string", name),
+                ("phone", "string", phone),
+                ("tax-id-type", "string", tax_id_type),
+                ("tax-id-value", "string", tax_id_value),
+            ],
+        )
+
+    async def receipts(self, *, from_: str | None = None, to: str | None = None) -> Any:
+        """Show credit purchase receipts and purchases (this billing account only).
+
+        CLI: ``billing receipts [--from=<YYYY-MM-DD>] [--to=<YYYY-MM-DD>]``
+
+        Args:
+            from_: start of the period, YYYY-MM-DD
+            to: end of the period, YYYY-MM-DD
+        """
+        return await self._t.call(
+            "billing receipts",
+            [],
+            [("from", "string", from_), ("to", "string", to)],
+        )
+
+    async def statement(self, *, from_: str | None = None, to: str | None = None) -> Any:
+        """Open a consolidated credit purchase statement.
+
+        CLI: ``billing statement [--from=<YYYY-MM-DD>] [--to=<YYYY-MM-DD>]``
+
+        Args:
+            from_: start of the period, YYYY-MM-DD
+            to: end of the period, YYYY-MM-DD
+        """
+        return await self._t.call(
+            "billing statement",
+            [],
+            [("from", "string", from_), ("to", "string", to)],
+        )
+
+
+class _AsyncBillingCredits:
+    """``billing credits`` commands."""
+
+    def __init__(self, t: _AsyncTransport) -> None:
+        self._t = t
+
+    async def __call__(self) -> Any:
+        """Show Shelley credit balances.
+
+        CLI: ``billing credits [usage|transactions|buy]``
+        """
+        return await self._t.call("billing credits", [])
+
+    async def usage(self, *, detail: bool = False, group: str | None = None, month: str | None = None) -> Any:
+        """Show Shelley (LLM) credit spend by model, day, or VM.
+
+        CLI: ``billing credits usage [--month=YYYY-MM] [--group=model|day|box] [--detail]``
+
+        Args:
+            detail: break each group down: models under a day or VM, VMs under a model
+            group: group spend by model, day, or box (server default: model)
+            month: calendar month to report, as YYYY-MM (default: this month, UTC)
+        """
+        return await self._t.call(
+            "billing credits usage",
+            [],
+            [
+                ("detail", "bool", detail or None),
+                ("group", "string", group),
+                ("month", "string", month),
+            ],
+        )
+
+    async def transactions(self, *, limit: str | None = None) -> Any:
+        """Show your credit purchases and gifts.
+
+        CLI: ``billing credits transactions [--limit=N]``
+
+        Args:
+            limit: how many transactions to show, 1-100 (default 20)
+        """
+        return await self._t.call("billing credits transactions", [], [("limit", "string", limit)])
+
+    async def buy(self, dollars: str, *, idempotency_key: str | None = None, yes: bool = False) -> Any:
+        """Buy Shelley credits with your personal payment method.
+
+        CLI: ``billing credits buy <dollars> [--yes]``
+
+        Args:
+            idempotency_key: retry key so a repeated purchase of the same amount charges
+                once
+            yes: skip the confirmation prompt (required when not running interactively)
+        """
+        return await self._t.call(
+            "billing credits buy",
+            [dollars],
+            [
+                ("idempotency-key", "string", idempotency_key),
+                ("yes", "bool", yes or None),
+            ],
+        )
+
+
+class _AsyncBillingPayment:
+    """``billing payment`` commands."""
+
+    def __init__(self, t: _AsyncTransport) -> None:
+        self._t = t
+
+    async def __call__(self) -> Any:
+        """Show your payment methods.
+
+        CLI: ``billing payment [list]``
+        """
+        return await self._t.call("billing payment", [])
+
+    async def list(self) -> Any:
+        """List all payment methods on file.
+
+        CLI: ``billing payment list``
+        """
+        return await self._t.call("billing payment list", [])
+
+    async def remove(self, ref: str) -> Any:
+        """Remove a saved payment method.
+
+        CLI: ``billing payment remove <ref>``
+        """
+        return await self._t.call("billing payment remove", [ref])
+
+    async def default(self, ref: str) -> Any:
+        """Make a saved payment method the default.
+
+        CLI: ``billing payment default <ref>``
+        """
+        return await self._t.call("billing payment default", [ref])
+
+
+class _AsyncBillingInvoices:
+    """``billing invoices`` commands."""
+
+    def __init__(self, t: _AsyncTransport) -> None:
+        self._t = t
+
+    async def __call__(self) -> Any:
+        """Show recent invoices.
+
+        CLI: ``billing invoices``
+        """
+        return await self._t.call("billing invoices", [])
+
+    async def list(self, *, account: str | None = None) -> Any:
+        """List invoices for your personal or team account.
+
+        CLI: ``billing invoices list [--account=personal|team]``
+
+        Args:
+            account: account whose invoices to list: personal or team (server default:
+                personal)
+        """
+        return await self._t.call("billing invoices list", [], [("account", "string", account)])
+
+    async def show(self, id: str, *, vms: bool = False) -> Any:
+        """Show one invoice with its usage breakdown.
+
+        CLI: ``billing invoices show <id> [--vms]``
+
+        Args:
+            vms: list VMs without a pool individually
+        """
+        return await self._t.call("billing invoices show", [id], [("vms", "bool", vms or None)])
+
+
+class _AsyncBillingProvider:
+    """``billing provider`` commands."""
+
+    def __init__(self, t: _AsyncTransport) -> None:
+        self._t = t
+
+    async def link(
+        self,
+        provider: Literal["aws", "azure"],
+        *,
+        size: str | None = None,
+        team_name: str | None = None,
+        token: str | None = None,
+    ) -> Any:
+        """Connect a marketplace subscription to your team.
+
+        CLI: ``billing provider link <aws|azure> --token=<link-token> [--size=<team-size>] [--team-name=<name>]``
+
+        Args:
+            size: team size: no marketplace team plans are available
+            team_name: name for the team to create (only when you have no team yet)
+            token: marketplace link token from the exe.dev link page
+        """
+        return await self._t.call(
+            "billing provider link",
+            [provider],
+            [
+                ("size", "string", size),
+                ("team-name", "string", team_name),
+                ("token", "string", token),
+            ],
+        )
+
+
+class _AsyncInvite:
+    """``invite`` commands."""
+
+    def __init__(self, t: _AsyncTransport) -> None:
+        self._t = t
+
+    async def __call__(self) -> Any:
+        """Manage your invite link and rewards."""
+        return await self._t.call("invite", [])
+
+    async def show(self) -> Any:
+        """Show your active invite link and reward.
+
+        CLI: ``invite show``
+        """
+        return await self._t.call("invite show", [])
+
+    async def link(self) -> Any:
+        """Print only your active invite link.
+
+        CLI: ``invite link``
+        """
+        return await self._t.call("invite link", [])
+
+    async def rewards(self) -> Any:
+        """List invite rewards you can use.
+
+        CLI: ``invite rewards``
+        """
+        return await self._t.call("invite rewards", [])
+
+    async def set_reward(self, reward: Literal["standard", "bonus-credits", "extra-memory", "extra-disk"]) -> Any:
+        """Choose the reward for your invite link.
+
+        CLI: ``invite set-reward standard|bonus-credits|extra-memory|extra-disk``
+        """
+        return await self._t.call("invite set-reward", [reward])
+
+    async def activity(self) -> Any:
+        """Show signups, upgrades, and reward status.
+
+        CLI: ``invite activity``
+        """
+        return await self._t.call("invite activity", [])
+
+    async def request(self) -> Any:
+        """Request more trial invites.
+
+        CLI: ``invite request``
+        """
+        return await self._t.call("invite request", [])
+
+    async def manage(self) -> Any:
+        """Open the invites page.
+
+        CLI: ``invite manage``
+        """
+        return await self._t.call("invite manage", [])
+
+
+class _AsyncVMDomain:
+    """The VM's ``domain`` commands."""
+
+    def __init__(self, vm: AsyncVM) -> None:
+        self._vm = vm
+
+    async def add(self, domain: str, *, wildcard: bool = False) -> t.DomainAddResponse:
+        """Link a custom domain to a VM.
+
+        CLI: ``domain add [--wildcard] <vm> <domain>``
+
+        Args:
+            wildcard: issue a wildcard (*.<parent>) certificate via DNS-01 delegation
+        """
+        result: t.DomainAddResponse = await self._vm._t.call(
+            "domain add",
+            [self._vm.name, domain],
+            [("wildcard", "bool", wildcard or None)],
+            json=True,
+        )
+        return result
+
+    async def remove(self, domain: str) -> t.DomainRmResponse:
+        """Remove a custom domain from a VM.
+
+        CLI: ``domain rm <vm> <domain>``
+        """
+        result: t.DomainRmResponse = await self._vm._t.call("domain rm", [self._vm.name, domain], json=True)
+        return result
+
+
+class _AsyncVMShare:
+    """The VM's ``share`` commands."""
+
+    def __init__(self, vm: AsyncVM) -> None:
+        self._vm = vm
+
+    async def show(self, *, qr: bool = False) -> t.ShareShowResponse:
+        """Show current shares for a VM.
+
+        CLI: ``share show <vm>``
+
+        Tag-scoped API keys may run this command.
+
+        Args:
+            qr: show QR code for the URL
+        """
+        result: t.ShareShowResponse = await self._vm._t.call("share show", [self._vm.name], [("qr", "bool", qr or None)], json=True)
+        return result
+
+    async def port(self, port: int | str | None = None) -> t.SharePortResponse:
+        """Set the HTTP proxy port for a VM.
+
+        CLI: ``share port <vm> [port]``
+
+        Tag-scoped API keys may run this command.
+        """
+        result: t.SharePortResponse = await self._vm._t.call("share port", [self._vm.name, port], json=True)
+        return result
+
+    async def set_public(self) -> t.ShareRouteUpdate:
+        """Make the HTTP proxy publicly accessible.
+
+        CLI: ``share set-public <vm>``
+
+        Tag-scoped API keys may run this command.
+        """
+        result: t.ShareRouteUpdate = await self._vm._t.call("share set-public", [self._vm.name], json=True)
+        return result
+
+    async def set_private(self) -> t.ShareRouteUpdate:
+        """Restrict the HTTP proxy to authenticated users.
+
+        CLI: ``share set-private <vm>``
+
+        Tag-scoped API keys may run this command.
+        """
+        result: t.ShareRouteUpdate = await self._vm._t.call("share set-private", [self._vm.name], json=True)
+        return result
+
+    async def add(
+        self,
+        email: str,
+        *,
+        message: str | None = None,
+        qr: bool = False,
+        root: bool = False,
+    ) -> t.ShareAddResponse:
+        """Share VM with a user via email, or grant shell access with ``root=True``.
+
+        CLI: ``share add <vm> <email|team> [--root] [--message='...']``
+
+        Tag-scoped API keys may run this command.
+
+        Args:
+            message: message to include in share invitation
+            qr: show QR code for the URL
+            root: grant/revoke shell (SSH, Terminal, Shelley) access instead of web-only
+        """
+        result: t.ShareAddResponse = await self._vm._t.call(
+            "share add",
+            [self._vm.name, email],
+            [
+                ("message", "string", message),
+                ("qr", "bool", qr or None),
+                ("root", "bool", root or None),
+            ],
+            json=True,
+        )
+        return result
+
+    async def remove(self, email: str, *, root: bool = False) -> t.ShareRemoveResponse:
+        """Revoke a user's access to a VM, or downgrade shell access to web with ``root=True``.
+
+        CLI: ``share remove <vm> <email|team> [--root]``
+
+        Tag-scoped API keys may run this command.
+
+        Args:
+            root: grant/revoke shell (SSH, Terminal, Shelley) access instead of web-only
+        """
+        result: t.ShareRemoveResponse = await self._vm._t.call(
+            "share remove",
+            [self._vm.name, email],
+            [("root", "bool", root or None)],
+            json=True,
+        )
+        return result
+
+    async def add_link(self, *, qr: bool = False) -> t.ShareLinkCreated:
+        """Create a shareable link for a VM.
+
+        CLI: ``share add-link <vm>``
+
+        Tag-scoped API keys may run this command.
+
+        Args:
+            qr: show QR code for the URL
+        """
+        result: t.ShareLinkCreated = await self._vm._t.call(
+            "share add-link",
+            [self._vm.name],
+            [("qr", "bool", qr or None)],
+            json=True,
+        )
+        return result
+
+    async def remove_link(self, token: str) -> t.ShareMessage:
+        """Revoke a shareable link.
+
+        CLI: ``share remove-link <vm> <token>``
+
+        Tag-scoped API keys may run this command.
+        """
+        result: t.ShareMessage = await self._vm._t.call("share remove-link", [self._vm.name, token], json=True)
+        return result
+
+    async def receive_email(
+        self,
+        enabled: bool | None = None,
+        *,
+        reply_policy: str | None = None,
+    ) -> t.ShareReceiveEmailResponse:
+        """Enable or disable inbound email for a VM.
+
+        CLI: ``share receive-email <vm> [on|off] [--reply-policy=all|known|owner|none]``
+
+        Tag-scoped API keys may run this command.
+
+        Args:
+            reply_policy: restrict who the VM may email: all|known|owner|none
+        """
+        result: t.ShareReceiveEmailResponse = await self._vm._t.call(
+            "share receive-email",
+            [self._vm.name, on_off(enabled)],
+            [("reply-policy", "string", reply_policy)],
+            json=True,
+        )
+        return result
+
+
+class _AsyncVMShelley:
+    """The VM's ``shelley`` commands."""
+
+    def __init__(self, vm: AsyncVM) -> None:
+        self._vm = vm
+
+    async def install(self) -> t.ShelleyInstallResponse:
+        """Install or upgrade Shelley to the current version.
+
+        CLI: ``shelley install <vm>``
+
+        Tag-scoped API keys may run this command.
+        """
+        result: t.ShelleyInstallResponse = await self._vm._t.call("shelley install", [self._vm.name], json=True)
+        return result