목적별 가이드
| 하려는 일 | 가이드 |
|---|---|
| 무료 한도와 로그인·API 키의 비용 구분하기 | 인증 방식별 한도·요금 |
| 외부 도구를 추가하고 연결 상태 확인하기 | MCP 설정 |
| 명령이 없거나 로그인·429 단계에서 막힘 | 실행·인증 오류 확인 |
| 웹에서 문장을 입력하며 시작하기 | Gemini 웹앱 사용법 |
| Node.js 실행 환경부터 준비하기 | Node.js 설치·LTS·npm |
Gemini 웹앱·CLI·Code Assist 구분하기
| 원하는 작업 | 시작할 곳 |
|---|---|
| 웹에서 대화·문서·이미지 활용 | Gemini 웹앱 |
| 현재 프로젝트를 터미널에서 설명·수정 | Gemini CLI |
| IDE의 코드 보조 기능 사용 | Gemini Code Assist의 해당 확장 |
VS Code의 터미널 안에서 gemini를 실행하는 것도 CLI 사용입니다. 확장을 설치해 IDE 기능을 쓰는 것과 시작 경로는 다릅니다. 또한 Gemini CLI는 대화 답변뿐 아니라 파일·명령 도구를 사용할 수 있으므로 현재 작업 폴더와 요청할 변경 범위를 먼저 정해야 합니다.
Node와 설치 버전 확인하기
공식 설치 문서는 런타임으로 Node.js 20 이상, 권장 환경으로 Windows 11 24H2 이상과 PowerShell 등을 안내합니다. 최소 엔진 조건을 만족하는 것과 현재 지원 중인 Node 버전을 쓰는 것은 별개입니다. Node 공식 릴리스 목록에서 지원 중인 LTS를 고르세요. 확인일에는 Node 24가 LTS이고 Node 20은 지원 종료 상태입니다.
PowerShell에서 먼저 확인합니다.
node --version
npm.cmd --version
Node가 없다면 Node.js 공식 다운로드에서 Windows용 LTS 설치 경로를 확인합니다. 이미 다른 프로젝트가 Node를 사용한다면 그 환경부터 확인하고 버전을 바꾸세요.
확인일의 npm 배포본은 0.65.0이지만 공식 안정판 안내 페이지는 0.64.0을 표시했습니다. 아래는 확인한 배포 버전을 고정한 예시이며, 나중에 따라 한다면 공식 설치 안내와 현재 배포판을 다시 확인해야 합니다.
npm.cmd install -g @google/gemini-cli@0.65.0
gemini.cmd --version
Windows에서는 npm이 제공하는 .cmd 실행 파일로 호출할 수 있습니다. 명령을 찾지 못하거나 PowerShell 스크립트 관련 오류가 뜨면 명령·설치 경로 확인으로 이어가세요. 실행 정책부터 일괄 변경하는 방식으로 시작하지 않습니다.
새 작업 폴더에서 로그인하기
아래 명령은 본인이 사용할 작업 위치에서 실행합니다. 같은 이름의 폴더가 이미 있다면 새 이름을 정하고 기존 파일과 섞지 마세요.
New-Item -ItemType Directory -Path .\bmt-cli-demo
Set-Location .\bmt-cli-demo
gemini.cmd
일반적인 개인 계정 시작은 CLI의 Sign in with Google 선택과 브라우저 로그인 절차입니다. Google AI Pro·Ultra를 사용한다면 구독한 계정과 같은 계정인지 확인하세요. 조직·회사·학교 계정이나 Code Assist 라이선스는 Cloud 프로젝트·자격 조건이 다를 수 있습니다.
API 키·Vertex AI도 지원하지만 무료 범위와 청구 경로가 같지 않습니다. 어떤 인증을 골라야 할지 모르겠다면 인증별 한도·요금부터 확인하세요. 기존 API 키나 Cloud 설정을 무조건 지울 필요는 없습니다.
첫 코드와 확인 기준 준비하기
편집기로 새 폴더 안에 total.mjs를 만듭니다. 아래 시작 코드는 수량을 반영하지 않는 간단한 예시입니다.
export function total(items) {
return items.reduce((sum, item) => sum + item.price, 0);
}
같은 폴더의 check.mjs에는 원하는 결과를 확인하는 코드를 넣습니다.
import assert from 'node:assert/strict';
import { total } from './total.mjs';
const items = [
{ price: 1200, quantity: 2 },
{ price: 800, quantity: 1 }
];
assert.equal(total(items), 3200);
console.log('total: OK');
PowerShell에서 실행하면 시작 코드가 원하는 결과와 다른지 확인할 수 있습니다.
node .\check.mjs
시작 코드는 2,000을 계산하지만 수량을 반영한 기준값은 3,200입니다. 이 차이는 자체 Node 검수로 확인한 예제이며 Gemini가 코드를 수정한 결과는 아닙니다.
설명부터 요청하고 변경 내용 확인하기
Gemini CLI의 입력창에서는 먼저 읽기와 설명을 요청합니다.
현재 폴더의 total.mjs와 check.mjs를 읽고,
합계 확인이 실패하는 이유를 설명해줘.
아직 파일은 수정하지 마.
원인을 확인한 뒤 수정 범위를 정합니다.
total.mjs만 수정해서 각 항목의 price와 quantity를 곱해 합산해줘.
check.mjs의 기대값과 입력은 유지해줘.
새 패키지를 설치하거나 다른 파일을 바꾸지 말고,
변경 내용과 확인 방법을 알려줘.
CLI가 파일 변경이나 명령 실행 승인을 요청하면 대상·내용을 확인합니다. 자동 승인 여부는 현재 설정에 따라 다를 수 있으므로 요청문만으로 도구 권한이 제한됐다고 판단하지 마세요.
이 예제에서 확인할 핵심은 합산 항목에 item.price * item.quantity가 반영됐는지입니다. 변경 뒤 PowerShell에서 node .\check.mjs를 다시 실행해 성공 메시지를 확인합니다. Git으로 관리하는 폴더라면 diff도 함께 보고, 새 패키지나 무관한 파일이 추가되지 않았는지 확인하세요.
폴더 신뢰와 프로젝트 지침 이해하기
공식 문서의 Trusted Folders는 기본적으로 꺼져 있는 선택 기능입니다. 켜진 환경에서 신뢰 안내가 나오면 현재 폴더와 상위 폴더를 신뢰하는 선택의 범위가 다르다는 점을 확인하세요. 모든 최초 실행에 같은 창이 나타나는 것은 아닙니다.
GEMINI.md는 프로젝트에 계속 적용할 작업 지침을 전달하는 파일입니다. 예를 들어 ‘계산 코드는 단위를 명시하고, 수정 뒤 기존 확인 명령을 실행한다’처럼 프로젝트의 기준을 적을 수 있습니다. 이미 있는 사용자·프로젝트 지침을 덮어쓰지는 마세요.
.geminiignore는 컨텍스트에서 제외할 파일을 정하는 기능입니다. 비밀번호 보관이나 접근 권한을 대신하는 장치로 여기지 말고, 첫 연습은 개인 자료가 없는 새 폴더에서 진행하세요. 필요한 외부 도구는 MCP 가이드에서 별도로 추가합니다.
종료·업데이트와 다음 작업
CLI 입력창의 /quit 또는 /exit로 종료할 수 있습니다. 일반 종료와 기록 삭제 옵션은 다르므로, 첫 사용에 삭제 옵션까지 붙일 필요는 없습니다.
나중에 업데이트할 때는 현재 버전·공식 배포판을 확인한 뒤 설치 때 사용한 방식으로 갱신합니다. npm 설치와 다른 설치 관리자를 섞지 말고, 문제가 생기면 실행·로그인 오류에서 실패 단계를 먼저 구분하세요.
참고자료
- Gemini CLI 설치·실행 안내 — 준비 조건·설치 방식·배포판
- Gemini CLI 인증 안내 — 개인·조직·API 키·Vertex AI 선택
- Gemini CLI 첫 사용 — 작업 시작·파일 설명·변경 승인 흐름