Metadata-Version: 2.3
Name: wkler
Version: 1.2026.3.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 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:

```bash
uv sync --group dev
```

2. Run the interactive setup guide:

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

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

```bash
uv run wkler
```

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

Useful commands:

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

```bash
uv run pytest
```

## Status

Alpha — daily dogfooding in progress.
