Code server에서 Gemini CLI사용법
2026년 현재, code-server(브라우저용 VS Code) 환경에서 Google의 공식 Gemini CLI(@google/gemini-cli)를 설치하고 사용하는 방법을 단계별로 설명해 드립니다.
Gemini CLI는 터미널에서 직접 AI와 대화하거나, 코드 분석, 문서 생성, MCP(Model Context Protocol)를 통한 도구 연결 등을 수행할 수 있는 강력한 도구입니다.
1. 사전 준비 (Prerequisites)
Gemini CLI를 설치하기 위해 다음이 설치되어 있어야 합니다. code-server 터미널에서 아래 명령어로 버전을 확인하세요.
- Node.js: v18 이상 (추천: v20+)
- npm: Node.js와 함께 설치됨
Bash
node -v
npm -v
2. Gemini CLI 설치하기
code-server 터미널에서 다음 명령어를 입력하여 전역(Global)으로 설치합니다.
Bash
# 전역 설치
sudo npm install -g @google/gemini-cli
# 설치 확인
gemini --version
Tip: 설치 없이 한 번만 실행해보고 싶다면
npx @google/gemini-cli를 사용할 수도 있습니다.
3. 인증 설정 (Authentication)
code-server는 원격 서버에서 동작하므로, 브라우저 팝업을 통한 로그인보다는 API Key를 사용하는 방식이 가장 확실하고 편리합니다.
1단계: API Key 발급
- Google AI Studio에 접속합니다.
- **”Get API key”**를 클릭하여 새로운 키를 생성하고 복사합니다.
2단계: 환경 변수 설정
터미널에서 매번 키를 입력하지 않도록 환경 변수에 등록합니다. (사용 중인 셸에 따라 .bashrc 또는 .zshrc 파일에 추가하세요.)
Bash
# .bashrc 파일 열기 (예시)
nano ~/.bashrc
# 파일 끝에 아래 내용 추가
export GEMINI_API_KEY="여러분의_API_키_입력"
# 변경사항 적용
source ~/.bashrc
4. Gemini CLI 사용법
이제 터미널에 gemini를 입력하여 대화형 모드를 시작할 수 있습니다.
주요 명령어 및 기능
| 명령어 | 설명 |
gemini | 대화형(Interactive) CLI 모드 시작 |
gemini "질문 내용" | 단발성 질문 및 답변 출력 |
/help | 사용 가능한 모든 명령어 확인 |
/clear | 현재 세션의 대화 내역 초기화 |
/mcp | MCP 서버 설정 및 도구 관리 |
/quit 또는 Ctrl+C | CLI 종료 |
활용 예시
- 파일 분석:
gemini "이 README.md 파일 내용을 요약해줘" - 코드 리뷰:
cat main.py | gemini "이 코드의 버그를 찾아줘" - 프로젝트 컨텍스트: Gemini CLI는 현재 작업 디렉토리의 파일을 인식할 수 있어, 프로젝트 전체 구조에 대한 질문도 가능합니다.
5. code-server(VS Code) 통합 기능
Gemini CLI 0.1.20 버전 이후부터는 IDE와의 연동 기능이 강화되었습니다. code-server 터미널에서 다음 명령어를 입력하면 현재 열려 있는 에디터와 더 긴밀하게 작동합니다.
Bash
# IDE 통합 활성화 (Diff 확인 및 파일 자동 수정 지원)
gemini /ide enable
이 기능을 활성화하면 Gemini가 제안한 코드 수정 사항을 에디터에서 바로 diff 형태로 확인하고 적용할 수 있습니다.
💡 유의사항
- 인터넷 연결: code-server가 구글 서버와 통신할 수 있는 환경이어야 합니다.
- 할당량(Quota): 무료 티어의 경우 분당/일일 호출 제한이 있으니 대규모 파일 분석 시 주의하세요.
다음 단계로 무엇을 도와드릴까요?
- “Gemini CLI에서 사용할 수 있는 MCP 서버 설정 방법을 알려드릴까요?”
- “환경 변수 설정 중 오류가 발생했나요?”
VS Code에서 **Gemini CLI (최신 Gemini 3 포함)**를 효과적으로 사용하는 방법은 크게 세 가지로 나뉩니다. 가장 강력한 방법은 터미널에서 실행하면서 VS Code의 편집 기능과 연동하는 컴패니언(Companion) 방식입니다.
1. 터미널 연동 (컴패니언 방식 – 추천)
Gemini CLI를 단순히 터미널에서 쓰는 것을 넘어, VS Code에서 선택한 코드를 인식하거나 변경 사항을 Diff(비교) 뷰로 바로 확인하고 적용할 수 있는 가장 진보된 방식입니다.
- 사전 준비: VS Code 내장 터미널을 열고 Gemini CLI를 최신 버전으로 업데이트합니다.
- 연동 설정: 터미널에 아래 명령어를 입력하여 컴패니언 확장 프로그램을 설치합니다.Bash
/ide install - 기능 활성화: 설치 후 터미널에서 다음 명령어로 연동을 활성화합니다.Bash
/ide enable - 주요 활용법:
- 코드 인식: 에디터에서 특정 코드를 블록 지정한 뒤 터미널에서
/explain이나 “이 코드 수정해줘”라고 요청하면 선택된 영역을 자동으로 인식합니다. - Diff 뷰 적용: Gemini가 제안한 수정 코드를 VS Code의 Diff 창에서 바로 확인하고
Accept버튼으로 즉시 반영할 수 있습니다.
- 코드 인식: 에디터에서 특정 코드를 블록 지정한 뒤 터미널에서
2. VS Code 태스크(Tasks)로 등록하기
터미널에 매번 명령어를 치는 게 번거롭다면, 특정 동작(예: 코드 설명, 버그 찾기)을 VS Code 단축키로 만들어 사용할 수 있습니다.
- 설정 방법:
Ctrl+Shift+P(또는Cmd+Shift+P) → Tasks: Configure Task 선택.tasks.json파일에 아래 내용을 추가합니다.
{ "label": "Gemini: Explain Code", "type": "shell", "command": "gemini explain \"${selectedText}\"", "presentation": { "reveal": "always", "panel": "shared" } } - 실행: 이제 코드를 선택하고
Run Task를 통해 Gemini CLI 기능을 즉시 실행할 수 있습니다.
3. Gemini 3 및 프리뷰 기능 활성화
Gemini 3 모델이나 에이전트 모드 기능을 사용하려면 설정 파일 수정이 필요할 수 있습니다.
- 설정 파일 생성: 프로젝트 루트에
.gemini/settings.json파일을 만듭니다. - 프리뷰 활성화: 아래 내용을 입력하여 최신 기능을 활성화합니다.JSON
{ "general": { "previewFeatures": true } } - 이 설정을 마치고 터미널에서
gemini를 실행하면 최신 모델 기반의 기능을 VS Code 환경에서 그대로 누릴 수 있습니다.
💡 팁: 더 쉬운 대안
CLI 조작보다 GUI가 편하다면, 마켓플레이스에서 공식 “Gemini Code Assist” 확장 프로그램을 설치하는 것도 방법입니다. 이는 CLI와 같은 엔진을 쓰면서도 채팅 패널과 인라인 코드 추천 기능을 제공합니다.
Gemini CLI VSCode Setup 가이드
이 영상은 VS Code 내장 터미널에서 Gemini CLI를 설치하고 실제 코드와 연동하여 사용하는 과정을 단계별로 보여주어 이해를 돕습니다.
