제미나이(Gemini) CLI 사용법, GEMINI.md·MCP 세팅과 안티그래비티 전환 정리

아직도 블로그 글 하나를 따라 제미나이 CLI를 설치했다가, 로그인 단계에서 막혀 어디가 잘못됐는지 한참 찾고 계신가요? 2026년 6월에 이용 방식이 크게 바뀌어서, 그 전에 쓰인 안내대로 하면 개인 Google 계정으로는 더 이상 진행되지 않습니다.

제미나이(Gemini) CLI는 Google이 만든 오픈소스 코딩 에이전트로, 터미널에서 Gemini 모델에게 코드 읽기·수정·명령 실행을 맡깁니다. 이 글은 2026년 10월 기준으로 누가 어떤 도구를 써야 하는지, 설치와 로그인, GEMINI.md 작성법, settings.json의 MCP 연결과 승인 모드를 순서대로 정리하고, Claude Code·Codex CLI와의 차이를 비교표로 보여 줍니다. 마지막에는 다글로로 받아쓴 기획 회의를 GEMINI.md의 근거 자료로 쓰는 방법도 담았습니다.

제미나이 CLI 사용법, 2026년 10월 기준 먼저 알아둘 점

2026년 6월 18일부터 무료 계정과 Google AI Pro·Ultra 같은 개인 구독 사용자는 제미나이 CLI 대신 안티그래비티(Antigravity) CLI를 씁니다. 제미나이 CLI는 유료 API 키나 기업용 라이선스로 계속 쓸 수 있습니다.

Google은 2026년 5월 19일 공식 저장소 공지로 이 전환을 알렸습니다. 안티그래비티 CLI는 agy 명령으로 실행하는 새 터미널 에이전트이고, 스킬·훅·서브에이전트를 그대로 지원하며 기존 확장 프로그램은 "플러그인"이라는 이름으로 이어집니다. 제미나이 CLI 저장소는 Apache 2.0 오픈소스로 그대로 남습니다.

두 도구는 GEMINI.md 지침 파일을 똑같이 읽으므로, 아래에서 설명하는 지침 작성법은 어느 쪽을 쓰든 그대로 적용됩니다.

설치와 로그인, 어떤 명령을 쓰나요?

제미나이 CLI는 npm이나 Homebrew로 설치하고, 안티그래비티 CLI는 공식 설치 스크립트로 설치합니다. 설치 후 각각 gemini, agy를 실행해 로그인합니다.

• 제미나이 CLI: npm install -g @google/gemini-cli 또는 brew install gemini-cli로 설치합니다. 설치 없이 써 보려면 npx @google/gemini-cli를 실행합니다. Google AI Studio에서 발급한 유료 API 키를 GEMINI_API_KEY 환경변수에 넣은 뒤 gemini를 실행합니다.
• 안티그래비티 CLI: macOS·Linux는 curl -fsSL https://antigravity.google/cli/install.sh | bash, Windows PowerShell은 irm https://antigravity.google/cli/install.ps1 | iex로 설치합니다. agy --version으로 설치를 확인하고, 프로젝트 폴더에서 agy를 실행해 Google 계정으로 로그인합니다.

안티그래비티 CLI는 처음 실행할 때 기존 제미나이 CLI 설정을 찾아 무엇을 옮길지 체크리스트로 묻습니다. 확장 프로그램은 agy plugin import gemini로 가져올 수 있습니다. 남은 사용량은 /usage로 확인합니다.

GEMINI.md 작성법과 읽는 순서

GEMINI.md는 제미나이 CLI가 작업 전에 읽는 마크다운 지침 파일입니다. 프로젝트 규칙, 빌드·테스트 명령, 하지 말아야 할 일을 적어 두면 매번 채팅창에 설명할 필요가 없습니다.

제미나이 CLI는 아래 순서로 지침 파일을 찾아 이어 붙인 뒤 시스템 프롬프트에 넣습니다.

1. 전역: ~/.gemini/GEMINI.md에 모든 프로젝트에 공통인 습관을 적습니다.
2. 프로젝트와 상위 폴더: 지금 폴더부터 .git이 있는 프로젝트 루트까지 올라가며 GEMINI.md를 읽습니다.
3. 하위 폴더: 작업 폴더 아래 폴더의 GEMINI.md도 찾습니다. node_modules 같은 폴더는 건너뛰고, 기본 200개 폴더까지만 살핍니다.

지침이 길어지면 @docs/style.md처럼 다른 마크다운 파일을 불러오는 문법으로 나눠 씁니다. 실제로 어떤 내용이 읽혔는지는 대화 중 /memory show로 확인하고, 파일을 고친 뒤에는 /memory refresh로 다시 불러옵니다. Codex와 함께 쓴다면 settings.json의 context.fileName에 ["AGENTS.md", "GEMINI.md"]를 넣어 AGENTS.md 하나를 원본으로 둘 수 있습니다. 안티그래비티 CLI는 GEMINI.md와 AGENTS.md를 모두 읽습니다.

settings.json으로 MCP 연결하고 승인 모드 정하기

settings.json은 제미나이 CLI의 모델·도구·권한을 정하는 설정 파일입니다. 사용자 설정은 ~/.gemini/settings.json, 프로젝트 설정은 .gemini/settings.json에 두며 프로젝트 설정이 우선합니다.

MCP(Model Context Protocol)는 AI를 외부 서비스·도구에 연결하는 표준입니다. settings.json의 mcpServers 안에 서버 이름과 실행 명령을 적으면 됩니다.

"mcpServers": { "github": { "command": "npx", "args": ["-y", "서버 패키지 이름"] } }

• 서버 이름: 밑줄(_)을 쓰면 권한 규칙이 제대로 맞지 않을 수 있어 하이픈을 씁니다.
• 원격 서버: command 대신 url이나 httpUrl을 적습니다. 안티그래비티 CLI는 MCP를 별도 파일(전역 ~/.gemini/config/mcp_config.json, 프로젝트 .agents/mcp_config.json)에 두고, 원격 주소 키 이름도 serverUrl로 바꿔야 합니다.
• 토큰: 설정 파일에 직접 적지 말고 환경변수로 넘깁니다.

승인 모드는 --approval-mode 옵션이나 general.defaultApprovalMode 설정으로 고릅니다. default는 도구를 실행할 때마다 묻고, auto_edit는 파일 수정만 자동 승인하며, plan은 읽기만 합니다. 모든 작업을 자동 승인하는 yolo는 --yolo 옵션으로만 켤 수 있습니다. 처음에는 default로 시작하고, 격리가 필요하면 tools.sandbox에 docker 같은 샌드박스를 지정합니다.

Claude Code·Codex CLI와 비교하면?

네 도구는 지침 파일 이름과 이용 조건이 다를 뿐, 지침 파일·설정 파일·MCP로 하네스를 세팅한다는 구조는 같습니다. 이미 쓰는 AI 구독이 무엇인지에 따라 고르면 됩니다.

무료 사용량과 요금은 자주 바뀌므로 각 서비스의 공식 문서에서 다시 확인하세요. Codex 세팅은 코덱스 사용법 글에, 지침·도구·권한을 묶어 설계하는 개념은 하네스 엔지니어링 글에 정리해 두었습니다.

다글로로 받아쓴 기획 회의를 GEMINI.md 근거로 쓰기

좋은 GEMINI.md는 회의에서 정한 요구사항에서 나옵니다. 기획 회의를 다글로로 받아쓰면 화자가 구분된 원문과 요약이 남아, 지침과 작업 지시의 근거 자료로 바로 쓸 수 있습니다.

1. 참석자 동의를 받고 기획 회의를 녹음한 뒤 다글로에 올려 받아씁니다.
2. 같은 프로젝트의 회의 기록을 한 보드에 모으고, 보드챗에 "확정된 요구사항과 제약 조건만 목록으로 정리해 줘"라고 묻습니다.
3. 계속 지킬 규칙은 GEMINI.md에, 이번 작업에만 필요한 내용은 제미나이 CLI에 줄 작업 지시로 옮깁니다.

회의마다 같은 형식으로 정리하고 싶다면 그 요청을 다글로 '내 템플릿'에 저장해 두세요. 다글로가 프롬프트를 기억해 녹음이 끝날 때마다 그 형식으로 자동 요약합니다.

정리하면, 개인 계정이라면 안티그래비티 CLI로, 유료 API 키나 기업 라이선스가 있다면 제미나이 CLI로 시작하고, 어느 쪽이든 GEMINI.md에 규칙을 적고 MCP와 승인 모드를 정해 두면 같은 품질의 결과를 꾸준히 얻을 수 있습니다.

#제미나이CLI #GeminiCLI #제미나이CLI사용법 #안티그래비티CLI #GEMINImd #MCP #하네스엔지니어링 #다글로

👉 기획 회의 무료로 받아쓰기 시작하기