{"id":15017241,"url":"https://github.com/lervag/apy","last_synced_at":"2026-01-24T01:18:45.305Z","repository":{"id":36046911,"uuid":"205250179","full_name":"lervag/apy","owner":"lervag","description":"CLI script for interacting with local Anki collection","archived":false,"fork":false,"pushed_at":"2026-01-12T22:09:15.000Z","size":624,"stargazers_count":306,"open_issues_count":4,"forks_count":27,"subscribers_count":4,"default_branch":"master","last_synced_at":"2026-01-13T02:43:00.131Z","etag":null,"topics":["anki","cli","python"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lervag.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2019-08-29T21:03:49.000Z","updated_at":"2026-01-12T22:09:19.000Z","dependencies_parsed_at":"2024-03-24T18:24:50.971Z","dependency_job_id":"b32b9ffe-bb5d-42b9-adb7-051eae44e89f","html_url":"https://github.com/lervag/apy","commit_stats":{"total_commits":334,"total_committers":10,"mean_commits":33.4,"dds":"0.13772455089820357","last_synced_commit":"89698bb79e31cc230af833a1211b8c70fdccc541"},"previous_names":[],"tags_count":48,"template":false,"template_full_name":null,"purl":"pkg:github/lervag/apy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lervag%2Fapy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lervag%2Fapy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lervag%2Fapy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lervag%2Fapy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lervag","download_url":"https://codeload.github.com/lervag/apy/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lervag%2Fapy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28490097,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T23:55:29.509Z","status":"ssl_error","status_checked_at":"2026-01-16T23:55:29.108Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["anki","cli","python"],"created_at":"2024-09-24T19:50:06.614Z","updated_at":"2026-01-17T00:28:21.958Z","avatar_url":"https://github.com/lervag.png","language":"Python","readme":"# apy\n\n[Anki](https://apps.ankiweb.net/index.html) is a flash card program which makes\nremembering things easy. `apy` is a Python script for easily adding cards to\nAnki. It does not require Anki to be running at the same time.\n\n### Important\n\n* This script and its author(s) are not affiliated/associated with the main\n  Anki project in any way.\n* Use this software entirely at your own risk. Frequent backups are encouraged.\n\n### Table of Contents\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n\n- [Install instructions](#install-instructions)\n- [Usage](#usage)\n- [Examples of adding new notes](#examples-of-adding-new-notes)\n- [Configuration](#configuration)\n- [Zsh completion](#zsh-completion)\n- [Fish completion](#fish-completion)\n- [Relevant resources](#relevant-resources)\n- [Alternatives](#alternatives)\n- [Contributing](#contributing)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n## Install instructions\n\n\u003e [!WARNING]\n\u003e\n\u003e Installing Python packages (e.g. with `pip install`) outside [virtual\n\u003e environments](https://docs.python.org/3/library/venv.html) is not recommended,\n\u003e even at the user level! If you do this, then be aware that you may experience\n\u003e issues due to conflicts with other packages/tools installed in the same manner.\n\nThere are two recommended ways to install `apy`.\n\n### With uv\n\n[`uv`](https://docs.astral.sh/uv/) is a relatively new python package and\nproject manager. It is very fast and it includes features to install and run\ntools in isolated environments.\n\nSee [`uv` Getting Started](https://docs.astral.sh/uv/#getting-started) for how\nto install `uv`. When it's available, you can install `apy` with:\n\n```bash\nuv tool install apyanki\n```\n\n### With pipx\n\n[`pipx`](https://pipx.pypa.io/stable/) is a simple and useful python tool to\ninstall and run python applications in isolated environments.\n\nIf you don't already have `pipx`, install it with your distribution's package\nmanager. For instance, on Ubuntu:\n\n```bash\nsudo apt update\nsudo apt install pipx\n```\n\nThen, install `apy` with:\n\n```bash\npipx install apyanki\n```\n\n### Requirements\n\n`apy` should work for Python 3.10 and later.\n\nTechnically, `apy` does **not** depend on any existing Anki installation, since\nit pulls in a copy of the non-GUI components of Anki as a separate dependency.\nHowever, you still need to have an Anki database with collections and profile\nsettings already existing on your machine, since `apy` can't create one from\nnothing.\n\n## Usage\n\n```sh\napy --help\n```\n\nSome examples:\n\n```sh\n# Add card with interactive editor session\napy add\n\n# Add single card with specified preset (see configuration for more info on\n# presets)\napy add-single -s preset \"Question/Front\" \"Answer/Back\"\n\n# List leech cards (will show cid values for each card). Note that the query\n# should be similar to a search query in the Anki browser.\napy list-cards -v tag:leech\n\n# Review and possibly edit file with given cid\napy review cid:12345678\n```\n\n`apy` can be combined with editor specific configuration and workflows to\nimprove the process of adding and editing cards. For more information about\nthis, see [the Wiki](https://github.com/lervag/apy/wiki/Vim).\n\n## Examples of adding new notes\n\nWith `apy add` and `apy add-from-file`, the note input is provided through\nMarkdown format. `apy add` opens an interactive editor that will write\na temporary file that `apy` reads afterwords. `apy add-from-file` will add\nnotes from a specified file. These are therefore more or less equivalent\ncommands.\n\nIn the following, you may find a few examples of how such notes can be written.\nThese will all be based on the standard note types (or _models_). See\n[here](https://docs.ankiweb.net/getting-started.html?highlight=note#note-types)\nfor the Anki documentation of the standard note types.\n\n### Add with a specified model/note type\n\nThis example will create two notes and four cards with the \"Basic (and reversed\ncard)\" note type.\n\n````md\nmodel: Basic (and reversed card)\ntags: mytag\n\n# Note\n\n## Front\n\nThis is my front.\n\n## Back\n\nThis is my back.\n\n# Note\n\n## Front\n\nThis is my second front.\n\n## Back\n\nThis is my second back.\n````\n\n### Add with code snippet\n\nThis example will create a Basic note with a single card that includes a code\nsnippet.\n\n````md\nmodel: Basic\ntags: code\n\n# Note\n\n## Front\n\nWhat programming language is this?\n\n## Back\n\n```python\nx = 1\nif x \u003e 0:\n    print(\"this is python\")\n```\n````\n\n### Add a Cloze note\n\nThe following shows how a Cloze card can be added, e.g. after doing `apy add -m Cloze`:\n\n```md\n# Note\nmodel: Cloze\ntags: mytag, othertag\n\n## Text\n\n{{c1::Canberra}} was {{c2::founded}}}} in 1913\n\nOr {{c3::REPLACE}} here.\n\n## Back Extra\nExtra information goes here.\n```\n\n## Configuration\n\n`apy` loads configuration from `~/.config/apy/apy.json`. The following keys are\ncurrently recognized:\n\n- `base_path`: Specify where `apy` should look for your Anki database. This is\n  usually something like `/home/your_name/.local/share/Anki2/`.\n- `auto_sync`: Set to `true` to enable auto sync after any mutating operations.\n- `img_viewers`: Specify a dictionary of image viewer commands. Each key is\n  a file extension. The value is a command list, e.g. `['display', 'density',\n  '300']` which specifies the command and its options to use for the\n  corresponding key (file extension).\n- `img_viewers_default`: Specify the default command to show an image. Must be\n  provided as a list of the command and desired options, such as `['feh',\n  '-d']`.\n- `markdown_models`: Specify a list of models for which `apy` will use\n  a markdown converter.\n- `markdown_pygments_style`: Specify the code highlight scheme to use for\n  fenced code blocks in Markdown notes. See the [Pygments\n  documentation](https://pygments.org/docs/styles/) for more details.\n- `markdown_latex_mode`: Specify how `$$ ... $$` and `$ ... $` will be\n  interpreted when transforming Markdown into field HTML and vice versa (it\n  works both ways). The following values are recognized:\n  - `mathjax` (default): `$$…$$` → `\\[…\\]` and `$…$` → `\\(…\\)`\n  - `latex`: `$$…$$` → `[$$]…[/$$]` and `$…$` → `[$]…[/$]`\n- `pngCommands`/`svgCommands`: Set LaTeX commands to generate PNG/SVG files.\n  This is inspired by the [Edit LaTeX build\n  process](https://ankiweb.net/shared/info/937148547) addon to Anki.\n- `presets`: Specify preset combination of model and tags for use with `apy\n  add-single`.\n- `profile_name`: Specify which profile to load by default.\n- `query`: Specify default query for `apy list*`, `apy review` and `apy tag`.\n- `review_show_cards`: Whether to show list of cards by default during note\n  review\n- `review_verbose`: Whether to show note details by default during note\n  review\n\nAn example configuration:\n\n```json\n{\n  \"auto_sync\": true,\n  \"base_path\": \"/home/your_name/.local/share/Anki2/\",\n  \"profile_name\": \"MyAnkiProfile\",\n  \"query\": \"tag:leech\",\n  \"presets\": {\n    \"default\": { \"model\": \"Custom\", \"tags\": [\"marked\"] }\n  },\n  \"pngCommands\": [\n    [\"latex\", \"-interaction=nonstopmode\", \"tmp.tex\"],\n    [\"dvipng\", \"-D\", \"150\", \"-T\", \"tight\", \"-bg\", \"Transparent\",\n      \"tmp.dvi\", \"-o\", \"tmp.png\"]\n  ],\n  \"svgCommands\": [\n    [\"lualatex\", \"-interaction=nonstopmode\", \"tmp.tex\"],\n    [\"pdfcrop\", \"tmp.pdf\", \"tmp.pdf\"],\n    [\"pdf2svg\", \"tmp.pdf\", \"tmp.svg\"]\n  ],\n  \"review_show_cards\": true,\n  \"markdown_latex_mode\": \"latex\"\n}\n```\n\n## Zsh completion\n\nThere is also a zsh completion file available. To use it, one may symlink or\ncopy it to a location that is already in ones `fpath` variable, or one may add\nthe `apy/completion` directory to the `fpath` list.\n\nAs an example, one may first symlink the `_apy` file:\n\n```sh\nmkdir -p ~/.local/zsh-functions\nln -s /path/to/apy/completion/_apy ~/.local/zsh-functions\n```\n\nThen add the following line to ones `.zshrc` file:\n\n```sh\nfpath=($HOME/.local/zsh-functions $fpath)\n```\n\n## Fish completion\n\nThere is also a fish completion file available. To use it, one may symlink or\ncopy it to `~/.config/fish/completions/` directory:\n\n```\nln -s /path/to/apy/completion/apy.fish ~/.config/fish/completions/\n```\n\n## Relevant resources\n\nHere are a list of relevant resources for learning how to work with the Anki\ndatabases and code:\n* [AnkiDroid: Database\n  Structure](https://github.com/ankidroid/Anki-Android/wiki/Database-Structure)\n* [AnkiConnect.py](https://github.com/FooSoft/anki-connect/blob/master/AnkiConnect.py)\n* [The Anki Manual](https://docs.ankiweb.net)\n\n## Alternatives\n\nHere are some alternatives to `apy` from which I've drawn inspiration. I've\nalso added a short note on why I did not just settle for the alternative.\n\n### Ankiconnect\n\n[Ankiconnect](https://foosoft.net/projects/anki-connect/) is an Anki plugin [2055492159](https://ankiweb.net/shared/info/2055492159)) hosted on [github](https://github.com/FooSoft/anki-connect).\n\n\u003e Ankiconnect enables external applications to communicate with Anki over\n\u003e a network interface. The exposed API makes it possible to execute queries\n\u003e against the user’s card deck, automatically create new vocabulary and Kanji\n\u003e flash cards, and more.\n\nA couple of relevant applications that use Ankiconnect:\n\n* [Anki Quick Adder](https://codehealthy.com/chrome-anki-quick-adder/):\n  A Chrome extension to add words to Anki desktop quickly.\n\n* [Anki-editor](https://github.com/louietan/anki-editor) is an emacs plugin for\n  making Anki cards with Org.\n\n* [anki-cli](https://github.com/towercity/anki-cli) is a simple nodejs based\n  command-line interface for Anki.\n\n* [trrc](https://github.com/Constantin1489/trrc) is a command-line program to\n  add a card to Anki using AnkiConnect API.\n\n_The Dealbreaker_: I wanted a script that does not require Anki to be running.\n\n### Anki::Import - Anki note generation made easy\n\n[Anki::Import](https://github.com/sdondley/Anki-Import) (see also\n[here](https://metacpan.org/pod/Anki::Import)) allows one to \"Efficiently\ngenerate Anki notes with your text editor for easy import into Anki\". Quote:\n\n\u003e Inputting notes into Anki can be a tedious chore. Anki::Import lets you you\n\u003e generate Anki notes with your favorite text editor (e.g. vim, BBEdit, Atom,\n\u003e etc.) so you can enter formatted notes into Anki's database more\n\u003e efficiently.\n\n_The Dealbreaker_: This sounds very good, except there are too many steps.\nI didn't want to have to open Anki desktop. It should work flawlessly directly\nfrom the terminal.\n\n### AnkiVim\n\n[AnkiVim](https://github.com/MFreidank/AnkiVim) may be used to \"Use vim to\nrapidly write textfiles immediately importable into anki(1).\"\n\n_The Dealbreaker_: Similar to `Anki::Import`: I didn't want to have to open\nAnki desktop. It should work flawlessly directly from the terminal.\n\n### Knowledge (Vim plugin)\n\n[Knowledge](https://github.com/tbabej/knowledge) is a Vim plugin for generating\nflash cards to either Anki or Mnemosyne.\n\n_The Dealbreaker_: It has [a single, open\nissue](https://github.com/tbabej/knowledge/issues/1), which seems to indicate\nthat the application does not work very well and/or is not well maintained.\n\n### Ankisync\n\n[Ankisync](https://github.com/patarapolw/ankisync) seems somewhat promising, in\nthat it exposes an API for working with Anki collections from Python. It is\na successor to [AnkiTools](https://github.com/patarapolw/AnkiTools), which is\nstated to be \"an Anki *.apkg and collection.anki2 reader and editor\".\n\n_The Dealbreaker_: It does not include any features to add or edit notes (as\nfar as I could tell).\n\n### Genanki\n\n[Genanki](https://github.com/kerrickstaley/genanki) is a library for generating\nAnki decks.\n\n_The Dealbreaker_: It is quite close to being something I wanted, except that\nit needs to run as a plugin to Anki desktop to generate notes to a local\ncollection. It does not seem to allow editing/adding to a local collection\noutside of Anki desktop.\n\n### inka\n\n[inka](https://github.com/lazy-void/inka) is a CLI utility for adding\nflashcards from Markdown files to Anki.\n\n_The Dealbreaker_: This did not exist when apy was created. It seems to be\nclose to what I would personally be interested in, but today I find apy solves\nall (or most) of my requirements. Also, `inka` requires the AnkiConnect plugin.\n\n### Obsidian_to_Anki\n\n[Obsidian_to_Anki](https://github.com/Pseudonium/Obsidian_to_Anki) is a plugin to add flashcards from a text or markdown file to Anki. It can also be run from the command-line as a python script. Built with Obsidian markdown syntax in mind.\n\n_The Dealbreaker_: Requires AnkiConnect.\n\n### Markdown2Anki\n\n[Markdown2Anki](https://github.com/Mochitto/Markdown2Anki) is a Python script that allows you to easily format your cards\nusing Markdown syntax, and then import them into Anki while retaining the\nstructure you gave them.\n\nAs many other alternatives, you need to manually import cards. It may provide\nsupport for AnkiConnect.\n\n## Contributing\n\nThe following is a short and simple guide to getting started with contributing\nand developing the `apy` code.\n\n### Setup\n\nThis project uses [`uv`](https://docs.astral.sh/uv/) as the build system and\nto manage dependencies. Install `uv` first if you don't have it already.\n\nNow fork the repository, then clone your fork and install a local development\nbuild of the project.\n\n```sh\n# Clone the forked repo\ngit clone git@github.com:\u003cusername\u003e/apy.git\ncd apy/\n```\n\n### Tests\n\nTo run the tests, run:\n\n```sh\nuv run pytest\n```\n\n### Linting\n\nTo format the code, run:\n\n```sh\nuv run ruff format\n```\n\nTo type-check the code, run:\n\n```sh\nuv run mypy .\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flervag%2Fapy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flervag%2Fapy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flervag%2Fapy/lists"}