clockify-export 0.1.1__py3-none-any.whl

clockify_export/api.py

@@ -0,0 +1,187 @@
+"""Minimal Clockify API client using only stdlib."""
+
+from __future__ import annotations
+
+import json
+import re
+import urllib.error
+import urllib.request
+from datetime import datetime, timezone
+from typing import Any
+
+BASE_URL = "https://api.clockify.me/api/v1"
+
+
+class ClockifyError(Exception):
+    def __init__(self, status: int, message: str):
+        self.status = status
+        super().__init__(f"HTTP {status}: {message}")
+
+
+class ClockifyAPI:
+    """Minimal Clockify REST API client."""
+
+    def __init__(self, api_key: str, base_url: str = BASE_URL):
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+
+    def _request(self, method: str, path: str, body: dict | None = None) -> tuple[Any, dict[str, str]]:
+        """Make a request, return (parsed_json, headers_dict)."""
+        url = f"{self.base_url}{path}"
+        data = json.dumps(body).encode() if body else None
+        req = urllib.request.Request(
+            url,
+            data=data,
+            method=method,
+            headers={
+                "X-Api-Key": self.api_key,
+                "Content-Type": "application/json",
+            },
+        )
+        try:
+            with urllib.request.urlopen(req) as resp:
+                headers = dict(resp.headers)
+                raw = resp.read()
+                return json.loads(raw) if raw else None, headers
+        except urllib.error.HTTPError as e:
+            body_text = e.read().decode(errors="replace")
+            raise ClockifyError(e.code, body_text) from e
+
+    def _get(self, path: str) -> tuple[Any, dict[str, str]]:
+        return self._request("GET", path)
+
+    # ── Workspaces ──
+
+    def get_workspaces(self) -> list[dict]:
+        data, _ = self._get("/workspaces")
+        return data
+
+    # ── Current user ──
+
+    def get_current_user(self) -> dict:
+        data, _ = self._get("/user")
+        return data
+
+    # ── Projects ──
+
+    def get_projects(self, workspace_id: str) -> list[dict]:
+        """Fetch all projects (paginated)."""
+        projects: list[dict] = []
+        page = 1
+        while True:
+            data, headers = self._get(
+                f"/workspaces/{workspace_id}/projects?page={page}&page-size=50"
+            )
+            if not data:
+                break
+            projects.extend(data)
+            if headers.get("Last-Page", "false").lower() == "true":
+                break
+            page += 1
+        return projects
+
+    # ── Tasks ──
+
+    def get_tasks(self, workspace_id: str, project_id: str) -> list[dict]:
+        """Fetch all tasks for a project (paginated)."""
+        tasks: list[dict] = []
+        page = 1
+        while True:
+            data, headers = self._get(
+                f"/workspaces/{workspace_id}/projects/{project_id}/tasks?page={page}&page-size=50"
+            )
+            if not data:
+                break
+            tasks.extend(data)
+            if headers.get("Last-Page", "false").lower() == "true":
+                break
+            page += 1
+        return tasks
+
+    # ── Clients ──
+
+    def get_clients(self, workspace_id: str) -> list[dict]:
+        """Fetch all clients (paginated)."""
+        clients: list[dict] = []
+        page = 1
+        while True:
+            data, headers = self._get(
+                f"/workspaces/{workspace_id}/clients?page={page}&page-size=50"
+            )
+            if not data:
+                break
+            clients.extend(data)
+            if headers.get("Last-Page", "false").lower() == "true":
+                break
+            page += 1
+        return clients
+
+    # ── Tags ──
+
+    def get_tags(self, workspace_id: str) -> list[dict]:
+        """Fetch all tags (paginated)."""
+        tags: list[dict] = []
+        page = 1
+        while True:
+            data, headers = self._get(
+                f"/workspaces/{workspace_id}/tags?page={page}&page-size=50"
+            )
+            if not data:
+                break
+            tags.extend(data)
+            if headers.get("Last-Page", "false").lower() == "true":
+                break
+            page += 1
+        return tags
+
+    # ── Time entries ──
+
+    def get_time_entries(
+        self,
+        workspace_id: str,
+        user_id: str,
+        start: datetime | None = None,
+        end: datetime | None = None,
+    ) -> list[dict]:
+        """Fetch all time entries for a user, paginated."""
+        entries: list[dict] = []
+        page = 1
+        while True:
+            params = f"page={page}&page-size=200"
+            if start:
+                # Clockify expects "yyyy-MM-ddThh:mm:ssZ" format
+                utc = start.astimezone(timezone.utc)
+                params += f"&start={utc.strftime('%Y-%m-%dT%H:%M:%SZ')}"
+            if end:
+                utc = end.astimezone(timezone.utc)
+                params += f"&end={utc.strftime('%Y-%m-%dT%H:%M:%SZ')}"
+            data, headers = self._get(
+                f"/workspaces/{workspace_id}/user/{user_id}/time-entries?{params}"
+            )
+            if not data:
+                break
+            entries.extend(data)
+            if headers.get("Last-Page", "false").lower() == "true":
+                break
+            page += 1
+            if page % 10 == 0:
+                print(f"    ... fetched {len(entries)} entries so far (page {page})")
+        return entries
+
+
+# ── Duration parsing ──
+
+_DURATION_RE = re.compile(r"P(?:(\d+)D)?T?(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?")
+
+
+def parse_iso_duration_to_hours(duration_str: str) -> float:
+    """Parse ISO 8601 duration (e.g. 'PT1H30M') to decimal hours."""
+    m = _DURATION_RE.match(duration_str)
+    if not m:
+        return 0.0
+    days = int(m.group(1) or 0)
+    hours = int(m.group(2) or 0)
+    minutes = int(m.group(3) or 0)
+    seconds = int(m.group(4) or 0)
+    total_minutes = days * 24 * 60 + hours * 60 + minutes + seconds / 60
+    return round(total_minutes / 60, 2)

clockify_export/cli.py

@@ -0,0 +1,171 @@
+"""CLI entry point for clockify-export."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from datetime import datetime, timedelta, timezone
+
+from .api import ClockifyAPI, ClockifyError
+from .config import CONFIG_FILE, Config, create_config_file, get_last_exported, set_last_exported
+from .export import export_workspace
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="clockify-export",
+        description="Export Clockify time entries to CSV",
+    )
+    parser.add_argument(
+        "--output-dir", "-o",
+        type=str,
+        default=None,
+        help="Output directory for CSV files (default: ./export or config export_dir)",
+    )
+    parser.add_argument(
+        "--api-key",
+        type=str,
+        default=None,
+        help="Clockify API key (overrides config/env). Alternatively use CLOCKIFY_API_KEY or config.",
+    )
+    parser.add_argument(
+        "--full",
+        action="store_true",
+        help="Full export: ignore incremental state, export everything",
+    )
+    parser.add_argument(
+        "--from",
+        dest="from_date",
+        type=str,
+        default=None,
+        help="Export entries from this date (YYYY-MM-DD). Overrides incremental state.",
+    )
+    parser.add_argument(
+        "--workspace",
+        "-w",
+        action="append",
+        help="Export only this workspace (can be repeated). Default: all workspaces.",
+    )
+    parser.add_argument(
+        "--status",
+        action="store_true",
+        help="Show export state and exit",
+    )
+    parser.add_argument(
+        "--init-config",
+        action="store_true",
+        help="Create ~/.config/clockify-export/config.toml and exit",
+    )
+    args = parser.parse_args()
+
+    if args.init_config:
+        path = create_config_file()
+        print(f"Created config file: {path}")
+        print("Edit it to set your API key and export directory.")
+        return
+
+    # Load configuration
+    cfg = Config.load(args)
+
+    if not cfg.api_key:
+        print(
+            "Error: No API key found.\n"
+            "  Set it via:\n"
+            "    1.  --api-key flag\n"
+            "    2.  CLOCKIFY_API_KEY environment variable\n"
+            "    3.  ~/.config/clockify-export/config.toml\n"
+            "    4.  .env file in the current directory\n"
+            "  Run: clockify-export --init-config to create a config file.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    api = ClockifyAPI(cfg.api_key)
+
+    # Status mode
+    if args.status:
+        import json
+        from .config import get_state
+        state = get_state()
+        print(f"Export directory: {cfg.export_dir}")
+        print(f"Config file: {CONFIG_FILE}")
+        if not state:
+            print("No export state found.")
+            return
+        print("Export state:")
+        for ws_id, info in state.items():
+            print(f"  {ws_id}: last_exported={info.get('last_exported', 'never')}")
+        return
+
+    # Discover workspaces
+    try:
+        workspaces = api.get_workspaces()
+    except ClockifyError as e:
+        print(f"Error fetching workspaces: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    if not workspaces:
+        print("No workspaces found.", file=sys.stderr)
+        sys.exit(1)
+
+    # Filter workspaces if specified
+    if cfg.workspaces:
+        ws_names = set(cfg.workspaces)
+        workspaces = [w for w in workspaces if w.get("name") in ws_names]
+        if not workspaces:
+            print(
+                f"Workspace(s) not found. Available: {[w['name'] for w in api.get_workspaces()]}",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+
+    print(f"Found {len(workspaces)} workspace(s): {', '.join(w['name'] for w in workspaces)}")
+    print()
+
+    output_dir = cfg.export_dir
+    for ws in workspaces:
+        ws_id = ws["id"]
+        ws_name = ws["name"]
+        print(f"── {ws_name} ({ws_id}) ──")
+
+        # Determine start date
+        since = None
+        if cfg.from_date:
+            # Explicit --from flag overrides everything
+            since = datetime.strptime(cfg.from_date, "%Y-%m-%d").replace(tzinfo=timezone.utc)
+            print(f"  --from: fetching since {cfg.from_date}")
+        elif not cfg.full:
+            last = get_last_exported(ws_id)
+            if last:
+                # Start from the day after last export
+                since = datetime.fromisoformat(last) + timedelta(days=1)
+                print(f"  Incremental: fetching since {since.strftime('%Y-%m-%d')}")
+            else:
+                print("  No prior export found — exporting all data")
+        else:
+            print("  Full export mode")
+
+        try:
+            counts = export_workspace(api, ws_id, ws_name, output_dir, since=since)
+            if counts:
+                # Update state to the latest entry date
+                latest_month = max(counts.keys())
+                latest_ts = datetime.strptime(latest_month, "%Y-%m").replace(tzinfo=timezone.utc)
+                # Set to end of month to mark the whole month as exported
+                from calendar import monthrange
+                _, last_day = monthrange(latest_ts.year, latest_ts.month)
+                latest_ts = latest_ts.replace(day=last_day)
+                set_last_exported(ws_id, latest_ts.isoformat())
+                total = sum(counts.values())
+                print(f"  Total: {total} entries across {len(counts)} month(s)")
+            else:
+                print("  No entries found")
+        except ClockifyError as e:
+            print(f"  Error: {e}", file=sys.stderr)
+        print()
+
+    print("Done.")
+
+
+if __name__ == "__main__":
+    main()

clockify_export/config.py

@@ -0,0 +1,142 @@
+"""Configuration management.
+
+Loads config from (in priority order):
+1. CLI flags (highest)
+2. Environment variables (CLOCKIFY_API_KEY, CLOCKIFY_EXPORT_DIR)
+3. ~/.config/clockify-export/config.toml
+4. ~/.config/clockify-export/config.json (deprecated fallback)
+5. Defaults (lowest)
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import tomllib
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+
+CONFIG_DIR = Path.home() / ".config" / "clockify-export"
+CONFIG_FILE = CONFIG_DIR / "config.toml"
+LEGACY_CONFIG_FILE = CONFIG_DIR / "config.json"
+STATE_FILE = CONFIG_DIR / "state.json"
+
+DEFAULTS = {
+    "api_key": None,
+    "export_dir": "export",
+}
+
+
+@dataclass
+class Config:
+    api_key: str
+    export_dir: Path
+    full: bool = False
+    workspaces: list[str] = field(default_factory=list)
+    from_date: str | None = None
+
+    @classmethod
+    def load(cls, args=None) -> Config:
+        """Load config from file, env, and CLI args. CLI args win."""
+        file_cfg = _load_config_file()
+
+        # Priority: CLI > env > config file > defaults
+        api_key = (
+            getattr(args, "api_key", None)
+            or os.environ.get("CLOCKIFY_API_KEY")
+            or file_cfg.get("api_key")
+        )
+        if not api_key:
+            # Try .env file as last resort
+            api_key = _load_dotenv()
+
+        export_dir = Path(
+            getattr(args, "output_dir", None)
+            or os.environ.get("CLOCKIFY_EXPORT_DIR")
+            or file_cfg.get("export_dir")
+            or DEFAULTS["export_dir"]
+        )
+
+        full = getattr(args, "full", False) if args else False
+        workspaces = getattr(args, "workspace", []) if args else []
+        from_date = getattr(args, "from_date", None) if args else None
+
+        return cls(
+            api_key=api_key or "",
+            export_dir=export_dir,
+            full=full,
+            workspaces=workspaces or [],
+            from_date=from_date,
+        )
+
+
+def _load_config_file() -> dict:
+    """Read config.toml (preferred) or legacy config.json."""
+    if CONFIG_FILE.exists():
+        try:
+            with open(CONFIG_FILE, "rb") as f:
+                return tomllib.load(f)
+        except (tomllib.TOMLDecodeError, OSError):
+            pass
+    if LEGACY_CONFIG_FILE.exists():
+        try:
+            import warnings
+            warnings.warn(
+                f"{LEGACY_CONFIG_FILE} is deprecated, use {CONFIG_FILE} instead",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            return json.loads(LEGACY_CONFIG_FILE.read_text())
+        except (json.JSONDecodeError, OSError):
+            pass
+    return {}
+
+
+def _load_dotenv() -> str | None:
+    """Read CLOCKIFY_API_KEY from .env in current directory."""
+    env_file = Path(".env")
+    if env_file.exists():
+        for line in env_file.read_text().splitlines():
+            line = line.strip()
+            if line.startswith("CLOCKIFY_API_KEY="):
+                return line.split("=", 1)[1].strip().strip("\"'")
+    return None
+
+
+def create_config_file(api_key: str = "", export_dir: str = "export") -> Path:
+    """Create a default TOML config file. Returns the path."""
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    CONFIG_FILE.write_text(
+        "# Clockify export configuration\n"
+        f'api_key = "{api_key}"\n'
+        f'export_dir = "{export_dir}"\n'
+    )
+    return CONFIG_FILE
+
+
+def get_state() -> dict:
+    if STATE_FILE.exists():
+        try:
+            return json.loads(STATE_FILE.read_text())
+        except (json.JSONDecodeError, OSError):
+            pass
+    return {}
+
+
+def save_state(state: dict) -> None:
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    STATE_FILE.write_text(json.dumps(state, indent=2) + "\n")
+
+
+def get_last_exported(workspace_id: str) -> str | None:
+    state = get_state()
+    return state.get(workspace_id, {}).get("last_exported")
+
+
+def set_last_exported(workspace_id: str, timestamp: str) -> None:
+    state = get_state()
+    ws = state.setdefault(workspace_id, {})
+    ws["last_exported"] = timestamp
+    ws["updated_at"] = datetime.now(timezone.utc).isoformat()
+    save_state(state)

clockify_export/export.py

@@ -0,0 +1,156 @@
+"""CSV export logic for Clockify time entries."""
+
+from __future__ import annotations
+
+import csv
+import re
+from datetime import datetime
+from pathlib import Path
+
+from .api import ClockifyAPI, parse_iso_duration_to_hours
+
+CSV_HEADERS = [
+    "Date",
+    "Start",
+    "End",
+    "Duration (h)",
+    "Project",
+    "Customer",
+    "Task",
+    "Description",
+    "Tags",
+    "Billable",
+    "Hourly Rate",
+    "Currency",
+    "Type",
+    "Timezone",
+]
+
+
+def _fmt_date(iso_str: str | None) -> str:
+    if not iso_str:
+        return ""
+    dt = datetime.fromisoformat(iso_str)
+    return dt.strftime("%Y-%m-%d")
+
+
+def _fmt_time(iso_str: str | None) -> str:
+    if not iso_str:
+        return ""
+    dt = datetime.fromisoformat(iso_str)
+    return dt.strftime("%H:%M")
+
+
+def _sanitize_dirname(name: str) -> str:
+    """Make a string safe for use as a directory name."""
+    return re.sub(r'[<>:"/\\|?*]', "_", name).strip()
+
+
+def export_workspace(
+    api: ClockifyAPI,
+    workspace_id: str,
+    workspace_name: str,
+    output_dir: Path,
+    since: datetime | None = None,
+) -> dict[str, int]:
+    """Export all time entries for a workspace, grouped by year/month.
+
+    Directory structure: {output_dir}/{workspace_name}/{year}/{MM}.csv
+    Returns dict of {YYYY-MM: row_count}.
+    """
+    # Resolve current user
+    user = api.get_current_user()
+    user_id = user["id"]
+    print(f"  User: {user.get('name', user_id)}")
+
+    # Fetch lookup tables
+    print("  Fetching projects...")
+    projects = {p["id"]: p for p in api.get_projects(workspace_id)}
+    print("  Fetching clients...")
+    clients = {c["id"]: c for c in api.get_clients(workspace_id)}
+    print("  Fetching tags...")
+    tags = {t["id"]: t for t in api.get_tags(workspace_id)}
+
+    # Fetch time entries first to know which projects have entries
+    print("  Fetching time entries...")
+    entries = api.get_time_entries(workspace_id, user_id, start=since)
+    print(f"  Got {len(entries)} entries")
+
+    # Only fetch tasks for projects that have entries (saves API calls)
+    project_ids_in_entries = {e.get("projectId") for e in entries if e.get("projectId")}
+    print(f"  Fetching tasks for {len(project_ids_in_entries)} active projects...")
+    tasks: dict[str, dict] = {}
+    for proj_id in project_ids_in_entries:
+        for t in api.get_tasks(workspace_id, proj_id):
+            tasks[t["id"]] = t
+
+    # Build project -> client mapping
+    project_client: dict[str, str] = {}
+    for p in projects.values():
+        client_id = p.get("clientId")
+        if client_id and client_id in clients:
+            project_client[p["id"]] = clients[client_id].get("name", "")
+
+    # Group by year/month
+    by_month: dict[str, list[dict]] = {}
+    for entry in entries:
+        start_str = entry.get("timeInterval", {}).get("start")
+        if not start_str:
+            continue
+        dt = datetime.fromisoformat(start_str)
+        month_key = dt.strftime("%Y-%m")
+        by_month.setdefault(month_key, []).append(entry)
+
+    # Write CSVs: output_dir / workspace_name / year / <workspace>_<year>-<month>.csv
+    safe_ws_name = _sanitize_dirname(workspace_name)
+    ws_dir = output_dir / safe_ws_name
+    counts: dict[str, int] = {}
+    for month_key, month_entries in sorted(by_month.items()):
+        year, month = month_key.split("-")
+        year_dir = ws_dir / year
+        year_dir.mkdir(parents=True, exist_ok=True)
+        # Filename carries workspace + year so files stay identifiable when moved
+        csv_path = year_dir / f"{safe_ws_name}_{year}-{month}.csv"
+
+        with open(csv_path, "w", newline="", encoding="utf-8") as f:
+            writer = csv.writer(f)
+            writer.writerow(CSV_HEADERS)
+            for entry in sorted(
+                month_entries,
+                key=lambda e: e.get("timeInterval", {}).get("start", ""),
+            ):
+                start = entry.get("timeInterval", {}).get("start")
+                end = entry.get("timeInterval", {}).get("end")
+                duration_str = entry.get("timeInterval", {}).get("duration", "")
+                duration_h = parse_iso_duration_to_hours(duration_str) if duration_str else 0
+
+                project_id = entry.get("projectId", "")
+                task_id = entry.get("taskId", "")
+                tag_ids = entry.get("tagIds") or []
+
+                # Hourly rate is in cents
+                hourly_rate_obj = entry.get("hourlyRate") or {}
+                rate_cents = hourly_rate_obj.get("amount", 0)
+                currency = hourly_rate_obj.get("currency", "")
+
+                writer.writerow([
+                    _fmt_date(start),
+                    _fmt_time(start),
+                    _fmt_time(end),
+                    duration_h,
+                    projects.get(project_id, {}).get("name", ""),
+                    project_client.get(project_id, ""),
+                    tasks.get(task_id, {}).get("name", ""),
+                    entry.get("description", ""),
+                    ", ".join(tags.get(tid, {}).get("name", "") for tid in tag_ids),
+                    entry.get("billable", ""),
+                    f"{rate_cents / 100:.2f}" if rate_cents else "",
+                    currency,
+                    entry.get("type", ""),
+                    (entry.get("timeInterval") or {}).get("timeZone", ""),
+                ])
+
+        counts[month_key] = len(month_entries)
+        print(f"  Wrote {csv_path.relative_to(output_dir)} ({len(month_entries)} entries)")
+
+    return counts

clockify_export-0.1.1.dist-info/METADATA

@@ -0,0 +1,193 @@
+Metadata-Version: 2.5
+Name: clockify-export
+Version: 0.1.1
+Summary: Export Clockify time entries to CSV with incremental support
+Project-URL: Homepage, https://github.com/ptandler/clockify-export
+Project-URL: Repository, https://github.com/ptandler/clockify-export
+Project-URL: Bug Tracker, https://github.com/ptandler/clockify-export/issues
+Author: Peter Tandler
+License: MIT
+License-File: LICENSE
+Keywords: clockify,csv,export,incremental,time-tracking
+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: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial :: Accounting
+Classifier: Topic :: Office/Business :: Scheduling
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# Clockify Export
+
+Export your Clockify time entries to CSV files, even on the Free plan.
+
+In April/May 2026, Clockify restricted the Free plan: CSV/Excel exports and
+reports longer than 31 days now require a paid plan. The API itself, however,
+is still available on the Free plan (30 requests/hour/workspace).
+
+This tool uses the **time entries API** (not the reports API), so it is **not**
+subject to the 31-day reporting window. It paginates through all your entries
+and writes one CSV per calendar month.
+
+## Features
+
+- ✅ **Multi-workspace** — exports all your workspaces (or select with `-w`)
+- ✅ **Incremental** — remembers what was exported and only fetches new entries
+- ✅ **Monthly CSVs** — one file per calendar month, current month gets re-exported/overwritten
+- ✅ **Per-workspace stat** — state is tracked in `~/.config/clockify-export/state.json`
+- ✅ **Zero dependencies** — stdlib only (`urllib`, `csv`, `json`), Python ≥ 3.11
+- ✅ **Config file** — API key + export path in `~/.config/clockify-export/config.toml`
+
+## Installation
+
+Requires [uv](https://docs.astral.sh/uv/) (or any Python 3.11+ + pip).
+
+### Global install (recommended, adds `clockify-export` to your PATH)
+
+```bash
+uv tool install clockify-export      # from PyPI
+# or from a local checkout:
+uv tool install .
+```
+
+Updates: `uv tool upgrade clockify-export`.
+
+### Development (from a checkout)
+
+```bash
+uv sync
+```
+
+## Setup
+
+### 1. API key
+
+Generate an API key in Clockify: **Profile → Preferences → API → Manage API Keys → Generate**.
+
+Provide it via one of (highest priority first):
+
+```bash
+# a) Config file (recommended)
+clockify-export --init-config
+# then edit ~/.config/clockify-export/config.toml:
+#
+#   # Clockify export configuration
+#   api_key = "YOUR_KEY"
+#   export_dir = "export"
+
+# b) Environment variable
+export CLOCKIFY_API_KEY=YOUR_KEY
+
+# c) .env file in the project directory
+echo "CLOCKIFY_API_KEY=YOUR_KEY" > .env
+
+# d) Command line flag
+clockify-export --api-key YOUR_KEY
+```
+
+> Note: TOML is parsed with Python's stdlib `tomllib` — no extra dependency.
+
+### 2. Export directory
+
+Defaults to `./export`. Override via config file or `-o` flag:
+
+```bash
+clockify-export -o /data/clockify
+```
+
+## Usage
+
+```bash
+# Full export of all workspaces (everything since the beginning)
+clockify-export --full
+
+# Incremental export (default — only fetches entries after last run)
+clockify-export
+
+# Export only specific workspace(s)
+clockify-export -w "Peter's workspace"
+
+# Export since a specific date (ignores incremental state)
+clockify-export --from 2026-01-01
+
+# Show export state
+clockify-export --status
+```
+
+## Output structure
+
+```
+export/
+└── <workspace name>/
+    └── <year>/
+        └── <workspace name>_<year>-<month>.csv
+```
+
+Each filename carries the workspace and year, so files stay identifiable even
+if you copy or move them out of the directory tree:
+
+```
+export/etalytics workspace/2026/etalytics workspace_2026-09.csv
+```
+
+### CSV columns
+
+| Column | Description |
+|--------|-------------|
+| `Date` | Entry date (YYYY-MM-DD) |
+| `Start` | Start time (HH:MM, UTC) |
+| `End` | End time (HH:MM, UTC) |
+| `Duration (h)` | Duration in decimal hours (e.g. 1.5 = 1h 30m) |
+| `Project` | Project name |
+| `Customer` | Client/customer name |
+| `Task` | Task name |
+| `Description` | Entry description |
+| `Tags` | Comma-separated tags |
+| `Billable` | True/False |
+| `Hourly Rate` | Billable rate (e.g. 13.00) |
+| `Currency` | Currency code (e.g. EUR) |
+| `Type` | Entry type (REGULAR, BREAK, …) |
+| `Timezone` | Timezone of the entry (e.g. Europe/Berlin) |
+
+## How incremental export works
+
+The tool stores the last exported date per workspace in
+`~/.config/clockify-export/state.json`:
+
+```json
+{
+  "5e9d613a265d3c117c6f3aeb": {
+    "last_exported": "2026-09-30T00:00:00+00:00",
+    "updated_at": "2026-09-10T10:20:38.530213+00:00"
+  }
+}
+```
+
+On the next run, entries are fetched starting the day after `last_exported`.
+Monthly CSVs are overwritten entirely, so a partially written current month is
+always consistent.
+
+## Free plan considerations
+
+- **Rate limit**: 30 API requests/hour/workspace on Free plan. Each page of
+  200 entries = 1 request. A full export of thousands of entries can exhaust
+  the quota — that's why `--from` and `--full` exist, and why the tool fetches
+  tasks only for projects that actually have entries.
+- If you hit the rate limit (HTTP 429), wait an hour and run again — the
+  incremental state means you won't re-fetch everything.
+
+## Related projects
+
+- [Clockify API docs](https://docs.clockify.me/)
+- [damirarh/ClockifyExport](https://github.com/damirarh/ClockifyExport) — C# tool
+  using shared reports (paid-only on Free plan now)
+- [apet97/clockify-ts-sdk](https://github.com/apet97/clockify-ts-sdk) — community
+  TypeScript SDK/CLI
+
+## License
+
+MIT

clockify_export-0.1.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+clockify_export/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+clockify_export/api.py,sha256=ekVyU9Yy0WfxPFLId-E-NxU8gmpSkhRfTo1v-okCKA8,5924
+clockify_export/cli.py,sha256=JsOxD19aOaWEoiKtUCBR5-kkgHfiI2IwNQIWa8y7bng,5645
+clockify_export/config.py,sha256=ziQH0aFa2vB3cZP-SV0949zbHa5anoyajAdy592Sj5M,4197
+clockify_export/export.py,sha256=tElB-rQWsWUBgfF_KaSsQvjyEWZJnW8er8X0Ld2-9VQ,5475
+clockify_export-0.1.1.dist-info/METADATA,sha256=sb3S-Rc2jW0jnfLR0cTWZ3Sv3zVvQAW1hpK3rUrN0w8,5829
+clockify_export-0.1.1.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+clockify_export-0.1.1.dist-info/entry_points.txt,sha256=-wbsj9roznlBMbnxLsAX9T7QooBQB-k3gMlsYEs34ew,61
+clockify_export-0.1.1.dist-info/licenses/LICENSE,sha256=zs_y0Uq4pUMCDrnaOfeUq8-bPE5lCV8V66F0IbuNw78,1069
+clockify_export-0.1.1.dist-info/RECORD,,

clockify_export-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

clockify_export-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+clockify-export = clockify_export.cli:main

clockify_export-0.1.1.dist-info/licenses/LICENSE

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