Arrival CLI

最終更新日:25.08.2026バージョン1.0

概要

Arrival CLI は Arrival.Space の Space をローカル Workspace として管理します。Space をファイルとして Pull し、room 設定、Entity、Plugin、Asset を自分のツールや AI Agent で編集し、サーバーで検証してから Live Space へ Push できます。Workspace は通常のファイルなので、他のプロジェクトと同じように Git で管理・レビューできます。

CLI はアプリ内の Space Agent と同じ Materialize、Validate、Sync-back のワークフローを使用しますが、AI は使用せず、Live Hot Reload も提供しません。ソースコードは Arrival Plugins Repository にあります。

AI Agent と使う場合

この Prompt を渡すと、Agent はこのページを読んで自分で設定します。

Please set yourself up to use the arrival CLI: https://codex.arrival.space/api/cli

前提条件

Node.js 18 以降
対象の Space を編集できる Arrival.Space アカウント
OAuth Login 用のブラウザ

インストール

git clone https://github.com/arrival-space/arrival-plugins.git
cd arrival-plugins/tools/arrival-cli
npm install
npm link

すでにリポジトリをローカルに持っている場合は、Clone を省略して tools/arrival-cli に移動してください。

npm link は任意です。arrival コマンドを PATH から実行できるようにします。プロジェクトフォルダから node index.js を実行することもできます。

認証

arrival login

CLI はブラウザを開き、OAuth 2.0 Authorization Code と PKCE を使用します。Token は ~/.arrival/config.json に保存されます。既定のサーバーは次のとおりです。

https://api-live.arrival.space

arrival logout はローカルの Token を削除します。サーバー上の API キーは無効化しません。

コマンド

`arrival spaces`

認証済みユーザーの Space を一覧表示します。--search でタイトルまたは説明を検索できます。

arrival spaces
arrival spaces --search gallery

`arrival create <title>`

新しい Space を作成し、その ID を出力します。--pull を指定すると、同じ手順でローカル Workspace として Checkout できます。

arrival create "Photo wall"
arrival create "Photo wall" --pull

オプション: --description <text>、--privacy Open|Closed（既定は Closed）、--type infinite|hub（既定は infinite）、--pull、および --pull の出力先を指定する --dir <path>。

`arrival pull <spaceId>`

Space をローカル Workspace にダウンロードします。既定の保存先は ./<spaceId> です。

arrival pull 45637586_1234
arrival pull 45637586_1234 --dir ./spaces/gallery
arrival pull 45637586_1234 --force

保存先は空である必要があります。既存の内容を上書きする場合は --force を使用します。Pull には生成された Space の概要や、利用可能な場合は AGENTS.md、CLAUDE.md、reference/ も含まれます。

`arrival status`

最後の Pull または成功した Push 以降のローカル変更を表示します。ネットワーク接続は不要です。

arrival status
arrival status --dir ./spaces/gallery

`arrival diff`

Text ファイルの行単位の差分を表示します。Binary ファイルは Binary ファイルとして表示されます。

arrival diff

`arrival validate`

変更を適用せずにサーバー側の Dry Run を実行します。

arrival validate
arrival validate --dir ./spaces/gallery

検証エラーには対象ファイルとサーバーのメッセージが含まれます。Workspace には arrival pull が作成した .arrival/manifest.json が必要です。

`arrival push`

変更したファイルを Live Space に送信します。

arrival push
arrival push --dir ./spaces/gallery
arrival push --dry-run

追加、変更されたファイルと明示的な削除だけが送信されます。ローカルでファイルを削除した場合、通常の Push には --force が必要です。

arrival push --force

注意

Push は次回の読み込みに使用される Live Space を更新します。既にブラウザで開いている Space は自動更新されません。ブラウザを Reload してください。

`arrival upload <file>`

大きな Asset を Presigned Upload フローで CDN に直接アップロードします。

arrival upload ./assets/museum.glb

Model、Splat、画像、音声、動画などを扱えます。CLI が URL または resource_key を表示するので、Entity から参照して arrival push を実行します。

Workspace の構成

<spaceId>/
  space/
    room.json              # RoomInfo と Space 設定
    entities/*.json        # Entity ごとの JSON ファイル
    plugins/<name>.mjs     # 単一ファイルの ArrivalScript Plugin
    plugins/<name>/        # 複数ファイルの Plugin
    assets/<name>          # ローカル Asset
    README.md              # Space の生成された概要
  .arrival/
    manifest.json          # Pull の Baseline とメタデータ
    base/space/            # status と diff が使う Baseline
  AGENTS.md                # Workspace ガイド
  CLAUDE.md                # 任意の Assistant ガイド
  reference/               # API ドキュメントとサンプル

編集前に space/README.md を読んでください。Entity、Plugin、位置、共有 Plugin の使用状況が記載されています。編集対象は space/ 以下だけです。.arrival/manifest.json、.arrival/base/space、AGENTS.md、CLAUDE.md、reference/ は編集しないでください。

Entity

Entity ファイルの基本形は次のとおりです。

{
  "id": "entity-id",
  "type": "UserModelEntity",
  "data": {
    "position": { "x": 0, "y": 1.5, "z": -3 },
    "rotation": { "x": 0, "y": 90, "z": 0 },
    "scale": 1,
    "glbUrl": "assets/museum.glb"
  }
}

編集するのは data であり、state ではありません。各 Entity には id、type、オブジェクト型の data が必要です。Space 全体の設定は room.json に、個別の設定は各 Entity の JSON に記述します。

Plugin

Plugin は space/plugins/ の .mjs ファイルとして保存します。通常は ArrivalScript を継承するクラスを 1 つ export し、固有の static scriptName を定義します。複数ファイルの Plugin はフォルダとして保存し、通常は index.mjs を入口にします。

Plugin Host Entity は data.glbUrl から plugins/my-plugin.mjs のような Workspace 相対パスを参照します。複数の Entity が同じ Plugin を使っている場合、変更はすべての Host に反映されます。1 つだけ変更したい場合は別名でコピーし、参照を更新してください。

内容が同一の Plugin ファイルは Apply 時に 1 つの共有 Plugin に統合されることがあります。

Asset

space/assets/ の Asset は文字列 assets/<name> で参照します。このフォルダには実際の Asset ファイルだけを置いてください。ドキュメント、Placeholder、.gitkeep は検証に失敗することがあります。

大きな Model、Splat、画像などには arrival upload を使用します。

検証ルール

arrival validate は次の項目などを検証します。

.mjs ファイルを解析できること
Entity が id、type、data を持つこと
Plugin と Asset の参照を解決できること
欠落した参照や壊れた参照がないこと

Cutscene と `.path` ファイル

アニメーション、オブジェクト移動、カメラ Flythrough などは .path ファイルとして作成できます。.path は JSON の Sequence Asset であり、Plugin は必要ありません。

reference/docs/cutscenes-via-mcp.md の形式で .path ファイルを作成します。
arrival upload animation.path でアップロードします。
アップロードした Asset を参照する Entity を作成または編集します。
arrival validate、続けて arrival push を実行します。

独自のロジック、入力、UI、Physics が必要な場合は Plugin を使用します。純粋なアニメーションやカメラ Sequence には .path Cutscene を使用します。loop と autoplay は .path ではなく Cutscene Entity の設定に記述します。

注意

Plugin の onInstall() Hook はアプリ内でのインストール時に実行されます。CLI または MCP Deployment では実行されません。CLI から Deployment する場合は Entity データに Plugin Parameter を直接設定してください。

動作と制限

arrival dev と Live Hot Reload はまだ利用できません。
現在の Workflow は Last-Writer-Wins です。
同時編集は自動的に Merge されません。
ローカル削除は arrival push --force 後に Live コンテンツを削除する場合があります。
大きな Asset には arrival upload を使用してください。

トラブルシューティング

「Not logged in」と表示された場合は arrival login を実行します。保存先が空でない場合は別のディレクトリを使うか --force を指定します。検証エラーでは表示されたファイルとメッセージを確認します。変更が表示されない場合はブラウザで Space を Reload してください。

概要​

前提条件​

インストール​

認証​

コマンド​

arrival spaces​

arrival create <title>​

arrival pull <spaceId>​

arrival status​

arrival diff​

arrival validate​

arrival push​

arrival upload <file>​

Workspace の構成​

Entity​

Plugin​

Asset​

検証ルール​

Cutscene と .path ファイル​

動作と制限​

トラブルシューティング​

概要