마이그레이션 가이드
이전 버전에서 최신 Gemini CLI로 업그레이드
마이그레이션 개요
이 가이드는 Gemini CLI의 이전 버전에서 최신 버전으로 마이그레이션하는 데 도움을 줍니다. 주요 변경사항, 구성 업데이트를 다루고 원활한 전환을 위한 단계별 지침을 제공합니다.
버전 호환성 매트릭스
현재 버전에 적용되는 마이그레이션 경로를 확인하세요
v2.0.0의 주요 변경사항
기존 설정에 영향을 줄 수 있는 중요한 변경사항
구성 파일 형식
더 나은 가독성과 주석 지원을 위해 구성 파일 형식이 JSON에서 YAML로 변경되었습니다.
이전 (v1.x)
{
"api_key": "your-key",
"model": "gemini-pro"
}이후 (v2.0)
api_key: your-key
model: gemini-pro
# 이제 주석이 지원됩니다!명령어 구조 변경
일관성을 위해 일부 명령어가 이름이 변경되거나 재구성되었습니다.
명령어 변경
gemini chatgemini askgemini generategemini creategemini config showgemini config listAPI 키 관리
API 키는 이제 암호화를 통해 더 안전한 형식으로 저장됩니다.
기존 API 키는 첫 실행 시 자동으로 마이그레이션됩니다
단계별 마이그레이션
Gemini CLI v2.0.0으로 마이그레이션하려면 다음 단계를 따르세요
구성 백업
마이그레이션을 시작하기 전에 현재 구성의 백업을 만드세요.
명령어:
gemini config list > gemini-config-backup.txtcp ~/.gemini/config.json ~/.gemini/config.json.backup필요한 경우 설정을 복원할 수 있도록 보장합니다.
Gemini CLI 업데이트
Gemini CLI의 최신 버전을 설치하세요.
명령어:
npm update -g @google/generative-ai-cli검증:
gemini --version마이그레이션 도구 실행
내장 마이그레이션 도구를 사용하여 구성을 업데이트하세요.
명령어:
gemini config migrate구성이 자동으로 새 형식으로 변환됩니다.
구성 확인
구성이 올바르게 마이그레이션되었는지 확인하세요.
명령어:
gemini config listgemini ask "안녕하세요, 마이그레이션 테스트"모든 설정이 보존되고 CLI가 예상대로 작동하는지 확인하세요.
스크립트와 별칭 업데이트
이전 명령어 구문을 사용하는 스크립트나 별칭을 업데이트하세요.
필요한 특정 업데이트는 위의 명령어 변경 섹션을 참조하세요.
마이그레이션 문제 해결
일반적인 문제와 해결책
구성 마이그레이션 실패
증상:
- 오류: 구성을 마이그레이션할 수 없음
- 구성 파일을 찾을 수 없음
해결책:
- ~/.gemini 디렉토리에 쓰기 권한이 있는지 확인하세요
- 이전 구성 파일이 존재하는지 확인: ls ~/.gemini/
- 수동 마이그레이션 시도: gemini config migrate --force
마이그레이션 후 명령어가 작동하지 않음
증상:
- 명령어를 찾을 수 없음 오류
- 예상치 못한 동작
해결책:
- 셸 캐시 지우기: hash -r
- 터미널 세션 재시작
- 문서에서 새로운 명령어 구문 확인
API 키가 작동하지 않음
증상:
- 인증 오류
- 유효하지 않은 API 키 메시지
해결책:
- API 키 재설정: gemini config set api-key YOUR_KEY
- 키가 올바른지 확인: gemini config get api-key
- Google AI Studio에서 API 키 권한 확인
롤백 지침
필요한 경우 이전 버전으로 되돌리는 방법
⚠️ 정상적인 작동을 방해하는 심각한 문제가 발생한 경우에만 롤백을 사용하세요.
- 1
현재 버전 제거: npm uninstall -g @google/generative-ai-cli - 2
이전 버전 설치: npm install -g @google/generative-ai-cli@1.9.0 - 3
구성 복원: cp ~/.gemini/config.json.backup ~/.gemini/config.json - 4
롤백 확인: gemini --version
마이그레이션 후 단계
성공적인 마이그레이션 후 권장 작업
문서 업데이트
중간새로운 명령어 구문을 반영하도록 내부 문서나 팀 가이드를 업데이트하세요.
자동화 스크립트 테스트
높음자동화된 스크립트와 CI/CD 파이프라인을 실행하여 새 버전에서 작동하는지 확인하세요.
백업 정리
낮음모든 것이 작동하는 것을 확인한 후 백업 파일을 제거할 수 있습니다.