Comandi

Questa pagina è una panoramica guidata. Per i flag esatti, usa il riferimento comandi aggiornato: app, bundle, canale, e build.

Utilizzo

Tutti i comandi vanno eseguiti nella cartella della tua app con il progetto capacitor inizializzato correttamente.

Capacitor Runtime nativo cross-platform per web app

Init

npx @capgo/cli@latest init [apikey]

Questo metodo ti guida passo dopo passo nell'onboarding.

Aggiungerà la tua app a Capgo. Installerà il code nell'app per validare l'update. Inoltre, effettuerà la build della tua app, ne caricherà il bundle su Capgo e ti aiuterà a verificare che l'update funzioni.

Accedi

npx @capgo/cli login [apikey]

Questo metodo serve a memorizzare il apikey per te.

Nota

usa --apikey=******** in qualsiasi comando per sovrascriverlo

Opzionalmente puoi specificare:

--local Questo salverà la tua apikey nel repo locale e la aggiungerà al git ignore.

Doctor

npx @capgo/cli doctor

Comando per verificare se i pacchetti Capgo sono aggiornati.

Questo comando sarà utile anche per le segnalazioni di bug.

App

Aggiungi

npx @capgo/cli app add [appId]

[appId] l'ID della tua app nel formato com.test.app viene spiegato qui.

💡 Se non specificate, tutte le opzioni verranno rilevate dalla tua config.

Facoltativamente, puoi fornire:

• --icon [/path/to/my/icon] per visualizzare un'icona personalizzata nella web app di Capgo.
• --name [test] per avere un nome personalizzato nella lista.
• --apikey [key] la chiave API per collegarti al tuo account.
• --retention [retention] periodo di retention del bundle dell'app in giorni, 0 di default = infinito.

Esempio di capacitor.config.json per appId e AppName, l'icona viene rilevata dalla cartella resources

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

Imposta

npx @capgo/cli app set [appId]

[appId] è l'ID della tua app, il formato è spiegato qui.

Facoltativamente, puoi fornire:

• --icon [/path/to/my/icon] per visualizzare un'icona personalizzata nella web app di Capgo.
• --name [test] per avere un nome personalizzato nella lista.
• --retention [retention] periodo di retention del bundle dell'app in giorni, 0 di default = infinito.
• --expose-metadata [true|false] per esporre i metadati del bundle (link e commento) al plugin.
• --preview o --no-preview per abilitare o disabilitare i QR code di anteprima per bundle e channel.
• --allow-device-custom-id o --no-allow-device-custom-id per gestire gli ID personalizzati dei dispositivi.
• --block-provider-infra-requests o --no-block-provider-infra-requests per controllare il blocco delle richieste dai datacenter noti di Google e Apple.
• --build-timeout-minutes [5-360] per impostare il timeout del Native Build.
• --ios-store-url [url] o --android-store-url [url] per impostare l'URL dello store.
• --default-upload-channel [channel] per impostare il canale di upload predefinito.
• --default-download-channel [channel] per impostare il canale di download predefinito, oppure --disable-download-channels per rendere tutti i canali di download non pubblici.
• --apikey [key] la chiave API per collegarti al tuo account.

Elenco

npx @capgo/cli app list [appId]

[appId] l'ID della tua app nel formato com.test.app viene spiegato qui.

Facoltativamente, puoi fornire:

• --apikey [key] la chiave API per collegarti al tuo account.

Elimina

npx @capgo/cli app delete [appId]

[appId] l'ID della tua app nel formato com.test.app viene spiegato qui.

Facoltativamente, puoi fornire:

• --apikey [key] la chiave API per collegarti al tuo account.
• --bundle con il numero di versione eliminerà solo questa versione.

Debug

npx @capgo/cli app debug [appId]

[appId] l'ID della tua app nel formato com.test.app viene spiegato qui.

Facoltativamente, puoi fornire:

• --apikey [key] la chiave API per collegarti al tuo account.
• --device con il dispositivo specifico che vuoi debuggare

Impostazione

npx @capgo/cli app setting [path]

Modifica la configurazione di Capacitor.

[path] - percorso dell'impostazione che vuoi cambiare. Ad esempio, per cambiare il appId, fornisci appId. Se desideri disabilitare l'auto update nella capacitor-updater, fornisci plugins.CapacitorUpdater.autoUpdate con --string off.

DEVI fornire uno tra --string o --bool!

Opzioni:

• --string <string> - imposta l'opzione come stringa
• --bool <true | false> - imposta l'opzione come boolean

Bundle

Carica

npx @capgo/cli bundle upload [appId]

[appId] è l'ID della tua app, il formato è spiegato qui.

Facoltativamente, puoi fornire:

• --apikey <apikey> la chiave API per collegarti al tuo account.
• --path <path> Percorso della cartella da caricare.
• --channel <channel> Channel da collegare.
• --external <url> Collega a un URL esterno invece di caricare su Capgo Cloud.
• --iv-session-key <key> Imposta l'IV e la session key per l'URL esterno del bundle.
• --s3-endpoint <s3Endpoint> URL dell'endpoint S3. Non funziona con delta upload o l'opzione esterna.
• --s3-region <region> Regione del tuo bucket S3.
• --s3-apikey <apikey> Chiave API per il tuo endpoint S3.
• --s3-apisecret <apisecret> Segreto API per il tuo endpoint S3.
• --s3-bucket-name <bucketName> Nome del tuo bucket AWS S3.
• --s3-port <port> Porta per il tuo endpoint S3.
• --no-s3-ssl Disabilita SSL per l'upload su S3.
• --key <key> Percorso personalizzato per la public signing key (sistema v1).
• --key-data <keyData> Public signing key (sistema v1).
• --key-v2 <key> Percorso personalizzato per la private signing key (sistema v2).
• --key-data-v2 <keyData> Private signing key (sistema v2).
• --bundle-url Stampa l'URL del bundle su stdout.
• --no-key Ignora la signing key e invia l'update in chiaro.
• --no-code-check Ignora il controllo su notifyAppReady() nel codice code e sulla presenza di index nella root folder.
• --display-iv-session Mostra in console l'IV e la session key usati per criptare l'update.
• --bundle <bundle> Numero di versione del bundle da caricare.
• --auto-bump [level] Auto-incrementa dal bundle collegato al canale, o dall'ultima versione remota dell'app. Level: major, minor (default), patch (alias fix), metadata, o ai (Workers AI confronta i file locali con il delta manifest di Capgo/channel, inferisce il livello e logga il motivo; salta l'AI e incrementa patch se non c'è una versione Capgo precedente). Incrementa finché non trova un nome libero (i nomi eliminati restano occupati). Non combinabile con --bundle.
• --min-update-version <minUpdateVersion> Versione minima richiesta per aggiornare a questa versione. Usata solo se il disable auto update è impostato su metadata nel canale.
• --auto-min-update-version Imposta la versione minima di update basata sui pacchetti nativi.
• --ignore-metadata-check Ignora il controllo dei metadata (node_modules) durante l'upload.
• --ignore-checksum-check Ignora il controllo del checksum durante l'upload.
• --timeout <timeout> Timeout per il processo di upload in secondi.
• --delta Carica i file Delta (manifest) insieme al bundle completo.
• --delta-only Carica solo gli aggiornamenti Delta (manifest), saltando il bundle completo.
• --no-delta Disabilita il caricamento dei file Delta (manifest) (utile se la modalità autoUpdate instant apply è attiva ma vuoi un bundle completo).
• --tus Carica il bundle usando il protocollo tus.
• --multipart Usa il protocollo multipart per caricare i dati su S3. Deprecato, usa TUS.
• --encrypted-checksum <encryptedChecksum> Un checksum crittografato (firma). Usato solo quando si carica un bundle esterno.
• --package-json <packageJson> Il percorso di package.json. Utile per i monorepo.
• --auto-set-bundle Imposta il bundle in capacitor.config.json.
• --node-modules <nodeModules> Un elenco di percorsi verso node_modules. Utile per i monorepo (separati da virgola es: ../../node_modules,./node_modules)

⭐️ L'opzione External aiuta in 2 casi: aziende con esigenze di privacy (non inviare code a terze parti) e app più grandi di 200 MB. Con questa impostazione, Capgo salva solo il link allo zip e lo invia a tutte le app.

👀 Il cloud di Capgo non analizza mai il contenuto del link (con l'opzione external) o di code una volta memorizzato.

🔑 Puoi aggiungere un secondo livello di sicurezza tramite crittografia: in questo modo Capgo non potrà né vedere né modificare nulla, rendendo il sistema “trustless”.

Esempio di package.json per la versione

{
  "version": "1.0.2"
}

⛔ La versione deve essere superiore a “0.0.0”.

💡 Ricorda di aggiornare il numero di versione ogni volta che ne invii uno: per motivi di sicurezza, il numero di versione non può essere sovrascritto o riutilizzato dopo l'eliminazione.

Elenco

npx @capgo/cli bundle list [appId]

[appId] l'ID della tua app nel formato com.test.app viene spiegato qui.

Facoltativamente, puoi fornire:

• --apikey [key] la chiave API per collegarti al tuo account.

Elimina

npx @capgo/cli bundle delete [appId]

[appId] l'ID della tua app nel formato com.test.app viene spiegato qui.

Facoltativamente, puoi fornire:

• --apikey [key] la chiave API per collegarti al tuo account.
• --bundle con il numero di versione eliminerà solo questa versione.

Pulizia

in un range SemVer per una versione major su Cloud

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

[appId] l'ID della tua app nel formato com.test.app viene spiegato qui.

Facoltativamente, puoi fornire:

• --apikey [key] la chiave API per collegarti al tuo account.
• --bundle [majorVersion] la versione per cui vuoi rimuovere i pacchetti precedenti, verrà mantenuto l'ultimo + numberToKeep.
• --keep [numberToKeep] il numero di pacchetti che vuoi mantenere (default 4).

Per esempio: se hai 10 versioni da 10.0.1 a 10.0.11 e usi npx @capgo/cli cleanup [appId] --bundle=10.0.0 rimuoverà dalla 10.0.1 alla 10.0.6. Verranno mantenute dalla 10.0.7 alla 10.0.11.

Se hai 20 versioni in totale e non indichi un numero di bundle come in questo caso: npx @capgo/cli cleanup [appId] --keep=2 Rimuoverà 18 versioni e manterrà le ultime 2.

Il comando chiederà conferma e mostrerà una tabella con ciò che verrà mantenuto e rimosso.

Nota

Questo comando ignorerà i bundle attualmente in uso in qualsiasi canale.

Encrypt

Attenzione: Questo comando è deprecato e verrà rimosso nel prossimo major release. Usa il nuovo sistema di crittografia. npx @capgo/cli bundle encrypt [path/to/zip]

Questo comando si usa quando utilizzi una sorgente esterna per i tuoi code o per scopi di test.

Facoltativamente, puoi fornire:

--key [/path/to/my/private_key] il percorso della tua chiave privata. --key-data [privateKey] i dati della chiave privata, se vuoi usarla inline. Il comando stamperà la tua ivSessionKeyy e genererà una zip criptata, da usare con il comando upload o decryt command.

Crittografia V2

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

Questo comando si usa quando utilizzi una sorgente esterna per archiviare i tuoi code o per scopi di test. Il checksum è lo sha256 del bundle (generato da —key-v2) ed è usato per verificare l'integrità del file dopo la decrittazione. Verrà crittografato con la chiave privata e inviato insieme al bundle. Con la versione 2 della crittografia, il checksum viene aggiornato per diventare una “firma” del bundle.

Facoltativamente, puoi fornire:

--key [/path/to/my/private_key] il percorso della tua chiave privata. --key-data [privateKey] i dati della chiave privata, se vuoi usarli inline. --json per outputtare le info in json. Il comando stamperà il tuo ivSessionKeyy e genererà uno zip crittografato, da usare con il comando upload o decryt.

Decrypt

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

Facoltativamente, puoi fornire:

--key [/path/to/my/private_key] il percorso della tua chiave privata.

--key-data [privateKey] i dati della chiave privata, se vuoi usarli inline. Questo comando è usato principalmente per test: decripta lo zip e stampa la session key decriptata in base64 nella console.

Decripta V2

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

Facoltativamente, puoi fornire:

--key [/path/to/my/private_key] il percorso della tua chiave privata. --key-data [privateKey] i dati della chiave privata, se vuoi usarli inline. Questo comando è usato principalmente per test: decripta lo zip e stampa la session key decriptata in base64 nella console. --checksum [checksum] il checksum del file; verificherà il checksum dopo la decriptazione.

Zip

npx @capgo/cli bundle zip [appId]

[appId] è l'ID della tua app, il formato è spiegato qui.

Facoltativamente, puoi fornire:

• --path [/path/to/my/bundle] per caricare una cartella specifica.
• --bundle [1.0.0] per impostare il numero di versione del bundle nel nome del file.
• --name [myapp] per sovrascrivere il nome del file.
• --json per restituire le info in formato json.
• --no-code-check per ignorare il controllo code e inviare comunque il bundle.
• --key-v2 per usare il nuovo sistema di crittografia. Necessario poiché il nuovo sistema usa checksum migliori per verificare l'integrità del file.

Compatibilità

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

[appId] è l'ID della tua app, il formato è spiegato qui. [channelName] il nome del channel da controllare.

Facoltativamente, puoi fornire:

• --apikey [key] la chiave API per collegarti al tuo account.
• --text usa il testo invece delle emoji nella tabella
• --channel [channel] il canale per verificarne la compatibilità.
• --package-json <packageJson> Il percorso verso package.json. Utile per i monorepo
• --node-modules <nodeModules> Un elenco di percorsi verso node_modules. Utile per i monorepo (separati da virgola es: ../../node_modules,./node_modules)

Canale

Aggiungi

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

[channelName] il nome del tuo nuovo canale, come ad esempio production o beta. [appId] l'ID della tua app nel formato com.test.app viene spiegato qui.

Elimina

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

[channelName] il nome del canale che desideri eliminare. [appId] l'ID della tua app nel formato com.test.app viene spiegato qui.

Elenco

npx @capgo/cli channel list [appId]

[appId] l'ID della tua app nel formato com.test.app viene spiegato qui.

Facoltativamente, puoi fornire:

• --apikey [key] la chiave API per collegarti al tuo account.

Imposta

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

[appId] è l'ID della tua app, il formato è spiegato qui. [channelName] il nome del canale che vuoi configurare, ad esempio production o beta.

Facoltativamente, puoi fornire:

• --bundle [1.2.3] il bundle della tua app già inviato al cloud, per collegarlo a un canale.
• --latest recupera la versione del bundle da package.json:version, non può essere usato con --bundle.
• --state [ normal | default ] imposta lo stato del canale, può essere normal o default. Un canale deve essere default.
• --downgrade permette al canale di inviare versioni inferiori ai dispositivi.
• --no-downgrade impedisce al canale di inviare versioni inferiori ai dispositivi.
• --upgrade permette al canale di inviare versioni superiori (major) ai dispositivi.
• --no-upgrade impedisce al canale di inviare versioni superiori (major) ai dispositivi.
• --ios permette al canale di inviare la versione ai dispositivi iOS.
• --no-ios impedisce al canale di inviare la versione ai dispositivi iOS.
• --android permette al canale di inviare la versione ai dispositivi Android.
• --no-android impedisce al canale di inviare la versione ai dispositivi Android.
• --self-assign permette ai dispositivi di auto-assegnarsi a questo canale.
• --no-self-assign impedisce ai dispositivi di auto-assegnarsi a questo canale.
• --disable-auto-update STRATEGY Disabilita la strategia di auto-update per questo canale. Le opzioni possibili sono: major, minor, patch, metadata, none.
• --apikey [key] la chiave API per collegarti al tuo account.

Disabilita la strategia di update

Ci sono alcuni modi per gestire la disabilitazione degli update per le versioni troppo vecchie.
Capgo non può aggiornare il code nativo; pertanto, un update da una versione con il vecchio code nativo a una con il code nativo aggiornato non dovrebbe essere possibile. Esistono un paio di modi per farlo.

Innanzitutto, la major strategia. Impedisce un update dalla baseline nativa 0.0.0 -> bundle di destinazione 1.0.0. Il major è il numero evidenziato (1.0.0 e 0.0.0).
La seconda è la minor strategia. Impedisce un aggiornamento quando il bundle di destinazione ha una major o minor diversa dalla baseline nativa del dispositivo, ad esempio 0.0.0 -> 1.1.0 o 1.1.0 -> 1.2.0.

La terza è la patch strategia. È stata aggiunta in capgo come modalità molto rigorosa. Se ne sconsiglia l'uso a meno che non se ne comprenda appieno il funzionamento. Per accettare un aggiornamento, devono essere soddisfatte le seguenti condizioni:

• La major è la stessa tra il bundle di destinazione e version_build
• La minor è la stessa tra il bundle di destinazione e version_build
• La patch è la stessa tra il bundle di destinazione e version_build
• Può differire solo il suffisso della versione, come prerelease (-beta.2) o i metadati di build (+build.2)

Ecco un esempio degli scenari in cui l'aggiornamento è consentito o negato

• 1.0.0-beta.1 -> 1.0.0-beta.2 consentito
• 1.0.0+build.1 -> 1.0.0+build.2 consentito
• 1.0.0 -> 1.0.1 bloccato
• 1.0.0 -> 1.1.0 bloccato
• 1.0.0 -> 2.0.0 bloccato

Il confronto della strategia usa il baseline nativo inviato come version_build, non l'attuale bundle scaricato inviato come version_name.

Infine, la strategia più complessa. La metadata strategia.
Innanzitutto, tieni presente che inizialmente, dopo averle abilitate, le update SERVIRÀ falliscono perché il canale non ha i metadati richiesti.
Se al canale mancano i metadati, vedrai un messaggio come questo:

Se visualizzi un errore del genere, devi andare al bundle attuale del canale interessato e impostare i metadati.
Per prima cosa, identifica il canale che sta fallendo. Puoi farlo controllando la misconfigured colonna

Poi vai al canale che fallisce e clicca su Bundle number. Verrai indirizzato alla pagina del bundle.

Una volta lì, compila il campo Minimal update version campo. Dovrebbe essere un semver.
Se il valore passato non è un semver riceverai un errore, ma se tutto procede correttamente vedrai qualcosa di simile:

Probabilmente non vorrai inserire questo dato manualmente ogni volta che aggiorni. Fortunatamente, CLI ti impedirà di inviare un aggiornamento senza questi metadati

Per caricare correttamente un bundle usando l'opzione metadata opzione da passare per il --min-update-version con il semver valido. Qualcosa di simile:

Il --min-update-version non è l'UNICO modo per gestire la compatibilità. Esiste anche il --auto-min-update-version. Ecco come funziona.

Per prima cosa, controlla la versione attualmente caricata sul canale. Verifica la compatibilità proprio come farebbe il bundle compatibility comando. In secondo luogo, se la nuova versione è compatibile al 100%, riutilizza il min_update_version dall'ultima versione disponibile nel channel.\nIn caso contrario, imposta il min_update_version al numero del bundle della nuova versione caricata.

Riceverai sempre informazioni su cosa sia il min_update_version usando questa opzione. Sarà simile a questo:

Se la nuova versione non è compatibile, l'errore apparirà simile a questo

Crittografia End-to-End (Trustless)

Capgo supporta la crittografia end-to-end: questo significa che il tuo bundle (code) viene crittografato prima dell'invio al cloud e decrittografato sul dispositivo. Per farlo, devi generare una coppia di chiavi RSA; puoi usare il seguente comando per generarla.

Il sistema di crittografia combina RSA e AES: la chiave RSA viene usata per crittografare la chiave AES, che a sua volta viene usata per crittografare il file.

Leggi sotto per maggiori informazioni sul sistema di crittografia.

Schema di crittografia

Crea la chiave per la tua app

npx @capgo/cli key create

Facoltativamente, puoi fornire: --force per sovrascrivere la chiave esistente. Questo comando genererà una coppia di chiavi per la tua app e ti chiederà di salvare la chiave privata in un luogo sicuro. Si raccomanda di non fare il git commit della chiave privata e di non condividerla con nessuno.

Dopo i test locali, rimuovi la chiave dal file di configurazione e aggiungila alla pipeline CI con key save

Salva la chiave nella config della tua app

npx @capgo/cli key save

Facoltativamente, puoi fornire:

--key [/path/to/my/public_key] il percorso del file della tua chiave pubblica.

--key-data [publicKey] i dati della chiave pubblica, se vuoi usarli inline. Questo comando è utile se hai seguito il consiglio e non hai committato la chiave nella config della tua app.

Integrazione CI

Per automatizzare il lavoro, ti consiglio di far eseguire all'action di GitHub il push sul nostro server

Tutorial sull'action GitHub

La nostra demo app

GitHub - Cap-go/demo-app

Non dimenticare di configurare la variabile d'ambiente CI con la tua chiave API

Continua con i comandi

Se stai usando Comandi per pianificare le operazioni della dashboard e di API, collegalo a Panoramica API per i dettagli di implementazione in Panoramica di API, Introduzione per i dettagli di implementazione in Introduzione, Chiavi API per i dettagli di implementazione delle chiavi API, Dispositivi per i dettagli di implementazione in Devices, e Bundle per il dettaglio di implementazione in Bundles.