anki-cli

Category: Development & Coding | Uploader: ubermenchh | Downloads: 0 | Version: v1.0（Latest）

Manage Anki flashcards via CLI with structured JSON output. Create, query, review, and organize cards, notes, decks, tags, and notetypes. Supports AnkiConnect and direct SQLite backends. Use when the user mentions Anki, flashcards, spaced repetition, SRS, reviewing cards, or managing decks.

Changelog: Source: GitHub https://github.com/ubermenchh/anki-cli

Directory Structure

Current level: Root

📁 .github/
- 📁 workflows/
  - 📄 ci.yml 945 B
  - 📄 publish.yml 837 B
  - 📄 tui.yml 498 B
📁 anki_cli/
- 📁 backends/
  - 📄 __init__.py 706 B
  - 📄 ankiconnect.py 32.1 KB
  - 📄 detect.py 8.5 KB
  - 📄 direct.py 7.0 KB
  - 📄 factory.py 2.5 KB
  - 📄 protocol.py 4.2 KB
- 📁 cli/
  - 📁 commands/
    
    📄 __init__.py 0 B
    
    📄 browse.py 1.5 KB
    
    📄 cards.py 22.1 KB
    
    📄 config.py 3.6 KB
    
    📄 deck.py 13.6 KB
    
    📄 general.py 2.0 KB
    
    📄 note.py 14.2 KB
    
    📄 notetype.py 14.9 KB
    
    📄 review.py 16.1 KB
    
    📄 search.py 2.3 KB
    
    📄 shell.py 818 B
    
    📄 tag.py 8.4 KB
  - 📄 __init__.py 0 B
  - 📄 app.py 4.9 KB
  - 📄 dispatcher.py 1.2 KB
  - 📄 formatter.py 9.5 KB
  - 📄 params.py 1.0 KB
- 📁 core/
  - 📄 scheduler.py 1.6 KB
  - 📄 search.py 19.1 KB
  - 📄 template.py 2.4 KB
  - 📄 undo.py 2.7 KB
- 📁 db/
  - 📄 anki_direct.py 104.7 KB
- 📁 models/
  - 📄 config.py 1.1 KB
  - 📄 output.py 922 B
- 📁 proto/
  - 📁 anki/
    
    📁 collection/
    
    📄 __init__.py 26.1 KB
    
    📁 deck_config/
    
    📄 __init__.py 24.2 KB
    
    📁 decks/
    
    📄 __init__.py 36.8 KB
    
    📁 generic/
    
    📄 __init__.py 1.1 KB
    
    📁 notetypes/
    
    📄 __init__.py 33.8 KB
    
    📁 sync/
    
    📄 __init__.py 14.3 KB
    
    📄 __init__.py 0 B
  - 📄 __init__.py 0 B
- 📁 tui/
  - 📄 __init__.py 0 B
  - 📄 browse_app.py 31.1 KB
  - 📄 colors.py 211 B
  - 📄 repl.py 28.2 KB
  - 📄 review_app.py 28.8 KB
- 📄 __init__.py 239 B
- 📄 __main__.py 72 B
- 📄 config_runtime.py 11.0 KB
📁 assets/
- 📄 anki-cli.png 233.5 KB
📁 tests/
- 📁 backends/
  - 📄 test_ankiconnect.py 7.3 KB
  - 📄 test_ankiconnect_deck_notetype_paths.py 21.0 KB
  - 📄 test_ankiconnect_operations.py 14.1 KB
  - 📄 test_detect.py 8.4 KB
  - 📄 test_detect_helpers.py 12.5 KB
  - 📄 test_direct_backend.py 8.3 KB
  - 📄 test_factory.py 4.6 KB
- 📁 cli/
  - 📄 test_app_bootstrap.py 9.7 KB
  - 📄 test_browse_command.py 3.4 KB
  - 📄 test_cards_commands_actions.py 12.3 KB
  - 📄 test_cards_commands_detail.py 9.6 KB
  - 📄 test_cards_helpers.py 3.3 KB
  - 📄 test_config_commands.py 6.2 KB
  - 📄 test_deck_commands.py 13.5 KB
  - 📄 test_deck_helpers.py 1.3 KB
  - 📄 test_dispatcher.py 3.8 KB
  - 📄 test_general_commands.py 2.6 KB
  - 📄 test_note_commands.py 13.2 KB
  - 📄 test_note_helpers.py 2.1 KB
  - 📄 test_notetype_commands.py 14.5 KB
  - 📄 test_notetype_helpers.py 738 B
  - 📄 test_review_commands.py 18.7 KB
  - 📄 test_review_helpers.py 2.3 KB
  - 📄 test_search_commands.py 4.2 KB
  - 📄 test_shell_command.py 2.2 KB
  - 📄 test_tag_commands.py 9.2 KB
- 📁 integration/
  - 📄 test_anki_direct_answer_card.py 8.0 KB
  - 📄 test_anki_direct_card_mutators.py 11.3 KB
  - 📄 test_anki_direct_card_note_revlog_reads.py 11.7 KB
  - 📄 test_anki_direct_deck_config_and_add_notes.py 14.2 KB
  - 📄 test_anki_direct_deck_write_paths.py 11.5 KB
  - 📄 test_anki_direct_delete_and_tag_reads.py 4.8 KB
  - 📄 test_anki_direct_due.py 4.7 KB
  - 📄 test_anki_direct_find_queries.py 6.7 KB
  - 📄 test_anki_direct_note_mutators.py 10.1 KB
  - 📄 test_anki_direct_notetype_mutators.py 16.0 KB
  - 📄 test_anki_direct_parse_decode.py 5.5 KB
  - 📄 test_anki_direct_preview_ratings.py 8.2 KB
  - 📄 test_anki_direct_read_apis.py 14.5 KB
  - 📄 test_anki_direct_snapshot_restore.py 6.2 KB
  - 📄 test_anki_direct_suspend_and_tags.py 9.2 KB
- 📁 tui/
  - 📄 test_browse_app.py 5.9 KB
  - 📄 test_repl_helpers.py 4.8 KB
  - 📄 test_repl_render_card_inline.py 6.3 KB
  - 📄 test_review_app.py 11.4 KB
- 📁 unit/
  - 📄 test_config_runtime.py 7.3 KB
  - 📄 test_entrypoint_and_colors.py 898 B
  - 📄 test_formatter.py 4.7 KB
  - 📄 test_models.py 3.3 KB
  - 📄 test_params.py 1.3 KB
  - 📄 test_scheduler.py 3.9 KB
  - 📄 test_template.py 2.5 KB
  - 📄 test_undo.py 3.2 KB
📄 .gitignore 4.6 KB
📄 .python-version 5 B
📄 LICENSE 1.0 KB
📄 pyproject.toml 1.9 KB
📄 README.md 5.9 KB
📄 SKILL.md 8.2 KB
📄 uv.lock 107.5 KB

SKILL.md

---
name: anki-cli
description: Manage Anki flashcards via CLI with structured JSON output. Create, query, review, and organize cards, notes, decks, tags, and notetypes. Supports AnkiConnect and direct SQLite backends. Use when the user mentions Anki, flashcards, spaced repetition, SRS, reviewing cards, or managing decks.
---

# anki-cli

A hybrid Anki CLI that works with both AnkiConnect (running Anki Desktop) and direct SQLite access. All commands emit structured output suitable for programmatic consumption.

## Quick Setup

```bash
anki status          # check backend and collection health
anki --format json status  # structured output for parsing
```

### Backend Selection

| Flag | Behavior |
|------|----------|
| `--backend auto` | Auto-detect best available (default) |
| `--backend ankiconnect` | Requires running Anki Desktop with AnkiConnect |
| `--backend direct` | Operates on SQLite collection file directly |
| `--backend direct --col /path/to/collection.anki2` | Explicit collection path |

Environment variable `ANKI_CLI_BACKEND` sets the default.

## Output Formats

Always use `--format json` when parsing output programmatically.

```bash
anki --format json cards --query "deck:Default"
```

Available: `json`, `table`, `md`, `csv`, `plain`.

### JSON Response Structure

Success:

```json
{
  "ok": true,
  "data": { "...": "..." },
  "meta": {
    "command": "cards",
    "backend": "direct",
    "collection": "/path/to/collection.anki2",
    "timestamp": "2026-02-21T12:00:00Z"
  }
}
```

Error:

```json
{
  "ok": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Deck not found: NonExistent",
    "details": {}
  },
  "meta": { "...": "..." }
}
```

### Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | Backend operation failed |
| 2 | Invalid input, confirmation required, or unsupported operation |
| 4 | Entity not found |
| 7 | Backend unavailable |

### Error Codes

`BACKEND_UNAVAILABLE`, `INVALID_INPUT`, `ENTITY_NOT_FOUND`, `BACKEND_OPERATION_FAILED`, `CONFIRMATION_REQUIRED`, `UNDO_EMPTY`, `TUI_NOT_AVAILABLE`, `UNSUPPORTED_BACKEND`.

## Command Reference

### Querying

```bash
anki cards --query "deck:Japanese is:due"
anki notes --query "tag:verb"
anki search --query "(tag:verb OR tag:noun) -is:suspended"
```

### Inspecting Entities

```bash
anki card --id <card_id>
anki note --id <note_id>
anki deck --deck "Default"
anki notetype --name "Basic"
anki tag --tag "verb"
```

### Listing

```bash
anki decks          # all decks with due counts
anki notetypes      # all note types
anki tags           # all tags with counts
```

### Creating Notes

```bash
anki note:add --deck "Default" --notetype "Basic" --Front "Question" --Back "Answer"
anki note:add --deck "Default" --notetype "Basic" --Front "Q" --Back "A" --tags "tag1,tag2"
```

Field names are passed as dynamic CLI options matching the notetype's field names.

### Bulk Adding Notes

Accepts JSON array from stdin or a file:

```bash
anki note:bulk --deck "Default" --notetype "Basic" --file notes.json
```

JSON format: `[{"Front": "Q1", "Back": "A1"}, {"Front": "Q2", "Back": "A2"}]`

### Editing Notes

```bash
anki note:edit --id <note_id> --Front "Updated question"
anki note:edit --id <note_id> --tags "new-tag1,new-tag2"
```

### Deleting (Destructive -- requires `--yes`)

```bash
anki note:delete --id <note_id> --yes
anki deck:delete --deck "Temporary" --yes
```

### Card Actions

```bash
anki card:suspend --query "deck:Old"
anki card:unsuspend --id <card_id>
anki card:move --query "tag:relocate" --deck "Archive"
anki card:flag --id <card_id> --flag 3
anki card:bury --query "deck:Default"
anki card:unbury --deck "Default"
anki card:reschedule --query "tag:reset" --days 5
anki card:reset --query "tag:relearn"
anki card:revlog --id <card_id> --limit 20
```

Most card actions accept either `--id <card_id>` for a single card or `--query "<search>"` for bulk operations.

### Tags

```bash
anki tag:add --query "deck:Default" --tag "important"
anki tag:remove --id <note_id> --tag "old-tag"
anki tag:rename --from "old" --to "new"
```

### Decks

```bash
anki deck:create --name "Japanese::Vocab"
anki deck:rename --from "Old Name" --to "New Name"
anki deck:config --deck "Default"
anki deck:config:set --deck "Default" --new-per-day 20 --reviews-per-day 200
```

### Notetypes

```bash
anki notetype:create --name "MyType" --field "Front" --field "Back"
anki notetype:field:add --notetype "Basic" --field "Extra"
anki notetype:field:remove --notetype "Basic" --field "Extra"
anki notetype:template:add --notetype "MyType" --template "Card 1" --front "{{Front}}" --back "{{Back}}"
anki notetype:template:edit --notetype "MyType" --template "Card 1" --front "{{Front}}" --back "{{FrontSide}}<hr>{{Back}}"
anki notetype:css --notetype "Basic"
anki notetype:css --notetype "Basic" --set ".card { font-size: 18px; }"
```

### Review

```bash
anki review                          # due counts
anki review:next --deck "Japanese"   # next due card (question only)
anki review:show --deck "Japanese"   # next card with answer
anki review:answer --id <card_id> --rating good   # answer: again|hard|good|easy
anki review:preview --id <card_id>   # scheduling preview per rating
anki review:undo                     # undo last answer (direct backend only)
```

### Configuration

```bash
anki config                          # show merged config
anki config:path                     # show all paths
anki config:set --key "display.default_output" --value "json"
```

## Search Query Language

### Filters

| Filter | Example |
|--------|---------|
| Deck | `deck:Japanese`, `deck:Japanese*` (glob) |
| Notetype | `notetype:Basic` |
| Tag | `tag:verb`, `tag:lang*` (glob) |
| State | `is:new`, `is:learn`, `is:review`, `is:due`, `is:suspended`, `is:buried` |
| Flag | `flag:1` through `flag:7`, `flag:0` (no flag) |
| Property | `prop:ivl>30`, `prop:due<5`, `prop:reps>=10`, `prop:lapses=0` |
| Note ID | `nid:1234567890` |
| Card ID | `cid:1234567890` |
| Text | bare words or `"quoted phrase"` |

### Logical Operators

- Implicit AND: `deck:Default is:due` (both must match)
- Explicit OR: `tag:verb OR tag:noun`
- NOT / negate: `-is:suspended` or `NOT is:suspended`
- Grouping: `(tag:a OR tag:b) is:new`

## Environment Variables

| Variable | Purpose | Example |
|----------|---------|---------|
| `ANKI_CLI_BACKEND` | Default backend | `direct` |
| `ANKI_CLI_OUTPUT` | Default output format | `json` |
| `ANKI_CLI_COLOR` | Enable/disable color | `0` |
| `ANKI_CLI_COLLECTION` | Collection path override | `/path/to/collection.anki2` |

## Config File

Location: `~/.config/anki-cli/config.toml`

```toml
[backend]
prefer = "auto"
ankiconnect_url = "http://localhost:8765"
allow_non_localhost = false

[display]
default_output = "table"
color = true
day_boundary_hour = 4
```

For remote AnkiConnect (e.g. via Tailscale or LAN):

```toml
[backend]
prefer = "ankiconnect"
ankiconnect_url = "http://192.168.1.100:8765"
allow_non_localhost = true
```

## Common Agent Workflows

### Create a deck and populate it

```bash
anki deck:create --name "Spanish::Vocab"
anki note:add --deck "Spanish::Vocab" --notetype "Basic" --Front "hola" --Back "hello"
anki note:add --deck "Spanish::Vocab" --notetype "Basic" --Front "gracias" --Back "thank you"
```

### Query and act on results

```bash
anki --format json cards --query "deck:Default is:due prop:lapses>3"
anki card:suspend --query "deck:Default prop:lapses>5"
anki tag:add --query "deck:Default prop:lapses>3" --tag "leech"
```

### Review loop (programmatic)

```bash
anki --format json review:next --deck "Japanese"
# parse card_id from response
anki --format json review:answer --id <card_id> --rating good
```

### Bulk import from JSON

```bash
echo '[{"Front":"Q1","Back":"A1"},{"Front":"Q2","Back":"A2"}]' | anki note:bulk --deck "Default" --notetype "Basic"
```

### Check health before operations

```bash
anki --format json status
# verify "ok": true before proceeding
```

## Safety

- Destructive commands (`note:delete`, `deck:delete`) require `--yes` or will exit with code 2 and `CONFIRMATION_REQUIRED`.
- Avoid direct-backend writes while Anki Desktop has the collection open.
- Use `--backend ankiconnect` when Anki Desktop is running.
- `review:undo` only works with the direct backend and only undoes the last answer.

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

anki-cli

Directory Structure

SKILL.md

Report

Notice