Metadata-Version: 2.3
Name: wkler
Version: 1.2026.5.1
Summary: Terminal-first WaniKani client
Keywords: wanikani,tui,cli,japanese,srs
Author: gabu
Author-email: gabu <gabu@gabu.quest>
License: MIT
Classifier: Development Status :: 3 - Alpha
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.12
Classifier: Topic :: Education
Classifier: Topic :: Software Development :: User Interfaces
Requires-Dist: httpx>=0.28,<1
Requires-Dist: loguru>=0.7,<1
Requires-Dist: pydantic>=2.12,<3
Requires-Dist: qler>=0.3,<1
Requires-Dist: sqler>=1.2026.2,<2
Requires-Dist: textual>=8,<9
Requires-Dist: wanakana-python>=1.2,<2
Requires-Python: >=3.12
Project-URL: Homepage, https://github.com/gabu-quest/wkler
Project-URL: Repository, https://github.com/gabu-quest/wkler
Project-URL: Issues, https://github.com/gabu-quest/wkler/issues
Description-Content-Type: text/markdown

# wkler

Terminal-first WaniKani client built with [Textual](https://textual.textualize.io/). Focused on real review and lesson sessions that submit to the official WaniKani API.

## Install

```bash
pip install wkler
```

Or with [uv](https://docs.astral.sh/uv/):

```bash
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](https://pypi.org/project/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

```bash
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

```bash
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

```bash
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:

```bash
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

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

## Status

Alpha — daily dogfooding in progress. Published on [PyPI](https://pypi.org/project/wkler/).
