GCP

Gemini CLI 완벽 가이드: 설치부터 인증, Google Cloud 프로젝트 설정까지

dma-ai 2025. 7. 1. 10:35
728x90

Gemini CLI 완벽 가이드: 설치부터 인증, Google Cloud 프로젝트 설정까지

이 글은 Gemini CLI를 처음 접하는 개발자와 Google Workspace 사용자, 그리고 구글 AI 서비스 연동을 위한 인증 및 프로젝트 설정이 필요한 분들을 위해 설치, 인증, Google Cloud 프로젝트 생성, Workspace 환경 설정, Node.js 설치 확인까지 모든 과정을 단계별로 정리한 메뉴얼입니다.

1. Gemini CLI란?

Gemini CLI는 구글이 제공하는 오픈소스 AI 에이전트로, 터미널에서 Gemini 2.5 Pro 모델을 무료(일 1,000회, 분당 60회 요청)로 사용할 수 있는 도구입니다. 최대 100만 토큰의 대규모 컨텍스트를 지원하며, 코드 생성, 요약, 리팩터링, 문서화 등 다양한 개발 업무를 자동화할 수 있습니다.

2. 사전 준비 사항

  • Google 계정(개인 또는 Workspace)
  • Node.js 18 이상 설치
    설치 여부는 아래 명령어로 확인:버전 정보가 출력되면 정상 설치된 것입니다.
  •  
  •  
    bash
    node -v npm -v
  • Google Cloud 프로젝트
    (Workspace 사용자 및 특정 인증 상황에서 필요)

3. Gemini CLI 설치 방법

3-1. 간단 설치(권장)

  • 별도 설치 없이 바로 실행 가능

3-2. 전역 설치

 
bash
npm install -g @google/gemini-cli
  • 설치 후 gemini 명령어로 실행

4. Gemini CLI 인증(로그인) 설정

Gemini CLI는 Google AI 서비스와 연동하기 위해 인증이 필요합니다.
아래 세 가지 방법 중 하나를 선택해 인증을 진행하세요.

4-1. Google 계정 로그인(개인 사용자)

  • 최초 실행 시 웹 브라우저에서 Google 계정으로 로그인
  • 인증 정보가 로컬에 저장되어 이후에는 인증 생략 가능
  • Workspace 계정 등은 추가 설정 필요

4-2. Gemini API 키 사용

  • Google AI Studio에서 API 키 발급
  • 환경변수 등록
  •  
    bash
    export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
  • 반복 사용 시 ~/.bashrc 등에 추가
  •  
    bash
    echo 'export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"' >> ~/.bashrc source ~/.bashrc

4-3. Vertex AI 인증

  • Google Cloud 프로젝트 및 Vertex AI API 활성화 필요
  • Application Default Credentials 설정
  •  
    bash
    gcloud auth application-default login
  • 환경변수 등록
  •  
    bash
    export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID" export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION" export GOOGLE_GENAI_USE_VERTEXAI=true
  • 반복 사용 시 ~/.bashrc 등에 추가

5. Google Workspace 사용자 인증 및 설정

Workspace 계정(회사/학교 계정)은 개인 계정과 달리 추가 인증 및 환경변수 설정이 필수입니다.

5-1. 인증 절차

  1. Google Cloud Console에서 새 프로젝트 생성
  2. Gemini for Cloud API 활성화
  3. IAM 권한 부여
  4. 환경변수 등록반복 사용 시:
  5.  
    bash
    echo 'export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"' >> ~/.bashrc source ~/.bashrc
  6.  
    bash
    export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"

5-2. 인증 흐름 요약

계정 유형인증 방식추가 설정 필요 여부
개인 Google 간단한 웹 로그인 불필요
Workspace Google Cloud 프로젝트 필요 필요 (환경변수 등)
엔터프라이즈 라이선스 또는 API 키 필요 필요 (별도 안내 참고)
 

6. Google Cloud 프로젝트 생성 및 설정 방법

  1. Google Cloud Console 접속 및 로그인
  2. 프로젝트 만들기
    • 상단의 프로젝트 선택 → "프로젝트 만들기" 클릭
    • 프로젝트 이름, ID 지정(생성 후 ID 변경 불가)
    • 조직/위치 선택(Workspace는 조직 자동 지정)
    • 필요시 결제 계정 연결
  3. API 및 서비스 > 라이브러리
    • Gemini API, Vertex AI API 등 필요한 API 활성화
  4. IAM 권한 설정
    • 프로젝트의 IAM에서 필요한 사용자/서비스 계정 권한 부여
  5. 프로젝트 ID 환경변수 등록반복 사용 시:
  6.  
    bash
    echo 'export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"' >> ~/.bashrc source ~/.bashrc
  7.  
    bash
    export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"

7. Gemini CLI 사용법

  • 터미널에서 gemini 명령어 실행
  • 자연어 또는 코드 프롬프트 입력
    • 예:
    •  
      text
      FAQ.md를 기반으로 디스코드 봇 만들어줘
  • 멀티모달 입력(PDF, 이미지 등) 지원, Google 검색 도구 내장

8. 문제 해결 및 참고

  • 인증/설치 오류 시 환경변수, 권한, API 활성화 여부를 반드시 확인
  • 공식 GitHub 저장소 및 Google Cloud 문서 참고
728x90
저작자표시 변경금지 (새창열림)