Bắt đầu (Getting Started)

Cài đặt (Installation)

Cài đặt toàn cục (Global):

npm install -g @google/gemini-cli

Chạy mà không cần cài đặt (Dùng npx):

npx @google/gemini-cli

Xác thực bằng Gemini API Key

1. Lấy Key: Nhận API key từ Google AI Studio.
2. Thiết lập Key: Cung cấp key cho CLI bằng một trong hai phương pháp sau.

Cách 1: Biến môi trường (Shell Environment Variable)

export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"

Cách 2: Tệp môi trường (Environment File)

snippet
# Trong tệp .gemini/.env
GEMINI_API_KEY="YOUR_GEMINI_API_KEY"

Cách gọi lệnh cơ bản (Basic Invocation)

gemini

gemini -p "Tóm tắt các ý chính của tệp đính kèm. @./summary.txt"

echo "Hãy đếm đến 10" | gemini

gemini --sandbox -p "câu lệnh của bạn"

Các tham số khác (Other Flags)

Cấu hình (Configuration)

Tệp cài đặt (settings.json)

1. Hệ thống (System): /etc/gemini-cli/settings.json (Áp dụng cho mọi người dùng, ưu tiên cao nhất).
2. Dự án (Project): .gemini/settings.json (Ghi đè thiết lập người dùng).
3. Người dùng (User): ~/.gemini/settings.json.

{
  "theme": "GitHub",
  "autoAccept": false,
  "sandbox": "docker",
  "vimMode": true,
  "checkpointing": { "enabled": true },
  "fileFiltering": { "respectGitIgnore": true },
  "usageStatisticsEnabled": true,
  "includeDirectories": ["../shared-library", "~/common-utils"],
  "chatCompression": { "contextPercentageThreshold": 0.6 }
}

• autoAccept: Tự động phê duyệt các lệnh gọi công cụ an toàn (chỉ đọc).
• sandbox: Cô lập việc thực thi công cụ (ví dụ: true, "docker", hoặc "podman").
• vimMode: Kích hoạt chế độ soạn thảo kiểu Vim cho cửa sổ nhập lệnh.
• checkpointing: Cho phép sử dụng lệnh /restore để hoàn tác các thay đổi tệp.
• includeDirectories: Định nghĩa không gian làm việc gồm nhiều thư mục.
• chatCompression: Cấu hình tự động nén lịch sử trò chuyện khi quá dài.
• usageStatisticsEnabled: Đặt thành false để tắt thu thập thống kê sử dụng.

Tệp ngữ cảnh (GEMINI.md)

1. Ngữ cảnh toàn cục: ~/.gemini/GEMINI.md (Chỉ dẫn áp dụng cho tất cả dự án).
2. Ngữ cảnh dự án/Cha: CLI tìm kiếm từ thư mục hiện tại lên đến thư mục gốc của dự án.
3. Ngữ cảnh thư mục con: CLI cũng quét các thư mục con để tìm tệp GEMINI.md, cho phép đưa ra chỉ dẫn riêng cho từng thành phần (component).

Module hóa ngữ cảnh bằng Import:

# Ngữ cảnh dự án chính: My Awesome App
 
## Chỉ dẫn chung
- Mọi mã nguồn Python phải tuân thủ PEP 8.
- Sử dụng thụt đầu dòng 2 khoảng trắng cho các tệp mới.
 
## Hướng dẫn phong cách cho từng thành phần
@./src/frontend/react-style-guide.md
@./src/backend/fastapi-style-guide.md

# .geminiignore
/backups/
*.log
secret-config.json

Làm việc với Công cụ (Tools)

Một số công cụ tích hợp sẵn

• Công cụ hệ thống tệp: Tương tác với tệp và thư mục - list_directory(path="/src"), read_file(path="..."), write_file(file_path="...", content="..."), replace(...) (thay thế chuỗi), search_file_content(...) (tìm kiếm nội dung).
• Công cụ Shell: Thực thi lệnh terminal. Sử dụng thận trọng. Để giới hạn lệnh, dùng excludeTools trong settings.json. Ví dụ: "excludeTools": ["run_shell_command(rm)"].
• Công cụ Web: Tìm kiếm và lấy nội dung trực tuyến - google_web_search(query="..."), web_fetch(url="...").
• Công cụ Ghi nhớ (Memory): Lưu trữ và truy xuất thông tin qua các phiên làm việc - save_memory(fact="Khung CSS yêu thích của tôi là Tailwind CSS.").

Công cụ tùy chỉnh qua MCP Servers

"mcpServers": {
  "myPythonServer": {
    "command": "python",
    "args": ["-m", "my_mcp_server", "--port", "8080"],
    "env": { "DATABASE_URL": "$DB_URL_FROM_ENV" },
    "trust": false,
    "includeTools": ["safe_tool_1"],
    "excludeTools": ["dangerous_tool"]
  }
}

• Transport: Chọn command (Stdio cục bộ), url (SSE), hoặc httpUrl (Streaming).
• trust: Nếu đặt là true, sẽ bỏ qua mọi xác nhận khi gọi công cụ từ server này.

Các lệnh cốt lõi

• /compress: Tóm tắt lịch sử chat để tiết kiệm token.
• /copy: Sao chép phản hồi cuối cùng vào clipboard.
• /mcp: Liệt kê các MCP server và công cụ khả dụng.
• /clear: Xóa màn hình và xóa ngữ cảnh hội thoại (phím tắt Ctrl+L).
• /stats: Hiển thị số lượng token đã sử dụng và tiết kiệm được.
• /memory show: Hiển thị toàn bộ ngữ cảnh kết hợp từ các tệp GEMINI.md.
• /chat save <tag>: Lưu cuộc hội thoại hiện tại với một nhãn (tag).
• /chat resume <tag>: Tiếp tục một cuộc hội thoại đã lưu.

Lệnh ngữ cảnh (@)

• Một tệp: > Giải thích mã nguồn này cho tôi. @./src/main.js
• Một hình ảnh: > Mô tả những gì bạn thấy trong ảnh này. @./mockup.png
• Cả thư mục: > Refactor mã nguồn trong thư mục này. @./src/

Lệnh Shell (!)

• Chạy lệnh đơn: > !git status
• Chế độ Shell: Nhập ! để chuyển sang chế độ terminal liên tục. Nhập ! lần nữa để thoát.

Phím tắt

• Ctrl+V: Dán văn bản hoặc hình ảnh từ clipboard.
• Ctrl+Y: Bật/tắt chế độ YOLO (tự động phê duyệt mọi lệnh gọi công cụ).
• Ctrl+X: Mở câu lệnh hiện tại trong trình soạn thảo bên ngoài.

Tính năng nâng cao

Tích hợp IDE (VS Code)

• Ngữ cảnh không gian làm việc: Tự động lấy thông tin về các tệp gần đây, vị trí con trỏ và văn bản đang chọn.
• Native Diffing: Xem và phê duyệt thay đổi mã nguồn trực tiếp qua trình so sánh (diff viewer) của IDE.
• Sử dụng /ide install để cài đặt và /ide enable để kết nối.

Lệnh tùy chỉnh (Custom Commands)

Checkpointing & Khôi phục

• Bật qua flag: gemini --checkpointing
• Khôi phục: /restore <tên_file_checkpoint>

• /restore Danh sách hoặc khôi phục trạng thái dự án (checkpoint).
• /settings Mở trình soạn thảo để chỉnh sửa tệp settings.json.
• /init Tạo tệp ngữ cảnh GEMINI.md mẫu cho dự án.