Markdown-native flashcard CLI with spaced repetition

The idea

A command-line flashcard tool where decks are folders of .md files you write yourself. Each file is one card: a --- separator on its own line splits the front from the back. The tool reads the folder, runs an FSRS-scheduled review session in an interactive TUI, and writes scheduling state back to a .fsrs.json file in the deck directory. Nothing else.

Why build this

Anki is the gold standard but its binary .apkg format, mandatory sync infrastructure, and desktop-app overhead put many developers off. Obsidian's spaced repetition plugin is popular but locks you into Obsidian. Neither option treats flashcard decks as plain text, stores them in git, or runs in a terminal the way every other developer tool does.

The FSRS algorithm was published as an open paper in 2022 and is now the default scheduler in Anki itself; a clean open-source Go implementation (go-fsrs) already exists and is easy to embed. The timing is right to build a developer-native alternative that sidesteps the binary ecosystem entirely. Decks become .md files you can grep, diff, and commit alongside the notes they came from.

Stack sketch

• Language: Go — single static binary, cross-platform, installable via go install
• TUI: Bubble Tea (Charm) for the interactive review session; Lip Gloss for layout and card rendering
• Scheduling: go-fsrs — open-source Go implementation of the FSRS-4.5 algorithm
• Deck format: folder of .md files; front/back split by --- on its own line; YAML frontmatter is ignored so cards can live in an Obsidian vault without conflict
• State: .fsrs.json in each deck directory — maps card filenames to FSRS state structs; users can gitignore it or commit it, their choice
• Markdown rendering: Glamour for terminal-rendered Markdown during review so code blocks, bold, and lists display correctly instead of as raw syntax

Scope for v1

• flash review <deck-path> — interactive session: show front, wait for keypress, reveal back, prompt for difficulty (Again / Hard / Good / Easy); loop until no cards are due or user presses q; save progress on any exit
• flash stats <deck-path> — due count by day for the next 14 days, estimated retention, and card count by maturity bucket (New / Learning / Review / Relearning)
• flash new <deck-path> — prompt for front and back text interactively, write a timestamped .md file into the deck folder
• Cards due today shown first; new cards introduced at a configurable daily limit (default 10) so a large imported deck does not flood a single session

Deliberately out of scope for v1: syncing across devices, shared or imported decks, image or audio support, a web UI.

Where it could go

The most valuable follow-on is flash import accepting Anki .apkg files: extract cards to Markdown, map existing scheduling state to FSRS structs, and drop everything into a deck folder. This is one command instead of a manual reformat and opens the tool to the large audience already invested in Anki who would switch if migration were free.

A mobile companion app — reading .fsrs.json state from a self-hosted sync endpoint (a small Go HTTP server pointed at the deck directory) — completes the workflow: write and do heavy review sessions at the desktop, knock off due cards on a phone during a commute, merge state back when you reconnect. The sync endpoint is maybe 200 lines; the hard part is the mobile client.

Watch out for

FSRS scheduling depends on accurate timestamps. If a user copies a deck to another machine without the .fsrs.json, the algorithm treats every card as new and months of progress vanish silently. Make the state file's coupling to the deck directory explicit in the README, and add a flash export <deck-path> command that writes each card's scheduling state as YAML frontmatter directly into its .md file — that makes the deck self-contained and portable without any extra step.