Antigravity CLI（agy）の使い方｜Linux導入・自動承認・無料枠とCIの終了コード

Antigravity CLI は、Google のコーディングエージェント Antigravity をターミナルから動かすツールで、コマンド名は agy です。2026年10月12日時点で配信サーバーが返す最新版は 1.3.3、公開されている changelog の最新は 1.3.1（2026年10月7日）で、ほぼ毎日のように版が上がっています。この記事では、Linux への導入と SSH 先での認証、確認なしで編集・実行させる「自動承認」の範囲、無料枠の仕組み、そして agy -p を CI に組み込むときに終了コードをどう読むかを、公式ドキュメントと配布バイナリの実測で整理します。

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

• 導入は公式スクリプト1行（curl -fsSL https://antigravity.google/cli/install.sh | bash）。Linux は x86_64・Arm64 の glibc 版と musl 版、Android の Termux 版まで配布されている。npm では配布されていない。
• SSH 先では URL とコードの貼り付けで認証する。ブラウザもキーリングも無いサーバーや CI では、GEMINI_API_KEY と modelProvider の設定で Gemini API キー認証に切り替えられる。
• 「auto mode」という名前のモードは無い。ファイル編集だけを自動承認するのが --mode accept-edits、コマンド実行まで含めて全部を自動承認するのが --dangerously-skip-permissions。両者の間を permissions.allow のルールとサンドボックスで埋めるのが実務の設定。
• 無料プランは週単位のクォータ、Google AI Pro は5時間ごとに回復して週の上限まで、Ultra は最も多い枠。残量は /usage で確認する。
• CI では終了コードだけで成否を判定しない。権限の足りないツールは標準エラー出力に案内を出して拒否され、--print-timeout の打ち切りも終了コード0で返る。JSON 出力の status と拒否された操作の有無まで確認する。

Antigravity CLI（agy）と Antigravity 2.0・IDE の違い

公式ドキュメントは CLI を「Antigravity の軽量な TUI（ターミナルユーザーインターフェース）」と位置づけています。agy を引数なしで起動すると対話画面が立ち上がり、agy -p "…" と渡すと1回だけ実行して結果を標準出力に書いて終了します。デスクトップアプリの Antigravity 2.0 とはエージェントの中核部分と設定・権限を共有し、作業中の会話を 2.0 へ書き出すこともできます（Antigravity CLI overview）。

2.0 本体はエディタを持たないエージェント管理アプリで、コードを書く画面が要るなら Antigravity IDE を併用します。2.0 と IDE の関係はAntigravity 2.0で変わった点｜IDEとの違い・エディタ復旧・料金・CLI移行、製品全体と料金はアンチグラビティ（Google Antigravity）とは？料金・使い方・2.0の最新情報まで解説【2026年最新】で整理しています。

Linux への Antigravity CLI 導入手順

公式スクリプトによる導入と PATH 設定

macOS・Linux・Googlebook は同じスクリプトです。インストーラは OS と CPU を判定して配信サーバーのマニフェストから最新版の URL を取り、SHA-512 を照合してから ~/.local/bin/agy に置きます（Installation and auth）。

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

# Windows（PowerShell）。%LOCALAPPDATA%\agy\bin\agy.exe に入る
irm https://antigravity.google/cli/install.ps1 | iex

# 版の確認と手動更新
agy --version
agy update

bash: agy: command not found と出たら、~/.local/bin がシェルの PATH に入っていません。~/.bashrc か ~/.zshrc に export PATH="$HOME/.local/bin:$PATH" を足して読み込み直します。書き込めないディレクトリで失敗したときは curl -fsSL https://antigravity.google/cli/install.sh | bash -s -- --dir "$HOME/bin" のように --dir で置き場所を変えます。PATH の追記は、スクリプトが最後に呼び出す agy install が行います。公式ドキュメントはインストールスクリプトのフラグとして --skip-path（PATH を追記しない）を挙げていますが、10月12日に取得した install.sh が受け付けるのは --dir と --help だけでした。--skip-path は agy install のフラグとしては存在するので、シェルの設定ファイルを書き換えさせたくない場合は、手で PATH を通してから agy install --skip-path を使います。

更新は、通常の実行中にバックグラウンドで自動的に行われます。版を固定したい CI では AGY_CLI_DISABLE_AUTO_UPDATE=true を環境変数に入れておきます。更新が update.lock の警告で止まった場合は、~/.gemini/antigravity-cli/updater/update.lock を消すのが公式の対処です（Troubleshooting）。

Linux 向けの配布物：glibc 版・musl 版・Arm64・Termux

インストーラは uname と musl の有無を見て、次のどれかを取得します。2026年10月12日に 1.3.3 の配布物を取得して file コマンドで確かめた結果を並べます。

x86_64 の glibc 版は GLIBC_2.26 までのシンボルを参照していました。glibc が 2.26 より古いディストリビューションでは起動しない前提で、コンテナのベースイメージを選んでください。

パッケージマネージャ経由の入手には注意が要ります。Snap の antigravity-cli は Google ではなく個人の発行者によるもので、10月12日時点の stable は 1.2.11 と公式より遅れていました（Snapcraft）。Homebrew の cask は 1.3.3 ですが macOS 12 以上が対象で、Linux には入りません。Windows の winget には発行者 Google の Google.AntigravityCLI があります。Linux では公式スクリプトを使うのが確実です。

VM の CPU 機能不足による起動エラーと対処

起動直後に FATAL ERROR: This binary was compiled with … enabled, but this feature is not available on this processor で落ちるのは、仮想マシンが CPU の命令セットを隠しているときです。1.3.3 の x86_64 版には、SSE4.2・POPCNT・PCLMUL・CMPXCHG16B などを要求するチェックが組み込まれていました。2026年6月時点の第三者の導入記事が取り上げていた AES は、1.3.3 のチェック対象には含まれていません。Proxmox や KVM では CPU タイプを host にし、VM を停止してから起動し直します（再起動だけでは CPU モデルが切り替わりません）。

WSL への導入と Windows 版との設定分離

CLI の公式ドキュメントに WSL の記載はありません。WSL のディストリビューション内は uname が Linux を返すので、上の Linux 用スクリプトでそのまま導入されます。Windows 側の PowerShell 版と WSL 内の Linux 版は別々の設定ディレクトリを持つため、両方に入れると認証も別々に必要です。なお 2.0 デスクトップアプリは 2.16.0（2026年9月22日）で WSL への接続に対応しましたが、これは CLI とは別の話です。

SSH 先・ヘッドレス環境の認証手順

SSH 越しのログイン手順

ローカルでは OS のキーリング（macOS のキーチェーン、Linux の Secret Service、Windows の資格情報マネージャー）に保存済みの認証があれば自動でサインインし、無ければブラウザが開きます。SSH 接続を検出した場合はブラウザを開けないので、次の流れになります。

1. リモートで agy を起動すると、認可用の URL が表示される。
2. 手元のブラウザでその URL を開き、Google アカウントでサインインする（法人は「Business account」で Gemini Enterprise を選ぶ）。
3. ブラウザに出た認可コードをコピーし、リモートのターミナルに貼り付ける。

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

キーリングが無い Linux 環境の認証保存とエラー対処

D-Bus のセッションが無いサーバーやコンテナでは、1.1.3 以降はキーリングを使わずファイルに保存するよう切り替わり、毎回ログインを求められる問題が解消されています。それでもキーリング関連のエラーが出る場合、公式の対処は export $(dbus-launch) で D-Bus セッションを起こすことです。

未認証のまま agy -p を実行すると、ハングはしません。手元の macOS で 1.3.3 を標準入力なしで実行したところ、認可 URL を出して60秒待ち、error: authentication failed or timed out を出して終了コード1で終わりました。CI では、事前に認証を済ませるか、次の API キー方式を使います。

CI 向けの Gemini API キー認証設定

1.1.13 から、Google アカウントの代わりに Google AI Studio の API キーで動かせます。環境変数 GEMINI_API_KEY だけでは有効にならず、設定ファイルに modelProvider を書く必要があります。

# ~/.gemini/antigravity-cli/settings.json
{
    "modelProvider": "gemini"
}

# シェルまたは CI のシークレットから渡す
export GEMINI_API_KEY="..."
agy models

公式の注意点は3つです。CLI は .env ファイルを読まず、GOOGLE_API_KEY も見ません。起動時にはキーが空でないかしか確認しないので、無効なキーは最初の会話で初めて失敗します。/logout は効きません。API キー方式ではリクエストが Gemini API に直接送られるため、課金も Antigravity のプランではなく Gemini API 側になります。

TUI の基本操作とスラッシュコマンド

入力欄で / を打つとコマンドの候補が出ます。@ でファイルパスを補完し、行頭の ! でシェルコマンドをそのまま実行できます。終了は Ctrl+C（エージェントが動作中なら確認あり）か、入力欄が空のときの Ctrl+D です。

一覧の全体は CLI reference にあります。サブエージェントの並列実行や /boost の使い方はAntigravityのマルチエージェントの使い方｜サブエージェント・/boost・Skills（SKILL.md）の設定で扱っています。

自動承認（auto mode・YOLO）の設定と適用範囲

「確認なしで進めたい」という設定は、Antigravity CLI では1つのスイッチではありません。ファイル編集・コマンド実行・Web や MCP の利用で、効く設定が分かれています。

モードは対話中に Shift+Tab で default→accept-edits→plan と循環します。ただしモードはファイル編集にしか効きません。公式ドキュメントは、シェルコマンド（run_command）はどのモードでも /permissions のルールか --dangerously-skip-permissions が決めると明記しています（Choose an execution mode）。accept-edits にしたのにテストの実行で毎回止まるのはこのためです。

他ツールの名前で指定しても通りません。1.3.3 で --mode yolo を渡すと warning: unrecognized --mode value "yolo" (valid: accept-edits, plan) と警告が出るだけで、既定モードのまま実行が続きました。--permission-mode も CLI には存在しません。

permissions.allow によるコマンド単位の許可設定

実務で勧めるのは、--dangerously-skip-permissions を使わずに、ファイル編集は accept-edits、コマンドは必要なものだけ permissions.allow で許可する構成です。ルールは action(target) の形式で、拒否（deny）＞確認（ask）＞許可（allow）の順に優先されます（Agent permissions）。

{
    "agentMode": "accept-edits",
    "permissions": {
        "allow": [
            "command(git status)",
            "command(git diff)",
            "command(regex:npm run (build|lint|test))"
        ],
        "deny": [
            "command(sudo)",
            "command(rm -rf)",
            "write_file(.git/)"
        ]
    }
}

前方一致で判定されるので、command(git) と書くと git push も許可されます。広く許可するより、使うサブコマンドまで書いて絞る方が安全です。

端末サンドボックスと自動承認の併用設定

CLI の端末サンドボックスは既定で無効（enableTerminalSandbox: false）です。2.0 のように最初から有効ではありません。有効にすると、Linux ではカーネルの名前空間、macOS では sandbox-exec でコマンドを隔離します。書き込めるのはワークスペース、一時ディレクトリ、一般的なビルドキャッシュと、write_file の許可ルールで追加したパスです。~/.ssh や .env は読めず、ネットワークは許可したドメイン以外に出られません（Sandbox）。

{
    "enableTerminalSandbox": true,
    "toolPermission": "proceed-in-sandbox"
}

この組み合わせでは、サンドボックス内のコマンドは確認なしで進み、外で動かす必要があるもの（git push や Docker など）だけ確認が出ます。決まった操作を外で動かすなら unsandboxed(git push) のように許可します。--dangerously-skip-permissions を使う場合は、機密情報やホストの重要なディレクトリにアクセスできない使い捨ての隔離環境に限定してください。Git のブランチを分けるだけでは、ファイルアクセスやコマンド実行の範囲は制限されません。

スクリプト・CI 向けの agy -p 実行と結果判定

出力形式とモデルの指定

-p（--print／--prompt）は応答を標準出力へ、エラーや進行状況を標準エラー出力へ分けて書きます。--output-format で text・json・stream-json を選べ、--json-schema を付けると回答をスキーマに沿わせて structured_output に入れます（Headless mode）。

agy models
agy -p "テストを実行して失敗の原因を要約して" \
  --model gemini-3.8-flash-medium \
  --output-format json \
  --print-timeout 15m

--model には agy models が表示するスラッグを渡します。存在しないモデル名を渡すと、対話画面と違って既定モデルへ黙って切り替えず、利用可能なモデルを並べて終了コード1で失敗します。--print-timeout は 1.2.6 で既定が5分から無制限に変わり、1.3.3 の --help も default 0s（完了まで待つ）と表示します。ヘッドレスのドキュメントの表にはまだ「5m」と残っているので、CI では明示的に指定してください。

終了コード 0・1・3 の実測

2026年10月12日に、macOS 26.6.2（Intel Core i9-9880H）で 1.3.3 の macOS x86_64 版を動かし、失敗の種類ごとに終了コードを確かめました。標準入力は空にし、モデルへのリクエストまで届かせるため意図的に無効な Gemini API キーを使っています。設定の影響を避けるため、HOME を空の一時ディレクトリに向けて実行しました。

終了コード3と AGY_ERROR の行は 1.2.6 で導入されたもので、JSON には status・error_code・retryable・error_id が入ります。retryable が true のときだけ再試行する、という分岐をこの行から組めます。

終了コード0でも作業されていない2つのケース

CI で一番危ないのは、失敗が成功に見える場合です。現行版では次の2つが該当します。

• 権限の足りないツールの拒否：ヘッドレスでは確認を出せないため、許可されていないコマンドは「ソフト拒否」され、実行はそのまま続いて終了コード0で終わります。標準エラー出力に許可ルールの案内が出て、JSON 出力には拒否された操作が denied_actions として入ります（1.1.27）。ワークスペース内のファイル読み書きは許可されていますが、シェルコマンドは既定で確認扱いなので、テストを走らせる指示はテストを実行しないまま「成功」で終わることがあります。
• --print-timeout の打ち切り：1.1.28 から、時間切れはエラーではなく、途中までの出力を返して警告付きで正常終了する仕様です。

このため、CLI の実行状態は終了コードに加えて JSON の中身で判定します。以下の例には Bash と jq が必要です。ただし、エージェントが処理を完了したこととテストが合格したことは別なので、テストの合否は CI がテストコマンドの終了コードや結果ファイルで別途判定してください。

#!/usr/bin/env bash
set -uo pipefail
result=$(agy -p "npm test を実行し、失敗したテスト名を列挙して" \
  --output-format json --print-timeout 20m)
code=$?
if ! printf '%s\n' "$result" | jq -e 'type == "object" and (.status | type == "string") and (.response | type == "string") and ((.denied_actions == null) or (.denied_actions | type == "array"))' >/dev/null; then
  echo "agy returned invalid JSON" >&2
  exit 1
fi
status=$(printf '%s\n' "$result" | jq -r '.status')
denied=$(echo "$result" | jq '.denied_actions // [] | length')
if [ "$code" -ne 0 ] || [ "$status" != "SUCCESS" ] || [ "$denied" -gt 0 ]; then
  echo "agy failed: exit=$code status=$status denied=$denied" >&2
  exit 1
fi
echo "$result" | jq -r '.response' > agy-result.txt

テストを実行させたいなら、permissions.allow に command(npm test) を入れておかないと、上のスクリプトは denied で止まります。止まるのが正しい動作です。

なお公式 FAQ は、ヘッドレスモードを直接のスクリプトと CI のためのものとし、個人向けプランで agy を他社のコーディングエージェントやアプリに組み込むことや、アカウントの自動切り替えはサポート外としています（FAQ）。社内の CI/CD に AI エージェントを組み込む設計は、DevOps・CI/CD導入支援でも相談を受けています。

AGENTS.md・スキル・MCP の置き場所

作業ディレクトリの AGENTS.md と GEMINI.md はそのまま読み込まれ、全体のルールは ~/.gemini/GEMINI.md に置きます。Gemini CLI から移行するときに手作業が要るのはスキルと MCP の置き場所です（Migrating from Gemini CLI）。

.gemini/skills/ に置いたままのスキルはスラッシュコマンドとして認識されないので、.agents/skills/ へ移します。MCP のリモートサーバーは、URL のキー名が url・httpUrl から serverUrl に変わっています。Gemini CLI の拡張機能は agy plugin import gemini でプラグインに変換できます。SKILL.md の書き方自体は他社の Agent Skills と同系統で、Claude Skillsとは？SKILL.mdの書き方とclaude.ai・Claude Code・APIでの使い方【2026年最新】の内容がそのまま参考になります。

無料枠・有料プランのクォータと残量確認

CLI はすべてのプランで使えます。公式のプランページによると、クォータの仕組みは次のとおりです（Plans）。

• 無料（Google AI Pro・Ultra 以外）：週ごとに回復するクォータと週の上限。
• Google AI Pro：5時間ごとに回復し、週の上限に達するまで使える。
• Google AI Ultra：最も多いクォータを5時間ごとに回復。他社モデルも使える。

上限はエージェントの作業量に連動し、簡単な依頼なら回数が多く、複雑な依頼ほど早く減ります。公式も上限は変更されうると書いているので、具体的な回数を手順書に書き込むのは避けてください。残量は /usage、追加購入した AI クレジットの残高は /credits で見られます。Pro・Ultra でクォータを使い切った後にクレジットを自動で使うかどうかは、設定の useG1Credits（/config の「Use G1 Credits」）で決めます。無料プランでは超過分のクレジット利用はできません。

無料枠で処理できる量は、依頼の複雑さや利用状況によって変わります。週の途中で上限に達することが続くなら、Pro 以上に上げるか、前述の Gemini API キー方式で従量課金にするかを選びます。

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

Gemini CLI と Gemini Code Assist の IDE 拡張は、2026年6月18日に無料・Google AI Pro・Ultra の利用者向けの提供を終えました。初めて agy を起動すると、Gemini CLI の設定を検出して移行する項目を選ぶ画面が出ます。残りは次の順で確認します。

1. Dockerfile や CI にある npm install -g の手順を、公式インストールスクリプトに置き換える。
2. .gemini/skills/ を .agents/skills/ へ移す。
3. MCP の定義を mcp_config.json へ移し、serverUrl に書き換える。
4. agy plugin import gemini で拡張機能を変換する。
5. CI では agy -p の判定を、前章のとおり終了コードと JSON の両方で行う。

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

よくある質問

agy とは何のコマンドですか？

Google の Antigravity CLI の実行コマンドです。Linux・macOS では ~/.local/bin/agy、Windows では %LOCALAPPDATA%\agy\bin\agy.exe に置かれます。配布物の中のファイル名は antigravity で、インストーラが agy という名前で配置します。

Antigravity CLI は WSL や Ubuntu で使えますか？

Ubuntu を含む Linux は公式の対応環境です。WSL は CLI のドキュメントに記載がありませんが、WSL 内で Linux 用スクリプトを実行すると Linux 版が入ります。Windows 側の版とは設定と認証が別になります。

確認なしで全部進める YOLO モードはありますか？

相当するのは --dangerously-skip-permissions で、すべてのツールを自動承認します。--mode accept-edits が自動にするのはファイル編集だけで、コマンド実行には確認が出ます。

Antigravity CLI は無料で使えますか？

使えます。Google AI Pro・Ultra に入っていないアカウントにも週単位のクォータがあります。上限に達することが続くなら、Pro 以上か Gemini API キーでの従量課金を検討してください。

Claude Code や Codex とはどう選べばよいですか？

Antigravity 2.0 とセッションを行き来したい場合や、Google のモデルと料金体系にそろえたい場合は Antigravity CLI が向きます。権限設定や CLAUDE.md の運用はClaude Codeの使い方｜導入から権限とCLAUDE.md設定まで実務手順、OpenAI 側はCodexの使い方｜料金・始め方・情報漏洩対策まで2026年7月版で解説と比べてください。エディタを含めた比較はCursorとAntigravityの違いを比較｜料金・商用利用・どっちを選ぶかにあります。

関連記事

• Antigravity 2.0で変わった点｜IDEとの違い・エディタ復旧・料金・CLI移行
• アンチグラビティ（Google Antigravity）とは？料金・使い方・2.0の最新情報まで解説【2026年最新】
• Antigravityのマルチエージェントの使い方｜サブエージェント・/boost・Skills（SKILL.md）の設定
• Gemini CLIとは？2026年6月の個人向け終了とAntigravity CLI移行・使い方まで解説
• Claude Codeの使い方｜導入から権限とCLAUDE.md設定まで実務手順