> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gravitex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Gemini CLI

> GravitexAI를 통해 Gemini CLI로 AI 지원 코딩: 코드 생성, 코드 리뷰, Q&A 등

## 1. 개요

**Gemini CLI**는 Google의 공식 명령줄 AI 코딩 도구로, 터미널에서 Gemini 모델과 직접 상호작용할 수 있습니다. **GravitexAI**를 gateway로 사용하면 다음을 할 수 있습니다:

<CardGroup cols={2}>
  <Card title="터미널 네이티브" icon="terminal">
    셸에서 Gemini 3.5 / 3.1 / 2.5 모델 직접 호출
  </Card>

  <Card title="AI 지원 코딩" icon="code">
    코드 생성, 리뷰 및 단위 테스트 자동화
  </Card>

  <Card title="스마트 Q&A" icon="message-question">
    기술 질문, 아키텍처 설계 및 디버깅
  </Card>

  <Card title="문서 생성" icon="file-lines">
    README, API 문서 및 JSDoc 주석 자동 생성
  </Card>
</CardGroup>

<Info>
  **GravitexAI**를 gateway로 사용하면 최적화된 연결, 통합 API key 관리, 단일 계정으로 Claude, GPT, Gemini 원스톱 액세스를 제공합니다.
</Info>

## 2. 사전 요구사항

* **Node.js** ≥ 18.0.0
* **npm** 또는 **yarn**
* [GravitexAI 콘솔](https://maas.gravitex.ai/#/keys)의 API key (형식 `sk-xxxxxxxxxx`)

## 3. 빠른 시작

### 1단계 — Gemini CLI 설치

<CodeGroup>
  ```bash npm theme={null}
  node --version  # must be >= 18

  npm install -g @google/gemini-cli

  gemini --version
  ```

  ```bash yarn theme={null}
  node --version  # must be >= 18

  yarn global add @google/gemini-cli

  gemini --version
  ```
</CodeGroup>

### 2단계 — GravitexAI API key 발급

<Steps>
  <Step title="GravitexAI 로그인">
    [maas.gravitex.ai](https://maas.gravitex.ai)에서 회원가입 또는 로그인합니다.
  </Step>

  <Step title="API key 생성">
    [API Keys](https://maas.gravitex.ai/#/keys) 페이지를 열고 "Create new token"을 클릭합니다.
  </Step>

  <Step title="키 복사">
    생성된 키(형식: `sk-xxxxxxxxxx`)를 복사하여 안전하게 보관합니다.
  </Step>
</Steps>

### 3단계 — 환경 변수 설정

<Warning>
  **중요**: `GOOGLE_GEMINI_BASE_URL`은 `https://api.gravitex.ai`로 설정해야 합니다. **`/v1`, `/gemini` 또는 기타 경로를 붙이지 마세요** — 연결이 깨집니다.
</Warning>

<Tabs>
  <Tab title="Zsh (macOS / Linux)">
    ```bash theme={null}
    # Edit your .zshrc
    nano ~/.zshrc

    # Add these environment variables
    export GOOGLE_GEMINI_BASE_URL="https://api.gravitex.ai"
    export GEMINI_API_KEY="sk-your-gravitex-key"  # replace with your GravitexAI key

    # Reload
    source ~/.zshrc
    ```
  </Tab>

  <Tab title="Bash (Linux)">
    ```bash theme={null}
    nano ~/.bashrc

    export GOOGLE_GEMINI_BASE_URL="https://api.gravitex.ai"
    export GEMINI_API_KEY="sk-your-gravitex-key"

    source ~/.bashrc
    ```
  </Tab>

  <Tab title="PowerShell (Windows)">
    ```powershell theme={null}
    # Temporary (current session)
    $env:GOOGLE_GEMINI_BASE_URL="https://api.gravitex.ai"
    $env:GEMINI_API_KEY="sk-your-gravitex-key"

    # Persistent (recommended)
    [System.Environment]::SetEnvironmentVariable('GOOGLE_GEMINI_BASE_URL', 'https://api.gravitex.ai', 'User')
    [System.Environment]::SetEnvironmentVariable('GEMINI_API_KEY', 'sk-your-gravitex-key', 'User')
    ```
  </Tab>

  <Tab title="CMD (Windows)">
    ```cmd theme={null}
    :: Temporary
    set GOOGLE_GEMINI_BASE_URL=https://api.gravitex.ai
    set GEMINI_API_KEY=sk-your-gravitex-key

    :: Persistent (needs admin)
    setx GOOGLE_GEMINI_BASE_URL "https://api.gravitex.ai"
    setx GEMINI_API_KEY "sk-your-gravitex-key"
    ```
  </Tab>
</Tabs>

### 4단계 — 초기화 및 테스트

<Steps>
  <Step title="CLI 시작">
    ```bash theme={null}
    gemini
    ```
  </Step>

  <Step title="최초 인증">
    대화형 UI에서 입력:

    ```
    /auth
    ```

    \*\*Gemini API Key (AI Studio)\*\*를 선택합니다.
  </Step>

  <Step title="연결 테스트">
    ```bash theme={null}
    # Simple test
    gemini "Hello, is the connection working?"

    # Coding test
    gemini "Explain how to use React Hooks"
    gemini "Write a Python function that computes Fibonacci numbers"
    ```
  </Step>
</Steps>

## 4. 추천 모델 (GravitexAI 경유)

GravitexAI는 최신 Gemini 제품군을 제공합니다. CLI에서 모두 호출 가능:

### Gemini 3.x 시리즈 (권장)

| Model ID                           | Best for          | Notes               |
| ---------------------------------- | ----------------- | ------------------- |
| **gemini-3.5-flash** ⭐             | 고처리량 채팅, 저지연 도구   | 최신 빠른 변형, 클래스 최고 속도 |
| **gemini-3.1-pro-preview**         | 심층 추론, 고품질 코드 생성  | 차세대 핵심 모델           |
| **gemini-3.1-flash-lite-preview**  | 고동시성, 배치 작업       | 최고 가성비 빠른 티어        |
| **gemini-3.1-flash-image-preview** | 이미지 이해 / 텍스트-이미지  | 멀티모달 강화             |
| **gemini-3-pro-image-preview**     | 고품질 텍스트-이미지       | 이미지 중심 변형           |
| **gemini-3-flash-preview**         | 다중 턴 채팅, tool use | 속도와 품질 균형           |

<Info>
  **권장 기본값**:

  * 복잡한 코딩 / 아키텍처: **gemini-3.1-pro-preview**
  * 일상 코딩 및 Q\&A: **gemini-3.5-flash**
  * 배치 / 고빈도: **gemini-3.1-flash-lite-preview**
</Info>

전체 카탈로그는 [GravitexAI 모델 목록](https://maas.gravitex.ai/#/models)을 참조하세요.

## 5. 핵심 기능

### 5.1 코드 생성

<Tabs>
  <Tab title="Function">
    ```bash theme={null}
    gemini "Write a quicksort algorithm in Python with detailed comments"
    ```

    **Sample output**:

    ```python theme={null}
    def quick_sort(arr):
        """
        Quicksort
        Time:  O(n log n) avg, O(n^2) worst
        Space: O(log n)
        """
        if len(arr) <= 1:
            return arr

        pivot = arr[len(arr) // 2]
        left = [x for x in arr if x < pivot]
        middle = [x for x in arr if x == pivot]
        right = [x for x in arr if x > pivot]

        return quick_sort(left) + middle + quick_sort(right)
    ```
  </Tab>

  <Tab title="Project scaffold">
    ```bash theme={null}
    gemini "Create an Express.js REST API project structure with auth and database config"
    ```
  </Tab>

  <Tab title="Unit tests">
    ```bash theme={null}
    gemini "Write Jest unit tests for this function:
    function fibonacci(n) {
      if (n <= 1) return n;
      return fibonacci(n - 1) + fibonacci(n - 2);
    }"
    ```
  </Tab>
</Tabs>

### 5.2 코드 리뷰

```bash theme={null}
# Performance / bugs
gemini "Review this code for performance issues and potential bugs:
[paste your code]"

# Security audit
gemini "Audit this code for security vulnerabilities, especially SQL injection and XSS"

# Best practices
gemini "What can be improved in this React component? Does it follow best practices?"
```

### 5.3 기술 Q\&A

```bash theme={null}
gemini "Explain JavaScript closures with real-world use cases"
gemini "Why is my Promise not resolving correctly?"
gemini "Compare microservices vs. monolithic architecture pros and cons"
```

### 5.4 문서 생성

```bash theme={null}
gemini "Generate a professional README.md for my Node.js library, including install, usage and API docs"
gemini "Generate OpenAPI 3.0 spec for this REST endpoint"
gemini "Add detailed JSDoc comments to the following code"
```

## 6. 대화형 명령어

| Command  | Description | Example                         |
| -------- | ----------- | ------------------------------- |
| `/auth`  | 재인증         | `/auth`                         |
| `/model` | 모델 전환       | `/model gemini-3.1-pro-preview` |
| `/clear` | 대화 초기화      | `/clear`                        |
| `/help`  | 도움말 표시      | `/help`                         |
| `/exit`  | CLI 종료      | `/exit` or `Ctrl+C`             |
| `/save`  | 대화를 파일로 저장  | `/save conversation.txt`        |

<Tip>
  **모델 전환**: 대화형 `/model` 사용, 또는 `--model`로 지정:

  ```bash theme={null}
  gemini --model gemini-3.1-pro-preview "your question"
  gemini --model gemini-3.5-flash "quick test"
  ```
</Tip>

## 7. 고급 사용

### 7.1 GitHub Actions (자동 리뷰)

```yaml theme={null}
name: Gemini Code Review
on:
  pull_request:
    branches: [ main ]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Install Gemini CLI
        run: npm install -g @google/gemini-cli

      - name: Run Code Review
        env:
          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
          GOOGLE_GEMINI_BASE_URL: https://api.gravitex.ai
        run: |
          gemini "Review this Pull Request for quality, security and performance:
          $(git diff origin/main...HEAD)"
```

### 7.2 배치 스크립트

```bash theme={null}
#!/bin/bash

# Batch code review
for file in src/**/*.js; do
  echo "Reviewing $file..."
  gemini "Review code quality of $file" < "$file"
done

# Generate project doc outline
gemini "Generate a technical doc outline for the whole project" < README.md
```

## 8. FAQ

<AccordionGroup>
  <Accordion title="연결 또는 인증 실패?">
    **체크리스트**:

    1. **환경 변수가 올바른가?**

       ```bash theme={null}
       echo $GOOGLE_GEMINI_BASE_URL
       echo $GEMINI_API_KEY
       ```

       예상값:

       * `GOOGLE_GEMINI_BASE_URL`: `https://api.gravitex.ai` (**`/v1` 또는 기타 경로 없음**)
       * `GEMINI_API_KEY`: 전체 `sk-…` 키

    2. **환경 변수 다시 로드**:
       ```bash theme={null}
       source ~/.zshrc  # or source ~/.bashrc
       ```

    3. **터미널 재시작**: 터미널 창을 닫고 다시 엽니다.

    4. [GravitexAI 콘솔](https://maas.gravitex.ai/#/keys)에서 **키 확인** — 활성 상태 및 잔액 확인.
  </Accordion>

  <Accordion title="Gemini 모델을 전환하려면?">
    **옵션 A — 대화형 `/model`**:

    ```
    /model gemini-3.1-pro-preview
    /model gemini-3.5-flash
    ```

    **옵션 B — CLI 플래그**:

    ```bash theme={null}
    gemini --model gemini-3.1-pro-preview "your question"
    gemini --model gemini-3.5-flash "quick test"
    ```
  </Accordion>

  <Accordion title="대화 기록을 저장하려면?">
    **방법 1**: `/save` 사용

    ```
    /save conversation-2025-01-01.txt
    ```

    **방법 2**: 셸 리다이렉션

    ```bash theme={null}
    gemini "your question" > output.txt
    gemini "your question" | tee output.txt   # show and save
    ```
  </Accordion>

  <Accordion title="Node.js 버전이 너무 낮나요?">
    **nvm**으로 Node 관리:

    ```bash theme={null}
    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

    nvm install 18
    nvm use 18
    nvm alias default 18

    node --version
    ```
  </Accordion>

  <Accordion title="응답이 느린 이유는?">
    가능한 원인 및 해결:

    1. **네트워크**: GravitexAI는 최적화된 경로 제공; [콘솔](https://maas.gravitex.ai)에서 상태 확인.
    2. **모델 선택**: 가장 빠른 응답을 위해 `gemini-3.5-flash` 또는 `gemini-3.1-flash-lite-preview` 사용.
    3. **토큰 크기**: 요청 복잡도 및 컨텍스트 길이 줄이기.

    **벤치마크**:

    ```bash theme={null}
    time gemini --model gemini-3.5-flash "Hello"
    ```
  </Accordion>

  <Accordion title="Windows에서 사용하려면?">
    **PowerShell (권장)**:

    1. [nodejs.org](https://nodejs.org/)에서 Node.js 설치
    2. **관리자** 권한으로 PowerShell 열기
    3. 환경 변수 설정:
       ```powershell theme={null}
       [System.Environment]::SetEnvironmentVariable('GOOGLE_GEMINI_BASE_URL', 'https://api.gravitex.ai', 'User')
       [System.Environment]::SetEnvironmentVariable('GEMINI_API_KEY', 'sk-your-key', 'User')
       ```
    4. PowerShell **재시작**
    5. 설치: `npm install -g @google/gemini-cli`

    또는 **WSL**로 더 네이티브한 경험 사용.
  </Accordion>
</AccordionGroup>

## 9. 모범 사례

### 프롬프트 설계

<CardGroup cols={2}>
  <Card title="구체적으로" icon="bullseye">
    ❌ "Optimize this code"

    ✅ "Optimize this code for performance, focus on loop efficiency and memory use"
  </Card>

  <Card title="맥락 제공" icon="book">
    ❌ "What's wrong with this function?"

    ✅ "This handles user login and throws an async error — help me find the bug"
  </Card>

  <Card title="단계별 분할" icon="list-ol">
    ❌ "Build the whole project"

    ✅ "Step 1: design DB model; Step 2: build API routes; Step 3: ..."
  </Card>

  <Card title="예시 요청" icon="code">
    ❌ "Explain closures"

    ✅ "Explain JS closures with 3 practical scenarios and code examples"
  </Card>
</CardGroup>

### 권장 워크플로

<Steps>
  <Step title="문제 정의">
    해결하거나 구축하려는 것을 명확히 설명합니다.
  </Step>

  <Step title="솔루션 획득">
    Gemini CLI로 초기 솔루션 또는 코드를 작성합니다.
  </Step>

  <Step title="리뷰 및 개선">
    AI에게 자체 출력을 리뷰하고 문제를 표시하도록 요청합니다.
  </Step>

  <Step title="반복">
    피드백을 기반으로 단계별로 개선합니다.
  </Step>

  <Step title="문서 추가">
    주석 및 문서를 생성합니다.
  </Step>
</Steps>

## 10. 참고 자료

* Gemini CLI 공식 문서: [https://ai.google.dev/gemini-api/docs/cli](https://ai.google.dev/gemini-api/docs/cli)
* GravitexAI 콘솔: [https://maas.gravitex.ai](https://maas.gravitex.ai)
* 모델 목록: [https://maas.gravitex.ai/#/models](https://maas.gravitex.ai/#/models)
* 빠른 시작: [/ko/quickstart](/ko/quickstart)

<Tip>
  **5분 안에 시작**: 위 "빠른 시작" 섹션을 따르면 Gemini CLI를 바로 사용할 수 있습니다.
</Tip>