benchloop-client 0.1.6__py3-none-any.whl

aliyun/bmcli/commands/metrics.py

@@ -0,0 +1,136 @@
+"""`bmcli metrics` — run metrics for Group (overall/detail) and Job."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import typer
+
+from aliyun.bmcli import output
+from aliyun.bmcli.commands._common import (
+    GroupOption,
+    JobOption,
+    OutputDirOption,
+    SkipExistingOption,
+    expand,
+    resolve_output_dir,
+)
+from aliyun.bmcli.ids import enforce_mutually_exclusive, require_any
+from aliyun.bmcli.runtime import get_runtime, report_and_exit, safe_run_concurrent
+
+app = typer.Typer(help="Run metrics (Group overall/detail, Job).", no_args_is_help=True)
+
+_SCOPES = ("overall", "detail", "all")
+
+
+def _validate_scope(scope: str) -> str:
+    if scope not in _SCOPES:
+        raise typer.BadParameter(f"--scope must be one of {', '.join(_SCOPES)}")
+    return scope
+
+
+def _fetch_job(client, job_id: str):
+    data = client.get_json(f"/openapi/metrics/{job_id}")
+    if isinstance(data, dict):
+        return {
+            "job_id": data.get("job_id", job_id),
+            "metrics": data.get("metrics"),
+            "tokenized_metrics": data.get("tokenized_metrics"),
+        }
+    # Fallback when the backend returns a non-dict (e.g. bare array) body.
+    return {"job_id": job_id, "metrics": data, "tokenized_metrics": None}
+
+
+def _fetch_group(client, group_id: str, scope: str):
+    result: dict = {"group_id": group_id}
+    if scope in ("overall", "all"):
+        result["overall"] = client.get_json(
+            f"/openapi/groups/{group_id}/metrics/overall"
+        )
+    if scope in ("detail", "all"):
+        result["detail"] = client.get_json(
+            f"/openapi/groups/{group_id}/metrics/detail"
+        )
+    return result
+
+
+@app.command("get")
+def get(
+    ctx: typer.Context,
+    group: Optional[list[str]] = GroupOption,
+    job: Optional[list[str]] = JobOption,
+    scope: str = typer.Option("all", "--scope", help="overall|detail|all (Group only)."),
+) -> None:
+    """Query metrics; prints a JSON array to stdout."""
+    rt = get_runtime(ctx)
+    groups = expand(group)
+    jobs = expand(job)
+    enforce_mutually_exclusive(groups, jobs)
+    require_any(groups, jobs)
+    _validate_scope(scope)
+
+    if jobs:
+        res = safe_run_concurrent(jobs, lambda jid: _fetch_job(rt.client, jid), rt.concurrency)
+    else:
+        res = safe_run_concurrent(
+            groups, lambda gid: _fetch_group(rt.client, gid, scope), rt.concurrency
+        )
+    report_and_exit(res, emit=True, pretty=rt.pretty)
+
+
+@app.command("download")
+def download(
+    ctx: typer.Context,
+    group: Optional[list[str]] = GroupOption,
+    job: Optional[list[str]] = JobOption,
+    scope: str = typer.Option("all", "--scope", help="overall|detail|all (Group only)."),
+    output_dir: Optional[str] = OutputDirOption,
+    skip_existing: bool = SkipExistingOption,
+) -> None:
+    """Download metrics to the standard file layout."""
+    rt = get_runtime(ctx)
+    groups = expand(group)
+    jobs = expand(job)
+    enforce_mutually_exclusive(groups, jobs)
+    require_any(groups, jobs)
+    _validate_scope(scope)
+    root = resolve_output_dir(rt.output_dir, output_dir)
+
+    def job_worker(job_id: str):
+        dest = root / f"{job_id}_run_metrics.json"
+        if skip_existing and dest.exists():
+            output.log(f"skip existing {dest}")
+            return str(dest)
+        data = rt.client.get_json(f"/openapi/metrics/{job_id}")
+        output.write_json_file(dest, data, pretty=rt.pretty)
+        output.log(f"wrote {dest}")
+        return str(dest)
+
+    def group_worker(group_id: str):
+        written = []
+        gdir = root / group_id
+        if scope in ("overall", "all"):
+            dest = gdir / "overall_metrics.json"
+            if skip_existing and dest.exists():
+                output.log(f"skip existing {dest}")
+            else:
+                data = rt.client.get_json(f"/openapi/groups/{group_id}/metrics/overall")
+                output.write_json_file(dest, data, pretty=rt.pretty)
+                output.log(f"wrote {dest}")
+            written.append(str(dest))
+        if scope in ("detail", "all"):
+            dest = gdir / "detail_metrics.json"
+            if skip_existing and dest.exists():
+                output.log(f"skip existing {dest}")
+            else:
+                data = rt.client.get_json(f"/openapi/groups/{group_id}/metrics/detail")
+                output.write_json_file(dest, data, pretty=rt.pretty)
+                output.log(f"wrote {dest}")
+            written.append(str(dest))
+        return written
+
+    if jobs:
+        res = safe_run_concurrent(jobs, job_worker, rt.concurrency)
+    else:
+        res = safe_run_concurrent(groups, group_worker, rt.concurrency)
+    report_and_exit(res, emit=False)

aliyun/bmcli/commands/overview.py

@@ -0,0 +1,70 @@
+"""`bmcli overview` — run statistics (Group / Task / Job); query only."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import typer
+
+from aliyun.bmcli.commands._common import GroupOption, JobOption, expand
+from aliyun.bmcli.ids import enforce_mutually_exclusive, require_any
+from aliyun.bmcli.runtime import get_runtime, report_and_exit, safe_run_concurrent
+
+app = typer.Typer(help="Run statistics overview (query only).", no_args_is_help=True)
+
+_SCOPES = ("summary", "tasks", "all")
+
+
+def _validate_scope(scope: str) -> str:
+    if scope not in _SCOPES:
+        raise typer.BadParameter(f"--scope must be one of {', '.join(_SCOPES)}")
+    return scope
+
+
+def _fetch_job(client, job_id: str):
+    job_obj = client.get_json(f"/openapi/jobs/{job_id}")
+    group_id = job_obj.get("group_id") if isinstance(job_obj, dict) else None
+    stats = client.get_json(
+        "/openapi/jobs/stats",
+        params={"group_id": group_id} if group_id else None,
+    )
+    return {"job_id": job_id, "job": job_obj, "stats": stats}
+
+
+def _fetch_group(client, group_id: str, scope: str):
+    result: dict = {"group_id": group_id}
+    if scope in ("summary", "all"):
+        result["summary"] = client.get_json(f"/openapi/groups/{group_id}/eval_summary")
+    if scope in ("tasks", "all"):
+        result["tasks"] = client.get_json(f"/openapi/groups/{group_id}/eval_tasks")
+    return result
+
+
+@app.command("get")
+def get(
+    ctx: typer.Context,
+    group: Optional[list[str]] = GroupOption,
+    job: Optional[list[str]] = JobOption,
+    scope: str = typer.Option(
+        "all", "--scope", help="summary|tasks|all (Group only)."
+    ),
+) -> None:
+    """Query overview; prints a JSON array to stdout.
+
+    Job (``-j``): jobs/{id} merged with jobs/stats.
+    Group (``-g``): eval_summary and/or eval_tasks per ``--scope``.
+    """
+    rt = get_runtime(ctx)
+    groups = expand(group)
+    jobs = expand(job)
+    enforce_mutually_exclusive(groups, jobs)
+    require_any(groups, jobs)
+    _validate_scope(scope)
+
+    if jobs:
+        res = safe_run_concurrent(jobs, lambda jid: _fetch_job(rt.client, jid), rt.concurrency)
+    else:
+        res = safe_run_concurrent(
+            groups, lambda gid: _fetch_group(rt.client, gid, scope), rt.concurrency
+        )
+    report_and_exit(res, emit=True, pretty=rt.pretty)

aliyun/bmcli/commands/pull.py

@@ -0,0 +1,168 @@
+"""`bmcli pull` — one-shot aggregate download into the standard layout."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Optional
+
+import typer
+
+from aliyun.bmcli import output
+from aliyun.bmcli.commands._common import (
+    GroupOption,
+    JobOption,
+    OutputDirOption,
+    SkipExistingOption,
+    expand,
+    resolve_output_dir,
+)
+from aliyun.bmcli.ids import enforce_mutually_exclusive, require_any
+from aliyun.bmcli.runtime import get_runtime
+from aliyun.bmcli.exit_codes import OK, PARTIAL
+
+_ALL_WITH = ("metrics", "trajectory", "report", "artifacts", "tasks", "jobs")
+_DEFAULT_WITH = "metrics,trajectory"
+
+
+def _parse_with(value: str) -> list[str]:
+    parts = [p.strip() for p in value.split(",") if p.strip()]
+    bad = [p for p in parts if p not in _ALL_WITH]
+    if bad:
+        raise typer.BadParameter(
+            f"--with has unsupported value(s): {', '.join(bad)}; "
+            f"choose from {', '.join(_ALL_WITH)}"
+        )
+    return parts
+
+
+def pull(
+    ctx: typer.Context,
+    group: Optional[list[str]] = GroupOption,
+    job: Optional[list[str]] = JobOption,
+    with_: str = typer.Option(
+        _DEFAULT_WITH, "--with", help="Comma list: metrics,trajectory,report,artifacts,tasks,jobs."
+    ),
+    output_dir: Optional[str] = OutputDirOption,
+    skip_existing: bool = SkipExistingOption,
+) -> None:
+    """Aggregate downloads for the given groups/jobs into the layout."""
+    rt = get_runtime(ctx)
+    groups = expand(group)
+    jobs = expand(job)
+    enforce_mutually_exclusive(groups, jobs)
+    require_any(groups, jobs)
+    selected = _parse_with(with_)
+    root = resolve_output_dir(rt.output_dir, output_dir)
+    client = rt.client
+
+    failures: list[tuple[str, str]] = []
+
+    def _safe(label: str, fn) -> None:
+        try:
+            fn()
+        except Exception as exc:  # noqa: BLE001 - aggregate, collect failures
+            failures.append((label, str(exc)))
+
+    def _write_json(dest: Path, data: Any) -> None:
+        if skip_existing and dest.exists():
+            output.log(f"skip existing {dest}")
+            return
+        output.write_json_file(dest, data, pretty=rt.pretty)
+        output.log(f"wrote {dest}")
+
+    for jid in jobs:
+        if "metrics" in selected:
+            _safe(f"{jid}:metrics", lambda jid=jid: _write_json(
+                root / f"{jid}_run_metrics.json",
+                client.get_json(f"/openapi/metrics/{jid}")))
+        if "trajectory" in selected:
+            _safe(f"{jid}:trajectory", lambda jid=jid: _write_json(
+                root / f"{jid}_trajectory.json",
+                client.get_json(f"/openapi/jobs/{jid}/trajectory")))
+        if "report" in selected:
+            _safe(f"{jid}:report", lambda jid=jid: _pull_report(client, jid, root, skip_existing))
+        if "artifacts" in selected:
+            _safe(f"{jid}:artifacts", lambda jid=jid: _pull_job_artifacts(
+                rt, jid, root, skip_existing, failures))
+
+    for gid in groups:
+        if "metrics" in selected:
+            _safe(f"{gid}:metrics:overall", lambda gid=gid: _write_json(
+                root / gid / "overall_metrics.json",
+                client.get_json(f"/openapi/groups/{gid}/metrics/overall")))
+            _safe(f"{gid}:metrics:detail", lambda gid=gid: _write_json(
+                root / gid / "detail_metrics.json",
+                client.get_json(f"/openapi/groups/{gid}/metrics/detail")))
+        if "trajectory" in selected:
+            _safe(f"{gid}:trajectory", lambda gid=gid: _write_json(
+                root / gid / "trajectory.json",
+                client.get_json(f"/openapi/groups/{gid}/trajectory")))
+        if "tasks" in selected:
+            _safe(f"{gid}:tasks", lambda gid=gid: _write_json(
+                root / gid / "task_list.json",
+                client.get_json(f"/openapi/groups/{gid}/eval_tasks", params={"skip": 0, "limit": 1000})))
+        if "jobs" in selected:
+            _safe(f"{gid}:jobs", lambda gid=gid: _write_json(
+                root / gid / "job_list.json",
+                client.get_json("/openapi/jobs", params={"group_id": gid, "skip": 0, "limit": 1000})))
+        if "artifacts" in selected:
+            _safe(f"{gid}:artifacts", lambda gid=gid: _pull_group_artifacts(
+                rt, gid, root, skip_existing, failures))
+
+    if failures:
+        output.error(f"{len(failures)} pull step(s) failed:")
+        for label, msg in failures:
+            output.error(f"  - {label}: {msg}")
+        raise typer.Exit(code=PARTIAL)
+    raise typer.Exit(code=OK)
+
+
+def _pull_report(client, job_id: str, root: Path, skip_existing: bool) -> None:
+    data = client.get_json(f"/openapi/jobs/{job_id}/report", params={"agent": "all"})
+    reports = data.get("reports", []) if isinstance(data, dict) else []
+    for entry in reports:
+        a = entry.get("agent", "")
+        dest = root / f"{job_id}_report_agent_{a}.md"
+        if skip_existing and dest.exists():
+            output.log(f"skip existing {dest}")
+            continue
+        output.write_text_file(dest, entry.get("content", "") or "")
+        output.log(f"wrote {dest}")
+
+
+def _filter_arts(arts: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    return [a for a in arts if a.get("url")]
+
+
+def _pull_job_artifacts(rt, job_id: str, root: Path, skip_existing: bool,
+                        failures: list[tuple[str, str]]) -> None:
+    data = rt.client.get_json(f"/openapi/jobs/{job_id}/artifacts")
+    arts = data.get("artifacts", []) if isinstance(data, dict) else []
+    for a in _filter_arts(arts):
+        dest = root / job_id / (a.get("name") or "artifact")
+        if skip_existing and dest.exists():
+            output.log(f"skip existing {dest}")
+            continue
+        try:
+            rt.client.download_file(a["url"], dest)
+            output.log(f"downloaded {dest}")
+        except Exception as exc:  # noqa: BLE001
+            failures.append((f"{job_id}:{a.get('name')}", str(exc)))
+
+
+def _pull_group_artifacts(rt, group_id: str, root: Path, skip_existing: bool,
+                          failures: list[tuple[str, str]]) -> None:
+    data = rt.client.get_json(f"/openapi/groups/{group_id}/artifacts")
+    arts = data.get("artifacts", []) if isinstance(data, dict) else []
+    for a in _filter_arts(arts):
+        # nest under {group_id}/{job_id}/ to avoid same-name (result.tgz) collisions
+        jid = str(a.get("job_id") or "")
+        dest = root / group_id / jid / (a.get("name") or "artifact")
+        if skip_existing and dest.exists():
+            output.log(f"skip existing {dest}")
+            continue
+        try:
+            rt.client.download_file(a["url"], dest)
+            output.log(f"downloaded {dest}")
+        except Exception as exc:  # noqa: BLE001
+            failures.append((f"{group_id}:{a.get('name')}", str(exc)))

aliyun/bmcli/commands/report.py

@@ -0,0 +1,103 @@
+"""`bmcli report` — pre-analysis agent a/b reports (Job only)."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import typer
+
+from aliyun.bmcli import output
+from aliyun.bmcli.commands._common import (
+    GroupOption,
+    JobOption,
+    OutputDirOption,
+    SkipExistingOption,
+    expand,
+    resolve_output_dir,
+)
+from aliyun.bmcli.ids import (
+    enforce_mutually_exclusive,
+    reject_unsupported_dimension,
+    require_any,
+)
+from aliyun.bmcli.runtime import get_runtime, report_and_exit, safe_run_concurrent
+
+app = typer.Typer(help="Pre-analysis agent a/b reports (Job only).", no_args_is_help=True)
+
+_AGENTS = ("a", "b", "all")
+
+
+def _validate_agent(agent: str) -> str:
+    if agent not in _AGENTS:
+        raise typer.BadParameter("--agent must be one of a, b, all")
+    return agent
+
+
+def _guard(groups: list[str], jobs: list[str]) -> None:
+    enforce_mutually_exclusive(groups, jobs)
+    reject_unsupported_dimension(
+        "report", groups=groups, jobs=jobs, allow_group=False, allow_job=True
+    )
+    require_any(groups, jobs)
+
+
+def _fetch(client, job_id: str, agent: str):
+    data = client.get_json(f"/openapi/jobs/{job_id}/report", params={"agent": agent})
+    return data
+
+
+@app.command("get")
+def get(
+    ctx: typer.Context,
+    group: Optional[list[str]] = GroupOption,
+    job: Optional[list[str]] = JobOption,
+    agent: str = typer.Option("all", "--agent", help="a|b|all (default all)."),
+) -> None:
+    """Query reports; prints a JSON array (with job_id, agent, content)."""
+    rt = get_runtime(ctx)
+    groups = expand(group)
+    jobs = expand(job)
+    _guard(groups, jobs)
+    _validate_agent(agent)
+
+    res = safe_run_concurrent(
+        jobs, lambda jid: _fetch(rt.client, jid, agent), rt.concurrency
+    )
+    report_and_exit(res, emit=True, pretty=rt.pretty)
+
+
+@app.command("download")
+def download(
+    ctx: typer.Context,
+    group: Optional[list[str]] = GroupOption,
+    job: Optional[list[str]] = JobOption,
+    agent: str = typer.Option("all", "--agent", help="a|b|all (default all)."),
+    output_dir: Optional[str] = OutputDirOption,
+    skip_existing: bool = SkipExistingOption,
+) -> None:
+    """Download reports as {job_id}_report_agent_<x>.md from the content field."""
+    rt = get_runtime(ctx)
+    groups = expand(group)
+    jobs = expand(job)
+    _guard(groups, jobs)
+    _validate_agent(agent)
+    root = resolve_output_dir(rt.output_dir, output_dir)
+
+    def worker(job_id: str):
+        data = _fetch(rt.client, job_id, agent)
+        reports = data.get("reports", []) if isinstance(data, dict) else []
+        written = []
+        for entry in reports:
+            a = entry.get("agent", "")
+            content = entry.get("content", "") or ""
+            dest = root / f"{job_id}_report_agent_{a}.md"
+            if skip_existing and dest.exists():
+                output.log(f"skip existing {dest}")
+            else:
+                output.write_text_file(dest, content)
+                output.log(f"wrote {dest}")
+            written.append(str(dest))
+        return written
+
+    res = safe_run_concurrent(jobs, worker, rt.concurrency)
+    report_and_exit(res, emit=False)

aliyun/bmcli/commands/tasks.py

@@ -0,0 +1,121 @@
+"""`bmcli tasks` — Group task list (eval_tasks) with pagination."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+import typer
+
+from aliyun.bmcli import output
+from aliyun.bmcli.commands._common import (
+    GroupOption,
+    JobOption,
+    OutputDirOption,
+    SkipExistingOption,
+    expand,
+    resolve_output_dir,
+)
+from aliyun.bmcli.ids import (
+    enforce_mutually_exclusive,
+    reject_unsupported_dimension,
+    require_any,
+)
+from aliyun.bmcli.runtime import get_runtime, report_and_exit, safe_run_concurrent
+
+app = typer.Typer(help="Group task list (eval_tasks).", no_args_is_help=True)
+
+
+def _guard(groups: list[str], jobs: list[str]) -> None:
+    enforce_mutually_exclusive(groups, jobs)
+    reject_unsupported_dimension(
+        "tasks", groups=groups, jobs=jobs, allow_group=True, allow_job=False
+    )
+    require_any(groups, jobs)
+
+
+def _fetch_page(client, group_id: str, skip: int, limit: int, search, status):
+    params: dict[str, Any] = {"skip": skip, "limit": limit}
+    if search:
+        params["search"] = search
+    if status:
+        params["status"] = status
+    return client.get_json(f"/openapi/groups/{group_id}/eval_tasks", params=params)
+
+
+def _fetch_all(client, group_id: str, page_size: int, search, status):
+    skip = 0
+    all_tasks: list[Any] = []
+    total = None
+    while True:
+        data = _fetch_page(client, group_id, skip, page_size, search, status)
+        tasks = data.get("tasks", []) if isinstance(data, dict) else []
+        if isinstance(data, dict) and total is None:
+            total = data.get("total")
+        all_tasks.extend(tasks)
+        if not tasks or len(tasks) < page_size:
+            break
+        skip += page_size
+        if total is not None and len(all_tasks) >= total:
+            break
+    return {"group_id": group_id, "total": total if total is not None else len(all_tasks),
+            "tasks": all_tasks}
+
+
+@app.command("get")
+def get(
+    ctx: typer.Context,
+    group: Optional[list[str]] = GroupOption,
+    job: Optional[list[str]] = JobOption,
+    page: int = typer.Option(1, "--page", help="Page number (1-based)."),
+    page_size: int = typer.Option(50, "--page-size", help="Page size."),
+    all_pages: bool = typer.Option(False, "--all", help="Auto-paginate all tasks."),
+    search: Optional[str] = typer.Option(None, "--search", show_default=False),
+    status: Optional[str] = typer.Option(None, "--status", show_default=False),
+) -> None:
+    """Query the group task list; prints a JSON array."""
+    rt = get_runtime(ctx)
+    groups = expand(group)
+    jobs = expand(job)
+    _guard(groups, jobs)
+
+    def worker(group_id: str):
+        if all_pages:
+            return _fetch_all(rt.client, group_id, page_size, search, status)
+        skip = max(0, (page - 1) * page_size)
+        data = _fetch_page(rt.client, group_id, skip, page_size, search, status)
+        return {"group_id": group_id, **(data if isinstance(data, dict) else {"data": data})}
+
+    res = safe_run_concurrent(groups, worker, rt.concurrency)
+    report_and_exit(res, emit=True, pretty=rt.pretty)
+
+
+@app.command("download")
+def download(
+    ctx: typer.Context,
+    group: Optional[list[str]] = GroupOption,
+    job: Optional[list[str]] = JobOption,
+    page_size: int = typer.Option(50, "--page-size", help="Page size for pagination."),
+    search: Optional[str] = typer.Option(None, "--search", show_default=False),
+    status: Optional[str] = typer.Option(None, "--status", show_default=False),
+    output_dir: Optional[str] = OutputDirOption,
+    skip_existing: bool = SkipExistingOption,
+) -> None:
+    """Download the full task list to {group_id}/task_list.json."""
+    rt = get_runtime(ctx)
+    groups = expand(group)
+    jobs = expand(job)
+    _guard(groups, jobs)
+    root = resolve_output_dir(rt.output_dir, output_dir)
+
+    def worker(group_id: str):
+        dest = root / group_id / "task_list.json"
+        if skip_existing and dest.exists():
+            output.log(f"skip existing {dest}")
+            return str(dest)
+        data = _fetch_all(rt.client, group_id, page_size, search, status)
+        output.write_json_file(dest, data, pretty=rt.pretty)
+        output.log(f"wrote {dest} ({len(data.get('tasks', []))} tasks)")
+        return str(dest)
+
+    res = safe_run_concurrent(groups, worker, rt.concurrency)
+    report_and_exit(res, emit=False)

aliyun/bmcli/commands/trajectory.py

@@ -0,0 +1,92 @@
+"""`bmcli trajectory` — trajectory data for Group and Job."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import typer
+
+from aliyun.bmcli import output
+from aliyun.bmcli.commands._common import (
+    GroupOption,
+    JobOption,
+    OutputDirOption,
+    SkipExistingOption,
+    expand,
+    resolve_output_dir,
+)
+from aliyun.bmcli.ids import enforce_mutually_exclusive, require_any
+from aliyun.bmcli.runtime import get_runtime, report_and_exit, safe_run_concurrent
+
+app = typer.Typer(help="Trajectory data (Group, Job).", no_args_is_help=True)
+
+
+@app.command("get")
+def get(
+    ctx: typer.Context,
+    group: Optional[list[str]] = GroupOption,
+    job: Optional[list[str]] = JobOption,
+) -> None:
+    """Query trajectory; prints a JSON array to stdout."""
+    rt = get_runtime(ctx)
+    groups = expand(group)
+    jobs = expand(job)
+    enforce_mutually_exclusive(groups, jobs)
+    require_any(groups, jobs)
+
+    if jobs:
+        res = safe_run_concurrent(
+            jobs,
+            lambda jid: rt.client.get_json(f"/openapi/jobs/{jid}/trajectory"),
+            rt.concurrency,
+        )
+    else:
+        res = safe_run_concurrent(
+            groups,
+            lambda gid: rt.client.get_json(f"/openapi/groups/{gid}/trajectory"),
+            rt.concurrency,
+        )
+    report_and_exit(res, emit=True, pretty=rt.pretty)
+
+
+@app.command("download")
+def download(
+    ctx: typer.Context,
+    group: Optional[list[str]] = GroupOption,
+    job: Optional[list[str]] = JobOption,
+    output_dir: Optional[str] = OutputDirOption,
+    skip_existing: bool = SkipExistingOption,
+) -> None:
+    """Download trajectory to the standard file layout."""
+    rt = get_runtime(ctx)
+    groups = expand(group)
+    jobs = expand(job)
+    enforce_mutually_exclusive(groups, jobs)
+    require_any(groups, jobs)
+    root = resolve_output_dir(rt.output_dir, output_dir)
+
+    def job_worker(job_id: str):
+        dest = root / f"{job_id}_trajectory.json"
+        if skip_existing and dest.exists():
+            output.log(f"skip existing {dest}")
+            return str(dest)
+        data = rt.client.get_json(f"/openapi/jobs/{job_id}/trajectory")
+        output.write_json_file(dest, data, pretty=rt.pretty)
+        output.log(f"wrote {dest}")
+        return str(dest)
+
+    def group_worker(group_id: str):
+        dest = root / group_id / "trajectory.json"
+        if skip_existing and dest.exists():
+            output.log(f"skip existing {dest}")
+            return str(dest)
+        data = rt.client.get_json(f"/openapi/groups/{group_id}/trajectory")
+        output.write_json_file(dest, data, pretty=rt.pretty)
+        output.log(f"wrote {dest}")
+        return str(dest)
+
+    if jobs:
+        res = safe_run_concurrent(jobs, job_worker, rt.concurrency)
+    else:
+        res = safe_run_concurrent(groups, group_worker, rt.concurrency)
+    report_and_exit(res, emit=False)