Zum Hauptinhalt springen

Arrival CLI

Zuletzt aktualisiert:25.08.2026Version1.0

Übersicht​

Mit dem Arrival CLI verwaltest du Arrival.Space Spaces als lokale Workspaces: einen Space als Dateien laden, Raumkonfiguration, Entities, Plugins und Assets mit deinen eigenen Tools oder einem AI Agenten bearbeiten, die Änderungen auf dem Server validieren und in den Live Space übertragen. Ein Workspace besteht aus normalen Dateien und lässt sich wie jedes andere Projekt in Git versionieren und prüfen.

Das CLI verwendet denselben Materialize-, Validate- und Sync-back-Workflow wie der Space Agent in der Anwendung — ohne AI und ohne Live-Hot-Reload. Der Quellcode ist im Arrival Plugins Repository verfügbar.

Mit einem AI Agenten arbeiten

Gib ihm diesen Prompt — er liest diese Seite und richtet sich selbst ein:

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

Voraussetzungen​

  • Node.js 18 oder neuer
  • Ein Arrival.Space-Konto mit Bearbeitungsrechten für den Ziel-Space
  • Ein Browser für den OAuth-Login

Installation​

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

Wenn du das Repository bereits lokal hast, überspringe den Clone und wechsle nach tools/arrival-cli.

npm link ist optional und stellt den Befehl arrival im PATH bereit. Alternativ kannst du das CLI mit node index.js aus dem Projektordner ausführen.

Authentifizierung​

arrival login

Das CLI öffnet einen Browser und verwendet OAuth 2.0 Authorization Code mit PKCE. Das Token wird lokal unter ~/.arrival/config.json gespeichert. Der Standardserver ist:

https://api-live.arrival.space

arrival logout entfernt das lokal gespeicherte Token. Der API-Schlüssel wird auf dem Server nicht widerrufen.

Befehle​

arrival spaces​

Listet die Spaces des authentifizierten Benutzers auf. Mit --search kannst du nach Titel oder Beschreibung filtern.

arrival spaces
arrival spaces --search gallery

arrival create <title>​

Erstellt einen neuen Space und gibt dessen ID aus. Mit --pull wird der neue Space im selben Schritt in einen lokalen Workspace ausgecheckt.

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

Optionen: --description <text>, --privacy Open|Closed (Standard Closed), --type infinite|hub (Standard infinite), --pull sowie --dir <path> für das Zielverzeichnis von --pull.

arrival pull <spaceId>​

Lädt einen Space in einen lokalen Workspace. Standardmäßig wird ./<spaceId> verwendet.

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

Das Zielverzeichnis muss leer sein, außer du verwendest --force. Der Pull kann außerdem AGENTS.md, CLAUDE.md, reference/ und eine generierte Übersicht des Spaces enthalten.

arrival status​

Zeigt lokale Änderungen seit dem letzten Pull oder erfolgreichen Push. Der Befehl benötigt kein Netzwerk.

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

arrival diff​

Zeigt zeilenweise Änderungen in Textdateien. Für Binärdateien wird nur angegeben, dass sie binär sind.

arrival diff

arrival validate​

Führt einen serverseitigen Dry Run aus, ohne Änderungen anzuwenden.

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

Validierungsfehler enthalten die betroffene Datei und die Meldung des Servers. Der Workspace muss aus arrival pull stammen und .arrival/manifest.json enthalten.

arrival push​

Überträgt geänderte Dateien in den Live Space.

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

Es werden nur hinzugefügte und geänderte Dateien sowie explizite Löschungen übertragen. Wenn lokale Dateien gelöscht wurden, ist eine Bestätigung mit --force erforderlich:

arrival push --force

Das CLI meldet erfolgreiche und fehlgeschlagene Serveroperationen. Bei einem teilweise erfolgreichen Ergebnis wird ein Fehlerstatus zurückgegeben.

vorsicht

Ein Push aktualisiert den Live Space für den nächsten Ladevorgang. Ein bereits geöffneter Browser wird nicht automatisch aktualisiert. Lade den Space neu.

arrival upload <file>​

Lädt ein großes Asset über den Presigned Upload-Workflow direkt zum CDN hoch.

arrival upload ./assets/museum.glb

Unterstützt werden unter anderem Modelle, Splats, Bilder, Audio und Video. Das CLI gibt die URL oder den resource_key aus. Verweise anschließend in einer Entity darauf und führe arrival push aus.

Workspace-Struktur​

<spaceId>/
  space/
    room.json              # RoomInfo und Space-Konfiguration
    entities/*.json        # Eine JSON-Datei pro Entity
    plugins/<name>.mjs     # Einzeldatei-ArrivalScript-Plugins
    plugins/<name>/        # Plugins mit mehreren Dateien
    assets/<name>          # Lokale Assets
    README.md              # Generierte Übersicht des Spaces
  .arrival/
    manifest.json          # Pull-Baseline und Space-Metadaten
    base/space/            # Lokale Baseline für status und diff
  AGENTS.md                # Workspace-Hinweise
  CLAUDE.md                # Optionale Assistant-Hinweise
  reference/               # API-Dokumentation und Beispiele

Lies space/README.md vor der Bearbeitung. Es beschreibt Entities, Plugins, Positionen und gemeinsam verwendete Plugins. Nur Dateien unter space/ sind editierbarer Space-Inhalt. Ändere .arrival/manifest.json, .arrival/base/space, AGENTS.md, CLAUDE.md und reference/ nicht.

Entities​

Entity-Dateien haben grundsätzlich diese Form:

{
  "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"
  }
}

Bearbeite data, nicht state. Jede Entity benötigt id, type und ein Objekt data. Space-weite Einstellungen gehören in room.json. Einstellungen einzelner Entities gehören in deren JSON-Datei.

Plugins​

Plugins liegen als .mjs Dateien unter space/plugins/. Ein Plugin exportiert normalerweise eine Klasse, die ArrivalScript erweitert, und definiert ein eindeutiges static scriptName. Multi-File-Plugins verwenden einen Ordner, normalerweise mit index.mjs als Einstiegspunkt.

Plugin-Host-Entities verweisen über data.glbUrl auf einen Workspace-Pfad wie plugins/my-plugin.mjs. Wenn mehrere Entities dasselbe Plugin verwenden, betrifft eine Änderung alle Hosts. Für einen einzelnen Host kopierst du das Plugin unter einen neuen Namen und aktualisierst die Referenz.

Plugins mit identischem Inhalt können beim Anwenden zu einem gemeinsamen Plugin zusammengeführt werden.

Assets​

Assets unter space/assets/ werden mit dem Literal assets/<name> referenziert. In diesen Ordner gehören nur echte Asset-Dateien. Dokumentationsdateien, Platzhalter und .gitkeep können die Validierung brechen.

Für große Modelle, Splats, Bilder oder andere Binärdateien verwendest du arrival upload.

Validierungsregeln​

arrival validate prüft unter anderem:

  • ob .mjs Dateien geparst werden können
  • ob Entities id, type und data enthalten
  • ob Plugin- und Asset-Referenzen aufgelöst werden können
  • ob fehlende oder verwaiste Referenzen existieren

Cutscenes und .path Dateien​

Animationen, Objektbewegungen und Kamera-Flythroughs können als .path Dateien erstellt werden. Eine .path Datei ist ein JSON-Sequenz-Asset und benötigt kein Plugin.

  1. Erstelle eine gültige .path Datei gemäß reference/docs/cutscenes-via-mcp.md.
  2. Lade sie mit arrival upload animation.path hoch.
  3. Erstelle oder bearbeite eine Entity, die auf das hochgeladene Asset verweist.
  4. Führe arrival validate und danach arrival push aus.

Verwende ein Plugin für eigene Logik, Eingaben, UI oder Physik. Verwende eine .path Cutscene für reine Animationen oder Kameraabläufe. loop und autoplay gehören in die Konfiguration der Cutscene-Entity, nicht in die .path Datei.

vorsicht

Der Plugin-Hook onInstall() wird bei einer Installation in der Anwendung ausgeführt, nicht bei CLI oder MCP Deployments. Setze Plugin-Parameter bei einem CLI Deployment direkt in den Entity-Daten.

Verhalten und Grenzen​

  • arrival dev und Live-Hot-Reload sind noch nicht verfügbar.
  • Der aktuelle Workflow verwendet Last-Writer-Wins.
  • Gleichzeitige Änderungen werden nicht automatisch zusammengeführt.
  • Lokale Löschungen können nach arrival push --force den entsprechenden Live-Inhalt löschen.
  • Große Assets sollten mit arrival upload hochgeladen werden.
  • Ein Push validiert den Changeset zuerst. Einzelne Operationen können teilweise fehlschlagen.

Fehlerbehebung​

Bei „Not logged in“ führst du arrival login aus. Bei einem nicht leeren Zielordner verwendest du ein anderes Verzeichnis oder bestätigst --force. Bei Validierungsfehlern prüfst du die genannte Datei und Meldung. Wenn Änderungen nicht sichtbar sind, lade den Space im Browser neu.