> For the complete documentation index, see [llms.txt](https://docs.avis.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avis.net/vi/tich-hop/coding/gemini-cli.md).

# Gemini CLI

## Hướng dẫn tích hợp Gemini CLI

Hướng dẫn này trình bày cách kết nối [Gemini CLI](https://github.com/google-gemini/gemini-cli), agent lập trình chính thức của Google chạy trên terminal, với API tương thích Gemini của AVIS.

### Gemini CLI là gì

Gemini CLI là agent lập trình mã nguồn mở chạy trên terminal, có thể đọc và sửa tệp cũng như thực thi lệnh shell. Công cụ dùng Gemini API gốc của Google, nhưng cũng có thể kết nối với AVIS qua giao diện tương thích Gemini bằng cơ chế ghi đè chính thức `GOOGLE_GEMINI_BASE_URL`, không cần sửa mã nguồn.

### 1) Cài đặt Gemini CLI

```bash
npm install -g @google/gemini-cli
```

Kiểm tra:

```bash
gemini --version
```

### 2) Lấy AVIS API key

Xem phần Xác thực — đăng nhập tại [avis.net](https://avis.net), vào **Settings → API Keys** và tạo một key.

### 3) Trỏ Gemini CLI tới AVIS

Gemini CLI chỉ áp dụng base URL tùy chỉnh khi xác thực bằng chế độ **Gemini API key** — không áp dụng với Google Sign-In hay Vertex AI. Đặt cả hai biến:

```bash
export GEMINI_API_KEY="<your-avis-api-key>"
export GOOGLE_GEMINI_BASE_URL="https://api.avis.net/api/gemini"
```

Thêm các dòng này vào `~/.zshrc` / `~/.bashrc` để giữ lại cho mọi terminal.

Ghi chú:

* `GOOGLE_GEMINI_BASE_URL` phải là một URL HTTPS hợp lệ.
* Không có trường `baseUrl` nào trong `settings.json` cho việc này — dù một số hướng dẫn tích hợp của bên thứ ba có nói vậy, cơ chế duy nhất được hỗ trợ là biến môi trường `GOOGLE_GEMINI_BASE_URL`, và chỉ khi kết hợp với xác thực bằng `GEMINI_API_KEY`.

### 4) Chạy Gemini CLI

```bash
cd your-project
gemini
```

Ở lần chạy đầu tiên, hãy chọn **Use Gemini API key** khi được hỏi phương thức xác thực (không chọn "Sign in with Google"). Nếu Gemini CLI trước đây đã xác thực bằng Google Sign-In hoặc Vertex AI trên máy này, hãy chủ động chuyển phương thức xác thực — các chế độ đó hoàn toàn bỏ qua `GOOGLE_GEMINI_BASE_URL` và sẽ tiếp tục gọi API thật của Google bất kể biến môi trường.

Chạy một lần / không tương tác:

```bash
gemini "Reply with exactly one word: pong"
```

### 5) Chọn mô hình

Truy vấn danh mục trực tiếp để lấy chính xác các ID hiện tại — giao diện này dùng id chuẩn dạng phẳng của AVIS (không có tiền tố `gemini/`):

```bash
curl https://api.avis.net/api/gemini/v1beta/models \
  -H "x-api-key: $GEMINI_API_KEY"
```

Chọn mô hình bằng cờ `-m`/`--model`:

```bash
gemini -m gemini-2.5-pro "Reply with exactly one word: pong"
```

### 6) Khắc phục sự cố

* Request vẫn đi tới API thật của Google thay vì AVIS
  * Phương thức xác thực đang dùng không phải `gemini-api-key` — `GOOGLE_GEMINI_BASE_URL` bị âm thầm bỏ qua khi dùng Google Sign-In hoặc Vertex AI. Chạy lại `gemini` và chủ động chọn **Use Gemini API key**.
* `401 Unauthorized`
  * `GEMINI_API_KEY` không hợp lệ, đã bị thu hồi hoặc chưa được đặt trong shell mà Gemini CLI được khởi chạy.
  * Kiểm tra trực tiếp: `curl -H "x-api-key: $GEMINI_API_KEY" https://api.avis.net/api/gemini/v1beta/models`.
* `403` với key hợp lệ
  * Số dư tài khoản đã hết — xem phần Lỗi.
* `404` / không tìm thấy mô hình
  * Mô hình truyền vào `-m`/`--model` không khớp với danh mục của AVIS — kiểm tra lại với `GET /api/gemini/v1beta/models` (§5).

### 7) Danh sách kiểm tra tối thiểu từ đầu đến cuối

1. Đã tạo AVIS API key (§2).
2. Đã export `GEMINI_API_KEY` và `GOOGLE_GEMINI_BASE_URL` (§3).
3. Phương thức xác thực đã được chủ động đặt thành **Use Gemini API key** (§4) — không phải Google Sign-In hay Vertex AI.
4. Đã xác nhận model ID với `GET /api/gemini/v1beta/models` (§5).
5. `gemini "..."` trả về kết quả từ mô hình chạy qua AVIS.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.avis.net/vi/tich-hop/coding/gemini-cli.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.