hyperun 0.2.0__py3-none-any.whl

hyperun/cli.py

@@ -0,0 +1,1202 @@
+"""The `hyperun` command: argument parsing, and deciding what to print.
+
+END-TO-END FLOW of one `hyperun submit -f job.yaml`:
+
+  1. `main()` parses the arguments and dispatches to `cmd_submit`.
+  2. `config.load()` finds the server URL and the token, from the environment or
+     from `~/.config/hyperun/config.json`.
+  3. `build_submit_body()` reads the file, applies any flag overrides on top,
+     and produces the request body. It does NOT validate: the server owns that
+     judgement, and a second copy here would eventually disagree with it.
+  4. `Client.submit()` POSTs it.
+  5. The job id, the phase and the result path are printed, or the whole JSON
+     when `--json` was given.
+
+THE COMMANDS, AND WHY EACH EXISTS
+
+  login / logout    store and remove the token. Stage 1 authentication is a
+                    static token an operator hands out, so `login` takes one
+                    rather than opening a browser. When Cognito lands
+                    (`docs/08-plan.md` open item 4) only this command changes.
+  explain / schema  ask the SERVER what it is and what it accepts, rather than
+                    printing something baked in here that can go stale. This is
+                    what makes the tool usable by a coding agent that has read
+                    no documentation (`docs/07-agent-skill.md`).
+  estimate          how long, how much, which GPU. Submits nothing.
+  validate          what is wrong with the job. Submits nothing. Exits 1 when
+                    something would actually stop it, so a script can gate a
+                    submit on it.
+  submit            the point of the whole thing.
+  status            phase, message, which GPU, how many restarts.
+  watch             GPU usage and training progress, read out of the job's own
+                    log. Nothing is stored anywhere for this.
+  stats             what your team has spent. Aggregate only: being on a team
+                    does not let you read a member's jobs.
+  logs              output, optionally followed.
+
+WHAT IS NOT HERE. No `gpus`. Answering it needs a vendor API key in the server
+and a catalogue cache, and a CLI that answered it locally would be the second
+source of truth this design exists to avoid.
+
+EXIT CODES, because a script will read them:
+  0  it worked
+  1  the server refused, or could not be reached
+  2  the command was wrong, or there are no credentials
+
+Grep anchor: DDPSRUN-CLI
+"""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import getpass
+import json
+import time
+import sys
+from typing import Any
+
+from . import __version__
+from . import browser_login
+from . import config
+from .client import Client, ServerError
+
+EXIT_OK = 0
+EXIT_SERVER = 1
+EXIT_USAGE = 2
+
+
+def job_arguments() -> argparse.ArgumentParser:
+    """The arguments that describe a job, shared by three subcommands.
+
+    WHY THIS IS A PARENT PARSER RATHER THAN THREE COPIES. `estimate`,
+    `validate` and `submit` must accept exactly the same job description, so
+    that a user checks a job and then submits THAT job with nothing rewritten
+    in between. Three copies would drift, and the drift would show up as a
+    validate that passes something the submit refuses.
+
+    Returns:
+        A parser with `add_help=False`, to be passed as a `parents=` entry.
+    """
+    shared = argparse.ArgumentParser(add_help=False)
+    shared.add_argument("-f", "--file", help="a YAML or JSON file describing the job")
+    shared.add_argument("--name", help="a name for your own benefit")
+    shared.add_argument("--image", help="container image to run")
+    shared.add_argument(
+        "--arg", action="append", default=[], dest="args_", metavar="ARG",
+        help="one argument to the container. Repeat it, in order.",
+    )
+    shared.add_argument(
+        "--env", action="append", default=[], metavar="KEY=VALUE",
+        help="a non-secret environment variable. Repeatable.",
+    )
+    shared.add_argument(
+        "--secret", action="append", default=[], metavar="NAME",
+        help="the NAME of a stored secret to inject. Never the value. Repeatable.",
+    )
+    shared.add_argument("--gpu-vram", type=int, metavar="GB", help="minimum GPU memory, e.g. 48")
+    shared.add_argument("--gpu-name", metavar="MODEL", help="exact GPU model, e.g. L40S")
+    shared.add_argument(
+        "--gpu-count", type=int, metavar="N", help="how many GPUs PER POD (default 1)"
+    )
+    shared.add_argument(
+        "--capacity-type", choices=["on-demand", "spot"],
+        help="how the machine is bought. YOU decide this. on-demand costs more and is "
+        "not taken away; spot is cheaper and can be reclaimed mid-run. Run "
+        "`hyperun estimate` first — it recommends one and says why. submit refuses "
+        "without it rather than choosing for you.",
+    )
+    # DDPSRUN-VENDOR-CHOICE. The two placement fields that are not capacity type.
+    # The valid names are NOT listed as argparse `choices` on purpose: the server
+    # owns that list and refuses an unknown one with a message naming every name
+    # that would have worked, and a second copy in this file would go stale the
+    # first time a vendor is added.
+    shared.add_argument(
+        "--vendor", action="append", metavar="NAME",
+        help="who the machine may be bought from. Repeat it to allow several; "
+        "omit it entirely for no restriction, which is what every job did before "
+        "this flag existed. aws and runpod can actually run a job; gcp, azure, "
+        "lambda and nebius can only be PRICED, so name one of those only with "
+        "--placement-mode compare.",
+    )
+    # DDPSRUN-REGIONS. Missing until 2026-09-08, so every job this CLI submitted
+    # ran in the operator's one default region and there was no way to say
+    # otherwise -- the same hole `--vendor` filled a day earlier.
+    shared.add_argument(
+        "--region", action="append", metavar="NAME",
+        help="where the machine may be bought, as PACSrun spells it: a bare "
+        "vendor ('gcp') or a vendor and region ('aws/us-east-1'). Repeat it to "
+        "allow several. OMITTING IT IS NOT 'anywhere' -- an AWS ask that names "
+        "no region gets the operator's ONE default region, us-west-2 on this "
+        "deployment. It matters: the H100 is $6.88/hour in us-west-2 and $8.60 "
+        "in ap-northeast-1. `hyperun schema` lists every region on offer.",
+    )
+    shared.add_argument(
+        "--placement-mode", choices=["ordered", "cheapest", "compare"],
+        help="what to do with the candidates. ordered (the default) asks them in "
+        "order and stops at the first that answers, comparing nothing. cheapest "
+        "asks every candidate and buys the cheapest answer. compare asks every "
+        "candidate, ranks them and then STOPS -- nothing is bought and the job "
+        "ends in the phase Compared with the winner and the margin in its "
+        "message. compare is the only mode that costs nothing to run.",
+    )
+    shared.add_argument(
+        "--parallelism", type=int, metavar="N",
+        help="how many pods run at once (default 1). They are independent workers that never "
+        "talk to each other. With --gpu-count this is how a job fills a multi-GPU machine: "
+        "--parallelism 8 --gpu-count 1 may land 4 pods on each of two 4-GPU boxes.",
+    )
+    # DDPSRUN-GROUP. Distributed training. Two flags and not one, because the
+    # size alone says nothing: `--group-size 2` with the default independent
+    # mode is identical to no group at all, and PACSrun treats the two shapes
+    # with opposite scheduling rules.
+    shared.add_argument(
+        "--group-size", type=int, metavar="N",
+        help="how many pods form ONE distributed group. --parallelism divided by "
+        "this is the number of groups, so --parallelism 6 --group-size 2 is three "
+        "groups of two. Needs --group-mode distributed to mean anything.",
+    )
+    shared.add_argument(
+        "--group-mode", choices=("independent", "distributed"),
+        help="independent (default) is pods that never talk. distributed makes "
+        "each group one process group: every pod is given PACSRUN_MASTER_ADDR, "
+        "PACSRUN_MASTER_PORT, PACSRUN_GROUP_RANK and PACSRUN_GROUP_SIZE, and NONE "
+        "starts until the whole group has a machine. Your script passes those to "
+        "its launcher -- nothing translates them for you.",
+    )
+    shared.add_argument("--cpus", help='CPU request, e.g. "4"')
+    shared.add_argument("--memory", help='memory request, e.g. "16Gi"')
+    shared.add_argument(
+        "--expected-hours", type=float, help="your own guess at the runtime, in hours"
+    )
+    # DDPSRUN-CONTINUE-FROM. Chain this job onto a previous one's result path.
+    shared.add_argument(
+        "--continue-from", metavar="JOB_ID",
+        help="the job id of a previous run of YOURS whose result path this job "
+        "should reuse, e.g. job-3e1e34cb042c. Use it to continue a "
+        "multi-iteration run: without it every submit writes to a fresh prefix "
+        "and the resume step finds nothing. Must be a job of yours in the same "
+        "namespace; anything else is refused with 404.",
+    )
+    # The facts the server cannot read out of a container image. Only estimate
+    # and validate use them today, but submit accepts them too so that one file
+    # works for all three.
+    shared.add_argument("--pairs", type=int, help="how many training pairs your dataset holds")
+    shared.add_argument("--epochs", type=int, help="how many passes over the dataset")
+    shared.add_argument(
+        "--row-tokens", type=int, metavar="N",
+        help="average length of ONE response, in tokens. Without it there is no "
+        "runtime estimate.",
+    )
+    shared.add_argument("--cap", type=int, help="--max-len, which decides peak memory")
+    shared.add_argument("--batch-size", type=int, help="per_device_train_batch_size (default 1)")
+    shared.add_argument("--grad-accum", type=int, help="gradient_accumulation_steps (default 8)")
+    shared.add_argument(
+        "--resumable", action="store_true",
+        help="your job can restart from a checkpoint",
+    )
+    shared.add_argument(
+        "--script", metavar="PATH",
+        help="your run.sh. THIS IS WHAT RUNS when you pass no --arg: the job gets "
+        "args ['bash','-lc',<the file's text>]. It also unlocks four more validate "
+        "checks. The text is read and sent; the path is not, and nothing is stored.",
+    )
+    return shared
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Assemble the command line.
+
+    Returns:
+        A parser whose every `help` string is written for someone who has not
+        read anything else. This is the only documentation most users will see.
+    """
+    parser = argparse.ArgumentParser(
+        prog="hyperun",
+        description="Submit a batch job to a GPU we rent for you, and get the results back.",
+        epilog="Run `hyperun explain` for the full description, straight from the server.",
+    )
+    # ON THE TOP-LEVEL PARSER ON PURPOSE, unlike --json below. "which version am
+    # I running" is a question about the INSTALL and not about any one command,
+    # and `hyperun --version` is where every other tool puts it. There was no way
+    # to ask at all before 2026-09-08, which is awkward the moment somebody
+    # reports a bug against a CLI they installed from PyPI.
+    parser.add_argument(
+        "--version", action="version", version=f"hyperun {__version__}",
+        help="print the installed version and exit",
+    )
+    # ★ THE dest IS `subcommand`, NOT `command`, AND THAT IS NOT COSMETIC. The
+    # `shell` subparser has its own positional called `command` -- the shell line
+    # to run -- and argparse writes both into the SAME namespace. With both named
+    # `command` the subparser's REMAINDER overwrote the subcommand name, so
+    # `ddpsrun shell job-x` set args.command to [] and main() printed the
+    # top-level help, while `ddpsrun shell job-x -- nvidia-smi` set it to
+    # ['nvidia-smi'] and main() died on `COMMANDS[['nvidia-smi']]` with
+    # "TypeError: unhashable type: 'list'". Both forms, every version: `shell`
+    # had never once dispatched. Found 2026-09-10 from a user's paste of the
+    # help text where a command should have run.
+    sub = parser.add_subparsers(dest="subcommand", metavar="<command>")
+
+    def add_json_flag(target: argparse.ArgumentParser) -> None:
+        """`--json` goes on each subcommand that has something to print.
+
+        Not on the top-level parser: argparse would require it BEFORE the
+        subcommand (`hyperun --json status X`), which is not the order anyone
+        types, and a subparser redefining it would silently reset it to False.
+        """
+        target.add_argument(
+            "--json", action="store_true",
+            help="print raw JSON instead of a human summary. Use this from a script.",
+        )
+
+    login = sub.add_parser("login", help="sign in and store the result")
+    login.add_argument("--server", required=True, help="the gateway URL, e.g. https://run.example")
+    login.add_argument(
+        "--token",
+        help="skip the browser and use this token. For CI and scripts, which "
+        "have nobody to sign in. Omitting it opens a browser when the server "
+        "supports that, and prompts otherwise so it stays out of shell history.",
+    )
+
+    # ★ THE COMMAND IS `delete` AND `cancel` IS THE OLD SPELLING. It was called
+    # cancel and that name described an intention rather than the action: there
+    # is no cancelled state to move a job into, because the CRD's only stop is
+    # deleting the PacsJob (config/deploy/rbac.yaml, and the phase enum in
+    # api/v1alpha1/pacsjob_types.go carries Pending / Starting / Running /
+    # Recovering / Succeeded / Failed / Compared and nothing else). A person
+    # who reads "cancel" expects the job to still be listed afterwards, and on
+    # 2026-09-09 one asked why a cancelled job showed no cancelled state. The
+    # alias stays because scripts and every document written before today say
+    # `cancel`, and breaking those to rename a verb is not a trade worth making.
+    cancel = sub.add_parser(
+        "delete", aliases=["cancel"],
+        help="delete a job -- it stops and disappears from the list",
+        description="Deletes the PacsJob. That is the only stop the CRD offers: "
+        "PACSrun watches for the object going away and gives back whatever the "
+        "job had rented. There is no cancelled state to look at afterwards, "
+        "because there is no object left to carry one. Files already written to "
+        "the job's result path are NOT deleted.",
+    )
+    cancel.add_argument("job_id", help="the id `submit` printed")
+    cancel.add_argument(
+        "--yes", "-y", action="store_true",
+        help="skip the confirmation. For scripts, which have nobody to answer it.",
+    )
+
+    sub.add_parser("logout", help="delete the stored token")
+    sub.add_parser("explain", help="what this tool is and how to use it (asks the server)")
+    sub.add_parser("schema", help="the exact shape of a submit request (asks the server)")
+
+    job = job_arguments()
+
+    estimate = sub.add_parser(
+        "estimate", parents=[job],
+        help="how long it will take, what it will cost, which GPU. Submits nothing",
+        description="Nothing is submitted. An answer of `unknown` is a real answer: "
+        "the last time we estimated a combination we had never measured, we were 96% out.",
+    )
+    add_json_flag(estimate)
+
+    validate = sub.add_parser(
+        "validate", parents=[job],
+        help="what is wrong with this job. Submits nothing",
+        description="Nothing is submitted. Pass --script to unlock four more checks.",
+    )
+    add_json_flag(validate)
+
+    submit = sub.add_parser(
+        "submit", parents=[job], help="submit a job",
+        description="Give a YAML or JSON file, or build the request from flags, or both. "
+        "Flags win over the file.",
+    )
+    add_json_flag(submit)
+
+    sub.add_parser(
+        "secrets", help="which secret names you can use",
+        description="`secrets: [NAME]` on a submit request is a word that opens "
+        "the server's vault, not a field you fill with a value. This prints the "
+        "words that work: the deployment's own, plus whatever your namespace "
+        "registered with `secret set`. Values are never shown by any command.",
+    )
+
+    # DDPSRUN-USER-SECRET. Registering a value for your own namespace.
+    secret_set = sub.add_parser(
+        "secret-set", help="store a value in your namespace under a name",
+        description="Store one value so your jobs can ask for it by name. It is "
+        "kept in a Kubernetes Secret in YOUR namespace; jobs elsewhere cannot "
+        "name it, and no command ever prints it back.\n\n"
+        "★ THE VALUE IS NEVER AN ARGUMENT. It comes from a file or from stdin, "
+        "because anything on a command line is in your shell history, in `ps` "
+        "output for every user on the machine, and in any terminal recording.",
+    )
+    secret_set.add_argument(
+        "name", help="the environment variable name your script reads, e.g. HF_TOKEN"
+    )
+    secret_set.add_argument(
+        "--from-file", metavar="PATH",
+        help="read the value from this file. Use - for stdin, which is also the "
+        "default when this is omitted.",
+    )
+    secret_set.add_argument(
+        "--expires-at", metavar="WHEN",
+        help="when this value stops working, ISO-8601 (e.g. 2026-09-10T02:27:00Z). "
+        "Worth sending for a TEMPORARY credential -- a federation token, an "
+        "assumed-role session. `validate` then refuses a job that asks for it "
+        "after that time, so the expiry is found before a GPU is rented instead "
+        "of an hour into the run.",
+    )
+
+    secret_rm = sub.add_parser(
+        "secret-rm", help="forget a name your namespace registered",
+        description="Remove one registered value. Do this the moment a "
+        "credential leaks: until it is gone, every job in the namespace can "
+        "still ask for it. An operator's deployment-wide binding cannot be "
+        "removed from here.",
+    )
+    secret_rm.add_argument("name")
+
+    status = sub.add_parser("status", help="how a job is doing")
+    status.add_argument("job_id")
+    add_json_flag(status)
+
+    shell = sub.add_parser(
+        "shell", help="run commands inside a running job's workload",
+        description="Each line is one HTTPS round trip: the server relays it "
+        "through the job's driver pod into the workload container on the "
+        "rented machine and brings the exit code back like ssh. It is NOT a "
+        "TTY — no vim, no top, about 25 seconds per command — because the "
+        "server is a Lambda and cannot hold a terminal open. AWS and GCP "
+        "machine rentals only: a RunPod job is a rented container with no "
+        "machine behind it, and the relay refuses it. ★ PUT OPTIONS BEFORE THE "
+        "JOB ID -- everything after it is sent to the workload as-is, so "
+        "`shell job-x --slot 2` asks pod 0 and passes `--slot 2` to the shell. "
+        "That is refused rather than obeyed.",
+    )
+    shell.add_argument("job", help="the job id, or the PacsJob's Kubernetes name")
+    shell.add_argument("--slot", type=int, default=0, help="which pod of a parallel job")
+    shell.add_argument(
+        "command", nargs=argparse.REMAINDER, metavar="-- COMMAND",
+        help="one shell line to run and exit; leave it off for a prompt",
+    )
+
+    watch = sub.add_parser(
+        "watch", help="GPU usage and training progress",
+        description="Read out of the job's own log. Nothing is stored, so what "
+        "you can see goes back as far as the log does.",
+    )
+    watch.add_argument("job_id")
+    watch.add_argument(
+        "--window", type=int, default=3600, metavar="SECONDS",
+        help="how far back to read (default 3600, max 86400)",
+    )
+    add_json_flag(watch)
+
+    team_stats = sub.add_parser(
+        "stats", help="what your team has spent",
+        description="Aggregate only. Being on a team does not let you read a member's jobs.",
+    )
+    add_json_flag(team_stats)
+
+    logs = sub.add_parser("logs", help="a job's output")
+    logs.add_argument("job_id")
+    logs.add_argument(
+        "-f", "--follow", action="store_true",
+        help="keep printing as new lines arrive. The server cannot stream, so this "
+        "asks again every few seconds and prints what is new.",
+    )
+    logs.add_argument(
+        "--interval", type=float, default=6.0, metavar="SECONDS",
+        help="how often to ask, with --follow (default 6)",
+    )
+
+    return parser
+
+
+def load_job_file(path: str) -> dict[str, Any]:
+    """Read a job description from YAML or JSON.
+
+    Args:
+        path: the file to read. `.json` is parsed as JSON, anything else as
+            YAML — and YAML is a superset of JSON, so a `.txt` holding JSON
+            works too.
+
+    Returns:
+        The parsed mapping.
+
+    Raises:
+        SystemExit: the file is unreadable or is not a mapping. Exiting here
+            rather than raising keeps the error one line instead of a traceback.
+    """
+    try:
+        with open(path, "r", encoding="utf-8") as handle:
+            text = handle.read()
+    except OSError as exc:
+        raise SystemExit(f"cannot read {path}: {exc}") from exc
+
+    try:
+        if path.endswith(".json"):
+            document = json.loads(text)
+        else:
+            import yaml
+
+            document = yaml.safe_load(text)
+    except Exception as exc:  # noqa: BLE001 - json and yaml raise different types
+        raise SystemExit(f"{path} does not parse: {exc}") from exc
+
+    if not isinstance(document, dict):
+        raise SystemExit(f"{path} must contain a mapping, not a {type(document).__name__}")
+    return document
+
+
+def parse_env_pairs(pairs: list[str]) -> dict[str, str]:
+    """Turn `--env KEY=VALUE` arguments into a mapping.
+
+    Args:
+        pairs: the raw strings.
+
+    Returns:
+        A dict. A value containing `=` is kept whole, because
+        `--env ARGS=--lr=1e-5` is a real thing people write.
+
+    Raises:
+        SystemExit: a pair has no `=` at all.
+    """
+    result: dict[str, str] = {}
+    for pair in pairs:
+        key, separator, value = pair.partition("=")
+        if not separator or not key:
+            raise SystemExit(f"--env {pair!r} must be KEY=VALUE")
+        result[key] = value
+    return result
+
+
+def build_submit_body(args: argparse.Namespace) -> dict[str, Any]:
+    """Assemble the request body from a file and the flags on top of it.
+
+    Args:
+        args: the parsed `submit` arguments.
+
+    Returns:
+        The body to POST. Nothing is validated here — the server decides what is
+        acceptable, and a second copy of that judgement in the CLI would drift
+        away from it. The one exception is the shape of `--env`, which has to be
+        parsed before it can be sent at all.
+
+    Raises:
+        SystemExit: neither a file nor the two fields the server requires.
+    """
+    body: dict[str, Any] = load_job_file(args.file) if args.file else {}
+
+    if args.name:
+        body["name"] = args.name
+    if args.image:
+        body["image"] = args.image
+    if args.args_:
+        body["args"] = args.args_
+    if args.env:
+        # Merged, not replaced: a file may carry the ten stable values and a
+        # flag override the one that changes between runs.
+        merged = dict(body.get("env") or {})
+        merged.update(parse_env_pairs(args.env))
+        body["env"] = merged
+    if args.secret:
+        body["secrets"] = sorted(set(body.get("secrets") or []) | set(args.secret))
+    if args.cpus:
+        body["cpus"] = args.cpus
+    if args.memory:
+        body["memory"] = args.memory
+    if args.expected_hours is not None:
+        body["expected_hours"] = args.expected_hours
+    if getattr(args, "parallelism", None) is not None:
+        body["parallelism"] = args.parallelism
+    if getattr(args, "continue_from", None):
+        body["continue_from"] = args.continue_from
+    if (getattr(args, "group_size", None) is not None
+            or getattr(args, "group_mode", None) is not None):
+        # Either flag alone is meaningful: a size with the default mode is
+        # `independent`, which the server drops, and a mode with no size is a
+        # group of one, which it also drops. Sending what was asked for and
+        # letting the server decide what is worth writing keeps one rule in one
+        # place.
+        body["group"] = {
+            "size": args.group_size if args.group_size is not None else 1,
+            "mode": args.group_mode or "independent",
+        }
+    if getattr(args, "capacity_type", None):
+        body["capacity_type"] = args.capacity_type
+    # DDPSRUN-VENDOR-CHOICE. `--vendor` REPLACES the file's list rather than
+    # adding to it, which is the opposite of how `--secret` behaves one screen
+    # up. The two are different in kind: a secret is one more thing to inject and
+    # a union is the obvious reading, while a vendor list is a RESTRICTION, so a
+    # union would silently WIDEN what the file allowed -- `--vendor runpod`
+    # against a file saying `[aws]` would run on either, which is not what
+    # anybody typing that means.
+    if getattr(args, "vendor", None):
+        body["vendors"] = list(dict.fromkeys(args.vendor))
+    if getattr(args, "placement_mode", None):
+        body["placement_mode"] = args.placement_mode
+    # REPLACES the file's list rather than adding to it, for the same reason
+    # --vendor does: a region list is a RESTRICTION, so a union would silently
+    # widen what the file allowed.
+    if getattr(args, "region", None):
+        body["regions"] = list(dict.fromkeys(args.region))
+
+    # A GPU is asked for in exactly one of two styles, by memory or by model.
+    # TWO CASES THAT LOOK ALIKE AND ARE NOT:
+    #   file says one style, a flag says the other  -> the flag is the newer
+    #       intent, so it replaces the file's style.
+    #   BOTH flags on the same command line         -> the user contradicted
+    #       themselves. Picking one would send a job to a GPU they did not ask
+    #       for, so this stops. Found 2026-08-31 by running the CLI against the
+    #       server: the two branches used to erase each other and whichever ran
+    #       last silently won.
+    if args.gpu_vram and args.gpu_name:
+        raise SystemExit(
+            "--gpu-vram and --gpu-name ask for a GPU in two different ways. "
+            "Give one: --gpu-vram 48 for 'at least 48 GB', --gpu-name L40S for "
+            "that exact model."
+        )
+    if args.gpu_vram or args.gpu_name or args.gpu_count:
+        gpu = dict(body.get("gpu") or {})
+        if args.gpu_vram:
+            gpu["vram_gb"] = args.gpu_vram
+            gpu.pop("name", None)
+        if args.gpu_name:
+            gpu["name"] = args.gpu_name
+            gpu.pop("vram_gb", None)
+        if args.gpu_count:
+            gpu["count"] = args.gpu_count
+        body["gpu"] = gpu
+
+    # The facts the server cannot read out of a container image. They live under
+    # `training` in the request, and a flag overrides the file the same way
+    # everything else does.
+    training = dict(body.get("training") or {})
+    for flag, field in (
+        ("pairs", "pairs"), ("epochs", "epochs"), ("row_tokens", "row_tokens"),
+        ("cap", "cap"), ("batch_size", "batch_size"), ("grad_accum", "grad_accum"),
+    ):
+        value = getattr(args, flag, None)
+        if value is not None:
+            training[field] = value
+    if getattr(args, "resumable", False):
+        training["resumable"] = True
+    if training:
+        body["training"] = training
+
+    # `--script run.sh` sends the file's TEXT, not its path. The server has no
+    # way to read a file on the user's laptop.
+    script_path = getattr(args, "script", None)
+    if script_path:
+        try:
+            with open(script_path, "r", encoding="utf-8") as handle:
+                body["script"] = handle.read()
+        except OSError as exc:
+            raise SystemExit(f"cannot read {script_path}: {exc}") from exc
+
+    if not body.get("name") or not body.get("image"):
+        raise SystemExit(
+            "a job needs at least a name and an image. Give them with --name and "
+            "--image, or in a file with -f. `hyperun schema` prints every field."
+        )
+    return body
+
+
+def refreshed(credentials: config.Credentials) -> config.Credentials:
+    """Renew the stored id_token when it is about to expire.
+
+    DDPSRUN-CLI-REFRESH. A Cognito id_token lives an hour. Without this, a
+    command run 61 minutes after `hyperun login` fails with 401 and the person
+    has no idea why. With a refresh token stored, the renewal is silent.
+
+    Args:
+        credentials: what `config.load` returned.
+
+    Returns:
+        The same credentials, or ones carrying a fresh id_token. A static token
+        has no `exp` and comes back untouched, as does anything that cannot be
+        renewed — the request then fails on its own and says so, which is a
+        better error than one from in here.
+    """
+    if not credentials.refresh_token:
+        return credentials
+    try:
+        payload = credentials.token.split(".")[1]
+        payload += "=" * (-len(payload) % 4)
+        claims = json.loads(base64.urlsafe_b64decode(payload).decode())
+        expiry = float(claims["exp"])
+    except Exception:
+        return credentials
+    # 60 seconds of margin, so a token does not expire between this check and
+    # the request it is about to be used on.
+    if time.time() < expiry - 60:
+        return credentials
+
+    try:
+        settings = browser_login.login_config(credentials.server)
+        if not settings.get("enabled"):
+            return credentials
+        tokens = browser_login.exchange(settings, {
+            "grant_type": "refresh_token",
+            "refresh_token": credentials.refresh_token,
+        })
+    except browser_login.LoginError:
+        return credentials
+
+    renewed = config.Credentials(
+        server=credentials.server,
+        token=tokens.id_token or credentials.token,
+        # A refresh does not mint a new refresh token, so keep the one we have.
+        refresh_token=tokens.refresh_token or credentials.refresh_token,
+    )
+    config.save(renewed)
+    return renewed
+
+
+def client_from_config() -> Client:
+    """Build a client, or exit 2 saying how to log in."""
+    try:
+        credentials = config.load()
+    except config.NotLoggedIn as exc:
+        print(exc, file=sys.stderr)
+        raise SystemExit(EXIT_USAGE) from exc
+    credentials = refreshed(credentials)
+    return Client(credentials.server, credentials.token)
+
+
+def cmd_login(args: argparse.Namespace) -> int:
+    """Store the server address and the token.
+
+    The token is read with `getpass` when it was not given on the command line,
+    so it does not end up in the shell's history file.
+    """
+    server = args.server.rstrip("/")
+    refresh = ""
+
+    if args.token:
+        token = args.token.strip()
+    else:
+        # DDPSRUN-CLI-LOGIN. With no --token, try the browser first. A server
+        # that has no user pool says so and we fall back to the prompt, which is
+        # exactly what this command did before Cognito existed.
+        try:
+            tokens = browser_login.login(server)
+            token, refresh = tokens.id_token, tokens.refresh_token
+        except browser_login.LoginError as exc:
+            if "does not have browser sign-in" not in str(exc):
+                print(str(exc), file=sys.stderr)
+                return EXIT_SERVER
+            token = getpass.getpass("token: ").strip()
+
+    if not token:
+        print("no token given", file=sys.stderr)
+        return EXIT_USAGE
+
+    path = config.save(config.Credentials(
+        server=server, token=token, refresh_token=refresh))
+    print(f"saved to {path}")
+
+    # Prove the credentials work now, rather than at the user's first real
+    # command. `status` on an id that cannot exist returns 404 when the token is
+    # good and 401 when it is not, which is exactly the distinction we want.
+    #
+    # The id has letters in it on purpose: twelve digits in a row is what an AWS
+    # account number looks like, and this repository's CI refuses those on
+    # sight (`.github/workflows/ci.yml`).
+    try:
+        Client(args.server, token).status("job-ffffffffffff")
+    except ServerError as exc:
+        message = str(exc)
+        if "no such job" in message:
+            print("token accepted")
+        else:
+            print(f"warning: the server did not accept this: {message}", file=sys.stderr)
+    return EXIT_OK
+
+
+def cmd_logout(_: argparse.Namespace) -> int:
+    """Delete the stored credentials."""
+    print("logged out" if config.forget() else "nothing stored")
+    return EXIT_OK
+
+
+def cmd_explain(_: argparse.Namespace) -> int:
+    """Print the server's own description of itself."""
+    print(client_from_config().explain(), end="")
+    return EXIT_OK
+
+
+def cmd_schema(args: argparse.Namespace) -> int:
+    """Print the JSON Schema of a submit request."""
+    print(json.dumps(client_from_config().schema(), indent=2, ensure_ascii=False))
+    return EXIT_OK
+
+
+def cmd_submit(args: argparse.Namespace) -> int:
+    """Submit a job and print where its output will go."""
+    body = build_submit_body(args)
+    result = client_from_config().submit(body)
+    if args.json:
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+    else:
+        print(f"submitted  {result['job_id']}")
+        print(f"results    {result['result_path']}")
+        print(f"follow     hyperun logs {result['job_id']} --follow")
+    return EXIT_OK
+
+
+def cmd_estimate(args: argparse.Namespace) -> int:
+    """Print how long a job will take, what it will cost, and which GPU it wants."""
+    body = build_submit_body(args)
+    result = client_from_config().estimate(body)
+    if args.json:
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+        return EXIT_OK
+
+    hours, cost, gpu = result["hours"], result["cost_usd"], result["gpu"]
+    rate = result.get("rate") or {}
+    if result.get("steps"):
+        print(f"  steps          {result['steps']:,}")
+    if hours.get("low") is not None:
+        print(f"  time           {hours['low']} - {hours['high']} h  [{hours['confidence']}]")
+    else:
+        # `unknown` is a real answer, and printing a blank instead of saying so
+        # is how a user ends up assuming zero.
+        print(f"  time           unknown  [{hours['confidence']}]")
+    # THE RATE IS PRINTED WHETHER OR NOT THE HOURS ARE KNOWN. Twelve of the
+    # fourteen choosable cards have no throughput measurement, so their `time`
+    # is `unknown` -- and this block used to skip the money entirely for them,
+    # which is the same blank-instead-of-saying-so hazard the `time` line above
+    # was already fixed for. The rate needs no measurement of ours.
+    if rate.get("usd_per_hour_low") is not None:
+        span = ("" if rate["usd_per_hour_high"] == rate["usd_per_hour_low"]
+                else f" - ${rate['usd_per_hour_high']}")
+        machines = f" ({rate['machines']} machine(s))" if rate.get("machines", 1) > 1 else ""
+        print(f"  rate           ${rate['usd_per_hour_low']}{span} /h"
+              f"  [{rate.get('vendor') or 'unpriced'}]{machines}")
+    if cost.get("low") is not None:
+        print(f"  cost           ${cost['low']} - ${cost['high']}")
+    elif rate.get("usd_per_hour_low") is not None:
+        print("  cost           unknown -- the rate above is known, the hours are not")
+    if rate.get("basis"):
+        print(f"  price basis    {rate['basis']}")
+    print(f"  basis          {result['basis']}")
+    print(f"  GPU            {gpu.get('recommended') or 'none'}"
+          f" ({gpu.get('recommended_vram_gb')} GB), logits peak {gpu['peak_logits_gib']} GiB")
+    print(f"                 {gpu['reason']}")
+    print(f"  capacity type  {result['capacity_type']}   "
+          f"<- pass --capacity-type {result['capacity_type']} when you submit")
+    print(f"                 {result['capacity_reason']}")
+    for warning in result.get("warnings", []):
+        print(f"  note           {warning}")
+    return EXIT_OK
+
+
+def cmd_validate(args: argparse.Namespace) -> int:
+    """Print what is wrong with a job, without submitting it.
+
+    Returns:
+        0 when nothing is an error, 1 when something is. A script can gate a
+        submit on this.
+    """
+    body = build_submit_body(args)
+    result = client_from_config().validate(body)
+    if args.json:
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+        return EXIT_OK if result["ok"] else EXIT_SERVER
+
+    marker = {"error": "[error]  ", "warning": "[warning]", "info": "[info]   "}
+    for finding in result.get("findings", []):
+        print(f"{marker.get(finding['level'], '[?]      ')} {finding['code']}")
+        print(f"  {finding['message']}")
+        if finding.get("fix"):
+            print(f"  fix: {finding['fix']}")
+        print()
+    for line in result.get("not_checked", []):
+        print(f"[not checked] {line}")
+    print()
+    print("Nothing blocking." if result["ok"] else "Something is blocking this job.")
+    return EXIT_OK if result["ok"] else EXIT_SERVER
+
+
+def cmd_shell(args: argparse.Namespace) -> int:
+    """Run commands inside a running job's workload container.
+
+    One line, one HTTPS round trip: the server relays it through the driver
+    pod onto the rented machine and returns the exit code like ssh. With a
+    trailing `-- command` it runs once and exits with that code; without one
+    it prompts, which FEELS like a slow shell and is honestly a request loop.
+    """
+    client = client_from_config()
+
+    def run_once(line: str) -> int:
+        answer = client.exec_in_job(args.job, line, slot=args.slot)
+        output = answer.get("output") or ""
+        if output:
+            print(output, end="" if output.endswith("\n") else "\n")
+        if answer.get("note"):
+            print(f"({answer['note']})", file=sys.stderr)
+        code = answer.get("exit_code")
+        return 1 if code is None else int(code)
+
+    # ★ A FLAG AFTER THE JOB ID IS SWALLOWED, so refuse it rather than run the
+    # wrong thing quietly. argparse.REMAINDER starts consuming at the token
+    # right after the `job` positional, so
+    #
+    #   hyperun shell job-x --slot 2 -- hostname
+    #
+    # parses as slot=0 with the command line "--slot 2 -- hostname": the user
+    # asked for pod 2 and would have got pod 0, with no message. Found
+    # 2026-09-10 while writing the first test that ever reached this function.
+    # The separator is the tell: argparse consumes a `--` that immediately
+    # follows the job id, so a `--` still sitting in the remainder -- or a
+    # remainder that begins with a dash -- means options were written late.
+    raw = list(args.command or [])
+    if raw and (raw[0].startswith("-") or "--" in raw):
+        # THE SHAPE, NOT A REBUILT LINE. A first draft printed a corrected
+        # command and got it wrong: `--slot` had already been swallowed, so it
+        # echoed the default slot and left the 2 in the workload's line
+        # ("--slot 0 job-x -- 2 hostname"). Suggesting a wrong command is worse
+        # than suggesting none, so this states the rule and the shape and lets
+        # the reader place their own flags.
+        print("error: options go BEFORE the job id. Everything after the job id "
+              "is sent to the workload as-is, so a flag written there became "
+              "part of the command line instead.", file=sys.stderr)
+        print("       shape: hyperun shell [--slot N] <job> -- <command>",
+              file=sys.stderr)
+        print(f"       you wrote: shell {args.job} " + " ".join(raw),
+              file=sys.stderr)
+        return EXIT_USAGE
+    # argparse.REMAINDER keeps the "--" separator itself; drop it.
+    words = [w for w in raw if w != "--"]
+    if words:
+        return run_once(" ".join(words))
+
+    print(
+        f"one command per line, ~25s each; 'exit' or Ctrl-D leaves. Not a TTY.",
+        file=sys.stderr,
+    )
+    while True:
+        try:
+            line = input(f"{args.job}$ ")
+        except (EOFError, KeyboardInterrupt):
+            print()
+            return EXIT_OK
+        line = line.strip()
+        if not line:
+            continue
+        if line in ("exit", "quit"):
+            return EXIT_OK
+        try:
+            code = run_once(line)
+            if code:
+                print(f"(exit {code})", file=sys.stderr)
+        except ServerError as exc:
+            # One failed command must not end the session: say what the server
+            # said and keep the prompt.
+            print(f"error: {exc}", file=sys.stderr)
+
+
+def cmd_secrets(args: argparse.Namespace) -> int:
+    """Print the secret names this caller can use, saying which are their own."""
+    answer = client_from_config().secrets()
+    names = answer.get("names") or []
+    own = set(answer.get("own") or [])
+    for name in names:
+        # Marking them matters: only the second kind can be changed from here,
+        # and only the second kind is invisible to the rest of the lab.
+        print(f"{name}  (yours)" if name in own else f"{name}  (deployment)")
+    if answer.get("note"):
+        print(f"\n{answer['note']}")
+    return EXIT_OK
+
+
+def cmd_secret_set(args: argparse.Namespace) -> int:
+    """Store one value under one name, for this caller's own namespace.
+
+    THE VALUE IS READ FROM A FILE OR STDIN AND NEVER FROM argv. A secret on a
+    command line is in the shell's history file, in `ps` output for every other
+    user on the machine, and in any terminal recording of the session -- three
+    copies nobody meant to make, in places nobody thinks to clear.
+
+    Returns:
+        EXIT_OK, or EXIT_USAGE when the file could not be read or is empty.
+    """
+    source = args.from_file or "-"
+    if source == "-":
+        if sys.stdin.isatty():
+            # A bare `hyperun secret-set NAME` on a terminal would sit there
+            # looking hung. Say what it is waiting for.
+            print(
+                f"reading the value for {args.name} from stdin. Paste it and press "
+                f"Ctrl-D, or re-run with --from-file PATH.",
+                file=sys.stderr,
+            )
+        value = sys.stdin.read()
+    else:
+        try:
+            with open(source, encoding="utf-8") as handle:
+                value = handle.read()
+        except OSError as exc:
+            print(f"cannot read {source}: {exc}", file=sys.stderr)
+            return EXIT_USAGE
+    # A trailing newline is what `echo` and every editor add, and it is not part
+    # of a token -- a newline inside an Authorization header is a 400 from the
+    # far end, an hour into a job. Only the trailing whitespace goes; anything
+    # else could be part of a private key or a JSON blob.
+    value = value.rstrip("\r\n")
+    if not value:
+        print(
+            f"nothing to store: the value for {args.name} is empty.", file=sys.stderr
+        )
+        return EXIT_USAGE
+
+    answer = client_from_config().put_secret(args.name, value,
+                                             expires_at=args.expires_at)
+    where = answer.get("namespace", "your namespace")
+    what = "stored" if answer.get("created") else "replaced"
+    print(f"{what} {answer.get('name', args.name)} in {where}.")
+    if answer.get("expires_at"):
+        print(f"it stops working at {answer['expires_at']}; after that a job asking "
+              f"for it is refused by `hyperun validate`.")
+    print(f"a job can now ask for it with `--secret {args.name}`.")
+    return EXIT_OK
+
+
+def cmd_secret_rm(args: argparse.Namespace) -> int:
+    """Forget one registered name."""
+    client_from_config().delete_secret(args.name)
+    print(f"{args.name} is no longer registered. Jobs asking for it are refused.")
+    return EXIT_OK
+
+
+def cmd_status(args: argparse.Namespace) -> int:
+    """Print one job's state."""
+    view = client_from_config().status(args.job_id)
+    if args.json:
+        print(json.dumps(view, indent=2, ensure_ascii=False))
+        return EXIT_OK
+
+    # A job the controller has not looked at yet has an empty phase. Saying
+    # "accepted" is truer than printing a blank.
+    print(f"{view['job_id']}  {view.get('name', '')}")
+    print(f"  phase      {view.get('phase') or 'accepted, not yet started'}")
+    if view.get("gpu"):
+        vendor = f" ({view['vendor']})" if view.get("vendor") else ""
+        print(f"  running on {view['gpu']}{vendor}")
+    if view.get("recovery_count"):
+        # Not a failure. Rented capacity is taken back, and the job is restarted.
+        print(f"  restarts   {view['recovery_count']} (the machine was reclaimed)")
+    if view.get("message"):
+        print(f"  message    {view['message']}")
+    if view.get("result_path"):
+        print(f"  results    {view['result_path']}")
+    return EXIT_OK
+
+
+def cmd_delete(args: argparse.Namespace) -> int:
+    """Delete a job. It stops, and it disappears.
+
+    DDPSRUN-CANCEL. A job can sit in Pending forever with nothing to do about
+    it: on 2026-09-02 one asked for an L40S on spot, which RunPod refuses before
+    reading the catalogue and which no AWS row matched, and the controller
+    retried that same failure every eleven minutes. Until this existed the only
+    way to stop it was kubectl, which is the thing this tool exists to remove.
+
+    Asks first unless --yes is given. The delete is not undoable and a job id is
+    twelve hex characters, which is easy enough to mistype.
+
+    THE PROMPT SAYS `delete`, NOT `cancel`, since 2026-09-10. The old wording
+    let a reader expect the job to survive in some cancelled state; what
+    actually happens is that the object is removed and the row is gone. What
+    survives is the result path in S3, which the prompt now says out loud so
+    nobody deletes a job expecting to lose its output, or keeps one expecting
+    to protect it.
+
+    Returns:
+        0 when the job is gone, 1 when the server refused, 2 when the user said
+        no at the prompt.
+    """
+    if not args.yes:
+        answer = input(
+            f"delete {args.job_id}? it stops and disappears from the list; "
+            f"files already in its result path stay [y/N] ").strip().lower()
+        if answer not in ("y", "yes"):
+            print("left alone")
+            return EXIT_USAGE
+
+    try:
+        client_from_config().cancel(args.job_id)
+    except ServerError as exc:
+        print(str(exc), file=sys.stderr)
+        return EXIT_SERVER
+    print(f"cancelled {args.job_id}")
+    return EXIT_OK
+
+
+def bar(percent: float, width: int = 20) -> str:
+    """Draw a progress bar.
+
+    Args:
+        percent: 0 to 100.
+        width: how many characters wide.
+
+    Returns:
+        A string of filled and empty blocks.
+
+    Example:
+        >>> bar(50, width=10)
+        '#####-----'
+    """
+    filled = int(round(width * max(0.0, min(100.0, percent)) / 100))
+    return "#" * filled + "-" * (width - filled)
+
+
+def cmd_watch(args: argparse.Namespace) -> int:
+    """Print a job's GPU usage and how far the training has got."""
+    result = client_from_config().metrics(args.job_id, args.window)
+    if args.json:
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+        return EXIT_OK
+
+    progress = result.get("progress")
+    if progress:
+        print(f"  training       {bar(progress['percent'])}  "
+              f"{progress['step']:,} / {progress['total_steps']:,} steps  "
+              f"({progress['percent']}%)")
+        print(f"                 {progress['seconds_per_step']} s/step, "
+              f"{progress['elapsed']} elapsed, {progress['remaining']} remaining")
+        # `steady` False means too few steps have run for this to be worth
+        # quoting, so it is labelled rather than printed as a fact.
+        settled = "" if progress["steady"] else "  (rate has not settled yet)"
+        print(f"  projected      {progress['projected_total_hours']} h{settled}")
+
+    gpu = result.get("latest_gpu")
+    if gpu:
+        print(f"  GPU util       {bar(gpu['utilization_percent'])}  "
+              f"{gpu['utilization_percent']}%")
+        print(f"  GPU memory     {bar(gpu['memory_percent'])}  "
+              f"{gpu['memory_used_mib']:,} / {gpu['memory_total_mib']:,} MiB "
+              f"({gpu['memory_percent']}%)")
+        print(f"  temp, power    {gpu['temperature_c']} C, {gpu['power_w']} W")
+        print(f"  samples        {len(result.get('gpu_series', []))}, "
+              f"last {result['window_seconds']}s")
+
+    if result.get("note"):
+        print(f"  note           {result['note']}")
+    return EXIT_OK
+
+
+def cmd_stats(args: argparse.Namespace) -> int:
+    """Print this caller's team figures."""
+    result = client_from_config().stats()
+    if args.json:
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+        return EXIT_OK
+
+    print(f"team {result['team'] or '(none)'}")
+    if result.get("members"):
+        print(f"  {'member':<14}{'jobs':>6}{'ok':>5}{'failed':>8}{'running':>9}"
+              f"{'GPU h':>9}{'spend':>10}")
+        for m in result["members"]:
+            print(f"  {m['user']:<14}{m['jobs']:>6}{m['succeeded']:>5}{m['failed']:>8}"
+                  f"{m['running']:>9}{m['gpu_hours']:>9}{('$' + str(m['cost_usd'])):>10}")
+        print(f"  {'total':<14}{result['jobs']:>6}{'':>5}{'':>8}{'':>9}"
+              f"{result['gpu_hours']:>9}{('$' + str(result['cost_usd'])):>10}")
+    if result.get("note"):
+        print(f"  note           {result['note']}")
+    return EXIT_OK
+
+
+def cmd_logs(args: argparse.Namespace) -> int:
+    """Print a job's output, once or repeatedly.
+
+    WHY THIS POLLS INSTEAD OF STREAMING. The server runs as a Lambda function
+    and one execution is capped at 15 minutes, while a training run is thirty
+    hours. So a window is read, printed, and asked for again.
+
+    The only state kept is `since`, the timestamp of the last line printed.
+    The server remembers nothing, which is what lets a fresh execution answer
+    every request.
+    """
+    client = client_from_config()
+    # A window several times the interval, so one slow round trip does not lose
+    # lines. Capped at the server's own limit.
+    window = min(3600, max(5, int(args.interval * 5)))
+    since: str | None = None
+
+    while True:
+        result = client.log_window(args.job_id, since=since, window_seconds=window)
+        for line in result["lines"]:
+            # The timestamp is bookkeeping for the next request, not something a
+            # user asked to read, so it is dropped on the way to the terminal.
+            print(line.split(" ", 1)[1] if " " in line else line)
+        if result.get("last_timestamp"):
+            since = result["last_timestamp"]
+        if not args.follow:
+            return EXIT_OK
+        time.sleep(args.interval)
+
+
+COMMANDS = {
+    "login": cmd_login,
+    "delete": cmd_delete,
+    # The old spelling, kept as an alias -- see the comment on the parser.
+    "cancel": cmd_delete,
+    "logout": cmd_logout,
+    "explain": cmd_explain,
+    "schema": cmd_schema,
+    "estimate": cmd_estimate,
+    "validate": cmd_validate,
+    "submit": cmd_submit,
+    "secrets": cmd_secrets,
+    "secret-set": cmd_secret_set,
+    "secret-rm": cmd_secret_rm,
+    "shell": cmd_shell,
+    "status": cmd_status,
+    "watch": cmd_watch,
+    "stats": cmd_stats,
+    "logs": cmd_logs,
+}
+
+
+def main(argv: list[str] | None = None) -> int:
+    """The entry point `pip install hyperun` puts on the PATH.
+
+    Args:
+        argv: arguments without the program name. Defaults to `sys.argv[1:]`.
+
+    Returns:
+        The exit code.
+    """
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if not args.subcommand:
+        parser.print_help()
+        return EXIT_USAGE
+
+    try:
+        return COMMANDS[args.subcommand](args)
+    except SystemExit as exc:
+        # `build_submit_body` and `client_from_config` raise SystemExit with a
+        # one-line message already printed, because a traceback for "you forgot
+        # --image" helps nobody. Catching it here keeps `main`'s contract — it
+        # RETURNS an exit code — true for every path, which is what lets a test
+        # call it directly and what lets another program import it.
+        code = exc.code
+        if isinstance(code, str):
+            print(code, file=sys.stderr)
+            return EXIT_USAGE
+        return EXIT_USAGE if code is None else int(code)
+    except ServerError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return EXIT_SERVER
+    except KeyboardInterrupt:
+        # Ctrl-C during `logs --follow` is how a user stops watching. It is not
+        # a failure and it does not touch the job, which keeps running.
+        print()
+        return EXIT_OK
+
+
+if __name__ == "__main__":
+    sys.exit(main())