VocabMaster

Master new languages with this CLI tool, designed to help you record vocabulary and create Anki flashcards without the need to manually input translations or example sentences.

Table of Contents

1. Features
2. Installation
   1. Prerequisites
   2. Install via pip
   3. Install via uv (recommended)
   4. OpenAI API key
   5. Shell Completion
3. Usage
   1. Add a new language pair
      1. Definition mode for same-language pairs
   2. Add words to your vocabulary list
   3. Manage language pairs
   4. Generate an Anki deck from your vocabulary list
   5. Choose where your files live
   6. For detailed help on each command, run
4. Importing into Anki
5. Licence

Features

• Record vocabulary words with ease
• Automatic translation and usage examples via OpenAI GPT
• Definition mode: use same-language pairs (e.g., french:french) to get concise definitions instead of translations
• Custom Anki deck names: personalize your deck names instead of using auto-generated names
• Anki integration for seamless language learning
• Supports multiple languages

Installation

Prerequisites

• Python 3.10+
• Compatible with Windows, Linux, and macOS

Install via pip

python3 -m pip install vocabmaster

Install via uv (recommended)

uv tool install vocabmaster

OpenAI API key

Vocabmaster requires an OpenAI API key to function. You can obtain a key by signing up for an account at OpenAI's website.

Once you have your API key, set it as an environment variable:

• On macOS and Linux:

  export OPENAI_API_KEY="your-api-key-here"

  To avoid having to type it everyday, you can create a file with the key:

  echo "your-api-key" > ~/.openai-api-key.txt

  Note: Remember to replace "your-api-key" with your actual API key.

  And then, you can add this to your shell configuration file (.bashrc, .zshrc, etc.):

  export OPENAI_API_KEY="$(cat ~/.openai-api-key.txt)"

• On Windows:

  setx OPENAI_API_KEY your_key
  

Shell Completion

To enable shell completion for bash or zsh, source the completion file (see the completion folder) related to your shell by adding the following line to your .bashrc or .zshrc file:

For bash

source /path/to/vocabmaster/completion/_complete_vocabmaster.bash

For zsh

source /path/to/vocabmaster/completion/_complete_vocabmaster.zsh

Remember to replace /path/to/vocabmaster with the actual path where the completion file is located.

Usage

Add a new language pair

vocabmaster pairs add

Definition mode for same-language pairs

VocabMaster supports same-language pairs for getting definitions instead of translations. This is useful when you want to learn more advanced vocabulary in a language you're already studying.

For example, to create a French vocabulary list with definitions in French:

vocabmaster pairs add
# When prompted, enter: french (language to learn) and french (mother tongue)

When using same-language pairs:

• The LLM provides concise definitions (2-3 words) instead of translations
• Example sentences are in the target language
• Anki decks are named "{Language} definitions" instead of "{Language} vocabulary"

Add words to your vocabulary list

vocabmaster add la casa

Manage language pairs

vocabmaster pairs list
vocabmaster pairs set-default
vocabmaster pairs remove
vocabmaster pairs rename
vocabmaster pairs inspect --pair english:french

inspect shows file locations, translation counts, and the estimated input-token cost (input tokens only) for a specific pair.

Custom deck names

Set a custom name for your Anki deck instead of using auto-generated names:

# Set a custom deck name
vocabmaster pairs set-deck-name --pair english:french --name "Business English"

# Interactive mode (prompts for pair selection and name)
vocabmaster pairs set-deck-name

# Remove custom name (revert to auto-generation)
vocabmaster pairs set-deck-name --pair english:french --remove

Once set, the custom deck name will be used automatically when generating Anki decks. You can also override it temporarily:

# Use custom name from config
vocabmaster anki --pair english:french

# Override with a different name for this generation only
vocabmaster anki --pair english:french --deck-name "Temporary Name"

The same --deck-name option works with the translate command.

Generate an Anki deck from your vocabulary list

vocabmaster translate

Generate a deck for a specific pair with:

vocabmaster anki --pair spanish:english

Choose where your files live

vocabmaster config dir --show
vocabmaster config dir ~/Documents/vocabmaster

Use --show to print your current storage directory. Vocabulary CSV and Anki decks default to ~/.vocabmaster, but you can relocate them anywhere. The configuration file itself always stays under ~/.config/vocabmaster/config.json.

For detailed help on each command, run

vocabmaster <command> --help

Importing into Anki

To import the vocabulary deck into Anki, follow the steps below:

1. Launch Anki.
2. Click on the Import File button. This will open a file picker dialog.
3. In the file picker, locate and select the anki_deck_language1-language2.csv file.
4. Ensure the Existing notes field is set to Update. This will prevent the creation of duplicate cards if the same note already exists in your deck.

Licence

VocabMaster is released under the Apache Licence version 2.

---

https://github.com/sderev/vocabmaster