WaniKani CLI

A tiny Node.js CLI tool to show your current WaniKani lessons and review counts right in your terminal.

Installation

npm install -g wanikani

Features

• 📚 Display current lesson and review counts
• 🔄 Watch mode with auto-refresh
• 🔐 Secure local token storage
• 🌈 Colorful terminal output
• ⚡ Zero dependencies
• 🚀 Fast and lightweight

Usage

Basic Commands

# Show current counts once
wanikani

# Watch mode - auto-refresh every 60 seconds
wanikani --watch

# Watch mode with custom interval (minimum 5 seconds)
wanikani --watch -i 30

# Quiet mode (no tips or extra messages)
wanikani --quiet
wanikani -q

# Combine flags
wanikani --watch --quiet -i 30

# Setup API token
wanikani login

# Remove saved token
wanikani logout

# Open token settings page in browser
wanikani open-token-link

# Show shell integration setup instructions
wanikani shell-setup

# Show version
wanikani --version
wanikani -v

# Show help
wanikani --help
wanikani -h

First Time Setup

1. Run wanikani login
2. Create a WaniKani API token with read permissions at https://www.wanikani.com/settings/personal_access_tokens
3. Paste the token when prompted
4. Start using wanikani to check your stats!

Environment Variable

You can also set your API token via environment variable instead of saving it locally:

WANIKANI_API_TOKEN=your_token_here wanikani

Shell Integration

Show WaniKani Stats on Terminal Startup

You can configure your shell to show WaniKani stats every time you open a new terminal.

Quick Setup: Run wanikani shell-setup to see copy-paste instructions for your shell.

Zsh (most common)

Add to your ~/.zshrc:

# Show WaniKani stats on terminal startup
wanikani --quiet 2>/dev/null || true

Or for a more advanced setup with error handling:

# WaniKani startup stats
if command -v wanikani >/dev/null 2>&1; then
    echo "📚 WaniKani Status:"
    wanikani --quiet 2>/dev/null || echo "   ⚠️  Unable to fetch WaniKani data"
    echo ""
fi

Bash

Add to your ~/.bashrc or ~/.bash_profile:

# Show WaniKani stats on terminal startup
wanikani --quiet 2>/dev/null || true

Fish

Add to your ~/.config/fish/config.fish:

# Show WaniKani stats on terminal startup
if command -v wanikani >/dev/null 2>&1
    wanikani --quiet 2>/dev/null; or true
end

Tips for Shell Integration

• Use --quiet to suppress tips and extra messages
• Add 2>/dev/null || true to prevent errors if WaniKani API is unavailable
• Consider adding a blank echo echo "" for spacing
• Test your setup by opening a new terminal session

Advanced Integration

For conditional display (only when you have pending items):

# Only show if there are lessons or reviews
if command -v wanikani >/dev/null 2>&1; then
    output=$(wanikani --quiet 2>/dev/null)
    if echo "$output" | grep -E "(Lessons: [1-9]|Reviews: [1-9])" >/dev/null; then
        echo "📚 You have WaniKani items waiting!"
        echo "$output"
        echo ""
    fi
fi

Development

This project is written in TypeScript. To contribute:

# Install dependencies
npm install

# Build the project
npm run build

# Watch mode for development
npm run dev

# Type checking
npm run typecheck

Requirements

• Node.js 18+
• WaniKani account with API access

Configuration

The CLI stores your API token securely in:

• macOS/Linux: ~/.config/wanikani/config.json
• Windows: %APPDATA%/wanikani/config.json

Example Output

WaniKani 8/26/2025, 2:30:45 PM
Lessons: 12
Reviews: 45
Next reviews in: 2h 15m (8/26/2025, 4:45:00 PM)

Tip: run "wanikani --watch" to auto-refresh.

Roadmap / TODO

The following features are planned for future releases:

🎯 Command-Line Reviews (v2.0)

Interactive review sessions directly in the terminal:

# Start a review session
wanikani review

# Review specific number of items
wanikani review --count 10

# Review only specific types
wanikani review --type radical
wanikani review --type kanji
wanikani review --type vocabulary

Planned Features:

• Interactive Review Flow: Step through available reviews one by one
• WanaKana Integration: Automatic romaji → hiragana conversion (ka → か)
• Real-time Input Validation: Instant feedback for correct/incorrect answers
• SRS Integration: Proper submission to WaniKani API with SRS stage updates
• Review Statistics: Track session accuracy and completion
• Keyboard Navigation: Arrow keys for navigation, Tab for field switching
• Color-coded Feedback: Green for correct, red for incorrect answers
• Offline Mode: Cache reviews for offline study (sync when online)

Technical Implementation:

• WaniKani API v2 /reviews POST endpoint for submitting answers
• WanaKana library for Japanese input conversion
• Interactive CLI prompts with real-time character conversion
• Assignment tracking and SRS stage progression

🎓 Command-Line Lessons (v2.1)

# Start lesson session
wanikani lesson

# Lesson specific counts
wanikani lesson --count 5

📊 Enhanced Statistics (v1.x)

# Detailed breakdown
wanikani stats --detailed

# Level progression
wanikani level

# Accuracy tracking
wanikani accuracy

🔧 Advanced Features (v3.0+)

• Custom Study Sessions: Review specific items or failed items
• Spaced Repetition Visualization: CLI charts showing SRS stage distribution
• Achievement Tracking: Level-up notifications and streak counters
• Community Integration: Compare progress with friends
• Backup/Export: Export study data and statistics

💡 Contributions Welcome

This is an open-source project! If you'd like to help implement any of these features:

1. Check the Issues tab
2. Fork the repository
3. Create a feature branch
4. Submit a pull request

Priority is given to:

• Command-line reviews with WanaKana integration
• Enhanced statistics and progress tracking
• Performance optimizations and error handling

License

MIT

Contributing

Issues and pull requests are welcome! Please visit the GitHub repository.

Author

Kai Macmaster