feat: CLI + hooks.

Author: fishmonger45

.gitignore

@@ -8,3 +8,4 @@ build/
 *.lock
 .ruff_cache/
 .mypy_cache/
+.DS_Store

.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.6
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

Makefile

@@ -0,0 +1,16 @@
+.PHONY: dev install lint format check
+
+dev:
+	uv run -- python -m uvicorn linguee_api.main:app --reload
+
+install:
+	uv venv && uv pip install -e ".[dev]"
+
+lint:
+	uv run ruff check src/
+
+format:
+	uv run ruff format src/
+
+check: lint
+	uv run ruff format --check src/

README.md

@@ -2,6 +2,8 @@
 
 Unofficial JSON API proxy for [Linguee](https://www.linguee.com). Scrapes Linguee HTML and returns structured JSON for translations, examples, external sources, and autocompletions.
 
+![screenshot](img/img.png)
+
 ## Quick Start
 
 ```bash
@@ -25,6 +27,31 @@ All endpoints accept `query`, `src`, and `dst` language code parameters.
 
 **Supported languages**: bg, cs, da, de, el, en, es, et, fi, fr, hu, it, ja, lt, lv, mt, nl, pl, pt, ro, ru, sk, sl, sv, zh
 
+## CLI
+
+German-English dictionary TUI with clickable words, history, and bookmarks.
+
+```bash
+linguee
+```
+
+Install globally with `uv tool install .` or run from the project with `uv run linguee`.
+
+Use `linguee --no-tui` for a simple REPL without the TUI.
+
+| Key | Action |
+|---|---|
+| `ctrl+o` / `ctrl+i` | Back / forward in history |
+| `ctrl+n` / `ctrl+p` | Navigate lists |
+| `ctrl+d` | Flip direction (de↔en) |
+| `ctrl+s` | Bookmark current word |
+| `ctrl+b` | Show bookmarks |
+| `ctrl+u` + vowel | Type umlauts (ä, ö, ü, ß) |
+| `ctrl+l` | Focus search |
+| `escape` | Close panel |
+
+History and bookmarks are stored in `~/.local/share/linguee/`. Lookups are cached in `~/.cache/linguee/`.
+
 ## Configuration
 
 Environment variables (prefix `LINGUEE_`):

img/img.png

@@ -18,11 +18,12 @@ dependencies = [
     "redis[hiredis]>=5.2",
     "slowapi>=0.1.9",
     "tenacity>=9.0",
+    "textual>=1.0",
 ]
 
 [project.optional-dependencies]
 sentry = ["sentry-sdk[fastapi]>=2.19"]
-dev = ["ruff>=0.8"]
+dev = ["ruff>=0.8", "pre-commit>=4.0"]
 
 [project.scripts]
 linguee = "linguee_api.cli:main"

pyproject.toml

@@ -1,4 +1,6 @@
 import hashlib
+import time
+from pathlib import Path
 from typing import Protocol
 
 import structlog
@@ -58,6 +60,26 @@ async def create_cache() -> Cache:
     return MemoryCache()
 
 
+class DiskCache:
+    def __init__(self, ttl: int = 86400) -> None:
+        self._dir = Path.home() / ".cache" / "linguee"
+        self._dir.mkdir(parents=True, exist_ok=True)
+        self._ttl = ttl
+
+    async def get(self, key: str) -> str | None:
+        p = self._dir / key
+        if not p.exists():
+            return None
+        if time.time() - p.stat().st_mtime > self._ttl:
+            p.unlink(missing_ok=True)
+            return None
+        return p.read_text()
+
+    async def set(self, key: str, value: str, ttl: int) -> None:
+        p = self._dir / key
+        p.write_text(value)
+
+
 async def cached_fetch(cache: Cache, key: str, fetcher) -> str:
     cached = await cache.get(key)
     if cached is not None:

src/linguee_api/cache.py

@@ -1,14 +1,12 @@
 import asyncio
-import sys
 
 import httpx
 
 from linguee_api.client import CaptchaError, LingueeError, fetch_search
+from linguee_api.logging import setup_logging
 from linguee_api.models import Correction, NotFound, ParseError
 from linguee_api.parser import parse_search_result
 
-from linguee_api.logging import setup_logging
-
 SRC = "de"
 DST = "en"
 
@@ -57,7 +55,10 @@ async def lookup(client: httpx.AsyncClient, word: str) -> None:
         for t in lemma.translations:
             freq = ""
             if t.usage_frequency:
-                freq = f" {GREEN}●{RESET}" if t.usage_frequency.value == "almost_always" else f" {GREEN}○{RESET}"
+                if t.usage_frequency.value == "almost_always":
+                    freq = f" {GREEN}●{RESET}"
+                else:
+                    freq = f" {GREEN}○{RESET}"
             t_pos = f" {DIM}{t.pos}{RESET}" if t.pos else ""
             print(f"    {CYAN}→{RESET} {t.text}{t_pos}{freq}")
 
@@ -94,10 +95,21 @@ async def repl() -> None:
 
 
 def main() -> None:
-    try:
-        asyncio.run(repl())
-    except KeyboardInterrupt:
-        pass
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Linguee dictionary")
+    parser.add_argument("--no-tui", action="store_true", help="use simple REPL instead of TUI")
+    args = parser.parse_args()
+
+    if args.no_tui:
+        import contextlib
+
+        with contextlib.suppress(KeyboardInterrupt):
+            asyncio.run(repl())
+    else:
+        from linguee_api.tui.app import LingueeApp
+
+        LingueeApp().run()
 
 
 if __name__ == "__main__":