Antigravity CLI（agy）の使い方｜Linux・SSHでの導入から実行モード・無料枠まで

Antigravity CLI は、Google の AI コーディングエージェントをターミナルから動かすためのコマンドラインツールです。実体は agy という単一バイナリで、Linux サーバーへ SSH でつないだ先でも動きます。デスクトップアプリの Antigravity 2.0 と同じエージェントエンジンを共有しているため、GUI を立ち上げられない環境でも同等の編集・実行能力が使えるのが存在意義です。この記事では v1.1.2（2026年7月13日 UTC リリース）時点の一次情報をもとに、インストール・認証・3つの実行モード・権限制御・拡張設定・無料枠の考え方・Gemini CLI からの移行を順にまとめます。

まとめ：Antigravity CLI を使い始める前に押さえる要点

• 実体は agy コマンド。インストールは公式スクリプト1行で、npm では配布されていない（Gemini CLI 時代の npm install 手順は使えない）。
• 公式の対応環境は64ビットの macOS・Linux・Windows。Antigravity 2.0 本体がリモート開発に対応していないため、SSH 先のサーバーで AI エージェントを使いたいなら CLI 一択になる。
• 実行モードは TUI（agy）／プリントモード（agy -p）／ヘッドレス（CI・スクリプト）の3つ。ヘッドレスは認証済みが前提で、未認証だと v1.1.2 では即座に失敗する。
• ファイル書き込み前に差分を提示して止まる default（request-review）が既定。--mode で accept-edits・plan に切り替える。いわゆる自動承認は accept-edits。
• Gemini CLI の個人向け提供は 2026年6月18日で終了済み。組織ライセンス（Standard/Enterprise）と有料 API キー経由は継続。
• レート上限は有料プランがクォータ5時間ごと更新、無料プランが週単位の上限という枠組み。具体的な数値は変更が頻繁なため、公式のプランページで都度確認する。

Antigravity CLI（agy）の位置づけとTUI・CLIの違い

Antigravity CLI は「ターミナルで動く Antigravity」です。Go 製のバイナリとして配布され、公式はキーボード中心のワークフローとリモート SSH セッションに最適化したと説明しています。GUI アプリである Antigravity 2.0 とはコアのエージェントエンジンを共有し、設定と権限は双方向に同期します。ターミナルで進めた作業を GUI へ持ち込むセッションエクスポートも用意されています。

一問一答型のCLIとTUIの違い

用語の混乱が起きやすい部分なので先に整理します。狭義の CLI（コマンドラインインターフェース）は「コマンドを1回打つと1回結果が返る」一問一答型で、agy -p "テストを直して" のような使い方がこれにあたります。対して TUI（ターミナルユーザーインターフェース）は、ターミナルの画面全体を1つのアプリとして描画し、対話を続けながら状態を保持する方式です。agy を引数なしで起動すると立ち上がるのが TUI で、会話履歴のペイン、入力ボックス、実行中のサブエージェントやバックグラウンドタスクを示すステータス表示が同居します。

この違いは使い分けに直結します。TUI は差分レビューやツール実行の承認といった「人が途中で判断する」作業に向き、一問一答型は「判断を挟まず結果だけ欲しい」自動化に向きます。Antigravity CLI は両方を1つのバイナリで提供しているため、同じ agy をシェルスクリプトからも対話作業からも呼べます。

Antigravity 2.0（GUI）とIDEとの役割分担

Antigravity 2.0 はエージェントを束ねる管理アプリで、エディタ機能を持ちません。コードを直接書きたいなら Antigravity IDE を併用します。詳しくはAntigravity 2.0で変わった点｜IDEとの違い・エディタ復旧・料金・CLI移行で整理しています。製品全体の成り立ちとスキル機能はGoogle Antigravityとは？できること・マルチエージェント並列実行とSkills（SKILL.md）の使い方を参照してください。

Linux・macOS・Windowsへのインストールと認証

OS別のインストールコマンドとPATH設定

インストーラは環境を判定し、agy バイナリを Unix 系では ~/.local/bin/agy、Windows では %LOCALAPPDATA%\agy\bin\agy.exe に配置します。前提は macOS・Linux なら curl または wget のいずれか、Windows なら PowerShell 5 以上です。対応アーキテクチャは64ビットのみで、それ以外の OS・CPU ではインストーラが「64-bit Windows, macOS, and Linux をサポート」と表示して停止します。

# macOS / Linux
curl -fsSL https://antigravity.google/cli/install.sh | bash

# Windows PowerShell
irm https://antigravity.google/cli/install.ps1 | iex

# Windows コマンドプロンプト
curl -fsSL https://antigravity.google/cli/install.cmd -o install.cmd && install.cmd && del install.cmd

導入直後の代表的なつまずきは PATH 未設定です。~/.local/bin がシェルの PATH に含まれていない場合は、.bashrc や .zshrc に追記してシェルを開き直します。agy: command not found の大半はこれが原因です。書き込み権限のないディレクトリへ入れようとして失敗した場合は、インストーラ自身が --dir で書き込み可能なディレクトリを指定するよう案内します（例：curl -fsSL ... | bash -s -- --dir "$HOME/bin"）。

もう1点、Antigravity CLI は npm では配布されていません。Gemini CLI を npm install -g で入れていたプロビジョニングスクリプトや Dockerfile がある場合、その経路は使えなくなるため上記のインストールスクリプトへ置き換える必要があります。

更新については、通常の実行中にバックグラウンドで自動的に自己更新するとインストーラが明記しています。版を確実に上げ直したいときは、既存バイナリを削除してインストールスクリプトを再実行します。

SSH・リモート環境での認証とサインアウト

認証はシステムのキーリングを使い、有効なセッションがなければ Google サインインにフォールバックします。ローカルでは既定のブラウザが自動で開きますが、SSH 接続を検出すると認証用 URL をターミナルに出力するため、手元の端末のブラウザでその URL を開いて認可を完了させます。ブラウザのない Linux サーバーでもこの流れで初回ログインができます。企業利用では、オンボーディング時に GCP プロジェクトを接続します。

認証情報を消したいときは TUI 内で /logout を実行します。共用サーバーで作業した後や、別アカウントへ切り替えるときに使います。

3つの実行モードと基本操作

TUIモード：対話しながら差分を承認する

引数なしで agy を実行すると TUI が起動します。操作の入り口は /help で、一般・コマンド・ショートカットのタブから使える機能を確認できます。よく使うスラッシュコマンドは次のとおりです。

入力ボックスで ! を押すとシェルモードに切り替わり、そのままコマンドを打てます。抜けるときは再度 ! か ESC です。ファイルやディレクトリを文脈に渡すときは @ 記法でパスを指定します。終了は Ctrl+C の2回押しで、1回目は実行中のエージェント処理の中断に割り当てられています。Ctrl+D は入力欄に文字があると前方削除として働き、空のときだけ終了フローに入ります。

画面下部のステータスラインには、クォータの使用状況と現在のエージェント実行モードが表示されます。表示内容は設定の statusLine で差し替えられ、stack_with_default を有効にすると既定の表示とカスタム出力を縦に並べられます。

プリントモード（agy -p）：一発実行して結果だけ受け取る

スクリプトから呼ぶときは -p（--print）にプロンプトを渡します。TUI を起動せず、応答を標準出力へ書いて終了します。

agy -p "src配下のTODOコメントを一覧にして"

# 利用可能なモデル名を確認してから指定する
agy models
agy -p "テストを実行して失敗原因を要約" --model "<models で表示された名称>"

モデル名は agy models サブコマンドで一覧できます。名前を正確に写す必要があるのは、v1.1.2 からプリントモードは --model を解決できないときに既定モデルへ黙って降格せず、利用可能なモデルを列挙して非ゼロ終了で失敗するようになったためです（対話セッションは従来どおりフォールバックします）。CI でモデル名を打ち間違えたまま「動いてはいるが別モデルで実行されている」事故は防げるようになりましたが、裏を返せばこれまでは誤りに気づけなかったということです。

ヘッドレス実行：CI/CDやサブプロセスから呼ぶ

ターミナルを持たない環境（CI ランナー、他のエージェントからのサブプロセス起動など）での実行もプリントモードで行いますが、認証まわりの挙動が対話時と異なります。v1.1.2 では、標準入力がパイプで埋まっている場合でも制御端末（POSIX の /dev/tty、Windows の CONIN$）から OAuth 認可コードを貼り付けられるようになり、完全にヘッドレスな実行は「ブロックして固まる」のではなく、対処方法を示して即座に失敗するよう変更されました。CI では、ジョブを回す前に認証を済ませておく設計が前提になります。

CI/CDでagyを回すときの落とし穴

ここは競合記事がほとんど触れていない領域なので、はっきり書きます。2026年7月より前のバージョンで agy -p を CI に組み込む設計は、いま採用すべきではありません。公式のリリースノートを追うと、自動化で踏む地雷が立て続けに修正されているからです。

• v1.1.1 以前：シェルスクリプトやサブプロセスの中で agy -p がハングした。プロンプトをフラグで渡しているのに標準入力を読みにいっていたのが原因で、v1.1.1 で解消。
• v1.1.1 以前：サーバー側でリクエストが失敗しても、プリントモードが出力空・終了コード0で終了していた。CI は成功と判定するため、エージェントが何もしていないのにグリーンになる状態が起きた。v1.1.1 でエラーは標準エラー出力へ、終了コードは非ゼロになった。
• v1.1.2：未認証のヘッドレス実行が無言でブロックせず即座に失敗するようになり、モデル名の解決失敗も非ゼロ終了に変わった。

したがって CI で使うなら、バージョンを 1.1.2 以上に固定し、終了コードを必ず判定するのが最低ラインです。標準出力が実端末でないときに出力が出ないという事象への対策として、疑似端末（PTY）を噛ませるラッパーが第三者から公開されていますが、上記の公式修正が入った後は、まず素の agy -p で終了コードと標準エラー出力を確認してから要否を判断してください。先回りして PTY ラッパーを常設すると、公式が直した挙動の恩恵を受けられず、切り分けも難しくなります。

自動化の前提として、公式 README は AI コーディングエージェントに自律的なコード実行・データ持ち出し・プロンプトインジェクション・サプライチェーンのリスクがあると警告し、エージェントの全アクションを監視・検証するよう求めています。無人実行するなら、書き込み権限を持つブランチと認証情報のスコープを絞り、行動をログで追える状態にしておくべきです。

権限とエージェント実行モード

v1.1.0 でエージェントの実行モード切り替えが正式公開され、default → accept-edits → plan を循環させられるようになりました。他ツールで「YOLO モード」と呼ばれる確認を挟まず編集を進める挙動にあたるのが accept-edits です。

既定は差分レビューを挟む default です。差分表示では f で全画面の差分ビューに切り替えられ、v1.1.2 からは新規ファイル作成の確認画面でも同じ操作が使えます。起動時に --mode を渡すか、/settings の Agent Mode で既定値を永続化できます。settings.json の許可設定に登録済みの書き込み操作は default でも確認を求められません。編集の自動受理は、リポジトリを汚しても捨てられる環境に限るのが実務上の線引きです。

AGENTS.md・スキル・フック・MCPによる拡張

Gemini CLI から Antigravity CLI へは、Agent Skills・Hooks・Subagents・Extensions（Antigravity プラグイン）という拡張の枠組みが引き継がれています。ただし置き場所と形式が変わった箇所があるため、既存プロジェクトをそのまま持ち込むと「設定したのに効かない」状態になります。

プロジェクトルールを書くAGENTS.mdとGEMINI.md

作業ディレクトリの AGENTS.md と GEMINI.md は引き続き読み込まれ、記述したルールがエージェントの制約として効きます。GEMINI.md を残したまま移行しても動くため、リポジトリ側のルールファイルを書き換える必要はありません。コーディング規約、使ってよいライブラリ、テストの実行方法など、毎回プロンプトに書いている前提をここへ移すと再現性が上がります。

スキルの置き場所は .agents/skills/ へ変わった

プロジェクト固有のスキルを .gemini/skills/ に置いていた場合、そのままではスラッシュコマンドとして認識されません。フォルダを .agents/skills/ へリネーム（または移動）する手作業が必要です。移行後にスキルが一覧に出てこないときは、まずここを疑ってください。スキルは Markdown で書く形式で、考え方はClaude Skillsとは？SKILL.mdの書き方とclaude.ai・Claude Code・APIでの使い方【2026年最新】で解説している SKILL.md と同系統です。

フックとMCPサーバーの設定

フックは、ツール実行の前後やセッション開始といったタイミングで任意の処理を差し込む仕組みです。権限判断をフックへ委ねる構成も可能で、v1.0.16 では判断が空文字で返ったときのエラーが修正されています。MCP サーバーの定義は、主設定に入れ子にせず独立した JSON プロファイル（mcp_config.json）へ分離されました。起動の遅い自社製 MCP サーバーで接続に失敗する問題は、v1.0.15 で接続タイムアウトが60秒へ延長されて改善しています。タイムアウト自体も設定可能で、-1 を指定すれば無効化できます。

サブエージェントと並行実行

複数のサブエージェントを並行して走らせ、その状態は入力ボックス下のステータス表示で追えます。v1.1.1 では孫以降の深い階層のサブエージェント表示とツール承認の中継に対応し、同版で追加された --agent フラグと agents サブコマンドを使うと、起動時にカスタムエージェントを選んだり一覧を出したりできます。動的に定義するサブエージェントは v1.0.16 で JSON から Markdown 形式へ変わったため、JSON で書いた定義は呼び出されません。

無料枠・レート上限の見方

ここは数値を覚えないほうがよい領域です。仕組みだけ押さえます。Google は2025年12月に、Google AI Pro／Ultra の有料利用者へ優先アクセスとより緩いレート上限を与え、クォータは5時間ごとに更新される方式へ、無料プランは週単位のより大きな上限へ移行すると告知しました。以降も無料枠の実効的な上限は繰り返し調整されており、利用者からは公表どおりに回復しないという報告も出ています。社内の手順書や見積もりに具体的な数値を書き込むと、その時点で陳腐化します。

実務上の判断は次の3点で足ります。無料枠はマルチエージェントの挙動を試すには十分だが、日常的な開発の主戦力として当てにしない。継続利用するなら Google AI Pro／Ultra、あるいは組織ライセンスを前提に設計する。現在の上限は公式のプランページと、CLI 内の「Models & Quota」画面およびステータスラインのクォータ表示で都度確認する。CI で回すなら、上限到達を前提にリトライとバックオフを組み込んでおいてください。

Gemini CLIからAntigravity CLIへの移行手順

Gemini CLI と Gemini Code Assist の IDE 拡張は、2026年6月18日をもって無料ユーザーおよび Google AI Pro／Ultra ユーザー向けのリクエスト処理を終了しました（予定ではなく実施済みです）。Standard／Enterprise ライセンスを持つ組織と、有料の API キー経由での利用は継続します。個人で使っていたなら、移行は選択ではなく前提条件です。手順は次の順で進めます。

1. npm 経由の Gemini CLI インストール手順（Dockerfile・CI・端末セットアップ手順書）を洗い出し、公式インストールスクリプトへ置き換える。
2. .gemini/skills/ があれば .agents/skills/ へリネームする。
3. MCP サーバー定義を mcp_config.json へ移す。
4. 動的サブエージェントの定義を JSON から Markdown へ書き換える。
5. agy を起動して認証し、/model と /permissions で既定を確認する。
6. CI で使っている場合は 1.1.2 以上に固定し、終了コード判定を追加する。

Gemini CLI 側の終了経緯と、組織ライセンスで使い続ける場合の条件はGemini CLIとは？2026年6月の個人向け終了とAntigravity CLI移行・使い方まで解説にまとめています。

よくある質問

Antigravity CLI は Linux で使えますか。WSL は対応していますか。

Linux は公式の対応環境です（64ビットの macOS・Linux・Windows がサポート対象）。WSL は公式が明示する対応環境には挙げられていません。WSL 内は Linux 環境なので Linux 版インストーラで導入すること自体は可能ですが、Windows 側のインストールを WSL から呼ぶ構成では不具合報告があるため、Windows で使うならネイティブの PowerShell 版を入れるのが素直です。なお Antigravity 2.0 本体はリモート開発に対応していないため、SSH 先の Linux サーバーで作業するなら CLI が唯一の選択肢になります。

agy -p の出力が空のまま終わります。

v1.1.1 より前のバージョンでは、サーバー側でリクエストが失敗した場合にプリントモードが出力なし・終了コード0で終了する不具合がありました。まずバージョンを確認し、1.1.2 以上へ上げてください。CLI は通常実行中にバックグラウンドで自己更新しますが、確実に上げるならバイナリを削除してインストールスクリプトを再実行します。更新後はエラーが標準エラー出力へ書かれ、終了コードが非ゼロになります。

無料枠だけで実務に使えますか。

試用には足りますが、日常的な開発の主戦力にはなりません。無料プランは週単位の上限で運用されており、上限に達すれば回復まで待つことになります。継続利用するなら有料プランか組織ライセンスを前提にしてください。

確認を挟まず自動で編集させる「YOLO モード」はありますか。

相当するのは accept-edits モードです。起動時に --mode accept-edits を渡すか、TUI 内でモードを循環させて切り替えます。差分の承認を省くため、使い捨てブランチやコンテナ内など、壊しても戻せる環境に限定してください。

既存の GEMINI.md は書き直しが必要ですか。

不要です。作業ディレクトリの GEMINI.md と AGENTS.md は引き続き読み込まれます。書き直しが必要なのはスキルの配置（.gemini/skills/ → .agents/skills/）と、動的サブエージェント定義の JSON から Markdown への変更です。

Claude Code や Codex と比べてどう選びますか。

Antigravity CLI の強みは、GUI 版とエージェントエンジン・設定・権限を共有し、セッションを GUI へ持ち出せる点と、SSH を含むリモート環境での軽さです。Google のモデルと課金体系に寄せたい場合や、リモートのサーバー上で作業する比率が高い場合に向きます。OpenAI 側の選択肢はCodexの使い方｜料金・始め方・情報漏洩対策まで2026年7月版で解説で比較検討できます。

関連記事

• Antigravity 2.0で変わった点｜IDEとの違い・エディタ復旧・料金・CLI移行
• Gemini CLIとは？2026年6月の個人向け終了とAntigravity CLI移行・使い方まで解説
• Google Antigravityとは？できること・マルチエージェント並列実行とSkills（SKILL.md）の使い方
• Claude Skillsとは？SKILL.mdの書き方とclaude.ai・Claude Code・APIでの使い方【2026年最新】
• Codexの使い方｜料金・始め方・情報漏洩対策まで2026年7月版で解説