omicslab 2.2.0__tar.gz → 2.6.0__tar.gz

{omicslab-2.2.0 → omicslab-2.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: omicslab
-Version: 2.2.0
+Version: 2.6.0
 Summary: Python SDK and CLI for the OmicsLab Platform
 Project-URL: Homepage, https://platform.omicslab.io
 Project-URL: Repository, https://github.com/vieomics/omicslab-platform
@@ -14,6 +14,7 @@ Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
 Classifier: Programming Language :: Python :: 3.12
 Requires-Python: >=3.12
 Requires-Dist: aiohttp>=3.10
+Requires-Dist: botocore<2,>=1.35
 Requires-Dist: httpx>=0.27
 Requires-Dist: psutil>=6
 Requires-Dist: pydantic>=2
@@ -51,7 +52,7 @@ omicslab use
 omicslab ls && omicslab upload ./data.csv
 
 # 4. Launch a job
-omicslab jobs launch --workspace <ws_id> --analysis <id> --compute <id>
+omicslab ws analysis launch --workspace <ws_id> --analysis <id> --compute <id>
 ```
 
 ## Storage Commands
@@ -93,7 +94,7 @@ omicslab upload -y ./data.csv s3://my-bucket/data/
 
 ### Download
 
-Download files or directories from workspace storage. Recursive downloads preserve subdirectory structure and use parallel threads.
+Download files or directories from workspace storage. A folder is detected automatically, so a trailing slash and `-r` are optional; recursive downloads preserve subdirectory structure and use parallel threads.
 
 ```bash
 # Single file (defaults to filename in current directory)
@@ -105,7 +106,13 @@ omicslab download results/run1/data.csv ./local_copy.csv
 # Download from s3:// path (auto-resolves workspace)
 omicslab download s3://my-bucket/data/results/report.html
 
-# Recursive directory download (preserves subdirectory structure)
+# Folder download (auto-detected; defaults to ./run1)
+omicslab download results/run1
+
+# Folder download with explicit destination
+omicslab download results/run1 ./local_results/
+
+# Same thing, explicit recursive (preserves subdirectory structure)
 omicslab download -r s3://my-bucket/data/results/ ./local_results/
 
 # Recursive download with custom thread count
@@ -119,12 +126,13 @@ omicslab download -y -r s3://my-bucket/data/results/ ./local_results/
 
 | Flag | Description |
 |------|-------------|
-| `--recursive`, `-r` | Download all files under an s3:// directory prefix |
+| `--recursive`, `-r` | Force recursive download (folders are detected automatically) |
+| `--zip` | Download a folder as a server-built zip archive |
 | `--threads` | Concurrent download threads (default: 4) |
 | `--workspace-id`, `-w` | Workspace ID (inferred from s3:// path if provided) |
 | `--yes`, `-y` | Skip confirmation prompt for s3:// path resolution |
 
-**Recursive download** lists all objects under the prefix, then downloads them in parallel while preserving the original subdirectory structure under the destination directory.
+**Recursive download** lists all objects under the prefix, then downloads them in parallel while preserving the original subdirectory structure under the destination directory. A folder key without a destination downloads into a local directory named after its last segment (`omicslab download snapshots` → `./snapshots/`). An exact object always wins over a same-named folder prefix, and a key that matches neither reports "File or folder not found" instead of a provider 403/404.
 
 ## Environment Variables
 
@@ -132,6 +140,7 @@ omicslab download -y -r s3://my-bucket/data/results/ ./local_results/
 |---|---|
 | `OMICSLAB_TOKEN` | API token (overrides config file) |
 | `OMICSLAB_BASE_URL` | API base URL (default: `https://platform.omicslab.io/api`) |
+| `OMICSLAB_CONFIG_DIR` | Directory holding `config.json` (default: `~/.omicslab`); used by studio sessions to read a container-private config without changing `$HOME` |
 
 ## Jobs API
 
@@ -139,12 +148,13 @@ Analysis and studio jobs share one backend namespace:
 `/workspaces/{workspace_id}/jobs/...` — `job_type` ("analysis" | "studio")
 is part of the launch payload / list filter, not a separate URL space.
 `client.jobs` exposes generic methods (`launch`, `list_jobs`, `get_job`,
-`get_job_manifest`, `terminate_job`, `delete_job`, `connect_job`,
-`disconnect_job`, `check_job_ready`, ...) plus the domain aliases
-(`launch_analysis`, `launch_studio`, `list_analysis`, `list_studio`, ...)
-for convenience. Job resources (`time`/`cpu`/`memory`/`disk`) and the
-launch config live in the per-job manifest on S3, retrievable via
-`get_job_manifest` / `get_job_audit_params` / `get_job_audit_config`.
+`get_job_manifest`, `rerun_job`, `terminate_job`, `delete_job`,
+`connect_job`, `disconnect_job`, `check_job_ready`, ...) plus the domain
+aliases (`launch_analysis`, `launch_studio`, `rerun_analysis`,
+`rerun_studio`, `list_analysis`, `list_studio`, ...) for convenience. Job
+resources (`time`/`cpu`/`memory`/`disk`) and the launch config live in the
+per-job manifest on S3, retrievable via `get_job_manifest` /
+`get_job_audit_params` / `get_job_audit_config`.
 
 ```python
 from omicslab import Client
@@ -171,6 +181,52 @@ studio = client.jobs.launch_studio(
     compute_id="cloud-comp-...",
 )
 access = client.jobs.connect_job("ws-...", studio["id"])  # {"access_url": ...}
+
+# Rerun a job from its resolved launch manifest. Only the overrides below
+# change; tool/tag/pinned commit/versioning/config stay fixed to the source.
+rerun = client.jobs.rerun_analysis(
+    "ws-...",
+    job_id,
+    cpu=8,
+    time=7200,
+    params={"max_cpus": 8},  # merged per top-level key
+)
+# Masked secret params must be supplied again, otherwise the API returns 400.
+```
+
+The same rerun is available for studio sessions via
+`client.jobs.rerun_studio(...)`; the generic `client.jobs.rerun_job(...)`
+works for both. The response carries `old_job_id` and
+`changed_parameters` so callers can show what changed.
+
+```python
+# Estimate the max cost before launching
+estimate = client.jobs.estimate_job(
+    "ws-...",
+    compute_type="cloud",
+    compute_id="cloud-comp-...",
+    time=7200,
+    cpu=8,
+    memory=32,
+    disk=100,
+)
+
+# Status counts + per-period launch trend (workspace or organization scope)
+counts = client.jobs.get_job_counts("ws-...", job_type="analysis", granularity="daily")
+org_counts = client.orgs.get_job_counts("org-...", job_type="analysis")
+
+# Snapshot a RUNNING studio session into workspace storage
+client.jobs.snapshot_studio("ws-...", studio["id"], outdir="snapshots")
+
+# Server-side search/filter/sort (exact statuses need filter_column="status")
+client.jobs.list_analysis(
+    "ws-...",
+    search="bacass",
+    filter_column="status",
+    filter_value="running,failed",
+    sort_column="created_at",
+    sort_desc=True,
+)
 ```
 
 ## Testing

{omicslab-2.2.0 → omicslab-2.6.0}/README.developer.md

@@ -92,11 +92,11 @@ and then hand the raw token to `Client`.
 
 | Property   | Class                    | Purpose |
 |------------|--------------------------|---------|
-| `orgs`     | `OrgResource`            | Org CRUD + members + roles |
+| `orgs`     | `OrgResource`            | Org CRUD + members + roles + job counts |
 | `workspaces` | `WorkspaceResource`    | Workspace CRUD, members, pin, linked resources, budget/storage-quota (read-only) |
 | `analysis` | `AnalysisResource`       | Tool catalog (batch tools) CRUD/tags/profiles/schema |
 | `studio`   | `StudioResource`         | Tool catalog (interactive tools) CRUD + tags/profiles/schema |
-| `jobs`     | `JobResource`            | Launch/list/get/terminate analysis + studio jobs |
+| `jobs`     | `JobResource`            | Launch/list/get/rerun/estimate/counts/snapshot/terminate analysis + studio jobs |
 | `storage`  | `StorageResource`        | Upload/download list/delete/rename vs workspace S3 |
 | `credentials` | `CredentialResource`  | S3/GitHub/Cloud credentials (user + org scopes) |
 | `tokens`   | `TokenResource`          | Create/list/revoke API tokens |
@@ -248,15 +248,16 @@ bootstraps one session-scoped user via raw `httpx`:
 ```
 POST /api/auth/register/   (unique email)
 POST /api/auth/standard/   → access_token cookie
-GET  /api/organizations/            → take first (auto-provisioned Sponsor org)
+POST /api/organizations/            → create the test org
 POST /api/credentials/organization/{org}/storage/base/ + link s3   (storage cred)
 POST /api/organizations/{org}/workspaces/                             (workspace)
 POST /api/tokens/          → omx_ token scoped to org (admin)
 Client(token=..., base_url=...)
 ```
 
-Registration auto-provisions a **Sponsor org + Free subscription + workspace**
-(`service_auth/utils/provisioning.py`), so no payment step is needed.
+Registration does not create any organization; the conftest creates the org
+explicitly. A subscription is still activated for it through the payment flow
+(see `test_subscription`).
 
 ### 7.2 Fixtures
 
@@ -463,6 +464,52 @@ Studio jobs are unchanged: they run as background sandbox services via
 `executor.submit(...)` (spec/bash path), as do jobs dispatched to a runner
 daemon over WebSocket. Only `job run --work-dir` analysis is native/synchronous.
 
+Studio session mounts (no token exposure, snapshot-safe):
+
+- The SDK environment is bind-mounted **read-only at its own absolute path**
+  (pixi/conda envs are path-sensitive), and `omicslab`/`omx` are exposed on
+  `PATH` via a dedicated `/opt/omicslab/bin` directory.
+- `pixi` itself is mounted there too, together with the SDK project's
+  `pixi.toml`/`pixi.lock`, so `pixi run ...` works inside the session. A
+  writable copy of the env's small `conda-meta` directory is mounted over the
+  read-only one because pixi takes its install lock there and appends to
+  `history`; the copy lives in the job dir and is never snapshotted.
+- Users can create their own project envs in the writable workspace
+  (`pixi init` + `pixi add`); those envs are in the writable layer and **are**
+  included in snapshots. Pixi keeps its default package cache under the
+  session user's home, so that cache is part of the writable layer too and is
+  included in snapshots. No cache directory is mounted: sessions need no extra
+  mount, the cache never runs out of a fixed size cap, and pixi works for any
+  image user without permission fixes.
+- The staged CLI config is mounted from the host into
+  `OMICSLAB_CONFIG_DIR=/run/omicslab` before the container starts. The token
+  is replaced with a placeholder first; the SDK talks to a host-side
+  credential broker over `OMICSLAB_BROKER_SOCKET`, and the broker injects the
+  real `Authorization` header upstream. The mount is writable so context
+  commands such as `omx cd` can persist, but it contains only the placeholder
+  token — the real token never appears in the container env, `docker inspect`,
+  the writable layer, or a snapshot.
+  Presigned S3 URLs are still fetched directly by the container. Commands
+  that bypass `Client` (for example the websocket log stream) are not proxied
+  yet.
+- A selected **personal** GitHub credential is injected by a host-side Git
+  HTTPS proxy. Git inside the session rewrites `https://github.com/` to the
+  proxy URL, so no token or credential helper is present in the container.
+  Studio launches reject organization and marketplace credentials. The token
+  stays in the agent process and is never logged or returned to the session.
+- When `STUDIO_EXPORT_AWS_CREDENTIALS` is enabled (Settings → Studio), the
+  backend mints short-lived STS credentials for the workspace storage and the
+  agent starts a host-side S3 signing proxy. The session receives only
+  `AWS_ACCESS_KEY_ID=proxy`, `AWS_SECRET_ACCESS_KEY=proxy`, and
+  `AWS_ENDPOINT_URL=<host proxy>`; the real STS never enters the container.
+  Only credentials carrying a session token are proxied; long-lived provider
+  keys are never exported by this path.
+- The old implicit `/home/omicslab` bind is gone (opt-in via
+  `runtime.home_mount` only): user files stay in the container's writable layer
+  and are therefore included in `docker commit` snapshots.
+- Bind mounts and tmpfs are never committed, so neither the SDK nor the token
+  can leak into a snapshot.
+
 The SDK bootstrap URL is configurable:
 
 - Env var `SDK_TOOLS_BASE` (backend `settings.py`), default

{omicslab-2.2.0 → omicslab-2.6.0}/README.md

@@ -24,7 +24,7 @@ omicslab use
 omicslab ls && omicslab upload ./data.csv
 
 # 4. Launch a job
-omicslab jobs launch --workspace <ws_id> --analysis <id> --compute <id>
+omicslab ws analysis launch --workspace <ws_id> --analysis <id> --compute <id>
 ```
 
 ## Storage Commands
@@ -66,7 +66,7 @@ omicslab upload -y ./data.csv s3://my-bucket/data/
 
 ### Download
 
-Download files or directories from workspace storage. Recursive downloads preserve subdirectory structure and use parallel threads.
+Download files or directories from workspace storage. A folder is detected automatically, so a trailing slash and `-r` are optional; recursive downloads preserve subdirectory structure and use parallel threads.
 
 ```bash
 # Single file (defaults to filename in current directory)
@@ -78,7 +78,13 @@ omicslab download results/run1/data.csv ./local_copy.csv
 # Download from s3:// path (auto-resolves workspace)
 omicslab download s3://my-bucket/data/results/report.html
 
-# Recursive directory download (preserves subdirectory structure)
+# Folder download (auto-detected; defaults to ./run1)
+omicslab download results/run1
+
+# Folder download with explicit destination
+omicslab download results/run1 ./local_results/
+
+# Same thing, explicit recursive (preserves subdirectory structure)
 omicslab download -r s3://my-bucket/data/results/ ./local_results/
 
 # Recursive download with custom thread count
@@ -92,12 +98,13 @@ omicslab download -y -r s3://my-bucket/data/results/ ./local_results/
 
 | Flag | Description |
 |------|-------------|
-| `--recursive`, `-r` | Download all files under an s3:// directory prefix |
+| `--recursive`, `-r` | Force recursive download (folders are detected automatically) |
+| `--zip` | Download a folder as a server-built zip archive |
 | `--threads` | Concurrent download threads (default: 4) |
 | `--workspace-id`, `-w` | Workspace ID (inferred from s3:// path if provided) |
 | `--yes`, `-y` | Skip confirmation prompt for s3:// path resolution |
 
-**Recursive download** lists all objects under the prefix, then downloads them in parallel while preserving the original subdirectory structure under the destination directory.
+**Recursive download** lists all objects under the prefix, then downloads them in parallel while preserving the original subdirectory structure under the destination directory. A folder key without a destination downloads into a local directory named after its last segment (`omicslab download snapshots` → `./snapshots/`). An exact object always wins over a same-named folder prefix, and a key that matches neither reports "File or folder not found" instead of a provider 403/404.
 
 ## Environment Variables
 
@@ -105,6 +112,7 @@ omicslab download -y -r s3://my-bucket/data/results/ ./local_results/
 |---|---|
 | `OMICSLAB_TOKEN` | API token (overrides config file) |
 | `OMICSLAB_BASE_URL` | API base URL (default: `https://platform.omicslab.io/api`) |
+| `OMICSLAB_CONFIG_DIR` | Directory holding `config.json` (default: `~/.omicslab`); used by studio sessions to read a container-private config without changing `$HOME` |
 
 ## Jobs API
 
@@ -112,12 +120,13 @@ Analysis and studio jobs share one backend namespace:
 `/workspaces/{workspace_id}/jobs/...` — `job_type` ("analysis" | "studio")
 is part of the launch payload / list filter, not a separate URL space.
 `client.jobs` exposes generic methods (`launch`, `list_jobs`, `get_job`,
-`get_job_manifest`, `terminate_job`, `delete_job`, `connect_job`,
-`disconnect_job`, `check_job_ready`, ...) plus the domain aliases
-(`launch_analysis`, `launch_studio`, `list_analysis`, `list_studio`, ...)
-for convenience. Job resources (`time`/`cpu`/`memory`/`disk`) and the
-launch config live in the per-job manifest on S3, retrievable via
-`get_job_manifest` / `get_job_audit_params` / `get_job_audit_config`.
+`get_job_manifest`, `rerun_job`, `terminate_job`, `delete_job`,
+`connect_job`, `disconnect_job`, `check_job_ready`, ...) plus the domain
+aliases (`launch_analysis`, `launch_studio`, `rerun_analysis`,
+`rerun_studio`, `list_analysis`, `list_studio`, ...) for convenience. Job
+resources (`time`/`cpu`/`memory`/`disk`) and the launch config live in the
+per-job manifest on S3, retrievable via `get_job_manifest` /
+`get_job_audit_params` / `get_job_audit_config`.
 
 ```python
 from omicslab import Client
@@ -144,6 +153,52 @@ studio = client.jobs.launch_studio(
     compute_id="cloud-comp-...",
 )
 access = client.jobs.connect_job("ws-...", studio["id"])  # {"access_url": ...}
+
+# Rerun a job from its resolved launch manifest. Only the overrides below
+# change; tool/tag/pinned commit/versioning/config stay fixed to the source.
+rerun = client.jobs.rerun_analysis(
+    "ws-...",
+    job_id,
+    cpu=8,
+    time=7200,
+    params={"max_cpus": 8},  # merged per top-level key
+)
+# Masked secret params must be supplied again, otherwise the API returns 400.
+```
+
+The same rerun is available for studio sessions via
+`client.jobs.rerun_studio(...)`; the generic `client.jobs.rerun_job(...)`
+works for both. The response carries `old_job_id` and
+`changed_parameters` so callers can show what changed.
+
+```python
+# Estimate the max cost before launching
+estimate = client.jobs.estimate_job(
+    "ws-...",
+    compute_type="cloud",
+    compute_id="cloud-comp-...",
+    time=7200,
+    cpu=8,
+    memory=32,
+    disk=100,
+)
+
+# Status counts + per-period launch trend (workspace or organization scope)
+counts = client.jobs.get_job_counts("ws-...", job_type="analysis", granularity="daily")
+org_counts = client.orgs.get_job_counts("org-...", job_type="analysis")
+
+# Snapshot a RUNNING studio session into workspace storage
+client.jobs.snapshot_studio("ws-...", studio["id"], outdir="snapshots")
+
+# Server-side search/filter/sort (exact statuses need filter_column="status")
+client.jobs.list_analysis(
+    "ws-...",
+    search="bacass",
+    filter_column="status",
+    filter_value="running,failed",
+    sort_column="created_at",
+    sort_desc=True,
+)
 ```
 
 ## Testing

{omicslab-2.2.0 → omicslab-2.6.0}/pyproject.toml

@@ -32,6 +32,7 @@ dependencies = [
     "websockets>=13",
     "psutil>=6",
     "aiohttp>=3.10",
+    "botocore>=1.35,<2",
 ]
 
 [project.scripts]

{omicslab-2.2.0 → omicslab-2.6.0}/scripts/bootstrap-env.sh

@@ -37,13 +37,32 @@ PIXI_LOCK="${PIXI_LOCK:-pixi.lock}"
 PIXI_VERSION="${PIXI_VERSION:-v0.76.1}"
 RETRIES=3
 
+# Download helper. Every fetch is bounded and retried so a stalled connection
+# fails in minutes with a clear message instead of hanging until the platform's
+# SSH bootstrap deadline (900s) kills the job with no diagnostics. The bucket
+# sits behind a single gateway that also serves the conda/pypi payload, so
+# transient 5xx/timeouts must be retried rather than abort the whole bootstrap.
+FETCH_CONNECT_TIMEOUT="${FETCH_CONNECT_TIMEOUT:-10}"
+FETCH_MAX_TIME="${FETCH_MAX_TIME:-300}"
+FETCH_RETRIES="${FETCH_RETRIES:-5}"
+fetch() {
+    local url="$1" out="$2"
+    curl -fsSL \
+        --connect-timeout "${FETCH_CONNECT_TIMEOUT}" \
+        --max-time "${FETCH_MAX_TIME}" \
+        --retry "${FETCH_RETRIES}" \
+        --retry-delay 5 \
+        --retry-connrefused \
+        "$url" -o "$out"
+}
+
 # ── 1. pixi (from the tools bucket, absolute path under $HOME) ────────────
 PIXI_BIN="${HOME}/.pixi/bin/pixi"
 if [ ! -x "${PIXI_BIN}" ]; then
     PIXI_URL="$TOOLS_BASE/pixi/bin/pixi-${PIXI_VERSION}-linux-amd64.tar.gz"
     echo "Installing pixi ${PIXI_VERSION} from: $PIXI_URL"
     mkdir -p "$(dirname "${PIXI_BIN}")"
-    curl -fsSL "$PIXI_URL" -o /tmp/pixi.tar.gz
+    fetch "$PIXI_URL" /tmp/pixi.tar.gz
     tar -xzf /tmp/pixi.tar.gz -C "$(dirname "${PIXI_BIN}")"
     rm -f /tmp/pixi.tar.gz
 else
@@ -136,23 +155,32 @@ echo "Fetching manifest:"
 echo "  TOML: $TOML_URL"
 echo "  LOCK: $LOCK_URL"
 mkdir -p "$OMICSLAB_HOME"
-curl -fsSL "$TOML_URL" -o "$OMICSLAB_HOME/pixi.toml"
-curl -fsSL "$LOCK_URL" -o "$OMICSLAB_HOME/pixi.lock"
+fetch "$TOML_URL" "$OMICSLAB_HOME/pixi.toml"
+fetch "$LOCK_URL" "$OMICSLAB_HOME/pixi.lock"
 
 # ── 3. pixi install + SDK wheel (with retries) ────────────────────────────
 cd "$OMICSLAB_HOME"
+env_ready=0
 for i in $(seq 1 $RETRIES); do
     if "${PIXI_BIN}" install --frozen; then
+        env_ready=1
         break
     fi
     echo "bootstrap-retry-$i"
     sleep 5
 done
+# `set -e` does not fire for a command used as an `if` condition, so without an
+# explicit check the script would carry on with a half-installed environment
+# and fail later at the wheel step with a misleading message.
+if [ "$env_ready" -ne 1 ]; then
+    echo "ERROR: pixi install --frozen failed after ${RETRIES} attempts" >&2
+    exit 1
+fi
 
 # Download the stable alias and resolve the real version from wheel
 # metadata so pip gets a valid PEP 427 filename.
 echo "Installing omicslab SDK wheel..."
-curl -fsSL "$TOOLS_BASE/omicslab-latest.whl" -o /tmp/omicslab.whl
+fetch "$TOOLS_BASE/omicslab-latest.whl" /tmp/omicslab.whl
 VERSION=$("${PIXI_BIN}" run python3 -c "
 import zipfile, os
 z = zipfile.ZipFile('/tmp/omicslab.whl')

omicslab-2.6.0/src/omicslab/_version.py

@@ -0,0 +1 @@
+__version__ = "2.6.0"

{omicslab-2.2.0 → omicslab-2.6.0}/src/omicslab/cli/main.py

@@ -265,13 +265,13 @@ def pwd():
     parts = []
     if org:
         org_name = config.get_org_name() or org[:8]
-        parts.append(f"[cyan]{org_name}[/cyan]")
+        parts.append(f"[bold]{org_name}[/bold]")
     if ws:
         ws_name = config.get_workspace_name() or ws[:8]
-        parts.append(f"[green]{ws_name}[/green]")
+        parts.append(f"[bold]{ws_name}[/bold]")
     if stored_prefix is not None:
         p = "/" if not stored_prefix else stored_prefix.rstrip("/")
-        parts.append(f"[yellow]{p}[/yellow]")
+        parts.append(f"[bold]{p}[/bold]")
 
     if parts:
         console.print("  ".join(parts))
@@ -563,6 +563,11 @@ def upload(
         error(f"Cannot use --recursive with a file: {source}")
         raise typer.Exit(1)
 
+    # Studio/sandbox sessions export the job id; use it when the caller did
+    # not pass --job-id so uploads are attributed to the running job.
+    if job_id is None:
+        job_id = os.environ.get("OMICSLAB_JOB_ID") or os.environ.get("JOB_ID") or None
+
     config = Config()
     client = get_client()
 
@@ -819,19 +824,31 @@ def upload(
     _BATCH_SIZE = 500
 
     def _get_upload_urls_batch(batch: list[tuple[str, str]]) -> dict[str, str]:
-        """Get presigned URLs for a batch of files."""
+        """Get presigned URLs for a batch of files.
+
+        Keys are sent relative to the folder ``prefix`` so the upload is
+        audited against the folder, with the files listed as affected keys.
+        Presigned responses echo those relative keys, so map them back to the
+        full remote key used by the uploader.
+        """
         files_payload = []
         for local_path, remote_key in batch:
             try:
                 sz = os.path.getsize(local_path)
             except OSError:
                 sz = 0
-            files_payload.append({"key": remote_key, "size": sz})
+            files_payload.append(
+                {"key": remote_key.removeprefix(remote_prefix), "size": sz}
+            )
         try:
-            result = client.storage.batch_upload(ws, "", files_payload)
+            result = client.storage.batch_upload(
+                ws, remote_prefix, files_payload, job_id=job_id
+            )
             url_list = result.get("urls", []) if isinstance(result, dict) else result
             return {
-                entry["key"]: entry["url"] for entry in url_list if entry.get("url")
+                f"{remote_prefix}{entry['key']}": entry["url"]
+                for entry in url_list
+                if entry.get("url")
             }
         except Exception:
             return {}
@@ -966,10 +983,15 @@ def _download_folder_as_zip(
 @app.command()
 def download(
     key: str = typer.Argument(
-        ..., help="Remote file key to download, or s3://bucket/key or s3://bucket/dir/"
+        ...,
+        help=(
+            "Remote file or folder key to download, "
+            "or s3://bucket/key or s3://bucket/dir/"
+        ),
     ),
     destination: str | None = typer.Argument(
-        None, help="Local path (defaults to filename)"
+        None,
+        help="Local path (defaults to the filename, or the folder name for a folder)",
     ),
     workspace_id: str | None = typer.Option(
         None,
@@ -981,7 +1003,7 @@ def download(
         False,
         "--recursive",
         "-r",
-        help="Download all files under an s3:// directory prefix",
+        help="Force recursive download (folders are detected automatically)",
     ),
     zip_archive: bool = typer.Option(
         False,
@@ -998,7 +1020,11 @@ def download(
     """Download a file or directory from workspace storage.
 
     Accepts an s3://bucket/key to resolve the workspace automatically.
-    Use --recursive (-r) to download all files under an s3:// directory prefix.
+
+    Folders are detected automatically: ``omicslab download snapshots`` and
+    ``omicslab download snapshots/ ./snapshots -r`` do the same thing. A
+    folder downloads into a local directory named after its last key segment
+    unless a destination is given.
     """
     config = Config()
     client = get_client()
@@ -1012,8 +1038,6 @@ def download(
     if s3_info:
         ws = s3_info["workspace_id"]
         full_key = s3_info["key_prefix"]
-        if recursive:
-            full_key = full_key.rstrip("/") + "/" if full_key else ""
         print_panel(
             "S3 Path Resolution",
             {
@@ -1029,6 +1053,45 @@ def download(
         if prefix:
             full_key = prefix + key
 
+    # A trailing slash always means a folder. Without one, ask the listing
+    # whether the key is an object or a folder instead of blindly presigning
+    # it: a folder key would fail with a provider 403/404 and look like a
+    # broken URL.
+    folder = bool(full_key) and full_key.endswith("/")
+    if full_key and not folder:
+        try:
+            listing = client.storage.list(ws, prefix=full_key)
+        except Exception as e:
+            error(f"Failed to inspect {full_key!r}: {e}")
+            raise typer.Exit(1)
+        objects = (
+            listing
+            if isinstance(listing, list)
+            else listing.get("objects", [])
+            if isinstance(listing, dict)
+            else None
+        )
+        # ``objects is None`` only happens with an unexpected client shape;
+        # fall back to the object download rather than guessing.
+        if objects is not None:
+            if any(obj.get("is_file") and not obj.get("name") for obj in objects):
+                folder = False
+            elif any(
+                not obj.get("is_file") and obj.get("name") == "/" for obj in objects
+            ):
+                folder = True
+            else:
+                error(f"File or folder not found: {full_key}")
+                raise typer.Exit(1)
+
+    if zip_archive and not folder:
+        error("--zip requires a folder key.")
+        raise typer.Exit(1)
+
+    if folder:
+        full_key = full_key.rstrip("/") + "/"
+        recursive = True
+
     # Recursive directory download
     if recursive and (full_key.endswith("/") or not full_key):
         if zip_archive:
@@ -1076,7 +1139,11 @@ def download(
             info("No files found in this path.")
             return
 
-        dest_dir = Path(destination or ".") if destination else Path(".")
+        # A folder downloads into a directory named after its last key
+        # segment, so `download snapshots` is equivalent to
+        # `download snapshots/ ./snapshots -r`.
+        folder_name = full_key.rstrip("/").rsplit("/", 1)[-1]
+        dest_dir = Path(destination) if destination else Path(folder_name or ".")
         dest_dir.mkdir(parents=True, exist_ok=True)
 
         from rich.progress import (