strava-client-cli 0.1.0__tar.gz

strava_client_cli-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+*.egg-info/
+uv.lock

strava_client_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Geo Deterra
+
+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.

strava_client_cli-0.1.0/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: strava-client-cli
+Version: 0.1.0
+Summary: CLI tool for interacting with the Strava API
+Project-URL: Homepage, https://github.com/geodeterra/strava-cli
+Project-URL: Repository, https://github.com/geodeterra/strava-cli
+Author-email: Geo Deterra <geo.deterra@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,cycling,fitness,running,strava
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.9.0
+Description-Content-Type: text/markdown
+
+# strava-cli
+
+CLI tool for interacting with the Strava API.
+
+## Install
+
+```bash
+uv pip install -e .
+```
+
+## Setup
+
+1. Create a Strava API app at https://www.strava.com/settings/api
+2. Set callback URL to `http://localhost`
+3. Run `strava auth` and follow the prompts
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `strava auth` | OAuth2 setup flow |
+| `strava profile` | Show athlete profile |
+| `strava stats` | Athlete stats summary |
+| `strava activities` | List recent activities |
+| `strava activity <id>` | Detailed activity view |
+| `strava export` | Bulk export activities |
+
+## Usage
+
+```bash
+# List last 10 activities
+strava activities --limit 10
+
+# Filter by type and date
+strava activities --type Run --after 2024-01-01
+
+# View a specific activity
+strava activity 12345678
+
+# Export activities to JSON
+strava export --output ./export --format json --after 2024-01-01
+```
+
+## Token Management
+
+Tokens are stored in `~/.config/strava-cli/tokens.json` and automatically refreshed when expired (every 6 hours).

strava_client_cli-0.1.0/README.md

@@ -0,0 +1,46 @@
+# strava-cli
+
+CLI tool for interacting with the Strava API.
+
+## Install
+
+```bash
+uv pip install -e .
+```
+
+## Setup
+
+1. Create a Strava API app at https://www.strava.com/settings/api
+2. Set callback URL to `http://localhost`
+3. Run `strava auth` and follow the prompts
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `strava auth` | OAuth2 setup flow |
+| `strava profile` | Show athlete profile |
+| `strava stats` | Athlete stats summary |
+| `strava activities` | List recent activities |
+| `strava activity <id>` | Detailed activity view |
+| `strava export` | Bulk export activities |
+
+## Usage
+
+```bash
+# List last 10 activities
+strava activities --limit 10
+
+# Filter by type and date
+strava activities --type Run --after 2024-01-01
+
+# View a specific activity
+strava activity 12345678
+
+# Export activities to JSON
+strava export --output ./export --format json --after 2024-01-01
+```
+
+## Token Management
+
+Tokens are stored in `~/.config/strava-cli/tokens.json` and automatically refreshed when expired (every 6 hours).

strava_client_cli-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[project]
+name = "strava-client-cli"
+version = "0.1.0"
+description = "CLI tool for interacting with the Strava API"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [
+    { name = "Geo Deterra", email = "geo.deterra@gmail.com" },
+]
+keywords = ["strava", "cli", "running", "cycling", "fitness"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Internet :: WWW/HTTP",
+]
+dependencies = [
+    "typer>=0.9.0",
+    "httpx>=0.27.0",
+    "rich>=13.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/geodeterra/strava-cli"
+Repository = "https://github.com/geodeterra/strava-cli"
+
+[project.scripts]
+strava = "strava_cli.cli:app"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/strava_cli"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

strava_client_cli-0.1.0/src/strava_cli/__init__.py

@@ -0,0 +1 @@
+"""Strava CLI — interact with the Strava API from the command line."""

strava_client_cli-0.1.0/src/strava_cli/cli.py

@@ -0,0 +1,342 @@
+"""Strava CLI — interact with Strava from the command line."""
+
+from __future__ import annotations
+
+import json
+import webbrowser
+from pathlib import Path
+from typing import Optional
+from urllib.parse import urlencode
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from strava_cli.config import (
+    STRAVA_AUTH_URL,
+    StravaClient,
+    StravaConfig,
+)
+from strava_cli.formatting import (
+    format_date,
+    format_date_short,
+    format_distance,
+    format_duration,
+    format_elevation,
+    format_pace,
+    format_speed,
+    parse_date_to_epoch,
+)
+
+app = typer.Typer(
+    name="strava",
+    help="Interact with the Strava API from the command line.",
+    no_args_is_help=True,
+)
+console = Console()
+err_console = Console(stderr=True)
+
+
+def _get_client() -> StravaClient:
+    return StravaClient()
+
+
+# ---------------------------------------------------------------------------
+# auth
+# ---------------------------------------------------------------------------
+
+@app.command()
+def auth() -> None:
+    """Authenticate with Strava via OAuth2."""
+    config = StravaConfig()
+    loaded = config.load()
+
+    if not loaded:
+        console.print("[bold]Strava OAuth Setup[/bold]\n")
+        console.print("Create an app at https://www.strava.com/settings/api")
+        console.print("Use [cyan]http://localhost[/cyan] as the callback URL.\n")
+        config.client_id = typer.prompt("Client ID")
+        config.client_secret = typer.prompt("Client Secret")
+        config.save()
+        console.print("[green]✓ Config saved[/green]\n")
+    else:
+        console.print(f"[dim]Using existing config (client_id: {config.client_id})[/dim]\n")
+
+    params = urlencode({
+        "client_id": config.client_id,
+        "response_type": "code",
+        "redirect_uri": "http://localhost",
+        "approval_prompt": "force",
+        "scope": "activity:read_all,profile:read_all",
+    })
+    auth_url = f"{STRAVA_AUTH_URL}?{params}"
+
+    console.print("Open this URL in your browser:\n")
+    console.print(f"[cyan]{auth_url}[/cyan]\n")
+
+    try:
+        webbrowser.open(auth_url)
+    except Exception:
+        pass
+
+    console.print(
+        "After authorizing, you'll be redirected to localhost with a [bold]code[/bold] parameter."
+    )
+    console.print("Copy the code from the URL (e.g. http://localhost/?code=XXXXX)\n")
+
+    code = typer.prompt("Paste the authorization code")
+
+    client = StravaClient()
+    data = client.exchange_code(code)
+
+    athlete = data.get("athlete", {})
+    name = f"{athlete.get('firstname', '')} {athlete.get('lastname', '')}".strip()
+    console.print(f"\n[green]✓ Authenticated as {name}[/green]")
+    console.print("[dim]Tokens saved to ~/.config/strava-cli/tokens.json[/dim]")
+
+
+# ---------------------------------------------------------------------------
+# profile
+# ---------------------------------------------------------------------------
+
+@app.command()
+def profile() -> None:
+    """Show your Strava athlete profile."""
+    client = _get_client()
+    data = client.get("/athlete")
+
+    table = Table(title="Athlete Profile")
+    table.add_column("Field", style="cyan")
+    table.add_column("Value")
+
+    name = f"{data.get('firstname', '')} {data.get('lastname', '')}".strip()
+    table.add_row("Name", name)
+    table.add_row("Username", data.get("username", "—"))
+    table.add_row("City", data.get("city", "—") or "—")
+    table.add_row("State", data.get("state", "—") or "—")
+    table.add_row("Country", data.get("country", "—") or "—")
+    table.add_row("Sex", data.get("sex", "—") or "—")
+    table.add_row("Weight", f"{data.get('weight', 0):.1f} kg" if data.get("weight") else "—")
+    table.add_row("FTP", str(data.get("ftp", "—")) if data.get("ftp") else "—")
+    table.add_row("Follower Count", str(data.get("follower_count", 0)))
+    table.add_row("Friend Count", str(data.get("friend_count", 0)))
+
+    console.print(table)
+
+
+# ---------------------------------------------------------------------------
+# stats
+# ---------------------------------------------------------------------------
+
+@app.command()
+def stats() -> None:
+    """Show your athlete stats summary."""
+    client = _get_client()
+    athlete_id = client.athlete_id
+
+    if not athlete_id:
+        # Fetch profile to get ID
+        profile_data = client.get("/athlete")
+        athlete_id = profile_data["id"]
+
+    data = client.get(f"/athletes/{athlete_id}/stats")
+
+    def _add_stat_section(table: Table, label: str, totals: dict) -> None:
+        count = totals.get("count", 0)
+        if count == 0:
+            table.add_row(label, "No activities", "", "", "")
+            return
+        table.add_row(
+            label,
+            str(count),
+            format_distance(totals.get("distance", 0)),
+            format_duration(totals.get("moving_time", 0)),
+            format_elevation(totals.get("elevation_gain", 0)),
+        )
+
+    for sport, key_prefix in [("Run", "run"), ("Ride", "ride"), ("Swim", "swim")]:
+        table = Table(title=f"{sport} Stats")
+        table.add_column("Period", style="cyan")
+        table.add_column("Count")
+        table.add_column("Distance")
+        table.add_column("Time")
+        table.add_column("Elevation")
+
+        _add_stat_section(table, "Recent", data.get(f"recent_{key_prefix}_totals", {}))
+        _add_stat_section(table, "YTD", data.get(f"ytd_{key_prefix}_totals", {}))
+        _add_stat_section(table, "All Time", data.get(f"all_{key_prefix}_totals", {}))
+
+        console.print(table)
+        console.print()
+
+
+# ---------------------------------------------------------------------------
+# activities
+# ---------------------------------------------------------------------------
+
+@app.command()
+def activities(
+    limit: int = typer.Option(20, "--limit", "-n", help="Number of activities to show."),
+    after: Optional[str] = typer.Option(None, help="Show activities after this date (YYYY-MM-DD)."),
+    before: Optional[str] = typer.Option(None, help="Show activities before this date (YYYY-MM-DD)."),
+    activity_type: Optional[str] = typer.Option(None, "--type", "-t", help="Filter by type (Run, Ride, Swim, etc.)."),
+) -> None:
+    """List recent activities."""
+    client = _get_client()
+
+    params: dict = {"per_page": min(limit, 200)}
+    if after:
+        params["after"] = parse_date_to_epoch(after)
+    if before:
+        params["before"] = parse_date_to_epoch(before)
+
+    data = client.get("/athlete/activities", params=params)
+
+    if activity_type:
+        normalized = activity_type.lower()
+        data = [a for a in data if a.get("type", "").lower() == normalized]
+
+    if not data:
+        console.print("[yellow]No activities found.[/yellow]")
+        return
+
+    table = Table(title="Activities")
+    table.add_column("ID", style="dim")
+    table.add_column("Date", style="cyan")
+    table.add_column("Type")
+    table.add_column("Name")
+    table.add_column("Distance", justify="right")
+    table.add_column("Time", justify="right")
+    table.add_column("Elevation", justify="right")
+
+    for a in data[:limit]:
+        table.add_row(
+            str(a["id"]),
+            format_date_short(a["start_date"]),
+            a.get("type", "—"),
+            a.get("name", "—"),
+            format_distance(a.get("distance", 0)),
+            format_duration(a.get("moving_time", 0)),
+            format_elevation(a.get("total_elevation_gain", 0)),
+        )
+
+    console.print(table)
+
+
+# ---------------------------------------------------------------------------
+# activity
+# ---------------------------------------------------------------------------
+
+@app.command()
+def activity(
+    activity_id: int = typer.Argument(help="Strava activity ID."),
+) -> None:
+    """Show detailed view of a single activity."""
+    client = _get_client()
+    data = client.get(f"/activities/{activity_id}")
+
+    title = data.get("name", "Activity")
+    activity_type = data.get("type", "Unknown")
+    date = format_date(data.get("start_date", ""))
+
+    table = Table(title=f"{title} ({activity_type})")
+    table.add_column("Field", style="cyan")
+    table.add_column("Value")
+
+    table.add_row("Date", date)
+    table.add_row("Distance", format_distance(data.get("distance", 0)))
+    table.add_row("Moving Time", format_duration(data.get("moving_time", 0)))
+    table.add_row("Elapsed Time", format_duration(data.get("elapsed_time", 0)))
+    table.add_row("Elevation Gain", format_elevation(data.get("total_elevation_gain", 0)))
+    table.add_row("Max Elevation", format_elevation(data.get("elev_high", 0)))
+    table.add_row("Min Elevation", format_elevation(data.get("elev_low", 0)))
+
+    avg_speed = data.get("average_speed", 0)
+    max_speed = data.get("max_speed", 0)
+    table.add_row("Avg Speed", format_speed(avg_speed))
+    table.add_row("Max Speed", format_speed(max_speed))
+
+    if data.get("type") in ("Run", "Walk", "Hike"):
+        table.add_row("Avg Pace", format_pace(data.get("distance", 0), data.get("moving_time", 0)))
+
+    if data.get("average_heartrate"):
+        table.add_row("Avg HR", f"{data['average_heartrate']:.0f} bpm")
+    if data.get("max_heartrate"):
+        table.add_row("Max HR", f"{data['max_heartrate']:.0f} bpm")
+    if data.get("average_cadence"):
+        table.add_row("Avg Cadence", f"{data['average_cadence']:.0f} rpm")
+    if data.get("average_watts"):
+        table.add_row("Avg Power", f"{data['average_watts']:.0f} W")
+    if data.get("calories"):
+        table.add_row("Calories", f"{data['calories']:.0f}")
+
+    table.add_row("Kudos", str(data.get("kudos_count", 0)))
+    table.add_row("Description", data.get("description", "—") or "—")
+
+    console.print(table)
+
+
+# ---------------------------------------------------------------------------
+# export
+# ---------------------------------------------------------------------------
+
+@app.command()
+def export(
+    output: Path = typer.Option(Path("./strava-export"), "--output", "-o", help="Output directory."),
+    fmt: str = typer.Option("json", "--format", "-f", help="Export format: json or gpx."),
+    after: Optional[str] = typer.Option(None, help="Export activities after this date (YYYY-MM-DD)."),
+    before: Optional[str] = typer.Option(None, help="Export activities before this date (YYYY-MM-DD)."),
+    limit: int = typer.Option(100, "--limit", "-n", help="Max activities to export."),
+) -> None:
+    """Bulk export activities to JSON or GPX files."""
+    client = _get_client()
+
+    params: dict = {"per_page": min(limit, 200)}
+    if after:
+        params["after"] = parse_date_to_epoch(after)
+    if before:
+        params["before"] = parse_date_to_epoch(before)
+
+    console.print(f"[dim]Fetching activities...[/dim]")
+    activity_list = client.get("/athlete/activities", params=params)
+
+    if not activity_list:
+        console.print("[yellow]No activities found.[/yellow]")
+        return
+
+    output.mkdir(parents=True, exist_ok=True)
+    exported = 0
+
+    for summary in activity_list[:limit]:
+        aid = summary["id"]
+
+        if fmt == "json":
+            detail = client.get(f"/activities/{aid}")
+            filepath = output / f"{aid}.json"
+            filepath.write_text(json.dumps(detail, indent=2) + "\n")
+            exported += 1
+        elif fmt == "gpx":
+            # Strava API v3 doesn't provide GPX directly; export streams as JSON
+            # and note this limitation
+            try:
+                streams = client.get(
+                    f"/activities/{aid}/streams",
+                    params={"keys": "latlng,altitude,time", "key_type": "stream"},
+                )
+                filepath = output / f"{aid}_streams.json"
+                filepath.write_text(json.dumps(streams, indent=2) + "\n")
+                exported += 1
+            except Exception as exc:
+                err_console.print(f"[red]Failed to export {aid}: {exc}[/red]")
+
+        name = summary.get("name", "")
+        console.print(f"  [green]✓[/green] {aid} — {name}")
+
+    console.print(f"\n[green]Exported {exported} activities to {output}[/green]")
+    if fmt == "gpx":
+        console.print("[dim]Note: Strava API v3 doesn't serve GPX directly. Exported stream data as JSON.[/dim]")
+
+
+if __name__ == "__main__":
+    app()

strava_client_cli-0.1.0/src/strava_cli/config.py

@@ -0,0 +1,155 @@
+"""Configuration and token management for Strava CLI."""
+
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+from typing import Optional
+
+import httpx
+
+CONFIG_DIR = Path.home() / ".config" / "strava-cli"
+TOKENS_PATH = CONFIG_DIR / "tokens.json"
+CONFIG_PATH = CONFIG_DIR / "config.json"
+
+STRAVA_AUTH_URL = "https://www.strava.com/oauth/authorize"
+STRAVA_TOKEN_URL = "https://www.strava.com/oauth/token"
+STRAVA_API_BASE = "https://www.strava.com/api/v3"
+
+
+class StravaConfig:
+    """Manages client credentials stored in config.json."""
+
+    def __init__(self) -> None:
+        self.client_id: str = ""
+        self.client_secret: str = ""
+
+    def load(self) -> bool:
+        if not CONFIG_PATH.exists():
+            return False
+        data = json.loads(CONFIG_PATH.read_text())
+        self.client_id = data.get("client_id", "")
+        self.client_secret = data.get("client_secret", "")
+        return bool(self.client_id and self.client_secret)
+
+    def save(self) -> None:
+        CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+        CONFIG_PATH.write_text(json.dumps({
+            "client_id": self.client_id,
+            "client_secret": self.client_secret,
+        }, indent=2) + "\n")
+
+
+class TokenStore:
+    """Manages OAuth tokens stored in tokens.json with auto-refresh."""
+
+    def __init__(self) -> None:
+        self.access_token: str = ""
+        self.refresh_token: str = ""
+        self.expires_at: int = 0
+        self.athlete_id: int = 0
+
+    def load(self) -> bool:
+        if not TOKENS_PATH.exists():
+            return False
+        data = json.loads(TOKENS_PATH.read_text())
+        self.access_token = data.get("access_token", "")
+        self.refresh_token = data.get("refresh_token", "")
+        self.expires_at = data.get("expires_at", 0)
+        self.athlete_id = data.get("athlete_id", 0)
+        return bool(self.access_token)
+
+    def save(self) -> None:
+        CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+        TOKENS_PATH.write_text(json.dumps({
+            "access_token": self.access_token,
+            "refresh_token": self.refresh_token,
+            "expires_at": self.expires_at,
+            "athlete_id": self.athlete_id,
+        }, indent=2) + "\n")
+
+    def is_expired(self) -> bool:
+        return time.time() >= self.expires_at
+
+    def update_from_response(self, data: dict) -> None:
+        self.access_token = data["access_token"]
+        self.refresh_token = data["refresh_token"]
+        self.expires_at = data["expires_at"]
+        if "athlete" in data:
+            self.athlete_id = data["athlete"]["id"]
+        self.save()
+
+
+class StravaClient:
+    """HTTP client for Strava API with automatic token refresh."""
+
+    def __init__(self) -> None:
+        self._config = StravaConfig()
+        self._tokens = TokenStore()
+        self._http: Optional[httpx.Client] = None
+
+    def _ensure_config(self) -> None:
+        if not self._config.load():
+            raise SystemExit(
+                "No Strava config found. Run 'strava auth' first."
+            )
+
+    def _ensure_tokens(self) -> None:
+        if not self._tokens.load():
+            raise SystemExit(
+                "No tokens found. Run 'strava auth' first."
+            )
+
+    def _refresh_if_needed(self) -> None:
+        if not self._tokens.is_expired():
+            return
+        self._ensure_config()
+        response = httpx.post(STRAVA_TOKEN_URL, data={
+            "client_id": self._config.client_id,
+            "client_secret": self._config.client_secret,
+            "grant_type": "refresh_token",
+            "refresh_token": self._tokens.refresh_token,
+        })
+        response.raise_for_status()
+        self._tokens.update_from_response(response.json())
+
+    @property
+    def athlete_id(self) -> int:
+        self._ensure_tokens()
+        return self._tokens.athlete_id
+
+    @property
+    def config(self) -> StravaConfig:
+        self._ensure_config()
+        return self._config
+
+    @property
+    def tokens(self) -> TokenStore:
+        self._ensure_tokens()
+        return self._tokens
+
+    def get(self, path: str, params: Optional[dict] = None) -> dict | list:
+        self._ensure_tokens()
+        self._refresh_if_needed()
+        response = httpx.get(
+            f"{STRAVA_API_BASE}{path}",
+            headers={"Authorization": f"Bearer {self._tokens.access_token}"},
+            params=params,
+            timeout=30,
+        )
+        response.raise_for_status()
+        return response.json()
+
+    def exchange_code(self, code: str) -> dict:
+        self._ensure_config()
+        response = httpx.post(STRAVA_TOKEN_URL, data={
+            "client_id": self._config.client_id,
+            "client_secret": self._config.client_secret,
+            "code": code,
+            "grant_type": "authorization_code",
+        })
+        response.raise_for_status()
+        data = response.json()
+        self._tokens.update_from_response(data)
+        return data

strava_client_cli-0.1.0/src/strava_cli/formatting.py

@@ -0,0 +1,66 @@
+"""Formatting helpers for Strava data display."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+
+def format_distance(meters: float) -> str:
+    """Format distance in meters to km."""
+    km = meters / 1000.0
+    return f"{km:.2f} km"
+
+
+def format_distance_miles(meters: float) -> str:
+    """Format distance in meters to miles."""
+    miles = meters / 1609.34
+    return f"{miles:.2f} mi"
+
+
+def format_duration(seconds: int) -> str:
+    """Format seconds into human readable duration."""
+    hours = seconds // 3600
+    minutes = (seconds % 3600) // 60
+    secs = seconds % 60
+    if hours > 0:
+        return f"{hours}h {minutes:02d}m {secs:02d}s"
+    return f"{minutes}m {secs:02d}s"
+
+
+def format_pace(meters: float, seconds: int) -> str:
+    """Format pace as min/km."""
+    if meters <= 0 or seconds <= 0:
+        return "—"
+    pace_seconds = seconds / (meters / 1000.0)
+    minutes = int(pace_seconds // 60)
+    secs = int(pace_seconds % 60)
+    return f"{minutes}:{secs:02d} /km"
+
+
+def format_speed(meters_per_second: float) -> str:
+    """Format speed in km/h."""
+    kmh = meters_per_second * 3.6
+    return f"{kmh:.1f} km/h"
+
+
+def format_elevation(meters: float) -> str:
+    """Format elevation in meters."""
+    return f"{meters:.0f} m"
+
+
+def format_date(iso_string: str) -> str:
+    """Format ISO date string to human readable."""
+    dt = datetime.fromisoformat(iso_string.replace("Z", "+00:00"))
+    return dt.strftime("%Y-%m-%d %H:%M")
+
+
+def format_date_short(iso_string: str) -> str:
+    """Format ISO date to short form."""
+    dt = datetime.fromisoformat(iso_string.replace("Z", "+00:00"))
+    return dt.strftime("%b %d")
+
+
+def parse_date_to_epoch(date_str: str) -> int:
+    """Parse YYYY-MM-DD to Unix timestamp."""
+    dt = datetime.strptime(date_str, "%Y-%m-%d").replace(tzinfo=timezone.utc)
+    return int(dt.timestamp())