¿Qué hace cli-anything-calibre?
Un interfaz de línea de comandos con estado para la gestión de bibliotecas electrónicas de Calibre. Envuelve las herramientas reales de Calibre (calibredb, ebook-convert, ebook-meta) para ofrecer a agentes de IA y scripts una interfaz limpia, estructurada y programática para operaciones de biblioteca, edición de metadatos y conversión de formatos.
Instalación
Este CLI se instala como parte del paquete cli-anything-calibre:
pip install git+https://github.com/HKUDS/CLI-Anything.git#subdirectory=calibre/agent-harness
Requisitos previos:
- Python 3.10+
- Calibre debe estar instalado en su sistema (dependencia obligatoria)
# Debian/Ubuntu
sudo apt-get install calibre
# macOS
brew install --cask calibre
# Verificar que las herramientas están en PATH
which calibredb
which ebook-convert
which ebook-meta
Uso
Comandos básicos
# Mostrar ayuda
cli-anything-calibre --help
# Iniciar modo REPL interactivo
cli-anything-calibre
# Conectar a una biblioteca de Calibre
cli-anything-calibre library connect ~/Calibre\ Library
# Ejecutar con salida JSON (para consumo por agentes)
cli-anything-calibre --json books list
Modo REPL
Cuando se invoca sin un subcomando, el CLI entra en una sesión REPL interactiva:
cli-anything-calibre
# Ingrese comandos interactivamente con autocompletado e historial
# Use 'help' para ver comandos disponibles
# Use 'quit' o 'exit' para salir
Grupos de comandos
Biblioteca
Comandos de gestión de biblioteca.
| Comando | Descripción |
|---|---|
connect <ruta> | Establecer ruta de biblioteca activa |
info | Mostrar estadísticas de biblioteca (cantidad de libros, formatos, tamaño de BD) |
check | Verificar integridad de biblioteca usando calibredb check_library |
Libros
Operaciones con libros (envuelve calibredb).
| Comando | Descripción |
|---|---|
list | Listar libros con filtrado y ordenación |
search <consulta> | Buscar usando el lenguaje de consulta de Calibre |
add <archivos> | Agregar archivos de libro a la biblioteca |
remove <ids> | Eliminar libros (mover a papelera o eliminar permanentemente) |
show <id> | Mostrar metadatos completos de un libro |
export <ids> | Exportar libros a un directorio |
export-chapters <id> | Exportar cada capítulo como PDF separado (requiere formato EPUB) |
Metadatos
Edición de metadatos (envuelve calibredb set_metadata).
| Comando | Descripción |
|---|---|
get <id> [campo] | Obtener metadatos (todos o un campo específico) |
set <id> <campo> <valor> | Establecer un campo de metadatos |
embed <ids> | Incrustar metadatos en archivos de libro |
Formatos
Gestión de formatos (envuelve calibredb + ebook-convert).
| Comando | Descripción |
|---|---|
list <id> | Listar formatos disponibles de un libro |
add <id> <archivo> | Agregar un formato a un libro |
remove <id> <fmt> | Eliminar un formato de un libro |
convert <id> <fmt_entrada> <fmt_salida> | Convertir formato de libro |
Personalizado
Columnas personalizadas (envuelve calibredb).
| Comando | Descripción |
|---|---|
list | Listar todas las columnas personalizadas |
add <etiqueta> <nombre> <tipo> | Crear columna personalizada |
remove <etiqueta> | Eliminar columna personalizada |
set <id> <etiqueta> <valor> | Establecer valor de campo personalizado |
Catálogo
Generación de catálogos.
| Comando | Descripción |
|---|---|
catalog <salida> | Generar un catálogo de la biblioteca (EPUB, CSV o OPDS) |
Ejemplos
Conectar y listar libros
Conéctese a su biblioteca de Calibre y liste libros.
cli-anything-calibre library connect ~/Calibre\ Library
cli-anything-calibre books list
# O con salida JSON
cli-anything-calibre --json books list --search "author:asimov"
Buscar y filtrar
Busque libros usando el lenguaje de consulta de 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"
Edición de metadatos
Establezca campos de metadatos en libros.
cli-anything-calibre meta set 42 title "Nuevo título"
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,clasico"
cli-anything-calibre meta set 42 rating 5
Conversión de formatos
Convierta entre formatos de libro electrónico.
cli-anything-calibre formats convert 42 EPUB MOBI
cli-anything-calibre formats convert 42 EPUB PDF --output /tmp/book.pdf
Exportar capítulos como PDFs
Exporte cada capítulo de un EPUB como un archivo PDF separado.
cli-anything-calibre books export-chapters 42 --to-dir ./pdfs
cli-anything-calibre books export-chapters 42 --to-dir ./pdfs --chapters 1-5
Lenguaje de consulta de Calibre
Se usa con books search y books list --search:
author:asimov # El autor contiene "asimov"
title:"Foundation" # Frase en título
tags:fiction # Coincidencia de etiqueta
rating:>3 # Calificación mayor que 3
series:"Foundation" # Coincidencia de serie
pubdate:[2020-01-01,2021-12-31] # Rango de fechas
identifiers:isbn:1234567890 # Identificador específico
has:cover # Tiene imagen de portada
not:tags:fiction # Negación
author:asimov and tags:scifi # Y booleano
Campos clave de metadatos
| Campo | Tipo | Descripción |
|---|---|---|
title | texto | Título del libro |
authors | texto | Nombres de autores (separados por &) |
tags | texto | Etiquetas separadas por comas |
series | texto | Nombre de la serie |
series_index | flotante | Posición en la serie |
rating | flotante | Calificación 1-5 |
publisher | texto | Nombre del editor |
pubdate | datetime | Fecha de publicación |
comments | texto | Descripción/comentarios |
languages | texto | Códigos de idioma |
identifiers | texto | ISBN, ASIN, etc. (tipo:valor) |
Formatos compatibles
Entrada: EPUB, MOBI, AZW, AZW3, PDF, HTML, DOCX, ODT, FB2, TXT, RTF, LIT, y más
Salida (conversión): EPUB, MOBI, AZW3, PDF, HTML, DOCX, TXT, y más
Gestión de estado
El CLI mantiene el estado de la sesión con:
- Archivo de sesión:
~/.cli-anything-calibre/session.json - Persistencia de ruta de biblioteca: La biblioteca activa se guarda entre sesiones
- Anulación por entorno: Variable de entorno
CALIBRE_LIBRARY
Formatos de salida
Todos los comandos soportan dos modos de salida:
- Legible para humanos (predeterminado): Tablas, colores, texto formateado
- Legible para máquinas (bandera
--json): JSON estructurado para consumo por agentes
# Salida humana
cli-anything-calibre books list
# Salida JSON para agentes
cli-anything-calibre --json books list
Para agentes de IA
Al usar este CLI de forma programática:
- Use siempre la bandera
--jsonpara salida analizable - Verifique los códigos de retorno - 0 para éxito, distinto de cero para errores
- Analice stderr para mensajes de error en caso de fallo
- Verifique que las salidas existan después de operaciones de exportación/conversión
- Use la bandera
--libraryo la variable de entornoCALIBRE_LIBRARYpara especificar la ruta de la biblioteca - La exportación de capítulos requiere formato EPUB - convierta primero si es necesario
Más información
- Documentación completa: Consulte README.md en el paquete
- SOP de arquitectura: Consulte CALIBRE.md en el directorio agent-harness
- Cobertura de pruebas: Consulte test_core.py y test_full_e2e.py en el directorio tests
- Metodología: Consulte HARNESS.md en cli-anything-plugin
Versión
1.0.0