anki-yaml-sync 0.1.0

A CLI tool to import/export Anki notes as YAML files

Anki YAML Sync

A Python CLI tool for bi-directional syncing of Anki notes as YAML files for easy editing and version control.

Features

• Import: Fetch all notes from Anki and save them as YAML files
• Export: Sync edited YAML files back to Anki
• Flexible: Update existing notes or create new ones
• Simple: Flat file structure, one YAML file per note

Installation

Requirements

• Python 3.8+
• Anki with AnkiConnect installed

Setup

1. Fork and clone the repository:

git clone <repo-url>
cd anki-yaml-sync

2. Install the package in development mode:

pip install -e .

This will install the CLI tool anki-yaml-sync and all dependencies.

Development Installation

To install with development dependencies (for testing and linting):

pip install -e ".[dev]"

Usage

Import Notes from Anki

Fetch all notes from Anki and save them as YAML files:

anki-yaml-sync import [--output-dir OUTPUT]

Options:

• --output-dir, -o: Directory to save YAML files (default: notes)

Example:

anki-yaml-sync import --output-dir ./my-notes

Export Notes to Anki

Sync YAML files back to Anki:

anki-yaml-sync export [--input-dir INPUT] [--deck DECK]

Options:

• --input-dir, -i: Directory containing YAML files (default: notes)
• --deck: Deck to add new notes to (default: Default)

Example:

anki-yaml-sync export --input-dir ./my-notes --deck "My Deck"

Verbose Output

Add -v or --verbose flag to any command for detailed logging:

anki-yaml-sync -v import
anki-yaml-sync -v export

YAML Format

Each note is stored as a separate YAML file. Example:

id: 1234567890
type: Basic
tags:
  - french
  - vocabulary
fields:
  Front: Bonjour
  Back: Hello
created: 2024-02-12T10:30:00
modified: 2024-02-12T10:30:00

Fields:

• id: Anki note ID (required for updates)
• type: Note type name (e.g., "Basic", "Cloze")
• tags: List of tags to apply
• fields: Dictionary of field names to field values
• created: Creation timestamp
• modified: LastModification timestamp

Workflow

1. Initial Import: Run anki-yaml-sync import to create YAML files from your Anki collection
2. Edit: Open and edit the YAML files with your text editor or IDE
3. Sync Back: Run anki-yaml-sync export to sync your changes back to Anki

Updating Existing Notes

If a YAML file has an id field that matches an existing Anki note, the export will update that note. Fields are completely replaced (not merged).

Creating New Notes

To create a new card:

1. Create a new YAML file with a temporary or missing id (e.g., 0 or null)
2. Run anki-yaml-sync export
3. The YAML file will be automatically updated with the assigned note ID

Requirements

• Anki: Running instance of Anki desktop
• AnkiConnect: Must be installed and running on localhost:8765 (default)

To set up AnkiConnect (https://ankiweb.net/shared/info/2055492159):

1. Open Anki > Menu Bar > Tools > Add-ons > Get Add-ons
2. Enter the code 2055492159 and click "OK" to install AnkiConnect
3. Restart Anki

Testing

Run tests with pytest:

source venv/bin/activate && pytest

With coverage:

source venv/bin/activate && pytest --cov=anki_sync

Troubleshooting

"Could not connect to Anki Connect"

• Ensure Anki is running
• Verify AnkiConnect is installed (Tools → Add-ons in Anki)
• Check that AnkiConnect is listening on localhost:8765

"Model not found"

• Ensure the note type (model) name matches exactly in Anki
• Check spelling and capitalization

YAML parsing errors

• Ensure YAML syntax is valid
• Use proper indentation (spaces, not tabs)
• Quote special characters in strings if needed

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.