verlet 0.1.0__tar.gz

verlet-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,20 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

verlet-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+.env

verlet-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Verlet
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

verlet-0.1.0/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: verlet
+Version: 0.1.0
+Summary: Download and explore Verlet datasets
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: click>=8.0
+Requires-Dist: httpx>=0.24
+Requires-Dist: rich>=13.0
+Description-Content-Type: text/markdown
+
+# verlet
+
+Download and explore Verlet datasets from the command line.
+
+## Install
+
+```bash
+curl -sSL https://raw.githubusercontent.com/verlet/verlet-cli/main/install.sh | bash
+```
+
+This creates an isolated venv at `~/.verlet/venv` and symlinks `verlet` into `~/.local/bin`.
+
+Or install manually:
+
+```bash
+pip install verlet
+```
+
+For development:
+
+```bash
+git clone https://github.com/verlet-robotics/verlet-cli.git
+cd verlet-cli
+pip install -e .
+```
+
+## Quick Start
+
+```bash
+# Authenticate with your access code
+verlet login
+
+# Browse available data
+verlet ego list
+verlet ego list --detailed --category Kitchen
+
+# Download data
+verlet ego download -o ./data --category Kitchen
+
+# Check segment details
+verlet ego info station-1__episode_042_seg5
+```
+
+## Commands
+
+### Authentication
+
+```bash
+verlet login       # Prompt for access code, store JWT
+verlet logout      # Remove stored credentials
+```
+
+### EgoDex Hand Pose Data (`verlet ego`)
+
+```bash
+# List categories and segment counts
+verlet ego list
+verlet ego list --task station-1
+verlet ego list --category Kitchen
+verlet ego list --detailed
+
+# Download segments
+verlet ego download                              # all segments to ./verlet-data/ego/
+verlet ego download -o ./data                    # custom output directory
+verlet ego download --category Kitchen           # filter by category
+verlet ego download --include "*.hdf5,*.mp4"     # only specific file types
+verlet ego download --exclude "*.egorec,*.rrd"   # skip large files
+verlet ego download --parallel 16                # concurrency (default 8)
+verlet ego download --dry-run                    # show download plan only
+
+# Segment info
+verlet ego info SEGMENT_ID
+```
+
+## Data Layout
+
+Downloaded data is organized by station and episode:
+
+```
+verlet-data/ego/
+  station-1/
+    episode_042_seg5/
+      segment.egorec
+      hands.npz
+      overlay.mp4
+      recording.rrd
+      egodex/manipulation/0.hdf5
+      egodex/manipulation/0.mp4
+```

verlet-0.1.0/README.md

@@ -0,0 +1,89 @@
+# verlet
+
+Download and explore Verlet datasets from the command line.
+
+## Install
+
+```bash
+curl -sSL https://raw.githubusercontent.com/verlet/verlet-cli/main/install.sh | bash
+```
+
+This creates an isolated venv at `~/.verlet/venv` and symlinks `verlet` into `~/.local/bin`.
+
+Or install manually:
+
+```bash
+pip install verlet
+```
+
+For development:
+
+```bash
+git clone https://github.com/verlet-robotics/verlet-cli.git
+cd verlet-cli
+pip install -e .
+```
+
+## Quick Start
+
+```bash
+# Authenticate with your access code
+verlet login
+
+# Browse available data
+verlet ego list
+verlet ego list --detailed --category Kitchen
+
+# Download data
+verlet ego download -o ./data --category Kitchen
+
+# Check segment details
+verlet ego info station-1__episode_042_seg5
+```
+
+## Commands
+
+### Authentication
+
+```bash
+verlet login       # Prompt for access code, store JWT
+verlet logout      # Remove stored credentials
+```
+
+### EgoDex Hand Pose Data (`verlet ego`)
+
+```bash
+# List categories and segment counts
+verlet ego list
+verlet ego list --task station-1
+verlet ego list --category Kitchen
+verlet ego list --detailed
+
+# Download segments
+verlet ego download                              # all segments to ./verlet-data/ego/
+verlet ego download -o ./data                    # custom output directory
+verlet ego download --category Kitchen           # filter by category
+verlet ego download --include "*.hdf5,*.mp4"     # only specific file types
+verlet ego download --exclude "*.egorec,*.rrd"   # skip large files
+verlet ego download --parallel 16                # concurrency (default 8)
+verlet ego download --dry-run                    # show download plan only
+
+# Segment info
+verlet ego info SEGMENT_ID
+```
+
+## Data Layout
+
+Downloaded data is organized by station and episode:
+
+```
+verlet-data/ego/
+  station-1/
+    episode_042_seg5/
+      segment.egorec
+      hands.npz
+      overlay.mp4
+      recording.rrd
+      egodex/manipulation/0.hdf5
+      egodex/manipulation/0.mp4
+```

verlet-0.1.0/install.sh

@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+# Install verlet CLI into ~/.verlet/venv and symlink to ~/.local/bin/verlet
+# Usage: curl -sSL https://raw.githubusercontent.com/verlet/verlet-cli/main/install.sh | bash
+set -euo pipefail
+
+INSTALL_DIR="$HOME/.verlet"
+VENV_DIR="$INSTALL_DIR/venv"
+BIN_DIR="$HOME/.local/bin"
+PACKAGE="verlet"
+REPO="https://github.com/verlet-robotics/verlet-cli.git"
+
+info()  { printf '\033[1;34m==>\033[0m %s\n' "$*"; }
+ok()    { printf '\033[1;32m==>\033[0m %s\n' "$*"; }
+err()   { printf '\033[1;31merror:\033[0m %s\n' "$*" >&2; exit 1; }
+
+# --- Check python ---
+PYTHON=""
+for cmd in python3 python; do
+    if command -v "$cmd" &>/dev/null; then
+        version=$("$cmd" -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')" 2>/dev/null || true)
+        major=$(echo "$version" | cut -d. -f1)
+        minor=$(echo "$version" | cut -d. -f2)
+        if [ "$major" = "3" ] && [ "$minor" -ge 10 ]; then
+            PYTHON="$cmd"
+            break
+        fi
+    fi
+done
+[ -n "$PYTHON" ] || err "Python 3.10+ is required but not found. Install it first."
+info "Using $PYTHON ($version)"
+
+# --- Create venv ---
+if [ -d "$VENV_DIR" ]; then
+    info "Removing existing venv..."
+    rm -rf "$VENV_DIR"
+fi
+
+info "Creating virtual environment at $VENV_DIR..."
+"$PYTHON" -m venv "$VENV_DIR"
+
+# --- Install ---
+info "Installing verlet..."
+"$VENV_DIR/bin/pip" install --quiet --upgrade pip
+"$VENV_DIR/bin/pip" install --quiet "$PACKAGE" 2>/dev/null \
+    || "$VENV_DIR/bin/pip" install --quiet "git+${REPO}"
+
+# --- Symlink ---
+mkdir -p "$BIN_DIR"
+ln -sf "$VENV_DIR/bin/verlet" "$BIN_DIR/verlet"
+
+# --- Check PATH ---
+if ! echo "$PATH" | tr ':' '\n' | grep -qx "$BIN_DIR"; then
+    SHELL_NAME=$(basename "$SHELL")
+    case "$SHELL_NAME" in
+        zsh)  RC="$HOME/.zshrc" ;;
+        bash) RC="$HOME/.bashrc" ;;
+        fish) RC="$HOME/.config/fish/config.fish" ;;
+        *)    RC="" ;;
+    esac
+
+    if [ -n "$RC" ]; then
+        if [ "$SHELL_NAME" = "fish" ]; then
+            echo "fish_add_path $BIN_DIR" >> "$RC"
+        else
+            echo "export PATH=\"$BIN_DIR:\$PATH\"" >> "$RC"
+        fi
+        ok "Added $BIN_DIR to PATH in $RC"
+        info "Restart your shell or run: export PATH=\"$BIN_DIR:\$PATH\""
+    else
+        info "Add $BIN_DIR to your PATH manually."
+    fi
+fi
+
+ok "Installed! Run 'verlet login' to get started."

verlet-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "verlet"
+version = "0.1.0"
+description = "Download and explore Verlet datasets"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+dependencies = [
+    "click>=8.0",
+    "httpx>=0.24",
+    "rich>=13.0",
+]
+
+[project.scripts]
+verlet = "verlet.cli:cli"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/verlet"]

verlet-0.1.0/src/verlet/__init__.py

@@ -0,0 +1,3 @@
+"""Verlet CLI — download and explore Verlet datasets."""
+
+__version__ = "0.1.0"

verlet-0.1.0/src/verlet/auth.py

@@ -0,0 +1,102 @@
+"""Authentication: login, logout, token validation."""
+
+from __future__ import annotations
+
+import base64
+import json
+import time
+
+import click
+import httpx
+
+from verlet.config import DEFAULT_API_BASE, clear_config, load_config, save_config
+
+
+def _decode_jwt_payload(token: str) -> dict:
+    """Decode JWT payload (no signature verification — server is authoritative)."""
+    parts = token.split(".")
+    if len(parts) != 3:
+        raise ValueError("Invalid JWT format")
+    # Add padding
+    payload_b64 = parts[1] + "=" * (-len(parts[1]) % 4)
+    return json.loads(base64.urlsafe_b64decode(payload_b64))
+
+
+def get_auth_headers() -> dict[str, str]:
+    """Return headers for authenticated API requests, or raise click.ClickException."""
+    cfg = load_config()
+    token = cfg.get("token")
+    if not token:
+        raise click.ClickException(
+            "Not logged in. Run 'verlet login' first."
+        )
+    expires_at = cfg.get("expires_at", 0)
+    if time.time() > expires_at:
+        raise click.ClickException(
+            "Session expired. Run 'verlet login' to re-authenticate."
+        )
+    return {
+        "Cookie": f"access_token={token}",
+        "Authorization": f"Bearer {token}",
+    }
+
+
+def get_api_base() -> str:
+    return load_config().get("api_base", DEFAULT_API_BASE)
+
+
+def login(api_base: str | None = None) -> None:
+    """Prompt for access code and authenticate."""
+    api_base = api_base or DEFAULT_API_BASE
+    code = click.prompt("Access code", hide_input=True)
+
+    try:
+        resp = httpx.post(
+            f"{api_base}/api/auth",
+            json={"code": code},
+            timeout=15,
+        )
+    except httpx.RequestError as e:
+        raise click.ClickException(f"Connection failed: {e}")
+
+    if resp.status_code != 200:
+        detail = resp.json().get("error", resp.text)
+        raise click.ClickException(f"Authentication failed: {detail}")
+
+    body = resp.json()
+    customer = body.get("customer", "unknown")
+
+    # Get token from response body (preferred) or Set-Cookie header (fallback)
+    token = body.get("token")
+    if not token:
+        cookie_header = resp.headers.get("set-cookie", "")
+        for part in cookie_header.split(";"):
+            part = part.strip()
+            if part.startswith("access_token="):
+                token = part.split("=", 1)[1]
+                break
+
+    if not token:
+        raise click.ClickException("No token received from server.")
+
+    # Decode expiry from JWT
+    try:
+        payload = _decode_jwt_payload(token)
+        expires_at = payload.get("exp", time.time() + 604800)
+    except Exception:
+        expires_at = time.time() + 604800  # fallback: 7 days
+
+    save_config({
+        "token": token,
+        "customer": customer,
+        "api_base": api_base,
+        "expires_at": expires_at,
+    })
+
+    click.echo(f"Logged in as {click.style(customer, bold=True)}")
+
+
+def logout() -> None:
+    """Remove stored credentials."""
+    clear_config()
+    click.echo("Logged out.")

verlet-0.1.0/src/verlet/cli.py

@@ -0,0 +1,39 @@
+"""Top-level CLI group — registers auth commands and modality subgroups."""
+
+from __future__ import annotations
+
+import click
+
+from verlet import __version__
+from verlet.auth import login, logout
+from verlet.config import DEFAULT_API_BASE
+from verlet.ego.commands import ego_group
+
+
+@click.group()
+@click.version_option(__version__, prog_name="verlet")
+def cli():
+    """Verlet CLI — download and explore Verlet datasets."""
+
+
+@cli.command()
+@click.option("--api-base", default=None, help=f"API base URL (default: {DEFAULT_API_BASE}).")
+def login_cmd(api_base: str | None):
+    """Authenticate with your access code."""
+    login(api_base)
+
+
+# Register as 'login' not 'login-cmd'
+login_cmd.name = "login"
+
+
+@cli.command()
+def logout_cmd():
+    """Remove stored credentials."""
+    logout()
+
+
+logout_cmd.name = "logout"
+
+# Register modality subgroups
+cli.add_command(ego_group)

verlet-0.1.0/src/verlet/config.py

@@ -0,0 +1,33 @@
+"""Config file management for ~/.verlet/config.json."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+CONFIG_DIR = Path.home() / ".verlet"
+CONFIG_FILE = CONFIG_DIR / "config.json"
+
+DEFAULT_API_BASE = "https://ego.verlet.co"
+
+
+def ensure_config_dir() -> Path:
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    return CONFIG_DIR
+
+
+def load_config() -> dict[str, Any]:
+    if not CONFIG_FILE.exists():
+        return {}
+    return json.loads(CONFIG_FILE.read_text())
+
+
+def save_config(data: dict[str, Any]) -> None:
+    ensure_config_dir()
+    CONFIG_FILE.write_text(json.dumps(data, indent=2) + "\n")
+
+
+def clear_config() -> None:
+    if CONFIG_FILE.exists():
+        CONFIG_FILE.unlink()

verlet-0.1.0/src/verlet/display.py

@@ -0,0 +1,79 @@
+"""Shared Rich display utilities for tables and formatting."""
+
+from __future__ import annotations
+
+from rich.console import Console
+from rich.table import Table
+
+console = Console()
+
+
+def format_duration(seconds: float) -> str:
+    """Format seconds as human-readable duration."""
+    if seconds < 60:
+        return f"{seconds:.0f}s"
+    minutes = int(seconds // 60)
+    secs = int(seconds % 60)
+    if minutes < 60:
+        return f"{minutes}m {secs:02d}s"
+    hours = minutes // 60
+    mins = minutes % 60
+    return f"{hours}h {mins:02d}m"
+
+
+def format_size(nbytes: int) -> str:
+    """Format bytes as human-readable size."""
+    for unit in ("B", "KB", "MB", "GB", "TB"):
+        if nbytes < 1024:
+            return f"{nbytes:.1f} {unit}"
+        nbytes /= 1024
+    return f"{nbytes:.1f} PB"
+
+
+def category_table(categories: list[dict]) -> Table:
+    """Build a Rich table for category listing."""
+    table = Table(title="EgoDex Catalog")
+    table.add_column("Category", style="bold cyan")
+    table.add_column("Subcategory", style="white")
+    table.add_column("Segments", justify="right", style="green")
+    table.add_column("Duration", justify="right", style="yellow")
+
+    for cat in categories:
+        first = True
+        for sub in cat.get("subcategories", []):
+            table.add_row(
+                cat["category"] if first else "",
+                sub["subcategory"],
+                str(sub["segmentCount"]),
+                format_duration(sub["totalDurationSec"]),
+            )
+            first = False
+        if not cat.get("subcategories"):
+            table.add_row(
+                cat["category"],
+                "-",
+                str(cat.get("segmentCount", 0)),
+                format_duration(cat.get("totalDurationSec", 0)),
+            )
+
+    return table
+
+
+def segment_table(segments: list[dict]) -> Table:
+    """Build a Rich table for detailed segment listing."""
+    table = Table(title="Segments")
+    table.add_column("ID", style="bold")
+    table.add_column("Category", style="cyan")
+    table.add_column("Subcategory", style="white")
+    table.add_column("Station", style="magenta")
+    table.add_column("Duration", justify="right", style="yellow")
+
+    for seg in segments:
+        table.add_row(
+            seg["id"],
+            seg.get("category", ""),
+            seg.get("subcategory", ""),
+            seg.get("station", ""),
+            format_duration(seg.get("durationSec", 0)),
+        )
+    return table

verlet-0.1.0/src/verlet/ego/__init__.py

@@ -0,0 +1 @@
+"""Ego modality commands."""

verlet-0.1.0/src/verlet/ego/catalog.py

@@ -0,0 +1,142 @@
+"""Fetch and filter the EgoDex catalog from the API."""
+
+from __future__ import annotations
+
+from fnmatch import fnmatch
+
+import click
+import httpx
+
+from verlet.auth import get_api_base, get_auth_headers
+
+# Known files per segment in the output bucket.
+# Key format: {station}/{episode}_seg{id}/{filename}
+SEGMENT_FILES = [
+    "segment.egorec",
+    "hands.npz",
+    "overlay.mp4",
+    "recording.rrd",
+    "egodex/manipulation/0.hdf5",
+    "egodex/manipulation/0.mp4",
+]
+
+
+def fetch_catalog() -> dict:
+    """Fetch the full catalog from the API."""
+    base = get_api_base()
+    headers = get_auth_headers()
+    try:
+        resp = httpx.get(f"{base}/api/catalog", headers=headers, timeout=30)
+    except httpx.RequestError as e:
+        raise click.ClickException(f"Connection failed: {e}")
+
+    if resp.status_code == 401:
+        raise click.ClickException("Session expired. Run 'verlet login' to re-authenticate.")
+    if resp.status_code != 200:
+        raise click.ClickException(f"Catalog request failed ({resp.status_code}): {resp.text}")
+
+    return resp.json()
+
+
+def flatten_segments(catalog: dict) -> list[dict]:
+    """Extract a flat list of segments from the catalog."""
+    segments = []
+    for cat in catalog.get("categories", []):
+        for sub in cat.get("subcategories", []):
+            for seg in sub.get("segments", []):
+                segments.append(seg)
+    return segments
+
+
+def filter_segments(
+    segments: list[dict],
+    *,
+    task: str | None = None,
+    category: str | None = None,
+) -> list[dict]:
+    """Filter segments by task (station) and/or category."""
+    out = segments
+    if task:
+        task_lower = task.lower()
+        out = [s for s in out if s.get("station", "").lower() == task_lower]
+    if category:
+        cat_lower = category.lower()
+        out = [s for s in out if s.get("category", "").lower() == cat_lower]
+    return out
+
+
+def filter_categories(
+    categories: list[dict],
+    *,
+    task: str | None = None,
+    category: str | None = None,
+) -> list[dict]:
+    """Filter category groups. Returns a new list with matching entries."""
+    out = categories
+    if category:
+        cat_lower = category.lower()
+        out = [c for c in out if c["category"].lower() == cat_lower]
+    if task:
+        # Filter segments within each category/subcategory by station
+        task_lower = task.lower()
+        filtered = []
+        for cat in out:
+            new_subs = []
+            for sub in cat.get("subcategories", []):
+                matching = [
+                    s for s in sub.get("segments", [])
+                    if s.get("station", "").lower() == task_lower
+                ]
+                if matching:
+                    new_subs.append({
+                        **sub,
+                        "segments": matching,
+                        "segmentCount": len(matching),
+                        "totalDurationSec": sum(s.get("durationSec", 0) for s in matching),
+                    })
+            if new_subs:
+                filtered.append({
+                    **cat,
+                    "subcategories": new_subs,
+                    "segmentCount": sum(s["segmentCount"] for s in new_subs),
+                    "totalDurationSec": sum(s["totalDurationSec"] for s in new_subs),
+                })
+        out = filtered
+    return out
+
+
+def segment_r2_prefix(seg: dict) -> str:
+    """Build the output-bucket prefix for a segment.
+
+    Segment IDs are like 'station-1__episode_042_seg5'.
+    Output bucket layout: station-1/episode_042_seg5/
+    """
+    sid = seg["id"]
+    parts = sid.split("__", 1)
+    if len(parts) == 2:
+        return f"{parts[0]}/{parts[1]}"
+    return sid
+
+
+def segment_file_list(
+    seg: dict,
+    *,
+    include: list[str] | None = None,
+    exclude: list[str] | None = None,
+) -> list[str]:
+    """Return list of R2 keys for a segment, after include/exclude filtering."""
+    prefix = segment_r2_prefix(seg)
+    keys = [f"{prefix}/{f}" for f in SEGMENT_FILES]
+
+    if include:
+        keys = [
+            k for k in keys
+            if any(fnmatch(k.rsplit("/", 1)[-1], pat) for pat in include)
+        ]
+    if exclude:
+        keys = [
+            k for k in keys
+            if not any(fnmatch(k.rsplit("/", 1)[-1], pat) for pat in exclude)
+        ]
+
+    return keys

verlet-0.1.0/src/verlet/ego/commands.py

@@ -0,0 +1,151 @@
+"""Click commands for the ego modality."""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+
+import click
+
+from verlet.display import category_table, console, format_duration, segment_table
+from verlet.ego.catalog import (
+    fetch_catalog,
+    filter_categories,
+    filter_segments,
+    flatten_segments,
+    segment_file_list,
+    segment_r2_prefix,
+)
+
+
+@click.group("ego")
+def ego_group():
+    """EgoDex hand-pose data."""
+
+
+@ego_group.command("list")
+@click.option("--task", default=None, help="Filter by station/task name.")
+@click.option("--category", default=None, help="Filter by category.")
+@click.option("--detailed", is_flag=True, help="Show individual segments.")
+def list_cmd(task: str | None, category: str | None, detailed: bool):
+    """List available EgoDex data."""
+    catalog = fetch_catalog()
+
+    if detailed:
+        segments = flatten_segments(catalog)
+        segments = filter_segments(segments, task=task, category=category)
+        if not segments:
+            console.print("No segments found matching filters.")
+            return
+        console.print(segment_table(segments))
+        console.print(f"\n[bold]{len(segments)}[/bold] segments, "
+                      f"{format_duration(sum(s.get('durationSec', 0) for s in segments))} total")
+    else:
+        categories = catalog.get("categories", [])
+        categories = filter_categories(categories, task=task, category=category)
+        if not categories:
+            console.print("No categories found matching filters.")
+            return
+        console.print(category_table(categories))
+        total_segs = sum(c.get("segmentCount", 0) for c in categories)
+        total_dur = sum(c.get("totalDurationSec", 0) for c in categories)
+        console.print(f"\n[bold]{total_segs}[/bold] segments, {format_duration(total_dur)} total")
+
+
+@ego_group.command("info")
+@click.argument("segment_id")
+def info_cmd(segment_id: str):
+    """Show details for a specific segment."""
+    catalog = fetch_catalog()
+    segments = flatten_segments(catalog)
+
+    seg = next((s for s in segments if s["id"] == segment_id), None)
+    if not seg:
+        raise click.ClickException(f"Segment '{segment_id}' not found.")
+
+    console.print(f"[bold]Segment:[/bold] {seg['id']}")
+    console.print(f"[bold]Station:[/bold] {seg.get('station', 'N/A')}")
+    console.print(f"[bold]Category:[/bold] {seg.get('category', 'N/A')}")
+    console.print(f"[bold]Subcategory:[/bold] {seg.get('subcategory', 'N/A')}")
+    console.print(f"[bold]Duration:[/bold] {format_duration(seg.get('durationSec', 0))}")
+    console.print(f"[bold]Time range:[/bold] {seg.get('startSec', 0):.1f}s — {seg.get('endSec', 0):.1f}s")
+
+    cam = seg.get("cameraInfo")
+    if cam:
+        console.print(f"[bold]Camera:[/bold] fx={cam['fx']:.1f} fy={cam['fy']:.1f} "
+                       f"ppx={cam['ppx']:.1f} ppy={cam['ppy']:.1f}")
+
+    prefix = segment_r2_prefix(seg)
+    console.print(f"[bold]R2 prefix:[/bold] {prefix}/")
+
+    console.print("\n[bold]Files:[/bold]")
+    for key in segment_file_list(seg):
+        console.print(f"  {key}")
+
+
+@ego_group.command("download")
+@click.option("-o", "--output", default="./verlet-data", type=click.Path(), help="Output directory.")
+@click.option("--task", default=None, help="Filter by station/task name.")
+@click.option("--category", default=None, help="Filter by category.")
+@click.option("--include", default=None, help="Comma-separated glob patterns for files to include.")
+@click.option("--exclude", default=None, help="Comma-separated glob patterns for files to exclude.")
+@click.option("--parallel", default=8, type=int, help="Number of concurrent downloads.")
+@click.option("--dry-run", is_flag=True, help="Show download plan without downloading.")
+def download_cmd(
+    output: str,
+    task: str | None,
+    category: str | None,
+    include: str | None,
+    exclude: str | None,
+    parallel: int,
+    dry_run: bool,
+):
+    """Download EgoDex data segments."""
+    catalog = fetch_catalog()
+    segments = flatten_segments(catalog)
+    segments = filter_segments(segments, task=task, category=category)
+
+    if not segments:
+        console.print("No segments found matching filters.")
+        return
+
+    include_pats = [p.strip() for p in include.split(",")] if include else None
+    exclude_pats = [p.strip() for p in exclude.split(",")] if exclude else None
+
+    # Build download plan: list of (r2_key, local_path)
+    base_dir = Path(output) / "ego"
+    file_plan: list[tuple[str, Path]] = []
+
+    for seg in segments:
+        keys = segment_file_list(seg, include=include_pats, exclude=exclude_pats)
+        prefix = segment_r2_prefix(seg)
+        for key in keys:
+            # key is like "station-1/episode_042_seg5/hands.npz"
+            rel = key  # already relative
+            local_path = base_dir / rel
+            file_plan.append((key, local_path))
+
+    # Skip already-downloaded files (size check happens during download)
+    existing = sum(1 for _, p in file_plan if p.exists())
+
+    console.print(f"[bold]{len(segments)}[/bold] segments, "
+                  f"[bold]{len(file_plan)}[/bold] files to download")
+    if existing:
+        console.print(f"  ({existing} files already exist locally — will verify sizes)")
+    console.print(f"  Output: {base_dir.resolve()}")
+
+    if dry_run:
+        console.print("\n[bold]Download plan:[/bold]")
+        for key, local in file_plan:
+            status = "[green]exists[/]" if local.exists() else "[dim]pending[/]"
+            console.print(f"  {status} {key}")
+        return
+
+    from verlet.ego.download import download_files
+
+    ok, fail = asyncio.run(download_files(file_plan, parallel=parallel))
+
+    console.print(f"\n[bold green]{ok}[/] downloaded", end="")
+    if fail:
+        console.print(f", [bold red]{fail}[/] failed", end="")
+    console.print()

verlet-0.1.0/src/verlet/ego/download.py

@@ -0,0 +1,145 @@
+"""Async download engine with presigned URLs and Rich progress."""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+
+import httpx
+from rich.progress import (
+    BarColumn,
+    DownloadColumn,
+    Progress,
+    TaskID,
+    TextColumn,
+    TimeRemainingColumn,
+    TransferSpeedColumn,
+)
+
+from verlet.auth import get_api_base, get_auth_headers
+from verlet.display import console
+
+CHUNK_SIZE = 256 * 1024  # 256 KB
+
+
+async def _presign(
+    client: httpx.AsyncClient,
+    api_base: str,
+    headers: dict[str, str],
+    r2_key: str,
+) -> str:
+    """Get a presigned URL for an R2 key."""
+    resp = await client.get(
+        f"{api_base}/api/presign",
+        params={"key": r2_key, "bucket": "output"},
+        headers=headers,
+    )
+    if resp.status_code == 401:
+        raise RuntimeError("Session expired. Run 'verlet login' to re-authenticate.")
+    resp.raise_for_status()
+    return resp.json()["url"]
+
+
+async def _download_file(
+    client: httpx.AsyncClient,
+    api_base: str,
+    auth_headers: dict[str, str],
+    r2_key: str,
+    local_path: Path,
+    semaphore: asyncio.Semaphore,
+    progress: Progress,
+    overall_task: TaskID,
+    retries: int = 3,
+) -> bool:
+    """Download a single file with retries and progress tracking."""
+    tmp_path = local_path.with_suffix(local_path.suffix + ".tmp")
+
+    for attempt in range(1, retries + 1):
+        try:
+            async with semaphore:
+                url = await _presign(client, api_base, auth_headers, r2_key)
+
+                async with client.stream("GET", url) as resp:
+                    resp.raise_for_status()
+                    total = int(resp.headers.get("content-length", 0))
+
+                    # Skip if local file matches remote size
+                    if local_path.exists() and local_path.stat().st_size == total and total > 0:
+                        progress.advance(overall_task, total)
+                        return True
+
+                    local_path.parent.mkdir(parents=True, exist_ok=True)
+
+                    file_task = progress.add_task(
+                        f"  {r2_key.rsplit('/', 1)[-1]}",
+                        total=total or None,
+                    )
+
+                    with open(tmp_path, "wb") as f:
+                        async for chunk in resp.aiter_bytes(CHUNK_SIZE):
+                            f.write(chunk)
+                            progress.advance(file_task, len(chunk))
+                            progress.advance(overall_task, len(chunk))
+
+                    progress.remove_task(file_task)
+
+                # Atomic rename
+                tmp_path.rename(local_path)
+                return True
+
+        except Exception as e:
+            if tmp_path.exists():
+                tmp_path.unlink()
+            if attempt == retries:
+                console.print(f"[red]Failed[/] {r2_key}: {e}")
+                return False
+            await asyncio.sleep(2 ** attempt)
+
+    return False
+
+
+async def download_files(
+    file_plan: list[tuple[str, Path]],
+    parallel: int = 8,
+) -> tuple[int, int]:
+    """Download a list of (r2_key, local_path) pairs concurrently.
+
+    Returns (success_count, fail_count).
+    """
+    if not file_plan:
+        console.print("Nothing to download.")
+        return 0, 0
+
+    # Check which files can be skipped (already downloaded with correct size)
+    api_base = get_api_base()
+    auth_headers = get_auth_headers()
+    semaphore = asyncio.Semaphore(parallel)
+
+    # Estimate total bytes (unknown until presign, so we track dynamically)
+    with Progress(
+        TextColumn("[bold blue]{task.description}"),
+        BarColumn(),
+        DownloadColumn(),
+        TransferSpeedColumn(),
+        TimeRemainingColumn(),
+        console=console,
+    ) as progress:
+        overall_task = progress.add_task("Downloading", total=0)
+
+        # First pass: get total size by presigning all files
+        # (done lazily during download to avoid expiry)
+
+        async with httpx.AsyncClient(timeout=httpx.Timeout(60, connect=15)) as client:
+            tasks = [
+                _download_file(
+                    client, api_base, auth_headers,
+                    r2_key, local_path,
+                    semaphore, progress, overall_task,
+                )
+                for r2_key, local_path in file_plan
+            ]
+            results = await asyncio.gather(*tasks)
+
+    ok = sum(1 for r in results if r)
+    fail = sum(1 for r in results if not r)
+    return ok, fail