Metadata-Version: 2.4
Name: ankicli-tool
Version: 0.1.0
Summary: Command-line interface for Anki via AnkiConnect
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Anki CLI

<div align="center">

![Anki CLI Banner](https://img.shields.io/badge/Anki-CLI-blue?style=for-the-badge)
![Python Version](https://img.shields.io/pypi/pyversions/anki-cli?style=for-the-badge)
![License](https://img.shields.io/github/license/liukuan-guilin/anki-cli?style=for-the-badge)
![PyPI](https://img.shields.io/pypi/v/ankicli-tool.svg?style=for-the-badge)
![GitHub stars](https://img.shields.io/github/stars/liukuan-guilin/anki-cli.svg?style=for-the-badge)

**A comprehensive command-line interface for Anki via AnkiConnect**

[English](README.md) | [简体中文](README_CN.md)

</div>

---

## Features

- **Complete API Coverage** - 60+ commands covering all AnkiConnect operations
- **AI Agent Ready** - SKILL.md for discoverable capabilities
- **CLI-Anything Compatible** - Follows agent-harness pattern
- **Batch Operations** - Add multiple cards, bulk tag management
- **Search & Filter** - Full Anki search syntax support
- **Review Automation** - Control review sessions programmatically

## Prerequisites

1. **Install Anki**: https://apps.ankiweb.net/
2. **Install AnkiConnect plugin**: https://ankiweb.net/shared/info/2055492159
3. **Python 3.8+**

## Installation

```bash
cd anki-cli
pip install -e .

# Verify installation
anki-cli --help
anki-cli version
```

## Quick Start

```bash
# List all decks
anki-cli deck-list

# Add a flashcard
anki-cli add-note -d "English" -m Basic -t vocabulary Front:Hello Back:你好

# Search for cards
anki-cli find-notes "deck:English"

# Start reviewing
anki-cli gui-review "English"
```

## Command Reference

### System Commands
```bash
anki-cli version              # Get AnkiConnect version
anki-cli sync                 # Sync with AnkiWeb
anki-cli profiles             # List profiles
anki-cli check-database       # Check database
```

### Deck Management
```bash
anki-cli deck-list                         # List decks
anki-cli deck-stats "Deck Name"            # Deck statistics
anki-cli create-deck "New Deck"            # Create deck
anki-cli delete-deck "Old Deck"            # Delete deck
```

### Note Operations
```bash
anki-cli add-note -d DECK -m MODEL -t TAGS Field:Value ...
anki-cli notes-info NOTE_ID [NOTE_ID ...]
anki-cli update-note NOTE_ID Field:NewValue
anki-cli delete-notes NOTE_ID [NOTE_ID ...]
```

### Tag Management
```bash
anki-cli add-tags NOTE_IDS... TAGS
anki-cli remove-tags NOTE_IDS... TAGS
anki-cli replace-tags NOTE_IDS... OLD_TAG NEW_TAG
anki-cli clear-tags                        # Remove unused tags
```

### Card State
```bash
anki-cli suspend NOTE_IDS...               # Suspend from reviews
anki-cli unsuspend NOTE_IDS...             # Resume reviews
anki-cli are-suspended NOTE_IDS...         # Check status
anki-cli are-due CARD_IDS...               # Check if due
anki-cli forget CARD_IDS...                # Reset to new
anki-cli set-due-date CARD_IDS... DAYS     # Reschedule
```

### Search (Full Anki syntax supported)
```bash
anki-cli find-notes "deck:English is:due"
anki-cli find-cards "tag:vocabulary prop:interval>7"
anki-cli find-notes "rated:7 -is:suspended"
```

### GUI Operations
```bash
anki-cli gui-add                           # Open Add dialog
anki-cli gui-edit NOTE_ID                  # Open Edit dialog
anki-cli gui-current                       # Get current card
anki-cli gui-browser "query"               # Open browser
anki-cli gui-review "Deck Name"            # Start review
anki-cli gui-exit                          # Close Anki
```

### Statistics
```bash
anki-cli today-stats                       # Cards reviewed today
anki-cli reviews-by-day                    # History by day
anki-cli collection-stats                  # Full stats HTML
```

## Anki Search Syntax

| Syntax | Description |
|--------|-------------|
| `deck:Name` | Cards in deck |
| `tag:Name` | Cards with tag |
| `is:new` | New cards |
| `is:due` | Due cards |
| `is:suspended` | Suspended cards |
| `prop:due<=7` | Due within 7 days |
| `prop:interval>30` | Interval > 30 days |
| `added:7` | Added in last 7 days |
| `rated:1` | Reviewed today |
| `front:text` | Search front field |

Combine with `AND` (space), `OR` (or), `-` (negate), `()` (group).

## Examples

### Create vocabulary cards
```bash
anki-cli add-note -d "French" -m Basic \
    Front:"Bonjour" Back:"Hello" -t lesson1
```

### Batch import from file
```bash
# notes.txt (tab-separated):
# Bonjour	Hello
# Merci	Thank you
# Au revoir	Goodbye

anki-cli add-notes -d "French" -m Basic -t lesson1 notes.txt
```

### Suspend old cards
```bash
# Suspend cards not reviewed in 90 days
anki-cli suspend $(anki-cli find-cards "rated:90 -prop:due<=90")
```

### Review workflow
```bash
# Check what's due
anki-cli find-notes "deck:Biology is:due"

# Start review
anki-cli gui-review "Biology"

# During review, answer cards
anki-cli answer $CARD_ID 3  # 3 = Good
```

## AI Agent Usage

This CLI is designed for AI agent integration:

1. **Discoverable**: Run `anki-cli --help` or read SKILL.md
2. **Structured output**: All commands return parseable text
3. **Error handling**: Clear error messages on stderr
4. **Batch operations**: Efficient bulk actions

### Example Agent Workflow

```python
# Pseudocode for AI agent
def create_study_session(topic):
    # 1. Check if deck exists
    decks = run("anki-cli deck-list")
    if topic not in decks:
        run(f"anki-cli create-deck {topic}")

    # 2. Generate cards from content
    cards = generate_flashcards(topic)  # AI generates
    for front, back in cards:
        run(f"anki-cli add-note -d {topic} Front:{front} Back:{back}")

    # 3. Start review
    run(f"anki-cli gui-review {topic}")
```

## Troubleshooting

**"Cannot connect to AnkiConnect"**
- Make sure Anki is running
- Verify AnkiConnect plugin is installed (Tools > Add-ons)
- Check AnkiConnect is configured for port 8765

**"Deck not found"**
- Deck names are case-sensitive
- Use quotes for names with spaces: `"My Deck"`

**"Note/Model not found"**
- List existing: `anki-cli model-list`
- Default model is "Basic"

## Advanced: Multi-Action Requests

For efficiency, execute multiple actions in one request:

```bash
# actions.txt (one JSON per line):
{"action":"createDeck","params":{"deck":"NewDeck"}}
{"action":"addNote","params":{"note":{"deckName":"NewDeck",...}}}

anki-cli multi actions.txt
```

## Resources

- [AnkiConnect API](https://github.com/FooSoft/anki-connect)
- [Anki Search Syntax](https://docs.ankiweb.net/searching.html)
- [Anki Browsing](https://docs.ankiweb.net/browsing.html)
- [AnkiConnect Plugin](https://ankiweb.net/shared/info/2055492159)

## License

MIT

---

<div align="center">

**Made with ❤️ by liukuan-guilin**

[⭐ Star on GitHub](https://github.com/liukuan-guilin/anki-cli/stargazers) | [📦 PyPI](https://pypi.org/project/anki-cli/) | [🐛 Report Issues](https://github.com/liukuan-guilin/anki-cli/issues)

[English](README.md) | [简体中文](README_CN.md)

</div>
