NAME
VocabCLI — Lightweight CLI that allows users to look up word definitions, examples, synonyms and antonyms directly via the…
SYNOPSIS
pip install vocabcliINFO
DESCRIPTION
Lightweight CLI that allows users to look up word definitions, examples, synonyms and antonyms directly via the command line. The app also offers advanced Text Classification and Processing via the use of Natural Language Processing and Machine Learning algorithms.
README
📕 VocabCLI
The AI-powered vocabulary builder for linguaphiles — right in your terminal.
⚡ Install
pip install vocabcli # core features
pip install "vocabcli[ai]" # + OpenAI-powered tools
pip install "vocabcli[nlp]" # + spaCy / transformers (heavy, opt-in)
Recommended:
pipx install "vocabcli[ai]"for an isolated, globally-available install.
🚀 30-Second Quickstart
# First-run setup (API key, provider preferences) vocab setupLook up a word
vocab define serendipity
AI deep-dive with etymology, register, and memory tip
vocab ai explain serendipity
Generate a mnemonic to remember it
vocab ai mnemonic serendipity
Add to your learning list & start spaced-repetition review
vocab learn serendipity vocab review
Check your streak
vocab streak
✨ Feature Grid
| Category | Features |
|---|---|
| 📚 Dictionary | Definitions, phonetics, audio pronunciation, commonly confused words |
| 🔤 Thesaurus | Synonyms & antonyms via API + NLTK WordNet fallback |
| 🧠 Spaced Repetition | SM-2 algorithm (vocab review) — the Anki algorithm built-in |
| 🤖 AI Explain | Etymology, register, usage tips, memory hook — streamed live |
| 🧠 AI Mnemonic | Vivid story hooks cached locally for instant re-display |
| 📖 AI Story | Short narrative using all your learning-list words |
| 💬 AI Chat | Interactive vocabulary tutor with conversation context |
| ❓ AI Quiz | Advanced question types: analogies, fill-in-the-blank, context usage |
| 🎫 Flashcards | Beautiful PIL-generated image cards for learning/mastered/favorite lists |
| 📊 Graphs | 8 visualisations: word distribution, tags, categories, weekly/monthly trends |
| 📥 Import/Export | Bulk CSV import, PDF export, quiz history export |
| 📰 RSS Reader | Subscribe to feeds; highlighted vocabulary words appear inline |
| 🔤 NLP Tools | Sentiment analysis, readability index, text summarization, bad-word censor |
| 🔥 Streaks | Daily lookup streak tracking |
| 💡 AI Suggest | Personalised next-10-words recommendation based on your history |
🤖 AI Features Spotlight
vocab ai explain <word>
Streams an educator-quality explanation covering etymology, core meaning, register (formal/informal/archaic), when to use it, when not to, and a memory tip.
vocab ai mnemonic <word>
Think of EPHEMERAL as an EP record — it barely lasts long enough to play one side.
vocab ai story
Takes every word in your --learning list and weaves them into a 150–200 word narrative. Reading words in context dramatically improves retention.
vocab ai chat
An interactive vocabulary tutor you can ask anything:
"What's the difference between ephemeral and transient?"
Local / Offline AI with Ollama
# ~/.vocabcli/config.toml
[ai]
provider = "ollama"
model = "llama3.2"
All AI commands then route to your local Llama 3 / Mistral instance — no API key, no cloud, complete privacy.
🗄 Database & Configuration
VocabCLI stores everything in ~/.vocabcli/:
~/.vocabcli/
├── VocabularyBuilder.db # SQLite — words, cache, quiz history, ai_cache, streaks
└── config.toml # User preferences
Manage config from the command line:
vocab config --show
vocab config --set ai.provider=ollama
vocab config --set ai.model=llama3.2
🔁 Spaced Repetition (SM-2)
vocab learn ephemeral serendipity eloquentThe next morning, review only words due today:
vocab review
Rate your recall: 1=forgot 3=hard 5=easy
VocabCLI automatically schedules the next review date
The SM-2 algorithm — the same one used by Anki — adjusts review intervals based on your ratings.
🎯 Complete Command Reference
vocab define <word> Look up a word vocab synonym <word> Find synonyms vocab antonym <word> Find antonyms vocab learn <word> Add to learning list vocab master <word> Mark as mastered vocab revise <word> Revise a word vocab review Spaced-repetition review (words due today) vocab quiz Classic 4-choice definition quiz vocab flashcard Generate flashcard imagesvocab streak View daily lookup streak vocab today Word of the day vocab daily_quote Quote of the day
vocab ai explain <word> Deep AI word explanation vocab ai mnemonic <word> Generate/show mnemonic vocab ai story Story using learning list vocab ai sentence <word> 3 example sentences vocab ai suggest Personalised recommendations vocab ai quiz Advanced AI quiz vocab ai chat Interactive tutor vocab ai paraphrase <text> AI paraphrase
vocab setup First-run setup wizard vocab config View/set configuration vocab refresh Refresh API cache vocab about About VocabCLI
🛠 Development Setup
git clone https://github.com/HighnessAtharva/VocabCLI.git cd VocabCLI pip install -e ".[dev,ai]"Run tests from repo root
pytest
📚 Documentation
Full documentation at vocabcli.github.io (built with MkDocs Material)
🤝 Contributors
Built with ❤️ by Atharva Shah and Anay Deshpande.
