gemini-cli: dùng Gemini ngay trong terminal — hướng dẫn cài đặt và dùng
Bài này là một góc nhìn khác về google-gemini/gemini-cli — repo từng đổi tên nên mình viết lại với cách tiếp cận khác. Bài hướng dẫn chính: Gemini CLI: trợ lý AI Gemini ngay trong terminal — hướng dẫn cài đặt và dùng →

Tóm tắt nhanh
Gemini CLI là agent AI mã nguồn mở chạy trong terminal, hỗ trợ đọc và sửa code, tạo ứng dụng, gỡ lỗi và tự động hoá quy trình qua MCP. Cài đặt khá đơn giản bằng npx hoặc npm, nhưng cần tài khoản Gemini Code Assist doanh nghiệp, API trả phí hoặc Vertex AI; không có gói miễn phí theo README.
gemini-cli là một agent AI mã nguồn mở đưa Gemini trực tiếp vào terminal. Bạn có thể mở một thư mục dự án, đặt câu hỏi bằng ngôn ngữ tự nhiên, nhờ công cụ phân tích code, sửa file, chạy lệnh và hỗ trợ xử lý các việc kỹ thuật.
Repo này hợp với lập trình viên, nhóm kỹ thuật, nhân viên vận hành và người dùng văn phòng có quy trình cần tự động hoá. Điểm đáng giá nhất là bạn không phải chuyển qua lại giữa trình duyệt và terminal: Gemini có thể làm việc với codebase hiện tại, nhận nhiều thư mục làm ngữ cảnh, chạy ở chế độ tương tác hoặc không tương tác trong script.
Bạn cần lưu ý phạm vi sử dụng. README nói Gemini CLI hiện dành cho tổ chức dùng Gemini Code Assist Standard hoặc Enterprise, Code Assist cho GitHub trên Google Cloud, cùng các trường hợp dùng API trả phí hoặc Vertex AI. README cũng ghi không có gói miễn phí và không tối ưu cho dòng Gemini 4 trở lên. Nếu bạn cần tài khoản cá nhân miễn phí hoặc Google AI Pro/Ultra, hãy xem công cụ khác được README gợi ý thay thế.
google-gemini/gemini-cli
Gemini CLI là agent AI mã nguồn mở giúp đọc, sửa code và tự động hoá công việc ngay trong terminal.
I.Gemini CLI làm được gì
A.Làm việc với codebase lớn
Bạn có thể yêu cầu Gemini đọc cấu trúc dự án, giải thích kiến trúc, tìm file liên quan hoặc tóm tắt thay đổi. Điều này hữu ích khi bạn mới tiếp nhận một repo nhiều thư mục và chưa biết nên bắt đầu từ đâu.
Gemini cũng có thể chỉnh sửa code theo yêu cầu. Bạn nên mô tả rõ mục tiêu, phạm vi file và cách kiểm tra kết quả. Với dự án quan trọng, hãy xem lại thay đổi trước khi chấp nhận và chạy test riêng.
B.Tạo ứng dụng từ mô tả hoặc tài liệu
README cho biết Gemini CLI có khả năng đa phương thức. Bạn có thể dùng PDF, hình ảnh hoặc bản phác thảo làm đầu vào để hỗ trợ tạo ứng dụng. Tài liệu được cung cấp không mô tả chi tiết cú pháp đưa file vào, nên phần này cần xem hướng dẫn chính thức trong repo trước khi áp dụng.
C.Gỡ lỗi bằng ngôn ngữ tự nhiên
Thay vì chỉ đọc thông báo lỗi, bạn có thể yêu cầu Gemini phân tích nguyên nhân, tìm vị trí liên quan và đề xuất cách sửa. Với lỗi có nhiều bước, hãy cung cấp mục tiêu, lệnh đã chạy và kết quả nhận được để câu trả lời sát hơn.
D.Tự động hoá công việc vận hành
Gemini CLI có thể chạy ở chế độ không tương tác. Bạn có thể đưa prompt vào lệnh để tạo câu trả lời dùng trong script, yêu cầu trả về JSON có cấu trúc hoặc theo dõi sự kiện theo thời gian thực qua stream-json.
README nêu một số hướng dùng như truy vấn pull request và xử lý các lần rebase phức tạp. Đây là nền tảng phù hợp cho nhóm muốn đưa AI vào quy trình kỹ thuật, nhưng mọi lệnh có tác động đến code hoặc hệ thống vẫn cần được kiểm tra quyền và đầu ra.
E.Mở rộng bằng MCP
Gemini CLI hỗ trợ kết nối MCP server để bổ sung công cụ. README đưa các ví dụ như kết nối GitHub, Slack, cơ sở dữ liệu và dùng MCP cho việc tạo media với Imagen, Veo hoặc Lyria.
Khi đã cấu hình MCP server, bạn có thể gọi công cụ theo ngữ cảnh, chẳng hạn yêu cầu liệt kê pull request đang mở hoặc gửi bản tóm tắt commit đến một kênh. Quyền truy cập phụ thuộc vào server và cấu hình của bạn.
F.Lưu ngữ cảnh và tuỳ biến cách làm việc
Repo có tài liệu cho file GEMINI.md, custom commands, checkpointing, token caching, trusted folders và sandboxing. Các tính năng này giúp giữ quy ước của dự án, tạo lệnh dùng lại, tiếp tục cuộc trò chuyện và kiểm soát việc thực thi theo thư mục.
Hiện repo có khoảng 108814 sao và 14945 fork, dùng TypeScript, giấy phép Apache-2.0 và vẫn còn được cập nhật. Đây là tín hiệu tốt về mức độ quan tâm, nhưng không thay thế việc kiểm tra tính phù hợp với chính sách dữ liệu của công ty.
II.Cần chuẩn bị gì
- Máy có Node.js từ phiên bản 20 trở lên. package.json của repo yêu cầu Node >=20.0.0.
- Một trong các phương án xác thực được README hỗ trợ: tài khoản Google có giấy phép Gemini Code Assist trả phí của tổ chức; Gemini API key; hoặc cấu hình Vertex AI.
- Nếu dùng giấy phép Code Assist của tổ chức, bạn cần biết Google Cloud Project tương ứng và đặt biến GOOGLE_CLOUD_PROJECT.
- Nếu dùng Gemini API key, bạn cần có API key và đặt biến GEMINI_API_KEY.
- Nếu dùng Vertex AI, README yêu cầu GOOGLE_API_KEY và GOOGLE_GENAI_USE_VERTEXAI=true.
- Terminal để chạy npx, npm hoặc các lệnh liên quan.
- Nếu muốn dùng Homebrew thì máy thuộc macOS hoặc Linux. Nếu muốn dùng MacPorts thì máy là macOS.
- Nếu chạy qua Anaconda trong môi trường bị hạn chế, cần có Anaconda hoặc conda.
README không nêu yêu cầu GPU. README cũng không nói một cấu hình RAM hay dung lượng đĩa cụ thể. Bạn không nên tự suy ra đây là công cụ chạy hoàn toàn cục bộ, vì các phương án xác thực được nêu đều liên quan đến dịch vụ Gemini hoặc Google Cloud.
README ghi rõ không có free tier hoặc Google AI plans cho Gemini CLI. Vì vậy, trước khi cài cho nhóm, bạn nên xác nhận giấy phép, billing và quyền truy cập dự án Google Cloud. Chi phí cụ thể không được nêu trong tài liệu được cung cấp.
III.Cài đặt từng bước
- Kiểm tra môi trườngĐảm bảo Node.js đáp ứng yêu cầu của package.json
- Cài Gemini CLIChọn npx, npm, Homebrew, MacPorts hoặc Anaconda
- Chọn xác thựcDùng Google OAuth, Gemini API key hoặc Vertex AI
- Khởi độngChạy gemini trong thư mục cần làm việc
- Kiểm tra đầu raGửi prompt thử hoặc chạy chế độ không tương tác
A.Kiểm tra Node.js
README chỉ ghi rõ yêu cầu Node.js từ phiên bản 20. Trong nội dung được cung cấp không có lệnh kiểm tra phiên bản Node, nên bạn hãy kiểm tra bằng công cụ Node đã có trên máy hoặc xem hướng dẫn cài đặt chi tiết mà README dẫn tới. Nếu Node thấp hơn yêu cầu, package có thể không cài hoặc không chạy đúng.
Đừng mở terminal ở một thư mục không có quyền truy cập nếu bạn định để Gemini đọc hoặc sửa file. Với người mới, nên bắt đầu bằng một thư mục dự án thử nghiệm và sao lưu thay đổi quan trọng.
B.Cài nhanh bằng npx
Đây là cách README đưa ra để chạy ngay mà không cần cài package toàn cục:
# Using npx (no installation required)
npx @google/gemini-clinpx sẽ gọi package @google/gemini-cli và khởi động CLI. README không nói rõ việc package được lưu tạm ở đâu, nên bạn không cần tự tạo thư mục cài riêng cho cách này.
Nếu lệnh không chạy, hãy kiểm tra Node.js và npm trước, sau đó kiểm tra quyền truy cập mạng, registry và phương án xác thực. Không nên tự đổi tên package vì tên được README cung cấp là @google/gemini-cli.
C.Cài toàn cục bằng npm
Nếu bạn muốn gọi lệnh gemini từ nhiều thư mục, dùng lệnh chính thức sau:
npm install -g @google/gemini-cliTuỳ chọn -g cài package ở phạm vi toàn cục của môi trường npm. Sau khi cài, mở terminal trong thư mục dự án rồi chạy gemini. Nếu terminal báo không tìm thấy lệnh, hãy kiểm tra npm global bin đã có trong PATH; README được cung cấp không nêu lệnh sửa PATH cụ thể.
Bạn cũng có thể chọn kênh phát hành. Kênh preview được phát hành thường xuyên nhưng có thể có lỗi hồi quy:
npm install -g @google/gemini-cli@previewKênh stable dùng tag latest:
npm install -g @google/gemini-cli@latestKênh nightly lấy các thay đổi mới nhất và được README cảnh báo có thể còn lỗi:
npm install -g @google/gemini-cli@nightlyNếu đây là máy làm việc chính, nên cân nhắc stable. Chỉ dùng preview hoặc nightly khi bạn chấp nhận thử nghiệm và biết cách quay lại phiên bản phù hợp.
D.Cài bằng Homebrew hoặc MacPorts
Trên macOS hoặc Linux, README cung cấp lệnh Homebrew:
brew install gemini-cliTrên macOS có MacPorts, dùng:
sudo port install gemini-cliLệnh MacPorts có sudo, nên hệ thống có thể yêu cầu mật khẩu quản trị. Nếu bạn không có quyền quản trị, hãy dùng npx hoặc npm theo chính sách máy của mình.
E.Cài trong môi trường Anaconda
README dành cách này cho môi trường bị hạn chế. Bạn tạo một môi trường mới, kích hoạt nó rồi cài package bằng npm:
# Create and activate a new environment
conda create -y -n gemini_env -c conda-forge nodejs
conda activate gemini_env
# Install Gemini CLI globally via npm (inside the environment)
npm install -g @google/gemini-cliĐiểm dễ vấp là phải chạy npm install sau khi conda activate. Khi đó Node.js và package được cài trong môi trường gemini_env theo cách README mô tả. Nếu đóng terminal, bạn cần kích hoạt lại môi trường trước khi gọi CLI.
F.Chọn phương án xác thực
Nếu tổ chức cấp giấy phép Code Assist, README hướng dẫn đặt Google Cloud Project trước khi khởi động:
# Set your Google Cloud Project
export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
geminiThay YOUR_PROJECT_ID bằng mã dự án thật của tổ chức. Không đặt nhầm tên hiển thị của dự án nếu hệ thống yêu cầu project ID. README gọi đây là phương án đăng nhập Google bằng OAuth khi dùng giấy phép Code Assist trả phí.
Nếu dùng API key, README đưa lệnh sau:
# Get your key from https://aistudio.google.com/apikey
export GEMINI_API_KEY="YOUR_API_KEY"
geminiThay YOUR_API_KEY bằng key thật. Không đưa key vào prompt, file code, commit hoặc log chia sẻ cho người khác.
Nếu dùng Vertex AI, dùng cấu hình sau:
# Get your key from Google Cloud Console
export GOOGLE_API_KEY="YOUR_API_KEY"
export GOOGLE_GENAI_USE_VERTEXAI=true
geminiREADME mô tả Vertex AI phù hợp hơn với nhóm doanh nghiệp và workload sản xuất, có tính năng doanh nghiệp, khả năng mở rộng khi có billing account và tích hợp với hạ tầng Google Cloud.
Các khối lệnh trên dùng cú pháp export như README. Nếu bạn chạy Windows PowerShell, README được cung cấp không có cú pháp PowerShell tương ứng. Hãy xem authentication guide trong tài liệu của repo trước khi đặt biến môi trường theo hệ điều hành của bạn.
G.Khởi động trong thư mục dự án
Sau khi cài và xác thực, mở terminal tại thư mục muốn Gemini làm việc rồi chạy:
geminiGemini sẽ bắt đầu phiên tương tác. Bạn có thể gõ yêu cầu ở dòng nhắc. Với repo có sẵn, README minh hoạ cách tải repo và vào thư mục:
git clone https://github.com/google-gemini/gemini-cli
cd gemini-cli
geminiĐây là ví dụ dùng chính repo Gemini CLI để phân tích. Khi làm với repo khác, hãy thay URL và tên thư mục bằng thông tin thật của repo đó.
IV.Kiểm tra đã chạy được chưa
Cách đơn giản nhất là chạy gemini trong một thư mục dự án và gửi yêu cầu ngắn, chẳng hạn yêu cầu giải thích cấu trúc codebase. Nếu CLI nhận prompt và trả về câu trả lời, cài đặt và xác thực cơ bản đã hoạt động.
Bạn cũng có thể kiểm tra chế độ không tương tác bằng lệnh README cung cấp:
gemini -p "Explain the architecture of this codebase"Kết quả mong đợi là một câu trả lời văn bản về kiến trúc codebase. Lệnh này phù hợp để thử trong script hoặc dùng nhanh mà không mở phiên tương tác.
Để kiểm tra đầu ra có cấu trúc, dùng:
gemini -p "Explain the architecture of this codebase" --output-format jsonKết quả mong đợi là JSON theo định dạng đầu ra của CLI. Nếu cần theo dõi hoạt động dài, README cung cấp stream-json:
gemini -p "Run tests and deploy" --output-format stream-jsonKết quả là các sự kiện JSON phân tách theo dòng, phù hợp cho việc giám sát. Câu lệnh mẫu có hành động chạy test và triển khai, nên chỉ dùng trong môi trường có quyền và quy trình phê duyệt phù hợp.
Bạn cũng có thể kiểm tra phạm vi ngữ cảnh bằng nhiều thư mục:
gemini --include-directories ../lib,../docsNếu Gemini đọc được cả hai thư mục và trả lời dựa trên chúng, tuỳ chọn include-directories đang được nhận đúng.
V.Dùng vào việc thật
A.Lập trình viên mới tiếp nhận một repo
Mở terminal tại thư mục dự án rồi chạy gemini. Sau đó yêu cầu Gemini giải thích kiến trúc, chỉ ra entry point và gợi ý nơi cần đọc trước. README có ví dụ tương ứng:
> Explain the architecture of this codebaseKết quả mong đợi là bản giải thích dựa trên codebase hiện tại. Bạn nên yêu cầu thêm tên file và lý do để dễ kiểm chứng, sau đó tự mở các file quan trọng thay vì xem câu trả lời là tài liệu tuyệt đối.
B.Nhóm phát triển cần xem thay đổi trong repo
Clone repo, vào thư mục và khởi động Gemini:
git clone https://github.com/google-gemini/gemini-cli
cd gemini-cli
geminiREADME đưa prompt mẫu để tóm tắt các thay đổi đã vào repo:
> Give me a summary of all of the changes that went in yesterdayTình huống này hữu ích khi chuẩn bị họp kỹ thuật hoặc bàn giao. Nếu bạn làm trong repo khác, hãy bảo đảm thư mục hiện tại đúng repo và dữ liệu lịch sử cần thiết có sẵn.
C.Người quản lý dự án muốn tạo ứng dụng mẫu
Bạn có thể bắt đầu từ một thư mục dự án mới rồi yêu cầu Gemini tạo ứng dụng theo mô tả. README minh hoạ việc tạo Discord bot dùng file FAQ.md:
cd new-project/
geminiSau đó nhập:
> Write me a Discord bot that answers questions using a FAQ.md file I will provideKết quả là đề xuất hoặc thay đổi phục vụ ứng dụng theo yêu cầu. Bạn cần cung cấp FAQ.md đúng cách theo tài liệu hỗ trợ file của CLI, xem lại code sinh ra, kiểm tra secret và chạy test trước khi đưa vào sử dụng.
D.Nhân viên vận hành tự động hoá báo cáo
Trong script, bạn có thể dùng prompt không tương tác:
gemini -p "Explain the architecture of this codebase" --output-format jsonCách này phù hợp khi hệ thống khác cần đọc kết quả JSON. Với quy trình dài cần cập nhật từng sự kiện, dùng stream-json như README hướng dẫn. Không nên đưa dữ liệu nhạy cảm vào prompt nếu chưa kiểm tra chính sách lưu trữ, telemetry, quyền truy cập và cấu hình enterprise.
E.Nhóm kỹ thuật mở rộng công cụ qua MCP
Sau khi cấu hình MCP server trong ~/.gemini/settings.json, bạn có thể gọi công cụ theo tên như các ví dụ trong README:
> @github List my open pull requests
> @slack Send a summary of today's commits to #dev channel
> @database Run a query to find inactive usersKết quả phụ thuộc vào MCP server, quyền của tài khoản và dữ liệu mà server được phép truy cập. Với Slack hoặc database, hãy thử ở phạm vi nhỏ trước. Đặc biệt, câu lệnh gửi tin nhắn hoặc truy vấn dữ liệu cần được kiểm tra quyền trước khi dùng trong môi trường thật.
Giá trị lớn nhất của Gemini CLI là biến lời yêu cầu bằng ngôn ngữ tự nhiên thành một bước làm việc ngay trong codebase.
Ông T
VI.Lỗi hay gặp và cách xử lý
A.Node.js thấp hơn yêu cầu
package.json yêu cầu Node >=20.0.0. Nếu npm báo lỗi tương thích hoặc CLI không khởi động, hãy nâng Node lên phiên bản đáp ứng yêu cầu rồi cài lại package. README không cung cấp lệnh nâng Node cụ thể, nên đừng tự thêm một trình quản lý phiên bản nếu chưa kiểm tra môi trường.
B.Dùng nhầm loại tài khoản
README nói Gemini CLI không có free tier hoặc Google AI plans. Nếu bạn chỉ có tài khoản cá nhân miễn phí hoặc Google AI Pro/Ultra, xác thực có thể không phù hợp với công cụ này. Hãy kiểm tra bạn có Gemini Code Assist Standard/Enterprise, Code Assist cho GitHub, API trả phí hoặc cấu hình Vertex AI hay chưa.
C.Biến môi trường hoặc key bị sai
Các tên biến phải khớp README: GOOGLE_CLOUD_PROJECT, GEMINI_API_KEY, GOOGLE_API_KEY và GOOGLE_GENAI_USE_VERTEXAI. Sai tên, sai project ID hoặc dán key có thêm ký tự có thể khiến CLI không xác thực. Không gửi key trong issue, prompt công khai hoặc commit.
Nếu chạy Windows PowerShell, hãy nhớ README chỉ đưa cú pháp export của shell kiểu Unix. Không nên dán nguyên khối lệnh đó vào PowerShell rồi kết luận package hỏng; hãy xem authentication guide của repo để dùng cách đặt biến phù hợp.
D.Gọi sai thư mục hoặc thiếu ngữ cảnh
Gemini mặc định bắt đầu trong thư mục hiện tại. Nếu bạn đang đứng nhầm thư mục, câu trả lời có thể thiếu file hoặc đọc nhầm dự án. Hãy cd đúng thư mục trước khi chạy gemini, hoặc dùng --include-directories theo cú pháp README cung cấp.
E.Dùng kênh preview hoặc nightly cho việc quan trọng
README cảnh báo preview có thể có hồi quy và nightly có thể còn lỗi. Nếu bản mới gây lỗi, hãy chuyển về kênh stable latest theo chính lệnh cài đặt trong README. Với hệ thống doanh nghiệp, nên thử trước trong môi trường riêng và ghi lại phiên bản đã dùng.
API key, quyền Google Cloud, MCP server và lệnh có thể sửa file hoặc triển khai đều cần được kiểm tra trước khi dùng. Không đưa dữ liệu bí mật vào prompt nếu chưa xác nhận chính sách của tổ chức và cấu hình bảo mật.
VII.Có nên dùng không
Nên dùng nếu bạn muốn một agent Gemini chạy ngay trong terminal, làm việc trực tiếp với codebase, hỗ trợ tạo và sửa code, chạy prompt trong script hoặc mở rộng qua MCP. Việc cài bằng npx hoặc npm khá ngắn, repo dùng giấy phép Apache-2.0 và có tài liệu cho nhiều nhu cầu như headless mode, sandboxing, trusted folders, IDE integration và enterprise.
Giới hạn lớn nhất là điều kiện truy cập. README không mô tả đây là công cụ miễn phí cho mọi tài khoản; ngược lại, nó nhắm tới Gemini Code Assist doanh nghiệp, API trả phí và Vertex AI. Người dùng cần Gemini 4 trở lên cũng nên cân nhắc công cụ khác vì README nói Gemini CLI chưa được tối ưu cho dòng đó.
Bạn cũng không nên dùng Gemini CLI để benchmark model. README cảnh báo harness của CLI không được tối ưu cho Gemini 4 trở lên và có thể cho điểm không đại diện. Với tác vụ có quyền xoá, sửa, gửi tin nhắn, truy vấn dữ liệu hoặc triển khai, hãy bật quy trình phê duyệt và kiểm tra đầu ra của agent.
Nếu nhu cầu của bạn là gọi Gemini theo kiểu API stateless từ script, README giới thiệu Gemini API CLI như một lựa chọn khác. Nếu bạn cần terminal đa agent, tài khoản cá nhân miễn phí, Google AI Pro/Ultra hoặc Gemini 4 Argon trở lên, README gợi ý Antigravity CLI. Còn nếu tổ chức đã có Code Assist phù hợp và muốn AI nằm ngay trong quy trình terminal, gemini-cli là lựa chọn đáng thử.
Câu hỏi thường gặp
Gemini CLI có miễn phí không?
README ghi rõ Gemini CLI không có free tier hoặc Google AI plans. Công cụ hướng tới Gemini Code Assist Standard/Enterprise, Code Assist cho GitHub trên Google Cloud, API trả phí hoặc Vertex AI.
Có cần GPU để chạy Gemini CLI không?
Tư liệu được cung cấp không nêu yêu cầu GPU. README chỉ nêu Node.js từ phiên bản 20 và các phương án xác thực liên quan đến Gemini hoặc Google Cloud.
Gemini CLI chạy Windows được không?
Tư liệu không đưa hướng dẫn cài đặt Windows riêng. README có lệnh npm và npx có thể dùng theo môi trường Node, nhưng phần đặt biến môi trường chỉ dùng cú pháp export nên người dùng Windows cần xem authentication guide trong repo.
Có thể dùng API key thay cho đăng nhập Google không?
Có. README hỗ trợ Gemini API key qua biến GEMINI_API_KEY, hoặc Vertex AI qua GOOGLE_API_KEY và GOOGLE_GENAI_USE_VERTEXAI=true.
Dữ liệu gửi vào Gemini CLI có an toàn không?
README có tài liệu về sandboxing, trusted folders, telemetry và enterprise, nhưng phần tư liệu được cung cấp không đưa cam kết bảo mật cụ thể cho từng phương án xác thực. Bạn nên kiểm tra chính sách của tổ chức trước khi đưa dữ liệu nhạy cảm vào prompt.
Gemini CLI khác gì công cụ gọi Gemini API?
README mô tả Gemini CLI là coding harness và agent chạy trong terminal, có thể làm việc với codebase, công cụ tích hợp và MCP. README giới thiệu Gemini API CLI cho API stateless, script, CI, phân tích file và các lệnh trực tiếp với model.
Có nên dùng Gemini CLI để benchmark model không?
Không nên. README cảnh báo harness của Gemini CLI không được tối ưu cho Gemini 4 trở lên và có thể tạo ra kết quả benchmark không đại diện.


