cli-anything-calibre은(는) 무엇을 하나요?
상태 저장형 Calibre 전자책 관리 CLI 도구입니다. 실제 Calibre 도구(calibredb, ebook-convert, ebook-meta)를 래핑하여 AI 에이전트와 스크립트가 라이브러리 작업, 메타데이터 편집, 형식 변환을 깔끔하고 구조화된 인터페이스로 수행할 수 있도록 합니다.
설치
이 CLI는 cli-anything-calibre 패키지의 일부로 설치됩니다:
pip install git+https://github.com/HKUDS/CLI-Anything.git#subdirectory=calibre/agent-harness
전제 조건:
- Python 3.10+
- Calibre가 시스템에 설치되어 있어야 합니다 (필수 의존성)
# Debian/Ubuntu
sudo apt-get install calibre
# macOS
brew install --cask calibre
# 도구가 PATH에 있는지 확인
which calibredb
which ebook-convert
which ebook-meta
사용법
기본 명령어
# 도움말 보기
cli-anything-calibre --help
# 대화형 REPL 모드 시작
cli-anything-calibre
# Calibre 라이브러리에 연결
cli-anything-calibre library connect ~/Calibre\ Library
# JSON 출력과 함께 실행 (에이전트용)
cli-anything-calibre --json books list
REPL 모드
하위 명령어 없이 호출하면 CLI가 대화형 REPL 세션을 시작합니다:
cli-anything-calibre
# 탭 완성 및 히스토리로 대화형 명령어 입력
# 'help'로 사용 가능한 명령어 확인
# 'quit' 또는 'exit'으로 종료
명령어 그룹
Library (라이브러리)
라이브러리 관리 명령어입니다.
| 명령어 | 설명 |
|---|---|
connect <path> | 활성 라이브러리 경로 설정 |
info | 라이브러리 통계 표시 (책 개수, 형식, DB 크기) |
check | calibredb check_library로 라이브러리 무결성 확인 |
Books (책)
책 관련 작업입니다 (calibredb 래핑).
| 명령어 | 설명 |
|---|---|
list | 필터링 및 정렬로 책 목록 표시 |
search <query> | Calibre 쿼리 언어로 검색 |
add <files> | 라이브러리에 책 파일 추가 |
remove <ids> | 책 삭제 (휴지통으로 이동 또는 영구 삭제) |
show <id> | 책의 전체 메타데이터 표시 |
export <ids> | 책을 디렉터리로 내보내기 |
export-chapters <id> | 각 장을 개별 PDF로 내보내기 (EPUB 형식 필요) |
Meta (메타데이터)
메타데이터 편집입니다 (calibredb set_metadata 래핑).
| 명령어 | 설명 |
|---|---|
get <id> [field] | 메타데이터 가져오기 (전체 또는 특정 필드) |
set <id> <field> <value> | 메타데이터 필드 설정 |
embed <ids> | 책 파일에 메타데이터 포함 |
Formats (형식)
형식 관리입니다 (calibredb + ebook-convert 래핑).
| 명령어 | 설명 |
|---|---|
list <id> | 책의 사용 가능한 형식 목록 |
add <id> <file> | 책에 형식 추가 |
remove <id> <fmt> | 책에서 형식 제거 |
convert <id> <input_fmt> <output_fmt> | 책 형식 변환 |
Custom (사용자 정의)
사용자 정의 컬럼입니다 (calibredb 래핑).
| 명령어 | 설명 |
|---|---|
list | 모든 사용자 정의 컬럼 목록 |
add <label> <name> <type> | 사용자 정의 컬럼 생성 |
remove <label> | 사용자 정의 컬럼 삭제 |
set <id> <label> <value> | 사용자 정의 필드 값 설정 |
Catalog (카탈로그)
카탈로그 생성입니다.
| 명령어 | 설명 |
|---|---|
catalog <output> | 라이브러리 카탈로그 생성 (EPUB, CSV, 또는 OPDS) |
예제
라이브러리 연결 및 책 목록 보기
Calibre 라이브러리에 연결하고 책 목록을 확인합니다.
cli-anything-calibre library connect ~/Calibre\ Library
cli-anything-calibre books list
# 또는 JSON 출력
cli-anything-calibre --json books list --search "author:asimov"
검색 및 필터링
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"
메타데이터 편집
책의 메타데이터 필드를 설정합니다.
cli-anything-calibre meta set 42 title "New Title"
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,classic"
cli-anything-calibre meta set 42 rating 5
형식 변환
전자책 형식 간 변환을 수행합니다.
cli-anything-calibre formats convert 42 EPUB MOBI
cli-anything-calibre formats convert 42 EPUB PDF --output /tmp/book.pdf
장을 PDF로 내보내기
EPUB의 각 장을 개별 PDF 파일로 내보냅니다.
cli-anything-calibre books export-chapters 42 --to-dir ./pdfs
cli-anything-calibre books export-chapters 42 --to-dir ./pdfs --chapters 1-5
Calibre 쿼리 언어
books search 및 books list --search와 함께 사용됩니다:
author:asimov # 저자에 "asimov" 포함
title:"Foundation" # 제목 구문 일치
tags:fiction # 태그 일치
rating:>3 # 평점 3 초과
series:"Foundation" # 시리즈 일치
pubdate:[2020-01-01,2021-12-31] # 날짜 범위
identifiers:isbn:1234567890 # 특정 식별자
has:cover # 표지 이미지 있음
not:tags:fiction # 부정
author:asimov and tags:scifi # 부울 AND 연산
주요 메타데이터 필드
| 필드 | 타입 | 설명 |
|---|---|---|
title | text | 책 제목 |
authors | text | 저자 이름 (&로 구분) |
tags | text | 쉼표로 구분된 태그 |
series | text | 시리즈 이름 |
series_index | float | 시리즈 내 순서 |
rating | float | 평점 1-5 |
publisher | text | 출판사 이름 |
pubdate | datetime | 출판일 |
comments | text | 설명/코멘트 |
languages | text | 언어 코드 |
identifiers | text | ISBN, ASIN 등 (type:value) |
지원 형식
입력: EPUB, MOBI, AZW, AZW3, PDF, HTML, DOCX, ODT, FB2, TXT, RTF, LIT 등
출력 (변환): EPUB, MOBI, AZW3, PDF, HTML, DOCX, TXT 등
상태 관리
CLI는 다음을 통해 세션 상태를 유지합니다:
- 세션 파일:
~/.cli-anything-calibre/session.json - 라이브러리 경로 유지: 활성 라이브러리는 세션 간에 저장됨
- 환경 변수 오버라이드:
CALIBRE_LIBRARY환경 변수
출력 형식
모든 명령어는 이중 출력 모드를 지원합니다:
- 사람이 읽을 수 있는 (기본값): 표, 색상, 서식이 지정된 텍스트
- 기계가 읽을 수 있는 (
--json플래그): 에이전트용 구조화된 JSON 출력
# 사람용 출력
cli-anything-calibre books list
# 에이전트용 JSON 출력
cli-anything-calibre --json books list
AI 에이전트를 위한 안내
프로그래밍 방식으로 이 CLI를 사용할 때:
- 항상
--json플래그를 사용하여 파싱 가능한 출력을 얻으세요 - 반환 코드 확인 - 0은 성공, 0이 아닌 값은 오류
- stderr를 파싱하여 오류 메시지를 확인하세요
- 내보내기/변환 작업 후 출력 결과 확인
--library플래그 또는CALIBRE_LIBRARY환경 변수를 사용하여 라이브러리 경로를 지정하세요- 장 내보내기는 EPUB 형식 필요 - 필요한 경우 먼저 변환하세요
더 많은 정보
- 전체 문서: 패키지의 README.md 참조
- 아키텍처 SOP: agent-harness 디렉터리의 CALIBRE.md 참조
- 테스트 커버리지: tests 디렉터리의 test_core.py 및 test_full_e2e.py 참조
- 방법론: cli-anything-plugin의 HARNESS.md 참조
버전
1.0.0