Neil Mahajan
Personal Project
July 2025

Vocabulary Study Go CLI

A command-line interface tool built with Go to help study and learn new vocabulary through interactive flashcard sessions with progress tracking and spaced repetition.

Go
CLI
JSON
Makefile
Terminal UI
File I/O
Progress Tracking
Spaced Repetition
GitHub
Terminal
$ ./vocab
📚 Vocabulary Study Session
────────────────────────────────────────
Card 1 of 1000

🔷 patent
Part of Speech: adjective
Press [q]uit to exit or [Enter] to flip the card...
────────────────────────────────────────
📖 glaringly obvious
💬 Since the book had been through no fewer than six proof runs, the staff was shocked to see such a patent spelling mistake remaining, right in the middle of the front cover!
Did you know this word? [y]es / [n]o / [q]uit:

Project Overview

The Vocabulary Study Go CLI is a command-line application designed to help users expand their vocabulary through interactive flashcard sessions. Built with Go, it provides an efficient and engaging way to learn new words while tracking progress over time.

The application implements spaced repetition principles by tracking which words users know and don't know, allowing them to focus on challenging vocabulary. With features like customizable word lists, progress statistics, vocabulary management commands, and various study modes, it's an ideal tool for students, professionals, and language learners.

The CLI tool stores vocabulary in JSON format and maintains user progress locally, making it lightweight and portable while providing powerful learning capabilities. Users can dynamically add and remove words through command-line operations, making it easy to customize their learning experience.

Key Features

  • Interactive Flashcard Sessions: Learn new words and their definitions in an engaging way with immediate feedback.
  • Progress Tracking: The application remembers which words you know and which you're still learning.
  • Spaced Repetition: Focus on words you don't know yet for more efficient learning.
  • Custom Vocabulary: Easily add your own words to the vocab.json file with definitions and example sentences.
  • Dynamic Word Management: Add new words or remove existing ones directly from the command line with comprehensive metadata support.
  • Study Statistics: Track your learning progress with detailed statistics on known vs. unknown words.
  • Flexible Study Modes: Filter words by status (all, unknown, unseen) and limit session length.
  • Progress Reset: Start fresh at any time while maintaining your vocabulary database.
  • Add New Words: Easily add custom words with part of speech, definitions, and example sentences directly from the command line.
  • Remove Words: Remove unwanted words from your vocabulary database with a simple command.

Usage Examples

Basic Commands

# Start a study session
$ ./vocab
# Limit session to 10 words
$ ./vocab --limit=10
# Study only unknown words
$ ./vocab --review=unknown

Progress Management

# View learning statistics
$ ./vocab stats
# Reset all progress
$ ./vocab reset
# Show help information
$ ./vocab --help

Vocabulary Management

# Add a new word to your vocabulary
$ ./vocab add --word=précis --pos=noun \
--definition="a summary or abstract of a text" \
--example="You can read a brief precis here."
# Remove a word from your vocabulary
$ ./vocab remove --word=précis

Technical Implementation

Architecture

The application is built using Go's standard library with a clean, modular architecture. It uses JSON for data storage, making it human-readable and easily editable while maintaining simplicity and performance.

Data Structure

// vocab.json structure
{
"word": {
"part_of_speech": "noun",
"definition": "A clear explanation",
"example_sentence": "Example usage"
}
}

Key Technical Features

  • Command-line argument parsing for flexible usage
  • JSON-based persistent storage for vocabulary and progress
  • Interactive terminal interface with user input handling
  • State management for tracking learning progress
  • Dynamic vocabulary management with add/remove commands
  • Comprehensive word metadata support (POS, definitions, examples)
  • Makefile for easy building and distribution

Installation & Setup

Prerequisites

Ensure you have Go installed on your system. You can download it from the official Go website.

Quick Start

# Clone the repository
$ git clone https://github.com/neilsmahajan/vocabulary_study_go_cli.git
# Navigate to project directory
$ cd vocabulary_study_go_cli
# Build the application
$ make build
# Start studying!
$ ./vocab

Terminal Screenshots

Terminal
$ ./vocab stats
📊 Vocabulary Stats
────────────────────────────────────────
Total words: 1000
Known: 0
Unknown: 0
Unseen: 1000

💡 Progress: 0.0% [░░░░░░░░░░░░░░░░░░░░]
Terminal
$ ./vocab add --word=précis --pos=noun \
--definition="a summary or abstract of a text" \
--example="You can read a brief precis here."
📚 Adding New Word
─────────────────────────────────────────
Word: précis
Part of speech: noun
Definition: a summary or abstract of a text
Example: You can read a brief precis here.

Saving vocab word précis to vocab.json
✅ Added word 'précis' to vocab
Terminal
$ ./vocab remove --word=précis
📚 Removing Word
────────────────────────────────────────
Word to remove: précis

Deleting word précis from vocab
✅ Removed word 'précis' from vocab