wkler 1.2026.3.1

Terminal-first WaniKani client

wkler

Terminal-first WaniKani client focused on real review sessions that submit to the official API.

Features

• wkler reviews Textual session flow
• Meaning + reading question handling by subject type
• Romaji-to-hiragana reading normalization (wanakana-python)
• WaniKani API client with pagination and rate-limit retry handling
• Local cache and review log with sqler (SQLite)
• Failed review submission queue backed by qler (persistent across restarts)
• Queue management commands: wkler retry, wkler queue list, wkler queue retry
• Lessons command for dogfooding: wkler lessons (--start N / --all)
• Appearance themes: default, retro, colorful with in-session F2 cycle
• Logler-compatible JSONL logs + dogfood feedback loop (wkler feedback)
• Interactive onboarding + settings page (wkler setup, wkler settings)
• Default home launcher TUI (wkler) with tabs/buttons for common actions
• Dedicated crash JSONL logging (WKLER_CRASH_LOG_PATH / crash_log_path)
• Rotating loguru-backed JSONL logs for runtime and crash events

Quickstart

1. Install dependencies:

uv sync --group dev

2. Run the interactive setup guide:

uv run wkler setup

This writes ~/.config/wkler/config.toml (or WKLER_CONFIG_PATH) and lets you set:

• API token
• Theme
• Reading mode
• Default lesson count
• DB/log/crash paths

3. Optional settings:

export WKLER_THEME="retro"           # default|retro|colorful
export WKLER_DB_PATH="~/.local/share/wkler/wkler.db"
export WKLER_LOG_PATH="~/.local/state/wkler/wkler.log"
export WKLER_CRASH_LOG_PATH="~/.local/state/wkler/wkler-crash.log"
export WKLER_READING_INPUT_MODE="always"  # always|auto
export WKLER_LESSON_BATCH_SIZE="5"        # 1-100

4. Launch the app home screen:

uv run wkler

Then pick actions from tabs/buttons (Study, Config, Maintenance).

Useful commands:

uv run wkler sync
uv run wkler settings
uv run wkler lessons --list-limit 20
uv run wkler lessons --start 5
uv run wkler lessons --start-default
uv run wkler reviews
uv run wkler doctor
uv run wkler feedback --note "reading mode label is confusing" --area ux --level warning
uv run wkler feedback --tail 20
uv run wkler retry --limit 50
uv run wkler queue list --status pending --limit 20
uv run wkler queue retry --all

Notes

• This client uses POST /reviews to register reviews that count.
• WaniKani GET /reviews is deprecated and intentionally not used.
• qler is currently consumed as a local editable dependency (../qler) for dogfooding.
• Current focus is dogfooding real review and lesson workflows before PyPI readiness.
• Logs are JSONL and logler-friendly; example:
  • logler llm search ~/.local/state/wkler/wkler.log --query "dogfood feedback" --tail 20
  • logler llm search ~/.local/state/wkler/wkler.log --level ERROR --tail 50
• Runtime failures show concise actionable errors in terminal instead of full Python tracebacks.
• Inside wkler settings, use radio/button controls for choices and click Save / Discard + Back / Back.
• Settings page is scrollable and keeps section content visible on smaller terminal heights.
• wkler defaults to a stealth-black visual style for lower-visibility terminal use.
• Inside wkler settings, use F8 to jump to feedback input and press Enter to log a dogfood note.
• When launched from wkler home, returning from settings/setup takes you back to home instead of exiting the app.
• Home launcher keyboard shortcuts: 1/2/3 switch tabs, r reviews, u setup, g settings, d doctor, arrows switch tabs, q quits.

Development

uv run pytest

Status

Alpha — daily dogfooding in progress.