FlashTUI ─ Terminal Spaced Repetition System

FlashTUI is a local-first, keyboard-driven, exceptionally aesthetic flashcard application optimized for standard terminal environments.

Core Design Pillars

• Keyboard-Driven modal flow: Modal Vim-style movement keys (h/j/k/l, gg, G, :) remove mouse friction.
• Harmony color palettes: Uses curated violet/cyan accents and Unicode elements (e.g. 🔥 for streak tracks).
• Zero dynamic compile ties: SQLite is embedded via a pure-Go driver with Write-Ahead Logging (WAL) and recursive CTE trees.
• ** Leeches and Undo rollbacks**: Sessions dynamically mark difficult "leech" cards and register snapshots for transactional undos.

Installation Instructions

Prerequisites

• Go compiler: Go 1.21 or higher installed on your path.
• Terminal Emulator: Any modern terminal with UTF-8 character and 256-color support.
  • Icon/Emoji Support: FlashTUI uses standard Unicode and emoji icons (e.g. 🔥, 📂, 🗃️, ⏳, 🎯, 🏆, 📅). If icons appear as hollow boxes or fail to render in your environment, configure your terminal emulator to use a font package with emoji fallback support (such as Noto Color Emoji) or install and use a Nerd Font (e.g., JetBrainsMono Nerd Font, FiraCode Nerd Font) for full glyph coverage.
  • Arch Linux Installation: Install fonts from the AUR using yay or paru:

    # Install JetBrains Mono Nerd Font for developer symbols
    yay -S ttf-jetbrains-mono-nerd
    # Also available via paru
    paru -S ttf-jetbrains-mono-nerd
    
    # Install JoyPixels for emoji/color emoji support
    yay -S ttf-joypixels
    # Or
    paru -S ttf-joypixels
    
    # Refresh the font cache after installation
    fc-cache -fv

Icon Rendering Troubleshooting

Even after installing the fonts above, icons may still not render if your terminal emulator is not configured to use the installed font. Follow the steps for your emulator:

Terminal	How to set the font
Alacritty	In ~/.config/alacritty/alacritty.toml: [font.normal] family = "JetBrainsMono Nerd Font"
Kitty	In ~/.config/kitty/kitty.conf: font_family JetBrainsMono Nerd Font
WezTerm	In ~/.config/wezterm/wezterm.lua: config.font = wezterm.font("JetBrainsMono Nerd Font")
GNOME Terminal	Edit > Preferences > Profile > Text tab → uncheck "Use system fixed-width font" → choose "JetBrainsMono Nerd Font"
Konsole	Settings > Edit Current Profile > Appearance → change Font to "JetBrainsMono Nerd Font"
Foot	In ~/.config/foot/foot.ini: [colors] font=JetBrainsMono Nerd Font:size=12

After changing the font, restart your terminal completely (not just the tab). If emoji boxes persist, ensure your locale is UTF-8:

# Verify locale
locale | grep UTF-8

# If missing, set in /etc/locale.gen and run:
sudo locale-gen

Compilation

From the project workspace root directory, compile the binary:

go build -o flashtui

This builds a self-contained, statically linked executable with no dynamically linked SQLite libraries.

Execution

Run the compiled binary:

./flashtui

The application will automatically initialize the base configuration at ~/.config/flashtui/config.yaml and standard sqlite database at ~/.config/flashtui/data.db on first boot.

Modal Mappings Cheat Sheet

Dashboard Normal Mode

• h / l : Switch between Left Panel (Decks tree) and Right Panel (Cards list).
• j / k : Scroll list selections.
• gg / G : Jump to top / bottom of list.
• ctrl+u / ctrl+d : Half-page scroll up / down.
• a : Create new Deck (when Left Panel focused) or Card (when Right Panel focused).
• e : Edit selected Deck name or Card contents.
• d d : Delete/purge selected Deck (recursive cascade) or Card.
• / : Focus search input block.
• : : Focus console command input.
• Enter : Start review study session on selected Deck.

Review Study Mode

• Space : Flip card to reveal answer.
• h : Peek hint.
• s : Shuffle remaining session queue.
• u : Rollback last graded card (undos database stats and log entry).
• 1 - 5 : Rate active card confidence score.
• Esc : Exit study session and return to dashboard.

Console Commands (:)

• :w : Force database sync update.
• :q / :q! : Safely close SQLite and quit (force quit).
• :wq / :x / :wq! / :x! : Save + quit (Vim-style).
• :tag <tag_name> : Filter card selections by a specific tag. Run :tag with no arguments to clear the filter.
• :tags : Display a list of all unique tags present in the current deck.
• :theme <name> : Switch the TUI color theme dynamically. Available themes: catppuccin, tokyonight, gruvbox, nord, monokai. Run :theme with no arguments to see the usage list.
• :import <path> : Parse cards from external Markdown file (headers = front, comment blocks = hints/tags).
• :export <deck_name> <path> : Compile deck tree and cards recursively to JSON file.
• :help / :h : Display list of all available console commands (opens help panel).