O que cli-anything-calibre faz?
Uma interface de linha de comando com estado para gerenciamento de e-books Calibre. Envolve as ferramentas reais do Calibre (calibredb, ebook-convert, ebook-meta) para fornecer a agentes de IA e scripts uma interface limpa e estruturada para operações de biblioteca, edição de metadados e conversão de formatos.
Instalação
Esta CLI é instalada como parte do pacote cli-anything-calibre:
pip install git+https://github.com/HKUDS/CLI-Anything.git#subdirectory=calibre/agent-harness
Pré-requisitos:
- Python 3.10+
- Calibre instalado no sistema (dependência obrigatória)
# Debian/Ubuntu
sudo apt-get install calibre
# macOS
brew install --cask calibre
# Verificar ferramentas no PATH
which calibredb
which ebook-convert
which ebook-meta
Uso
Comandos Básicos
# Mostrar ajuda
cli-anything-calibre --help
# Iniciar modo REPL interativo
cli-anything-calibre
# Conectar a uma biblioteca Calibre
cli-anything-calibre library connect ~/Calibre\ Library
# Executar com saída JSON (para consumo por agentes)
cli-anything-calibre --json books list
Modo REPL
Quando invocado sem um subcomando, a CLI entra em uma sessão REPL interativa:
cli-anything-calibre
# Digite comandos interativamente com autocompletar e histórico
# Use 'help' para ver comandos disponíveis
# Use 'quit' ou 'exit' para sair
Grupos de Comandos
Biblioteca
Comandos de gerenciamento da biblioteca.
| Comando | Descrição |
|---|---|
connect <caminho> | Define o caminho da biblioteca ativa |
info | Mostra estatísticas da biblioteca (quantidade de livros, formatos, tamanho do banco) |
check | Verifica integridade da biblioteca usando calibredb check_library |
Livros
Operações com livros (encapsulam calibredb).
| Comando | Descrição |
|---|---|
list | Lista livros com filtragem e ordenação |
search <consulta> | Pesquisa usando a linguagem de consulta do Calibre |
add <arquivos> | Adiciona arquivos de livros à biblioteca |
remove <ids> | Remove livros (move para lixeira ou exclui permanentemente) |
show <id> | Mostra metadados completos de um livro |
export <ids> | Exporta livros para um diretório |
export-chapters <id> | Exporta cada capítulo como PDF separado (requer formato EPUB) |
Metadados
Edição de metadados (encapsula calibredb set_metadata).
| Comando | Descrição |
|---|---|
get <id> [campo] | Obtém metadados (todos ou um campo específico) |
set <id> <campo> <valor> | Define um campo de metadados |
embed <ids> | Incorpora metadados nos arquivos dos livros |
Formatos
Gerenciamento de formatos (encapsula calibredb + ebook-convert).
| Comando | Descrição |
|---|---|
list <id> | Lista formatos disponíveis para um livro |
add <id> <arquivo> | Adiciona um formato a um livro |
remove <id> <fmt> | Remove um formato de um livro |
convert <id> <fmt_entrada> <fmt_saida> | Converte formato do livro |
Personalizados
Colunas personalizadas (encapsula calibredb).
| Comando | Descrição |
|---|---|
list | Lista todas as colunas personalizadas |
add <rótulo> <nome> <tipo> | Cria coluna personalizada |
remove <rótulo> | Exclui coluna personalizada |
set <id> <rótulo> <valor> | Define valor de campo personalizado |
Catálogo
Geração de catálogo.
| Comando | Descrição |
|---|---|
catalog <saída> | Gera um catálogo da biblioteca (EPUB, CSV ou OPDS) |
Exemplos
Conectar e Listar Livros
Conecte-se à sua biblioteca Calibre e liste livros.
cli-anything-calibre library connect ~/Calibre\ Library
cli-anything-calibre books list
# Ou com saída JSON
cli-anything-calibre --json books list --search "author:asimov"
Pesquisar e Filtrar
Pesquise livros usando a linguagem de consulta do 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"
Edição de Metadados
Defina campos de metadados em livros.
cli-anything-calibre meta set 42 title "Novo 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,classico"
cli-anything-calibre meta set 42 rating 5
Conversão de Formatos
Converta entre formatos de e-book.
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 um EPUB como um arquivo 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
Linguagem de Consulta do Calibre
Usada com books search e books list --search:
author:asimov # Autor contém "asimov"
title:"Foundation" # Frase no título
tags:fiction # Correspondência de tag
rating:>3 # Avaliação maior que 3
series:"Foundation" # Correspondência de série
pubdate:[2020-01-01,2021-12-31] # Intervalo de datas
identifiers:isbn:1234567890 # Identificador específico
has:cover # Possui imagem de capa
not:tags:fiction # Negação
author:asimov and tags:scifi # E booleano
Principais Campos de Metadados
| Campo | Tipo | Descrição |
|---|---|---|
title | texto | Título do livro |
authors | texto | Nomes dos autores (separados por &) |
tags | texto | Tags separadas por vírgula |
series | texto | Nome da série |
series_index | float | Posição na série |
rating | float | Avaliação 1-5 |
publisher | texto | Nome da editora |
pubdate | datetime | Data de publicação |
comments | texto | Descrição/comentários |
languages | texto | Códigos de idioma |
identifiers | texto | ISBN, ASIN, etc. (tipo:valor) |
Formatos Suportados
Entrada: EPUB, MOBI, AZW, AZW3, PDF, HTML, DOCX, ODT, FB2, TXT, RTF, LIT e mais
Saída (conversão): EPUB, MOBI, AZW3, PDF, HTML, DOCX, TXT e mais
Gerenciamento de Estado
A CLI mantém o estado da sessão com:
- Arquivo de sessão:
~/.cli-anything-calibre/session.json - Persistência do caminho da biblioteca: A biblioteca ativa é salva entre sessões
- Sobrescrita por ambiente: Variável de ambiente
CALIBRE_LIBRARY
Formatos de Saída
Todos os comandos suportam dois modos de saída:
- Legível por humanos (padrão): Tabelas, cores, texto formatado
- Legível por máquina (flag
--json): JSON estruturado para consumo por agentes
# Saída humana
cli-anything-calibre books list
# Saída JSON para agentes
cli-anything-calibre --json books list
Para Agentes de IA
Ao usar esta CLI programaticamente:
- Sempre use a flag
--jsonpara saída parseável - Verifique os códigos de retorno - 0 para sucesso, diferente de zero para erros
- Analise o stderr para mensagens de erro em caso de falha
- Verifique se as saídas existem após operações de exportação/conversão
- Use a flag
--libraryou a variável de ambienteCALIBRE_LIBRARYpara especificar o caminho da biblioteca - Exportação de capítulos requer formato EPUB - converta primeiro se necessário
Mais Informações
- Documentação completa: Veja README.md no pacote
- SOP de arquitetura: Veja CALIBRE.md no diretório agent-harness
- Cobertura de testes: Veja test_core.py e test_full_e2e.py no diretório tests
- Metodologia: Veja HARNESS.md no cli-anything-plugin
Versão
1.0.0