wkler

Terminal-first WaniKani client built with Textual. Focused on real review and lesson sessions that submit to the official WaniKani API.

Install

pip install wkler

Or with uv:

uv tool install wkler

Features

Review sessions — Full meaning + reading flow with subject-type-aware answer checking, romaji-to-hiragana live conversion, and immediate API submission.

Compact mode — Minimal single-screen TUI for quick sessions (wkler --compact). Reviews and lessons without leaving the app. Inline cache sync (y hotkey).

Unified mode — Full-featured home launcher with tabbed navigation, in-app review/lesson flows, and lesson center for batch management.

Review wrap-up — Press Ctrl+W mid-session to limit remaining items. Prioritizes items with only one question left, then alternates with fresh items.

Rolling shuffle — Configurable item scheduling: rolling (windowed, default), full (classic shuffle), or none (API order). Window size is adjustable (1-500, default 20).

Lesson safety — Confirmation prompt before starting lessons. Shows item preview with characters, level, type, and meanings. Use --yes to bypass for scripted use.

Offline queue — Failed review submissions are persisted via qler and automatically retried next session.

Study visuals — Color-coded subject type badges (vocabulary green, kanji orange, radical purple, kana-vocabulary yellow). Inline miss/correct feedback.

Themes — default (stealth black), retro (green terminal), colorful. Cycle with F2 in-session.

Structured logging — Loguru-backed JSONL logs with rotation. Dedicated crash log. Dogfood feedback loop (wkler feedback).

Quickstart

wkler setup          # interactive onboarding — sets API token, theme, paths
wkler doctor         # verify config, API, and queue connectivity
wkler                # launch unified home TUI
wkler --compact      # launch compact mode

Commands

wkler                       # home launcher (unified mode)
wkler --compact             # compact mode
wkler reviews               # start review session
wkler lessons               # list available lessons
wkler lessons --start 5     # start 5 lessons (with confirmation)
wkler lessons --start-default  # start configured batch size
wkler lessons --all --yes   # start all (skip confirmation)
wkler sync                  # prefetch assignments and subjects
wkler setup                 # first-time onboarding
wkler settings              # edit settings interactively
wkler doctor                # diagnostics
wkler retry                 # retry failed submissions
wkler queue list             # inspect submission queue
wkler feedback --note "..."  # log dogfood feedback
wkler feedback --tail 20    # view recent feedback

Review options

wkler reviews --shuffle-mode rolling   # rolling window (default)
wkler reviews --shuffle-mode full      # classic full shuffle
wkler reviews --shuffle-mode none      # API order
wkler reviews --shuffle-window 40      # window size for rolling mode
wkler reviews --seed abc               # deterministic shuffle

Configuration

Config file: ~/.config/wkler/config.toml (or WKLER_CONFIG_PATH).

Created by wkler setup, editable via wkler settings.

Environment variable overrides:

WKLER_API_TOKEN                  # WaniKani API token
WKLER_THEME="retro"              # default|retro|colorful
WKLER_READING_INPUT_MODE="always"  # always|auto
WKLER_LESSON_BATCH_SIZE="5"     # 1-100
WKLER_REVIEW_SHUFFLE_MODE="rolling"  # rolling|full|none
WKLER_REVIEW_SHUFFLE_WINDOW="20"     # 1-500
WKLER_DB_PATH="~/.local/share/wkler/wkler.db"
WKLER_LOG_PATH="~/.local/state/wkler/wkler.log"
WKLER_CRASH_LOG_PATH="~/.local/state/wkler/wkler-crash.log"

Keyboard shortcuts

Home (unified mode)

1/2/3 switch tabs, r reviews, l default lessons, u setup, g settings, d doctor, q quit.

Compact mode

r reviews, l lessons, y sync cache, q quit. In review: Ctrl+W wrap-up, Ctrl+R reveal, Esc back. In lesson: r reveal, 1-5 score, Esc back.

Review session

F2 cycle theme, Ctrl+W wrap-up, Esc abort.

Development

uv sync --group dev
uv run pytest
uv run ruff check src/ tests/

Status

Alpha — daily dogfooding in progress. Published on PyPI.