AnkiNotesCLI

A general-purpose note-taking CLI tool with AI enrichment and Anki integration for spaced repetition learning.

Quickly capture concepts, terms, or phrases from any subject, enrich them with AI-generated explanations and examples, and sync them directly to Anki for effective spaced repetition learning.

Perfect for:

🌍 Language learning (Chinese, French, Spanish, etc.)
💻 Programming concepts and syntax
📚 Academic subjects (Biology, History, Math, etc.)
📖 General knowledge and vocabulary building

Features

Course-based organization: Create separate courses for different subjects
AI-powered enrichment: Automatically generate explanations, examples, and usage notes
Flexible levels/topics: Organize notes with custom levels (e.g., HSK 1-6, Beginner/Advanced, Chapter 1-10)
Customizable AI prompts: Tailor AI responses for each course
Anki integration: Seamlessly sync notes to Anki with hierarchical deck structure
Simple CLI: Fast, keyboard-driven workflow

Screenshots

Anki Decks Organization

Chinese Note Example

Quick Start

# Set up a course (first time only)
./notes.py course "French"

# Set your current level (optional)
./notes.py level "Beginner"

# Add notes
./notes.py new "ateliers pédagogiques" -c "Les élèves participe à des ateliers pédagogiques pour apprendre de manière interactive"
./notes.py new "C'est la vie" -g "common expression"

# Sync to Anki
./notes.py sync

Installation

1. Clone the Repository

cd ~/
git clone https://github.com/yourusername/lang-anki-cli.git
cd lang-anki-cli

2. Install Anki

Linux (Ubuntu/Debian - Recommended):

snap install anki-woodrow

Other Linux Distros:

# Using Flatpak
flatpak install flathub net.ankiweb.Anki

# Or download from official website
# Visit https://apps.ankiweb.net/

macOS:

brew install --cask anki

Windows:

Download from https://apps.ankiweb.net/
Run the installer
Follow the installation wizard

3. Install AnkiConnect Add-on

Open Anki
Go to Tools > Add-ons
Click Get Add-ons...
Paste in the code: 2055492159
Click OK and restart Anki

Note: Anki must be running for sync commands to work.

4. Set Up Python Environment

# Create virtual environment
python3 -m venv venv

# Activate it
source venv/bin/activate  # Linux/macOS
# OR
.\venv\Scripts\activate   # Windows

# Install dependencies
pip install -r requirements.txt

5. Configure Environment Variables

# Copy example env file
cp env.example .env

# Edit .env and add your OpenAI API key
vim .env  # or use your preferred editor

Add your API key:

OPENAI_API_KEY="sk-..."

6. Create a System Alias (Optional but Recommended)

For easier access, create an alias:

Linux/macOS (add to ~/.bashrc or ~/.zshrc):

alias notes='~/lang-anki-cli/notes.py'

Windows (PowerShell Profile):

function notes { python ~/lang-anki-cli/notes.py $args }

After adding the alias, restart your terminal or run source ~/.bashrc.

Usage

Course Management

Create or Select a Course

notes course "French"
notes course "Python Programming"
notes course "Biology 101"

When creating a new course, you'll be asked:

Whether it's a language learning course (affects default AI prompt)
Option to customize the AI prompt (or use the default)

The AI prompt template is saved in courses/<course_name>.json and can be edited anytime.

Set Current Level/Topic

notes level "Beginner"
notes level "HSK 3"
notes level "Chapter 5"

Levels are optional but help organize notes into Anki sub-decks and provide context for AI.

Adding Notes

Basic Usage

notes new "phrase or concept"

With Context (Example Sentence)

notes new "être" -c "Je suis étudiant"
notes new "list comprehension" -c "squares = [x**2 for x in range(10)]"

The -c flag provides context or an example that will appear on your Anki card.

With Grammar/Additional Info

notes new "être" -g "irregular verb, one of the most common verbs"
notes new "mitochondria" -g "powerhouse of the cell, has its own DNA"

The -g flag adds grammar points or additional learning notes.

Combining Both

notes new "faire" -c "Je fais mes devoirs" -g "irregular -re verb"

Viewing Notes

# Show last 5 notes
notes list

# Show last 10 notes
notes list -n 10

Syncing to Anki

notes sync

This will:

Find all unsynced notes in the current course
Create Anki decks (with sub-decks for levels if set)
Add cards with AI-generated content
Mark notes as synced

Workflow Examples

Language Learning (Chinese)

# Initial setup
notes course "Chinese"
notes level "HSK 3"

# Add vocabulary
notes new "一寸光阴 一寸金"
# AI generates: pinyin, translation, example, grammar notes

notes new "熟能生巧" -g "idiom about practice"

# Sync to Anki deck: Chinese::HSK 3
notes sync

Programming (Python)

notes course "Python"
notes level "Advanced"

# Add concepts
notes new "decorator" -c "@property\ndef name(self): return self._name"
# AI generates: explanation, example, important details

notes new "generator" -g "uses yield, lazy evaluation"

notes sync  # → Anki deck: Python::Advanced

Academic Subject (Biology)

notes course "Biology 101"
notes level "Cell Biology"

notes new "mitochondria" -g "powerhouse of the cell"
notes new "ribosomes" -c "found in cytoplasm and on ER"

notes sync  # → Anki deck: Biology 101::Cell Biology

Customizing AI Prompts

Each course has a customizable AI prompt template stored in courses/<course_name>.json.

Available placeholders:

{course} - Course name
{phrase} - The term/concept being learned
{level} - Current level/topic
{context_section} - Context provided with -c flag
{grammar_section} - Additional info provided with -g flag

Example custom prompt for a programming course:

{
  "ai_prompt": "You are an expert programming tutor for {course}. The student is learning about: \"{phrase}\"\n\nLevel: {level}\n{context_section}\n{grammar_section}\n\nProvide:\n1. A clear explanation\n2. A code example\n3. Common use cases\n4. Common pitfalls\n\nFormat as JSON: {\"term\": \"...\", \"explanation\": \"...\", \"example\": \"...\", \"example_explanation\": \"...\", \"notes\": \"...\"}"
}

Edit the course config file anytime to adjust how AI generates your notes!

Directory Structure

lang-anki-cli/
├── notes.py              # Main CLI script
├── anki.py              # AnkiConnect integration
├── courses/             # Course configurations and note data
│   ├── french.json      # Course config
│   ├── french_notes.json # Stored notes
│   ├── chinese.json
│   └── chinese_notes.json
├── .notes_config.json   # Global config (current course)
├── .env                 # Your API keys (gitignored)
├── env.example          # Example environment file
├── requirements.txt     # Python dependencies
└── README.md           # This file

Troubleshooting

"OPENAI_API_KEY not set"

Make sure you've created a .env file with your API key
Check that the key starts with sk-

"No course selected"

Run notes course "<name>" to set your active course first

Anki sync fails

Make sure Anki is running
Verify AnkiConnect add-on is installed (code: 2055492159)
Check Anki is not showing any dialog boxes (close all dialogs)

AI returns weird formatting

The AI prompt might need adjustment
Edit the course config in courses/<course_name>.json
Make sure the prompt asks for JSON output

Contributing

Contributions are welcome! Feel free to:

Report bugs
Suggest features
Submit pull requests
Share custom AI prompts

License

MIT License - feel free to use and modify as needed.

Credits

Built with:

OpenAI API for AI-powered note enrichment
Anki for spaced repetition
AnkiConnect for Anki integration

Name		Name	Last commit message	Last commit date
images		images
.gitignore		.gitignore
README.md		README.md
anki.py		anki.py
env.example		env.example
notes.py		notes.py
requirements.txt		requirements.txt

Latest commit

History

Folders and files

Repository files navigation