Antigravity CLI (agy): chạy tác tử trong terminal và script

Antigravity CLI là gì? Antigravity CLI là công cụ dòng lệnh của Google, gọi bằng lệnh agy, dùng chung tác tử, tài khoản và tuỳ biến với ứng dụng Antigravity nhưng chạy ngay trong terminal: có giao diện tương tác (TUI) để làm việc trực tiếp và có chế độ print (headless) để gọi tác tử từ script, Git hook hoặc CI. Phần giới thiệu chung đã có ở bài Antigravity là gì?; bài này chỉ đi sâu vào antigravity cli. Chúng tôi không hứa CLI thay được ứng dụng desktop và không đo tốc độ hay độ chính xác; cờ và lệnh dưới đây lấy từ tài liệu chính thức và agy --help bản 1.4.12, đọc ngày 03/11/2026, chỗ tài liệu tự mâu thuẫn được ghi rõ. Bài đi qua cài đặt, chế độ print, nối tiếp hội thoại, chế độ chạy, CI, chuyển từ Gemini CLI và AI credits.

Từ cài đặt đến chạy tác tử trong script: các lớp chính của Antigravity CLI. Sơ đồ: OPCAIOS.

Cài đặt Antigravity CLI như thế nào?

Cài đặt Antigravity CLI dùng một script cài tự động của Google, theo trang Getting Started trong tài liệu Antigravity (đọc ngày 03/11/2026). Trên macOS, Linux và Googlebook, lệnh cài là một dòng curl tải install.sh rồi chạy bằng bash; trên Windows có bản cho PowerShell (install.ps1) và cho CMD (install.cmd). Kiểm tra bằng agy --version; lần chạy đầu, CLI hỏi có tin thư mục hiện tại không. Script cài nhận hai cờ: --skip-aliases để không đụng alias cũ trong hồ sơ shell và --skip-path để không tự thêm PATH. Về sau, agy update cập nhật CLI, còn agy install cấu hình lại PATH với cùng hai cờ cộng --dir. Trang /docs/install hiện là trang Authenticate: ứng dụng, CLI, tiện ích IDE và SDK dùng chung một lớp đăng nhập, nên đăng nhập ở một nơi là các nơi khác trên máy dùng được.

curl -fsSL https://antigravity.google/cli/install.sh | bash
agy --version

Đăng nhập Antigravity CLI có những cách nào?

Antigravity CLI có bốn cách xác thực, theo trang Authenticate (đọc ngày 03/11/2026):

1. Keyring cục bộ: CLI tìm phiên trong kho khoá của hệ điều hành; không có thì mở trình duyệt để đăng nhập tài khoản Google.
2. SSH: CLI in một URL, người dùng mở trên máy mình, đăng nhập, rồi dán mã xác nhận lại vào terminal từ xa.
3. Khoá Gemini API: đặt modelProvider là gemini trong settings.json của CLI và xuất biến GEMINI_API_KEY. Chỉ đặt biến thì không có tác dụng, và CLI không đọc tệp .env.
4. ADC của Google Cloud: cho doanh nghiệp, bật bằng AGY_ADC_AUTH=true.

Những lệnh chính của agy là gì?

Lệnh của Antigravity CLI chia ba nhóm, theo trang CLI reference và agy --help (đọc ngày 03/11/2026):

Nhóm	Ví dụ	Dùng để
Lệnh con	agy models, agy agents, agy mcp, agy plugin, agy update	Xem model, tác tử, quản lý MCP, plugin
Cờ khởi động	--model, --effort, --mode, --add-dir, --sandbox	Cấu hình một phiên
Lệnh gạch chéo	/plan, /goal, /rewind, /fork, /resume, /usage	Điều khiển phiên đang chạy

Chạy agy mở TUI ở thư mục hiện tại; trong TUI, @ gợi ý đường dẫn tệp, ! đầu dòng chạy lệnh terminal, Shift+Tab đổi chế độ. Cấu hình lâu dài nằm trong settings.json, mở bằng /config; cờ khởi động chỉ ghi đè cho phiên hiện tại.

Chế độ print (headless) của Antigravity CLI hoạt động thế nào?

Chế độ print, còn gọi là headless, là cách chạy Antigravity CLI không tương tác: gửi một yêu cầu, nhận kết quả rồi thoát, theo trang Headless mode (đọc ngày 03/11/2026). Gọi bằng -p hoặc --print, --prompt. Câu trả lời ra stdout, còn lỗi, thông báo quyền và tiến độ ra stderr, nên gán thẳng kết quả vào biến shell được. Cờ --output-format có ba giá trị: text (mặc định), json (một đối tượng khi xong, gồm conversation_id, status, response, duration_seconds, num_turns và usage đếm token) và stream-json (mỗi dòng một sự kiện: một init, nhiều step_update, một result). Headless dùng phiên đăng nhập đã lưu; trong CI chưa đăng nhập, lệnh thoát với lỗi xác thực thay vì treo.

agy -p "In one sentence, what is a git rebase?" --output-format json | jq -r '.response'

--json-schema và --print-timeout dùng khi nào?

--json-schema ép câu trả lời theo JSON Schema, nhận chuỗi schema, đường dẫn tệp .json hoặc tên kiểu đơn giản; kết quả đã phân tích nằm ở structured_output. Cách này đáng tin hơn dặn tác tử "trả JSON" rồi tự cắt chuỗi. --print-timeout đặt giới hạn thời gian, ví dụ 15m. Lưu ý: agy --help và CLI reference ghi mặc định 0s (chờ đến khi xong), còn trang Headless ghi mặc định chờ tối đa 5 phút. Vì tài liệu mâu thuẫn, nên luôn đặt giá trị rõ ràng trong script.

Làm sao nối tiếp một hội thoại trong script?

Nối tiếp hội thoại trong Antigravity CLI dùng hai cờ, vì mỗi lượt headless mặc định không nhớ gì, theo trang Headless mode (đọc ngày 03/11/2026). --continue (viết tắt -c) mở lại hội thoại gần nhất, còn --conversation <ID> mở đúng hội thoại có ID lấy từ trường conversation_id của lần chạy trước. Theo trang Managing conversations, lịch sử gắn theo thư mục làm việc: chạy agy từ thư mục nào thì chỉ thấy phiên của thư mục đó. Mỗi lần --continue là một tiến trình mới. Khi cần nhiều lượt trong một tiến trình, dùng --input-format stream-json kèm --output-format stream-json: script ghi từng dòng JSON có event: "user" vào stdin, mỗi dòng chạy một lượt và trả về một sự kiện result; đóng stdin là kết thúc. Tài liệu nói cách này nhanh hơn gọi lặp --continue; chúng tôi chưa đo.

--mode và --effort khác nhau thế nào?

--mode quyết định tác tử tự làm đến đâu, còn --effort quyết định model suy luận sâu đến đâu. Theo trang Choose an execution mode (đọc ngày 03/11/2026), có bốn chế độ:

1. default: cho xem diff trước khi sửa tệp, hỏi trước khi chạy lệnh.
2. accept-edits: tự duyệt sửa tệp trong workspace, vẫn hỏi trước khi chạy lệnh.
3. auto (Preview): tự duyệt sửa tệp, chạy lệnh trong sandbox, tự đánh giá lệnh ngoài sandbox; lệnh không đảo ngược được vẫn hỏi. Cần terminal sandbox, có từ bản 1.3.5 trên macOS, Linux và 1.4.4 trên Windows, chưa có cho tài khoản doanh nghiệp.
4. plan: nghiên cứu và lập kế hoạch trước khi viết mã.

Quy tắc allow, ask, deny trong /permissions vẫn ưu tiên hơn chế độ. Về --effort, agy --help liệt kê low, medium, high, xhigh, max; trang /effort giải thích phần lớn model chỉ có ba mức đầu. Trong headless, --model sai tên làm lệnh thoát mã khác 0 thay vì lặng lẽ đổi model.

Chạy agy qua SSH, Git hook và CI cần lưu ý gì?

Chạy Antigravity CLI ngoài máy cá nhân cần giải quyết ba việc: đăng nhập, quyền và xử lý lỗi. Qua SSH dùng luồng URL và mã xác nhận; trong CI không có trình duyệt, dùng khoá Gemini API hoặc ADC. Theo trang Headless mode và CLI best practices (đọc ngày 03/11/2026), nên:

1. Dùng --output-format json và kiểm tra status bằng jq; chỉ SUCCESS là thành công.
2. Đặt --print-timeout rõ ràng.
3. Cho phép đúng lệnh cần bằng permissions.allow, không dùng --dangerously-skip-permissions trên máy có dữ liệu thật.
4. Cân nhắc --sandbox; từ bản 1.4.4, cờ này không có tác dụng nếu máy không có sandbox.
5. Ghim --model để kết quả không đổi khi model mặc định đổi.

Ví dụ giả định: Git hook gọi agy -p soạn thông điệp commit từ diff, người dùng đọc lại trước khi commit. Trang best practices có ví dụ dùng cờ --cwd, nhưng cờ này không có trong agy --help bản 1.4.12. Cách làm này gần với codex exec.

Chuyển từ Gemini CLI sang agy thế nào?

Chuyển từ Gemini CLI sang Antigravity CLI phần lớn diễn ra tự động ở lần chạy đầu, theo trang Migrating from Gemini CLI (đọc ngày 03/11/2026): CLI hiện danh sách tài sản để chọn, chuyển token vào keyring và ánh xạ thiết lập hiển thị. Những điểm cần tự kiểm tra:

Thứ cần chuyển	Gemini CLI	Antigravity CLI
Extension	Extension	Plugin, qua agy plugin import gemini
Skill của dự án	.gemini/skills/	.agents/skills/ (tự đổi tên thư mục)
Cấu hình MCP	Trong settings.json	Tệp riêng mcp_config.json
URL server MCP từ xa	url hoặc httpUrl	serverUrl
Tệp quy tắc	GEMINI.md, AGENTS.md	Giữ nguyên

Tài liệu ghi rõ chỉ tương thích một phần. Chi tiết về MCP và plugin có ở bài MCP và skill trong Antigravity; về tệp quy tắc, xem AGENTS.md là gì?.

AI credits trong CLI hoạt động thế nào?

AI credits là tín dụng dùng thêm khi hạn mức của gói đã hết, theo trang CLI AI credits (đọc ngày 03/11/2026). Thanh trạng thái hiện số credit còn lại; /credits mở bảng chi tiết, /usage hiện mức dùng hạn mức. Khoá useG1Credits, mặc định false, quyết định CLI có dùng credit khi hết hạn mức gói hay không, và không có cho tài khoản doanh nghiệp. Chúng tôi chưa đọc bảng giá credit nên không nêu giá. Với script định kỳ, để khoá này tắt thì hết hạn mức script sẽ dừng thay vì âm thầm tiêu credit.

Kinh nghiệm của OPCAIOS

Trên máy Mac chính, chúng tôi cài CLI agy bản 1.4.12 song song với ứng dụng Antigravity 2.28.x, Antigravity IDE 2.5.x, Claude Code và Codex. Trong hệ thống của OPCAIOS, Antigravity là tác tử điều phối: quản lý hạ tầng, giao và theo dõi việc. Cấu hình CLI có danh sách cho phép khoảng 20 mục và vài thư mục làm việc tin cậy, thay vì duyệt tất cả; CLI có một skill trình duyệt cài thêm. Quy tắc chung nằm trong AGENTS.md, còn GEMINI.md cấp người dùng chỉ có một dòng yêu cầu trả lời tiếng Việt. Chúng tôi chưa đưa agy -p vào CI, chưa dùng Remote Control và chưa đo năng suất.

Câu hỏi thường gặp

Antigravity CLI có cần cài ứng dụng Antigravity không?

Trang Getting Started hướng dẫn cài CLI bằng script riêng, độc lập với ứng dụng desktop, và trang Authenticate mô tả một lớp đăng nhập chung cho ứng dụng, CLI, IDE và SDK. Một số bài bên thứ ba nói cần cài ứng dụng trước, nhưng chúng tôi không thấy yêu cầu đó trong tài liệu đọc ngày 03/11/2026. Trong CI, có thể dùng khoá Gemini API hoặc ADC thay vì đăng nhập tài khoản.

Trong chế độ print, tác tử có tự chạy lệnh shell không?

Không, theo mặc định. Không ai bấm duyệt trong headless, nên công cụ cần duyệt bị "từ chối mềm": lượt chạy tiếp tục, thoát mã 0 và in thông báo ra stderr nêu tên công cụ bị chặn. Đọc, ghi tệp trong workspace được cho phép; lệnh shell chỉ chạy khi có quy tắc permissions.allow trong settings.json, ví dụ command(git). Xem thêm chế độ an toàn trong Antigravity.

Có nên dùng --dangerously-skip-permissions không?

Chỉ nên dùng trong môi trường tách biệt, có thể vứt đi như container tạm hay máy ảo, với mã và yêu cầu bạn hoàn toàn tin. Cờ này duyệt mọi lệnh, kể cả xoá tệp và gọi mạng. Cách an toàn hơn là thêm quy tắc permissions.allow cho đúng lệnh cần, kết hợp --sandbox. Xem bảo mật khi dùng AI viết code để chọn mức rủi ro.

Extension Gemini CLI có chạy được trên agy không?

Phần lớn chuyển được: agy plugin import gemini chuyển extension cũ thành plugin, lệnh cũ thành skill và server MCP thành mục trong mcp_config.json. Tài liệu ghi chỉ tương thích một phần. Sau khi nhập, chạy agy plugin list để xem thành phần nào đã được nhận.

Học dùng Antigravity CLI trong quy trình thật bắt đầu từ đâu?

Bắt đầu ở chế độ default trong một thư mục thử, quen với duyệt diff và /rewind, rồi mới sang accept-edits hoặc plan. Sau đó viết một script agy -p nhỏ có --output-format json, kiểm tra status và đặt --print-timeout. Chỉ mở rộng quyền khi đã hiểu tác tử làm gì. Muốn học có hướng dẫn cách đưa tác tử vào công việc hằng ngày an toàn, xem khoá đào tạo ứng dụng AI của OPCAIOS.

Nguồn: tài liệu Google Antigravity tại antigravity.google/docs (getting-started, install, cli/reference, cli/using, cli/headless, cli/best-practices, cli/credits, cli/gcli-migration, cli/modes, cli/conversations, cli/commands/effort) và agy --help bản 1.4.12 (đọc ngày 03/11/2026); chưa kiểm chứng: mặc định thật của --print-timeout, tốc độ của stream-json, giá AI credits. Kinh nghiệm là của OPCAIOS.