gemini-ocr-cli
사용 시기
이 스킬은 로컬 터미널 워크플로에서 고품질 OCR이 필요하고, 호스트 모델 자체의 OCR이 충분히 신뢰할 수 없을 때 사용하십시오.
특히 에이전트가 다음 작업을 수행해야 할 때 사용하십시오:
- 로컬 이미지를 충실한 Markdown으로 OCR,
- 로컬 PDF를 충실한 Markdown으로 OCR,
- 페이지 구조, 표, 레이블을 최대한 보존,
- 임시 멀티모달 프롬프팅 대신 결정론적 CLI를 통해 작업.
사전 조건
- CLI가
PATH에 전역적으로 설치되어 있는지 확인하십시오:- 권장:
npm install -g @codecell-germany/gemini-ocr-agent-skill - 확인:
gemini-ocr --help
- 권장:
- 필요한 경우 스킬 페이로드를 설치하십시오:
gemini-ocr-skill install --force
- 필수 비밀 환경 변수:
GEMINI_API_KEY=<api-key>
- 지원되는 별칭 비밀 환경 변수:
GOOGLE_GENERATIVE_AI_API_KEY=<api-key>
- 지원되는 대체 비밀 환경 변수:
GOOGLE_API_KEY=<api-key>
- 선택적 모델 재정의:
GEMINI_OCR_MODEL=gemini-3-flash-preview
핵심 워크플로
- 공개 CLI 인터페이스를 확인하십시오:
gemini-ocr --help
- 환경을 검증하십시오:
gemini-ocr doctor --json
- 환경이 불완전하면 설정 가이드를 출력하십시오:
gemini-ocr setup --language engemini-ocr setup --language de
- 지원되는 API 키 환경 변수 중 하나를 내보내고 다시 실행하십시오:
gemini-ocr doctor --json
- 이미지를 OCR하십시오:
gemini-ocr scan-image /absolute/path/to/image.png
- PDF를 OCR하십시오:
gemini-ocr scan-pdf /absolute/path/to/document.pdf
- 호출 워크플로가 구조화된 OCR 객체를 필요로 할 때만 JSON 출력을 사용하십시오:
gemini-ocr scan-pdf /absolute/path/to/document.pdf --format json
가드레일
- 공개 CLI 이름
gemini-ocr와gemini-ocr-skill을 사용하십시오. node dist/index.js와 같은 저장소 로컬 진입점으로 제품 인터페이스를 우회하지 마십시오.~/.codex/tools/gemini-ocr-cli/dist/index.js와 같은 숨겨진 설치 런타임 경로를 호출하지 마십시오.- 입력은 원격 처리를 위해 Gemini로 전송됩니다. 해당 원격 처리 정책이 허용되지 않는 경우 완전히 로컬로 유지해야 하는 문서에는 이 도구를 사용하지 마십시오.
- 기본 출력은 stdout의 Markdown입니다.
- 진단 및 경고는 stderr에 속합니다.
--format json은 기계가 읽을 수 있는 이스케이프 해치입니다.--pdf-mode auto는pdftoppm을 사용할 수 있을 때 실패한 네이티브 PDF 요청을 래스터 OCR로 재시도할 수 있습니다.--pdf-mode raster는pdftoppm이 필요합니다.- API 키는 셸 환경에 남아 있습니다. 프롬프트, 티켓, 스크린샷 또는 채팅에 붙여넣지 마십시오.
- 새 셸 또는 환경에서 첫 번째 실제 OCR 실행 전에
doctor를 선호하십시오.
참고 자료
- 주요 개요:
references/overview.md - 에이전트 온보딩:
references/agent-onboarding.md - OCR 첫 실행:
references/ocr-first-run.md - 명령어 치트 시트:
references/command-cheatsheet.md - 아키텍처:
knowledge/ARCHITECTURE.md - 릴리스 체크리스트:
knowledge/RELEASE_CHECKLIST.md