Que fait cli-anything-calibre ?
Un harnais CLI d'état pour la gestion de bibliothèque Calibre. Encapsule les outils Calibre réels (calibredb, ebook-convert, ebook-meta) pour offrir aux agents IA et aux scripts une interface claire et structurée pour les opérations de bibliothèque, l'édition de métadonnées et la conversion de formats.
Installation
Cette CLI est installée dans le cadre du paquet cli-anything-calibre :
pip install git+https://github.com/HKUDS/CLI-Anything.git#subdirectory=calibre/agent-harness
Prérequis :
- Python 3.10+
- Calibre doit être installé sur votre système (dépendance stricte)
# Debian/Ubuntu
sudo apt-get install calibre
# macOS
brew install --cask calibre
# Vérifier que les outils sont dans le PATH
which calibredb
which ebook-convert
which ebook-meta
Utilisation
Commandes de base
# Afficher l'aide
cli-anything-calibre --help
# Démarrer le mode REPL interactif
cli-anything-calibre
# Se connecter à une bibliothèque Calibre
cli-anything-calibre library connect ~/Calibre\ Library
# Exécuter avec sortie JSON (pour consommation par agent)
cli-anything-calibre --json books list
Mode REPL
Lorsqu'elle est invoquée sans sous-commande, la CLI entre dans une session REPL interactive :
cli-anything-calibre
# Saisissez les commandes interactivement avec complétion par tabulation et historique
# Utilisez 'help' pour voir les commandes disponibles
# Utilisez 'quit' ou 'exit' pour quitter
Groupes de commandes
Bibliothèque
Commandes de gestion de la bibliothèque.
| Commande | Description |
|---|---|
connect <chemin> | Définir le chemin de la bibliothèque active |
info | Afficher les statistiques de la bibliothèque (nombre de livres, formats, taille de la base) |
check | Vérifier l'intégrité de la bibliothèque avec calibredb check_library |
Livres
Opérations sur les livres (encapsulent calibredb).
| Commande | Description |
|---|---|
list | Lister les livres avec filtrage et tri |
search <requête> | Rechercher en utilisant le langage de requête Calibre |
add <fichiers> | Ajouter des fichiers de livres à la bibliothèque |
remove <ids> | Supprimer des livres (mettre à la corbeille ou supprimer définitivement) |
show <id> | Afficher les métadonnées complètes d'un livre |
export <ids> | Exporter les livres vers un répertoire |
export-chapters <id> | Exporter chaque chapitre comme un PDF séparé (nécessite le format EPUB) |
Métadonnées
Édition des métadonnées (encapsulent calibredb set_metadata).
| Commande | Description |
|---|---|
get <id> [champ] | Obtenir les métadonnées (toutes ou un champ spécifique) |
set <id> <champ> <valeur> | Définir un champ de métadonnées |
embed <ids> | Intégrer les métadonnées dans les fichiers de livres |
Formats
Gestion des formats (encapsulent calibredb + ebook-convert).
| Commande | Description |
|---|---|
list <id> | Lister les formats disponibles pour un livre |
add <id> <fichier> | Ajouter un format à un livre |
remove <id> <fmt> | Supprimer un format d'un livre |
convert <id> <fmt_entrée> <fmt_sortie> | Convertir le format d'un livre |
Personnalisé
Colonnes personnalisées (encapsulent calibredb).
| Commande | Description |
|---|---|
list | Lister toutes les colonnes personnalisées |
add <libellé> <nom> <type> | Créer une colonne personnalisée |
remove <libellé> | Supprimer une colonne personnalisée |
set <id> <libellé> <valeur> | Définir la valeur d'un champ personnalisé |
Catalogue
Génération de catalogue.
| Commande | Description |
|---|---|
catalog <sortie> | Générer un catalogue de la bibliothèque (EPUB, CSV ou OPDS) |
Exemples
Se connecter et lister les livres
Connectez-vous à votre bibliothèque Calibre et listez les livres.
cli-anything-calibre library connect ~/Calibre\ Library
cli-anything-calibre books list
# Ou avec sortie JSON
cli-anything-calibre --json books list --search "author:asimov"
Rechercher et filtrer
Rechercher des livres en utilisant le langage de requête Calibre.
cli-anything-calibre books search "title:Foundation"
cli-anything-calibre books search "author:asimov and tags:scifi"
cli-anything-calibre books search "rating:>3"
Édition de métadonnées
Définir des champs de métadonnées sur les livres.
cli-anything-calibre meta set 42 title "Nouveau Titre"
cli-anything-calibre meta set 42 series "Foundation"
cli-anything-calibre meta set 42 series_index 1
cli-anything-calibre meta set 42 tags "scifi,classique"
cli-anything-calibre meta set 42 rating 5
Conversion de formats
Convertir entre formats de livres électroniques.
cli-anything-calibre formats convert 42 EPUB MOBI
cli-anything-calibre formats convert 42 EPUB PDF --output /tmp/book.pdf
Exporter des chapitres en PDF
Exporter chaque chapitre d'un EPUB sous forme de fichier PDF séparé.
cli-anything-calibre books export-chapters 42 --to-dir ./pdfs
cli-anything-calibre books export-chapters 42 --to-dir ./pdfs --chapters 1-5
Langage de requête Calibre
Utilisé avec books search et books list --search :
author:asimov # L'auteur contient "asimov"
title:"Foundation" # L'expression du titre
tags:fiction # Correspondance d'étiquette
rating:>3 # Note supérieure à 3
series:"Foundation" # Correspondance de série
pubdate:[2020-01-01,2021-12-31] # Plage de dates
identifiers:isbn:1234567890 # Identifiant spécifique
has:cover # A une image de couverture
not:tags:fiction # Négation
author:asimov and tags:scifi # ET booléen
Champs clés des métadonnées
| Champ | Type | Description |
|---|---|---|
title | texte | Titre du livre |
authors | texte | Noms des auteurs (séparés par &) |
tags | texte | Étiquettes séparées par des virgules |
series | texte | Nom de la série |
series_index | flottant | Position dans la série |
rating | flottant | Note de 1 à 5 |
publisher | texte | Nom de l'éditeur |
pubdate | datetime | Date de publication |
comments | texte | Description/commentaires |
languages | texte | Codes de langue |
identifiers | texte | ISBN, ASIN, etc. (type:valeur) |
Formats pris en charge
Entrée : EPUB, MOBI, AZW, AZW3, PDF, HTML, DOCX, ODT, FB2, TXT, RTF, LIT, et plus
Sortie (conversion) : EPUB, MOBI, AZW3, PDF, HTML, DOCX, TXT, et plus
Gestion de l'état
La CLI maintient l'état de session avec :
- Fichier de session :
~/.cli-anything-calibre/session.json - Persistance du chemin de bibliothèque : La bibliothèque active est sauvegardée entre les sessions
- Remplacement par environnement : Variable d'environnement
CALIBRE_LIBRARY
Formats de sortie
Toutes les commandes prennent en charge deux modes de sortie :
- Lisible par l'humain (par défaut) : Tableaux, couleurs, texte formaté
- Lisible par machine (drapeau
--json) : JSON structuré pour consommation par agent
# Sortie humaine
cli-anything-calibre books list
# Sortie JSON pour les agents
cli-anything-calibre --json books list
Pour les agents IA
Lorsque vous utilisez cette CLI de manière programmatique :
- Utilisez toujours le drapeau
--jsonpour une sortie analysable - Vérifiez les codes de retour - 0 pour succès, non nul pour erreurs
- Analysez stderr pour les messages d'erreur en cas d'échec
- Vérifiez que les sorties existent après les opérations d'exportation/conversion
- Utilisez le drapeau
--libraryou la variable d'environnementCALIBRE_LIBRARYpour spécifier le chemin de la bibliothèque - L'exportation de chapitres nécessite le format EPUB - convertissez d'abord si nécessaire
Plus d'informations
- Documentation complète : Voir README.md dans le paquet
- Architecture SOP : Voir CALIBRE.md dans le répertoire agent-harness
- Couverture de test : Voir test_core.py et test_full_e2e.py dans le répertoire tests
- Méthodologie : Voir HARNESS.md dans le cli-anything-plugin
Version
1.0.0