Befehle

Diese Seite dient als Übersicht. Nutze die aktuelle Befehlsreferenz für exakte Flags: App, Bundle, Channel, und Build.

Nutzung

Alle Befehle sollten im App-Ordner ausgeführt werden, wenn das capacitor Projekt korrekt initialisiert ist.

Capacitor Cross-Platform Native Runtime für Web-Apps

Init

npx @capgo/cli@latest init [apikey]

Diese Methode führt dich Schritt für Schritt durch das Onboarding.

Damit wird deine App zu Capgo hinzugefügt. Zudem wird code in deine App integriert, um das Update zu validieren. Gleichzeitig wird deine App gebaut und zu Capgo hochgeladen. Außerdem hilft sie dir dabei, die Funktionalität des Updates zu prüfen.

Login

npx @capgo/cli login [apikey]

Diese Methode dient dazu, den apikey für dich.

Hinweis

mit --apikey=******** in jedem Befehl, um ihn zu überschreiben

Optional kannst du angeben:

--local Dadurch wird dein API-Key im lokalen Repo und ignoriere es per git ignore.

Doctor

npx @capgo/cli doctor

Befehl, um zu prüfen, ob deine Capgo Pakete auf dem neuesten Stand sind.

Dieser Befehl ist auch für Bug-Reports nützlich.

App hinzu

Füge

npx @capgo/cli app add [appId]

[appId] deine App-ID im Format com.test.app wird erklärt hier.

💡 Falls nicht angegeben, werden alle Optionen aus deiner Config übernommen.

Optional kannst du angeben:

• --icon [/path/to/my/icon] um ein benutzerdefiniertes Icon in der Capgo Web-App anzuzeigen.
• --name [test] um einen eigenen Namen in der Liste zu haben.
• --apikey [key] API Key zum Verknüpfen mit deinem Account.
• --retention [retention] Aufbewahrungsdauer des App-Bundles in Tagen, Standard 0 = unendlich.

Beispiel für capacitor.config.json für appId und AppName wird das Icon aus dem Ressourcen-Ordner ermittelt

{
  "appId": "ee.forgr.capacitor_go",
  "appName": "Capgo",
  "webDir": "dist"
}

Setzen Sie

npx @capgo/cli app set [appId]

[appId] ist deine App-ID, das Format wird erklärt hier.

Optional kannst du angeben:

• --icon [/path/to/my/icon] um ein benutzerdefiniertes Icon in der Capgo Web-App anzuzeigen.
• --name [test] um einen eigenen Namen in der Liste zu haben.
• --retention [retention] Aufbewahrungsdauer des App-Bundles in Tagen, Standard 0 = unendlich.
• --expose-metadata [true|false] um Bundle-Metadaten (Link und Kommentar) für das Plugin bereitzustellen.
• --preview oder --no-preview um QR-Codes für Bundle- und Channel-Previews zu aktivieren oder zu deaktivieren.
• --allow-device-custom-id oder --no-allow-device-custom-id um benutzerdefinierte Device-IDs zu steuern.
• --block-provider-infra-requests oder --no-block-provider-infra-requests um das Blockieren bekannter Google- und Apple-Datacenter-Anfragen zu steuern.
• --build-timeout-minutes [5-360] um das Timeout für den Native Build festzulegen.
• --ios-store-url [url] oder --android-store-url [url] um die Store-URL festzulegen.
• --default-upload-channel [channel] um den Standard-Upload-Channel festzulegen.
• --default-download-channel [channel] um den Standard-Download-Channel festzulegen, oder --disable-download-channels um alle Download-Channels auf nicht-öffentlich zu setzen.
• --apikey [key] API Key zum Verknüpfen mit deinem Account.

Liste

npx @capgo/cli app list [appId]

[appId] deine App-ID im Format com.test.app wird erklärt hier.

Optional kannst du angeben:

• --apikey [key] API Key zum Verknüpfen mit deinem Account.

Löschen

npx @capgo/cli app delete [appId]

[appId] deine App-ID im Format com.test.app wird erklärt hier.

Optional kannst du angeben:

• --apikey [key] API Key zum Verknüpfen mit deinem Account.
• --bundle mit der Versionsnummer löscht nur diese Version.

Debuggen

npx @capgo/cli app debug [appId]

[appId] deine App-ID im Format com.test.app wird erklärt hier.

Optional kannst du angeben:

• --apikey [key] API Key zum Verknüpfen mit deinem Account.
• --device mit dem konkreten Gerät, das du debuggen möchtest

Einstellung

npx @capgo/cli app setting [path]

Bearbeite die Capacitor Config.

[path] - Pfad der Einstellung, die du ändern möchtest. Um zum Beispiel den appId, gib an appId.\nFalls du Auto-Updates deaktivieren möchtest, im capacitor-updater, gib an plugins.CapacitorUpdater.autoUpdate mit --string off.

Du MUSST entweder angeben: --string oder --bool!

Optionen:

• --string <string> - setzt die Einstellung auf einen String
• --bool <true | false> - setzt die Einstellung auf einen Boolean

Bundle

Upload

npx @capgo/cli bundle upload [appId]

[appId] ist deine App-ID, das Format wird erklärt hier.

Optional kannst du angeben:

• --apikey <apikey> API Key zum Verknüpfen mit deinem Account.
• --path <path> Pfad des zu uploadenden Ordners.
• --channel <channel> Zu verknüpfender Channel.
• --external <url> Verlinkt eine externe URL statt eines Uploads zu Capgo Cloud.
• --iv-session-key <key> Setzt IV und Session-Key für die externe Bundle-URL.
• --s3-endpoint <s3Endpoint> URL des S3-Endpoints. Funktioniert nicht mit Delta-Uploads oder der externen Option.
• --s3-region <region> Region für deinen S3-Bucket.
• --s3-apikey <apikey> API Key für deinen S3-Endpoint.
• --s3-apisecret <apisecret> API Secret für deinen S3-Endpoint.
• --s3-bucket-name <bucketName> Name deines AWS S3-Buckets.
• --s3-port <port> Port für deinen S3-Endpoint.
• --no-s3-ssl SSL für den S3-Upload deaktivieren.
• --key <key> Benutzerdefinierter Pfad für den Public Signing Key (v1-System).
• --key-data <keyData> Public Signing Key (v1-System).
• --key-v2 <key> Benutzerdefinierter Pfad für den Private Signing Key (v2-System).
• --key-data-v2 <keyData> Private Signing Key (v2-System).
• --bundle-url Gibt die Bundle-URL in stdout aus.
• --no-key Signing Key ignorieren und unverschlüsseltes Update senden.
• --no-code-check Prüfung ignorieren, ob notifyAppReady() in der Source-Datei code aufgerufen wird und index im Root-Ordner vorhanden ist.
• --display-iv-session Zeigt IV und Session Key zur Verschlüsselung des Updates in der Konsole an.
• --bundle <bundle> Versionsnummer des zu uploadenden Bundles.
• --auto-bump [level] Auto-Increment basierend auf dem Channel-Bundle oder der neuesten Remote-App-Version. Level: major, minor (Standard), patch (Alias fix), metadata, oder ai (Workers AI vergleicht lokale Dateien mit dem vorherigen Capgo/channel Delta-Manifest, ermittelt das Level und loggt den Grund; überspringt AI und erhöht, patch falls keine Capgo Version vorhanden ist). Erhöht, bis ein freier Name gefunden wird (gelöschte Namen bleiben belegt). Nicht kombinierbar mit --bundle.
• --min-update-version <minUpdateVersion> Minimale Version, die für ein Update auf diese Version erforderlich ist. Nur aktiv, wenn 'disable auto update' im Channel auf 'metadata' steht.
• --auto-min-update-version Setzt die minimale Update-Version basierend auf Native Packages.
• --ignore-metadata-check Ignoriert den Metadata-Check (node_modules) beim Upload.
• --ignore-checksum-check Ignoriert den Checksum-Check beim Upload.
• --timeout <timeout> Timeout für den Upload-Prozess in Sekunden.
• --delta Lädt Delta (Manifest)-Dateien zusammen mit dem Full Bundle hoch.
• --delta-only Lädt nur Delta (Manifest)-Updates hoch und überspringt das Full Bundle.
• --no-delta Deaktiviert Delta (Manifest)-Uploads (hilfreich, wenn der Instant Apply- autoUpdate Modus aktiv ist, du aber ein Full Bundle benötigst).
• --tus Lädt das Bundle über das tus-Protokoll hoch.
• --multipart Verwendet das Multipart-Protokoll zum Hochladen von Daten nach S3. Veraltet, bitte stattdessen TUS verwenden.
• --encrypted-checksum <encryptedChecksum> Ein verschlüsselter Checksum (Signatur). Nur beim Upload externer Bundles.
• --package-json <packageJson> Pfad zur package.json. Nützlich für Monorepos.
• --auto-set-bundle Setzt das Bundle in capacitor.config.json.
• --node-modules <nodeModules> Liste der Pfade zu node_modules. Nützlich für Monorepos (kommagetrennt, z. B.: ../../node_modules,./node_modules)

⭐️ Die externe Option hilft in 2 Fällen: Datenschutz in Unternehmen (kein Senden von code an Dritte) und Apps > 200 MB. Hierbei speichert Capgo nur den Link zur Zip und sendet diesen an alle Apps.

👀 Die Capgo Cloud sieht niemals den Inhalt des Links (bei externer Option) oder in code beim Speichern.

🔑 Durch Verschlüsselung kannst du eine zweite Sicherheitsebene hinzufügen. So kann Capgo nichts einsehen oder verändern – es wird „trustless“.

Beispiel für package.json für Version

{
  "version": "1.0.2"
}

⛔ Die Version muss größer als „0.0.0“ sein.

💡 Denke daran, die Versionsnummer bei jedem Release zu aktualisieren. Aus Sicherheitsgründen kann eine Versionsnummer nicht überschrieben oder nach dem Löschen wiederverwendet werden.

Liste

npx @capgo/cli bundle list [appId]

[appId] deine App-ID im Format com.test.app wird erklärt hier.

Optional kannst du angeben:

• --apikey [key] API Key zum Verknüpfen mit deinem Account.

Löschen

npx @capgo/cli bundle delete [appId]

[appId] deine App-ID im Format com.test.app wird erklärt hier.

Optional kannst du angeben:

• --apikey [key] API Key zum Verknüpfen mit deinem Account.
• --bundle mit der Versionsnummer löscht nur diese Version.

Aufräumen

in einem SemVer-Bereich für eine Major-Version zu Cloud

npx @capgo/cli bundle cleanup [appId] --bundle=[majorVersion] --keep=[numberToKeep]

[appId] deine App-ID im Format com.test.app wird erklärt hier.

Optional kannst du angeben:

• --apikey [key] API Key zum Verknüpfen mit deinem Account.
• --bundle [majorVersion] die Version, für die alte Pakete entfernt werden sollen; es bleibt das letzte + numberToKeep.
• --keep [numberToKeep] die Anzahl der Pakete, die du behalten möchtest (Standard: 4).

Beispiel: Wenn du 10 Versionen von 10.0.1 bis 10.0.11 hast und npx @capgo/cli cleanup [appId] --bundle=10.0.0 wird 10.0.1 bis 10.0.6 entfernt. 10.0.7 bis 10.0.11 bleiben erhalten.

Wenn du insgesamt 20 Versionen hast und keine Bundle-Nummer angibst, wie zum Beispiel hier: npx @capgo/cli cleanup [appId] --keep=2 Werden 18 Versionen entfernt und die letzten 2 behalten.

Dieser Befehl fragt nach einer Bestätigung und zeigt eine Tabelle mit den behaltenen und entfernten Paketen.

Hinweis

Dieser Befehl ignoriert Bundles, die aktuell in einem Channel verwendet werden.

Encrypt

Warnung: Dieser Befehl ist veraltet und wird im nächsten Major-Release entfernt. Bitte nutze das neue Verschlüsselungssystem. npx @capgo/cli bundle encrypt [path/to/zip]

Dieser Befehl wird verwendet, wenn du eine externe Quelle für dein code nutzt oder zu Testzwecken.

Optional kannst du angeben:

--key [/path/to/my/private_key] der Pfad zu deinem Private Key. --key-data [privateKey] die Private-Key-Daten, falls du Inline-Verschlüsselung nutzen möchtest. Der Befehl gibt deine ivSessionKeyaus und erstellt ein verschlüsseltes ZIP, das du mit dem upload- oder decrypt-Befehl nutzen kannst.

V2-Verschlüsselung

npx @capgo/cli bundle encrypt [path/to/zip] [checksum]

Dieser Befehl wird verwendet, wenn du eine externe Quelle für deine code nutzt oder zu Testzwecken. Der Checksum ist der sha256 des Bundles (generiert durch —key-v2) und dient dazu, die Integrität der Datei nach der Entschlüsselung zu prüfen. Er wird mit dem Private Key verschlüsselt und zusammen mit dem Bundle gesendet. Bei Encryption V2 wird der Checksum zum „Signature“ des Bundles aufgewertet.

Optional kannst du angeben:

--key [/path/to/my/private_key] der Pfad zu deinem Private Key. --key-data [privateKey] die Private Key Daten, falls du sie inline verwenden möchtest. --json um Infos als JSON auszugeben. Der Befehl gibt deine ivSessionKeyy aus und erstellt ein verschlüsseltes ZIP, um es mit dem upload oder decrypt Befehl zu nutzen.

Entschlüsseln

npx @capgo/cli bundle decrypt [path/to/zip] [ivSessionKey]

Optional kannst du angeben:

--key [/path/to/my/private_key] der Pfad zu deinem Private Key.

--key-data [privateKey] die Private-Key-Daten, wenn du sie inline verwenden möchtest. Dieser Befehl ist hauptsächlich für Testzwecke gedacht; er entschlüsselt das Zip und gibt den base64-entschlüsselten Session Key in der Konsole aus.

V2 entschlüsseln

npx @capgo/cli bundle decryptV2 [path/to/zip] [ivSessionKey]

Optional kannst du angeben:

--key [/path/to/my/private_key] der Pfad zu deinem Private Key. --key-data [privateKey] die Private-Key-Daten, wenn du sie inline verwenden möchtest. Dieser Befehl ist hauptsächlich für Testzwecke gedacht; er entschlüsselt das Zip und gibt den base64-entschlüsselten Session Key in der Konsole aus. --checksum [checksum] die Checksumme der Datei; sie wird nach der Entschlüsselung verifiziert.

Zip

npx @capgo/cli bundle zip [appId]

[appId] ist deine App-ID, das Format wird erklärt hier.

Optional kannst du angeben:

• --path [/path/to/my/bundle] um einen bestimmten Ordner hochzuladen.
• --bundle [1.0.0] um die Bundle-Versionsnummer des Dateinamens festzulegen.
• --name [myapp] um den Dateinamen zu überschreiben.
• --json um Infos als JSON auszugeben.
• --no-code-check um den code Check zu ignorieren und das Bundle trotzdem zu senden.
• --key-v2 um das neue Verschlüsselungssystem zu nutzen. Dies ist erforderlich, da das neue System bessere Prüfsummen verwendet, um die Integrität der Datei zu verifizieren.

Kompatibilität

npx @capgo/cli bundle compatibility [appId] -c [channelName]

[appId] ist deine App-ID, das Format wird erklärt hier. [channelName] der Name des zu prüfenden Channels.

Optional kannst du angeben:

• --apikey [key] API Key zum Verknüpfen mit deinem Account.
• --text Verwende Text statt Emojis in der Tabelle
• --channel [channel] der Channel, mit dem die Kompatibilität geprüft wird.
• --package-json <packageJson> Pfad zur package.json. Nützlich für Monorepos
• --node-modules <nodeModules> Liste der Pfade zu node_modules. Nützlich für Monorepos (kommagetrennt, z. B.: ../../node_modules,./node_modules)

Channel

Füge

npx @capgo/cli channel add [channelName] [appId]

[channelName] der Name deines neuen Channels, wie zum Beispiel production oder beta. [appId] deine App-ID im Format com.test.app wird erklärt hier.

Löschen

npx @capgo/cli channel delete [channelName] [appId]

[channelName] der Name des Channels, den du löschen möchtest. [appId] deine App-ID im Format com.test.app wird erklärt hier.

Liste

npx @capgo/cli channel list [appId]

[appId] deine App-ID im Format com.test.app wird erklärt hier.

Optional kannst du angeben:

• --apikey [key] API Key zum Verknüpfen mit deinem Account.

Setzen Sie

npx @capgo/cli channel set [channelName] [appId]

[appId] ist deine App-ID, das Format wird erklärt hier. [channelName] den Namen des Kanals, den du konfigurieren möchtest, wie zum Beispiel production oder beta.

Optional kannst du angeben:

• --bundle [1.2.3] dein bereits an die Cloud gesendetes App-Bundle, um es mit einem Kanal zu verknüpfen.
• --latest die Bundle-Version abrufen von package.json:version, ist nicht kombinierbar mit --bundle.
• --state [ normal | default ] setzt den Channel-Status, kann normal oder default. Ein Channel muss default.
• --downgrade erlaubt dem Channel, Downgrade-Versionen an Geräte zu senden.
• --no-downgrade verbietet dem Channel, Downgrade-Versionen an Geräte zu senden.
• --upgrade erlaubt dem Channel, Upgrade-Versionen (Major) an Geräte zu senden.
• --no-upgrade verbietet dem Channel, Upgrade-Versionen (Major) an Geräte zu senden.
• --ios erlaubt dem Channel, Versionen an iOS-Geräte zu senden.
• --no-ios verbietet dem Channel, Versionen an iOS-Geräte zu senden.
• --android erlaubt dem Channel, Versionen an Android-Geräte zu senden.
• --no-android verbietet dem Channel, Versionen an Android-Geräte zu senden.
• --self-assign erlaubt es Geräten, sich selbst diesem Channel zuzuweisen.
• --no-self-assign verhindert, dass sich Geräte selbst diesem Channel zuweisen.
• --disable-auto-update STRATEGY Deaktiviert die Auto-Update-Strategie für diesen Channel. Mögliche Optionen: major, minor, patch, metadata, none.
• --apikey [key] API Key zum Verknüpfen mit deinem Account.

Update-Strategie deaktivieren

Es gibt verschiedene Möglichkeiten, das Update für zu alte Versionen zu unterbinden.
Capgo kann native code nicht aktualisieren. Daher sollte ein Update von einer Version mit dem alten nativen code zu einer Version mit dem aktualisierten nativen code nicht möglich sein. Es gibt verschiedene Wege, dies umzusetzen.

Zuerst die major Strategie. Sie verhindert ein Update vom nativen Baseline- 0.0.0 -> Target-Bundle 1.0.0. Die Major-Version ist die hervorgehobene Zahl (1.0.0 und 0.0.0).
Zweitens ist die minor Strategie. Sie verhindert Updates, wenn das Ziel-Bundle eine andere Major- oder Minor-Version als die native Baseline des Geräts hat, wie zum Beispiel 0.0.0 -> 1.1.0 oder 1.1.0 -> 1.2.0.

Drittens die patch Strategie. Sie wurde als sehr strikter Modus in capgo hinzugefügt. Die Nutzung wird nicht empfohlen, es sei denn, du verstehst genau, wie sie funktioniert. Damit ein Update akzeptiert wird, müssen folgende Bedingungen erfüllt sein:

• Die Major-Version ist gleich zwischen dem Ziel-Bundle und version_build
• Die Minor-Version ist gleich zwischen dem Ziel-Bundle und version_build
• Die Patch-Version ist gleich zwischen dem Ziel-Bundle und version_build
• Nur das Versions-Suffix darf abweichen, wie z. B. Prerelease (-beta.2) oder Build-Metadaten (+build.2)

Hier ist ein Beispiel für Szenarien, in denen das Update erlaubt oder abgelehnt wird

• 1.0.0-beta.1 -> 1.0.0-beta.2 erlaubt
• 1.0.0+build.1 -> 1.0.0+build.2 erlaubt
• 1.0.0 -> 1.0.1 blockiert
• 1.0.0 -> 1.1.0 blockiert
• 1.0.0 -> 2.0.0 blockiert

Der Strategievergleich nutzt die native Baseline, die als version_buildgesendet wird, nicht das aktuell heruntergeladene Bundle als version_name.

Zuletzt die komplexeste Strategie. Die metadata Strategie.
Wichtig zu wissen: Direkt nach der Aktivierung schlagen die Updates WIRD fehl, da dem Channel die erforderlichen Metadaten fehlen.
Falls dem Channel die Metadaten fehlen, erscheint eine Meldung wie diese:

Wenn du so etwas siehst, musst du zum aktuellen Bundle des betroffenen Channels gehen und die Metadaten setzen.
Finde zuerst heraus, welcher Channel fehlerhaft ist. Das kannst du anhand der misconfigured Spalte

Gehe dann zum betroffenen Channel und klicke auf Bundle number. Das sollte dich zur Bundle-Seite führen.

Fülle dort das Minimal update version Feld aus. Dies sollte ein semver.
Falls der übergebene Wert kein gültiges Semver ist, erhältst du eine Fehlermeldung. Wenn alles korrekt läuft, sollte es jedoch so aussehen:

Wahrscheinlich möchtest du diese Daten nicht bei jedem Update manuell setzen. Glücklicherweise verhindert CLI, dass du ein Update ohne diese Metadaten sendest.

Um ein Bundle korrekt hochzuladen, wenn du die metadata Option nutzt, musst du ein --min-update-version mit dem gültiges Semverübergeben. Zum Beispiel so:

Der --min-update-version ist nicht der EINZIGE Weg, um Kompatibilität sicherzustellen. Es gibt auch die --auto-min-update-version. So funktioniert es.

Zuerst wird die aktuell im Channel hochgeladene Version geprüft. Dabei wird die Kompatibilität genauso geprüft, wie es der bundle compatibility Befehl tun würde. Zweitens: Wenn die neue Version zu 100 % kompatibel ist, wird die min_update_version der neuesten Version im Channel wiederverwendet. Falls nicht, wird die min_update_version auf die Bundle-Nummer der neu hochgeladenen Version gesetzt.

Du erhältst immer Informationen darüber, was der min_update_version wenn du diese Option verwendest. Es sieht dann etwa so aus:

Wenn die neue Version nicht kompatibel ist, sieht es etwa so aus:

End-to-End-Verschlüsselung (Trustless)

Capgo unterstützt End-to-End-Verschlüsselung. Das bedeutet, dass dein Bundle (code) verschlüsselt wird, bevor es in die Cloud gesendet wird, und erst auf dem Gerät wieder entschlüsselt wird. Dafür musst du ein RSA-Schlüsselpaar generieren; nutze dazu den folgenden Befehl.

Das Verschlüsselungssystem kombiniert RSA und AES: Der RSA-Schlüssel verschlüsselt den AES-Schlüssel, welcher wiederum die Datei verschlüsselt.

Weitere Informationen zum Verschlüsselungssystem findest du unten.

Verschlüsselungsschema

Key für deine App erstellen

npx @capgo/cli key create

Optional kannst du angeben: --force um den vorhandenen Schlüssel zu überschreiben. Dieser Befehl erstellt ein Schlüsselpaar für deine App und fordert dich auf, den Private Key an einem sicheren Ort zu speichern. Es wird empfohlen, den Private Key nicht per git commit zu speichern und ihn niemals mit anderen zu teilen.

Entferne nach deinen lokalen Tests den Schlüssel aus der Config-Datei und füge ihn im CI-Schritt mit folgendem Befehl hinzu: key save

Key in der App-Config speichern

npx @capgo/cli key save

Optional kannst du angeben:

--key [/path/to/my/public_key] der Pfad zu deiner Public-Key-Datei.

--key-data [publicKey] die Public-Key-Daten für die Inline-Nutzung. Dieser Befehl ist hilfreich, wenn du die Empfehlung befolgt und den Key nicht in deiner App-Config committet hast.

CI-Integration

Um deine Arbeit zu automatisieren, empfehle ich dir, die GitHub Action den Push auf unseren Server erledigen zu lassen.

GitHub Action-Tutorial

Unsere Demo-App

GitHub - Capgo/demo-app

Vergiss nicht, die CI-Umgebungsvariable mit deinem API Key zu konfigurieren.

Weiter mit Commands

Wenn du es nutzt Befehle um Dashboard- und API-Operationen zu planen, verbinde es mit API Übersicht für Details zur Implementierung im API Overview, Einführung für die Implementierungsdetails in der Einleitung, API Schlüssel für die Implementierungsdetails in API Keys, Geräte für die Implementierungsdetails in Devices und Bundles für die Implementierungsdetails in Bundles.