Comandos

Esta página es una guía general. Consulta la referencia de comandos para ver los flags exactos: app, bundle, channel, y build.

Uso

Todos los comandos deben ejecutarse en la carpeta de tu app con el proyecto capacitor correctamente iniciado.

Capacitor Runtime nativo multiplataforma para web apps

Init

npx @capgo/cli@latest init [apikey]

Este método te guiará paso a paso en el onboarding.

Añadirá tu app a Capgo. Agregará el code a tu app para validar la actualización. Asimismo, hará el build de tu app. Además, hará el upload de tu app a Capgo. Y te ayudará a verificar si la actualización funciona.

Login

npx @capgo/cli login [apikey]

Este método sirve para recordar el apikey por ti.

Nota

usar --apikey=******** en cualquier comando para sobrescribirlo

Opcionalmente puedes proporcionar:

--local Esto guardará tu apikey en el repo local y lo añadirá al git ignore.

Doctor

npx @capgo/cli doctor

Comando para verificar si tienes los paquetes Capgo actualizados.

Este comando también será útil para reportar bugs.

App

Añade

npx @capgo/cli app add [appId]

[appId] el ID de tu app con el formato com.test.app se explica aquí.

💡 Si no se proporcionan, todas las opciones se detectarán desde tu config.

Opcionalmente, puedes indicar:

• --icon [/path/to/my/icon] para mostrar un icono personalizado en la web app de Capgo.
• --name [test] para usar un nombre personalizado en la lista.
• --apikey [key] la clave de API para vincularla con tu cuenta.
• --retention [retention] periodo de retención del bundle en días; 0 por defecto = infinito.

Ejemplo de capacitor.config.json para appId y AppName, el icono se detecta en la carpeta de resources

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

Configurar

npx @capgo/cli app set [appId]

[appId] es el ID de tu app, el formato se explica aquí.

Opcionalmente, puedes definir:

• --icon [/path/to/my/icon] para mostrar un icono personalizado en la web app de Capgo.
• --name [test] para tener un nombre personalizado en la lista.
• --retention [retention] periodo de retención del bundle en días, 0 por defecto = infinito.
• --expose-metadata [true|false] para exponer los metadatos del bundle (link y comment) al plugin.
• --preview o --no-preview para activar o desactivar los QR codes de preview de bundle y channel.
• --allow-device-custom-id o --no-allow-device-custom-id para controlar los IDs de dispositivos personalizados.
• --block-provider-infra-requests o --no-block-provider-infra-requests para controlar el bloqueo de peticiones de datacenters conocidos de Google y Apple.
• --build-timeout-minutes [5-360] para establecer el timeout del Native Build.
• --ios-store-url [url] o --android-store-url [url] para configurar la URL de la tienda.
• --default-upload-channel [channel] para establecer el canal de upload por defecto.
• --default-download-channel [channel] para establecer el canal de download por defecto, o --disable-download-channels para hacer que todos los canales de download sean privados.
• --apikey [key] API clave para vincular tu cuenta.

Lista

npx @capgo/cli app list [appId]

[appId] el ID de tu app con el formato com.test.app se explica aquí.

Opcionalmente, puedes añadir:

• --apikey [key] la clave API para vincularla con tu cuenta.

Eliminar

npx @capgo/cli app delete [appId]

[appId] el ID de tu app con el formato com.test.app se explica aquí.

Opcionalmente, puedes añadir:

• --apikey [key] la clave API para vincularla con tu cuenta.
• --bundle con el número de versión solo eliminará esta versión.

Depuración

npx @capgo/cli app debug [appId]

[appId] el formato de tu app ID com.test.app se explica aquí.

Opcionalmente, puedes indicar:

• --apikey [key] la clave API para vincularla con tu cuenta.
• --device con el dispositivo específico que quieras depurar

Configuración

npx @capgo/cli app setting [path]

Edita la configuración de Capacitor.

[path] - la ruta del ajuste que quieras cambiar. Por ejemplo, para cambiar el appId, proporciona appId. Si quieres desactivar el auto update en el capacitor-updater, proporciona plugins.CapacitorUpdater.autoUpdate con --string off.

DEBES proporcionar uno de los siguientes --string o --bool!

Opciones:

• --string <string> - establece el ajuste como un string
• --bool <true | false> - establece el ajuste como un boolean

Bundle

Upload

npx @capgo/cli bundle upload [appId]

[appId] es el ID de tu app; el formato se explica aquí.

Opcionalmente, puedes indicar:

• --apikey <apikey> la clave API para vincularla con tu cuenta.
• --path <path> Ruta de la carpeta a subir.
• --channel <channel> Channel al que vincular.
• --external <url> Enlace a una URL externa en vez de subir a Capgo Cloud.
• --iv-session-key <key> Establece el IV y la session key para la URL externa del bundle.
• --s3-endpoint <s3Endpoint> URL del endpoint de S3. No funciona con delta uploads ni con la opción externa.
• --s3-region <region> Región de tu bucket de S3.
• --s3-apikey <apikey> Clave API para tu endpoint de S3.
• --s3-apisecret <apisecret> Secreto API para tu endpoint de S3.
• --s3-bucket-name <bucketName> Nombre de tu bucket de AWS S3.
• --s3-port <port> Puerto para tu endpoint de S3.
• --no-s3-ssl Desactivar SSL para la subida a S3.
• --key <key> Ruta personalizada para la clave pública (sistema v1).
• --key-data <keyData> Clave pública de firma (sistema v1).
• --key-v2 <key> Ruta personalizada para la clave privada (sistema v2).
• --key-data-v2 <keyData> Clave privada de firma (sistema v2).
• --bundle-url Imprime la URL del bundle en stdout.
• --no-key Ignora la clave de firma y envía la actualización sin cifrar.
• --no-code-check Ignorar la comprobación de notifyAppReady() en code e index en la raíz.
• --display-iv-session Muestra en consola el IV y la session key usados para cifrar la actualización.
• --bundle <bundle> Número de versión del bundle a subir.
• --auto-bump [level] Auto-incrementa desde el bundle del canal o la última versión remota. Nivel: major, minor (por defecto), patch (alias fix), metadata, o ai (Workers AI compara archivos locales con el manifiesto delta de Capgo/channel, infiere el nivel y registra el motivo; salta la IA y aumenta patch si no hay versión previa de Capgo. Aumenta hasta hallar un nombre libre (los nombres borrados siguen ocupados). No se puede combinar con --bundle.
• --min-update-version <minUpdateVersion> Versión mínima para actualizar a esta versión. Solo se usa si el auto-update está en 'metadata' en el canal.
• --auto-min-update-version Establece la versión mínima de actualización según los paquetes nativos.
• --ignore-metadata-check Ignora la comprobación de metadatos (node_modules) al subir.
• --ignore-checksum-check Ignora la comprobación de checksum al subir.
• --timeout <timeout> Tiempo de espera para el proceso de upload en segundos.
• --delta Sube archivos Delta (manifest) junto al bundle completo.
• --delta-only Sube solo actualizaciones Delta (manifest), omitiendo el bundle completo.
• --no-delta Desactiva la subida de archivos Delta (manifest) (útil si el modo autoUpdate instant apply está activo pero prefieres un bundle completo).
• --tus Sube el bundle usando el protocolo tus.
• --multipart Usa el protocolo multipart para subir datos a S3. Deprecated, usa TUS.
• --encrypted-checksum <encryptedChecksum> Un checksum cifrado (firma). Solo se usa al subir un bundle externo.
• --package-json <packageJson> Ruta al package.json. Útil para monorepos.
• --auto-set-bundle Establece el bundle en capacitor.config.json.
• --node-modules <nodeModules> Lista de rutas a node_modules. Útil para monorepos (separadas por comas: ../../node_modules,./node_modules)

⭐️ La opción External ayuda en 2 casos: empresas con privacidad estricta que no envían el code a terceros, y apps de más de 200 MB. Con esto, Capgo solo guarda el link al zip y lo envía a las apps.

👀 Capgo cloud nunca revisa el contenido del link (con la opción external), ni lo que hay en code al almacenarlo.

🔑 Puedes añadir una segunda capa de seguridad mediante cifrado; así, Capgo no podrá ver ni modificar nada, volviéndose un sistema “trustless”.

Ejemplo de package.json para la versión

{
  "version": "1.0.2"
}

⛔ La versión debe ser superior a “0.0.0”.

💡 No olvides actualizar el número de versión cada vez que envíes una; por seguridad, no se puede sobrescribir ni reutilizar tras eliminarla.

Listar

npx @capgo/cli bundle list [appId]

[appId] el formato de tu app ID com.test.app se explica aquí.

Opcionalmente, puedes indicar:

• --apikey [key] la clave API para vincularla con tu cuenta.

Eliminar

npx @capgo/cli bundle delete [appId]

[appId] el formato de tu app ID com.test.app se explica aquí.

Opcionalmente, puedes indicar:

• --apikey [key] la clave API para vincularla con tu cuenta.
• --bundle con el número de versión solo eliminará esta versión.

Limpieza

en un rango SemVer para una versión mayor en Cloud

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

[appId] el formato de tu app ID com.test.app se explica aquí.

Opcionalmente, puedes indicar:

• --apikey [key] la clave API para vincularla con tu cuenta.
• --bundle [majorVersion] una versión para la cual quieras eliminar paquetes anteriores; conservará la última + numberToKeep.
• --keep [numberToKeep] el número de paquetes que desees mantener (por defecto 4).

Por ejemplo: si tienes 10 versiones de la 10.0.1 a la 10.0.11, y usas npx @capgo/cli cleanup [appId] --bundle=10.0.0 eliminará de la 10.0.1 a la 10.0.6. Se mantendrán de la 10.0.7 a la 10.0.11.

Si tienes 20 versiones en total y no especificas un número de bundle así: npx @capgo/cli cleanup [appId] --keep=2 Eliminará 18 versiones y mantendrá las últimas 2.

Este comando pedirá confirmación y mostrará una tabla con lo que se mantendrá y eliminará.

Nota

Este comando ignorará los bundles que estén actualmente en uso en cualquier canal.

Encrypt

Advertencia: Este comando está deprecado y se eliminará en la próxima versión mayor. Por favor, usa el nuevo sistema de cifrado. npx @capgo/cli bundle encrypt [path/to/zip]

Este comando se usa cuando utilizas una fuente externa para almacenar tu code o con fines de prueba.

Opcionalmente, puedes indicar:

--key [/path/to/my/private_key] la ruta de tu clave privada. --key-data [privateKey] los datos de la clave privada, si quieres usarlos inline. El comando imprimirá tu ivSessionKeyy generará un zip cifrado para usarlo con el comando upload o el comando decrypt.

Encriptar V2

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

Este comando se usa cuando utilizas una fuente externa para guardar tu code o para pruebas. El checksum es el sha256 del bundle (generado por —key-v2) y sirve para verificar la integridad del archivo tras el descifrado. Se cifrará con la clave privada y se enviará junto al bundle. En la versión v2 de cifrado, el checksum se mejora para convertirse en una “firma” del bundle.

Opcionalmente, puedes indicar:

--key [/path/to/my/private_key] la ruta de tu clave privada. --key-data [privateKey] los datos de la clave privada, si quieres usarlos inline. --json para mostrar la info como json. El comando imprimirá tu ivSessionKeyy generará un zip cifrado para usarlo con el comando upload o el comando decrypt.

Decrypt

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

Opcionalmente, puedes indicar:

--key [/path/to/my/private_key] la ruta de tu clave privada.

--key-data [privateKey] los datos de la clave privada, si quieres usar inline. Este comando se usa principalmente para pruebas; descifra el zip e imprime la session key en base64 en la consola.

Desencriptar V2

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

Opcionalmente, puedes indicar:

--key [/path/to/my/private_key] la ruta de tu clave privada. --key-data [privateKey] los datos de la clave privada, si quieres usar inline. Este comando se usa principalmente para pruebas; descifra el zip e imprime la session key en base64 en la consola. --checksum [checksum] el checksum del archivo; verificará el checksum tras el descifrado.

Zip

npx @capgo/cli bundle zip [appId]

[appId] es el ID de tu app; el formato se explica aquí.

Opcionalmente, puedes indicar:

• --path [/path/to/my/bundle] para subir una carpeta específica.
• --bundle [1.0.0] para establecer el número de versión del bundle en el nombre del archivo.
• --name [myapp] para sobrescribir el nombre del archivo.
• --json para mostrar la información en formato JSON.
• --no-code-check para ignorar la comprobación de code y enviar el bundle de todos modos.
• --key-v2 para usar el nuevo sistema de cifrado. Es necesario ya que utiliza mejores checksums para verificar la integridad del archivo.

Compatibilidad

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

[appId] es el ID de tu app; el formato se explica aquí. [channelName] el nombre del channel a consultar.

Opcionalmente, puedes indicar:

• --apikey [key] la clave API para vincularla con tu cuenta.
• --text usa texto en lugar de emojis en la tabla
• --channel [channel] el canal para verificar la compatibilidad.
• --package-json <packageJson> Una ruta al package.json. Útil para monorepos
• --node-modules <nodeModules> Una lista de rutas a node_modules. Útil para monorepos (separadas por comas ej: ../../node_modules,./node_modules)

Canal

Añadir

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

[channelName] el nombre de tu nuevo canal, como production o beta. [appId] el formato de tu app ID com.test.app se explica aquí.

Eliminar

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

[channelName] el nombre del channel que quieras eliminar. [appId] el formato de tu app ID com.test.app se explica aquí.

Listar

npx @capgo/cli channel list [appId]

[appId] el formato de tu app ID com.test.app se explica aquí.

Opcionalmente, puedes indicar:

• --apikey [key] la clave API para vincularla con tu cuenta.

Configurar

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

[appId] es el ID de tu app, el formato se explica aquí. [channelName] el nombre del channel que quieras configurar, como production o beta.

Opcionalmente, puedes indicar:

• --bundle [1.2.3] tu bundle de la app ya enviado a la nube, para vincularlo a un channel.
• --latest obtén la versión del bundle desde package.json:version, no se puede usar con --bundle.
• --state [ normal | default ] establecer el estado del channel, puede ser normal o default. Un channel debe ser default.
• --downgrade permite que el channel envíe versiones downgrade a los dispositivos.
• --no-downgrade impide que el channel envíe versiones downgrade a los dispositivos.
• --upgrade permite que el channel envíe versiones upgrade (major) a los dispositivos.
• --no-upgrade impide que el channel envíe versiones upgrade (major) a los dispositivos.
• --ios permite que el channel envíe la versión a dispositivos iOS.
• --no-ios impide que el channel envíe la versión a dispositivos iOS.
• --android permite que el channel envíe la versión a dispositivos Android.
• --no-android impide que el channel envíe la versión a dispositivos Android.
• --self-assign permite que los dispositivos se asignen solos a este canal.
• --no-self-assign impide que los dispositivos se asignen solos a este canal.
• --disable-auto-update STRATEGY Desactiva la estrategia de auto update para este canal. Las opciones son: major, minor, patch, metadata, none.
• --apikey [key] la clave API para vincularla con tu cuenta.

Desactivar estrategia de updates

Hay varias formas de gestionar la desactivación de updates para versiones muy antiguas.
Capgo no puede actualizar el code nativo, por lo que no debería ser posible pasar de una versión con el code nativo antiguo a una con el code nativo actualizado. Existen un par de formas de lograrlo.

Primero, la major estrategia. Evita un update desde el baseline nativo 0.0.0 -> bundle de destino 1.0.0. El major es el número resaltado (1.0.0 y 0.0.0).
La segunda es la minor estrategia. Evita actualizaciones si el bundle de destino tiene una versión major o minor distinta a la base nativa del dispositivo, como 0.0.0 -> 1.1.0 o 1.1.0 -> 1.2.0.

Tercero, la patch estrategia. Se añadió a capgo como un modo muy estricto. No se recomienda su uso a menos que entiendas perfectamente cómo funciona. Para que acepte una actualización, deben cumplirse las siguientes condiciones:

• La major es la misma entre el bundle de destino y version_build
• La minor es la misma entre el bundle de destino y version_build
• La patch es la misma entre el bundle de destino y version_build
• Solo puede variar el sufijo de la versión, como un prerelease ("-beta.2") o metadatos de build ("+build.2)

Aquí tienes un ejemplo de en qué escenarios se permite o deniega la actualización

• Permitido: 1.0.0-beta.1 -> 1.0.0-beta.2
• Permitido: 1.0.0+build.1 -> 1.0.0+build.2
• Bloqueado: 1.0.0 -> 1.0.1
• Bloqueado: 1.0.0 -> 1.1.0
• Bloqueado: 1.0.0 -> 2.0.0

La comparación de la estrategia usa el baseline nativo enviado como version_build, no el bundle descargado actualmente enviado como version_name.

Por último, la estrategia más compleja. La metadata estrategia.
Primero debes saber que, tras activarlo, las actualizaciones FALLARÁN ya que al canal le falta la metadata requerida.
Si al canal le falta metadata, verás un mensaje como este:

Si ves algo así, significa que debes ir al bundle actual del canal con error y configurar la metadata.
Primero, identifica qué canal está fallando. Puedes hacerlo revisando la misconfigured columna

Luego, ve al canal que falla y haz clic en Bundle number. Esto te llevará a la página del bundle.

Una vez allí, completa el campo Minimal update version campo. Debería ser un semver.
Si el valor que pasas no es un semver recibirás un error, pero si todo sale bien deberías ver algo como esto:

Probablemente no quieras configurar esto manualmente cada vez que actualices. Por suerte, CLI evitará que envíes un update sin estos metadatos

Para hacer el upload de un bundle correctamente usando la metadata opción, necesitas pasar el --min-update-version con el semver válido. Algo como esto:

El --min-update-version no es la ÚNICA forma de gestionar la compatibilidad. También existe la --auto-min-update-version. Así es como funciona.

Primero, analiza la versión que está subida actualmente al channel. Comprueba la compatibilidad de la misma forma que bundle compatibility comando haría. Segundo, si la nueva versión es 100% compatible, reutiliza el min_update_version de la última versión en el channel. Si no, establece el min_update_version al número de bundle de la nueva versión subida.

Siempre recibirás información sobre cuál es la min_update_version when using this option. It will look something like this:

Si la nueva versión no es compatible, se verá algo así:

Cifrado de extremo a extremo (Trustless)

Capgo soporta cifrado de extremo a extremo; esto significa que tu bundle (code) se cifra antes de enviarse a la nube y se descifra en el dispositivo. Para ello, debes generar un par de claves RSA; puedes usar el siguiente comando para generarlo.

El sistema de cifrado combina RSA y AES: la clave RSA se usa para cifrar la clave AES, y la clave AES se usa para cifrar el archivo.

Consulta abajo más información sobre el sistema de cifrado.

Esquema de cifrado

Crear clave para tu app

npx @capgo/cli key create

Opcionalmente, puedes indicar: --force para sobrescribir la clave existente. Este comando creará un par de claves en tu app y te pedirá que guardes la clave privada en un lugar seguro. Se recomienda no hacer git commit de la clave privada y no compartirla con nadie.

Tras tus pruebas locales, elimina la clave del archivo de configuración y añádela al paso de CI con key save

Guardar clave en la config de tu app

npx @capgo/cli key save

Opcionalmente, puedes indicar:

--key [/path/to/my/public_key] la ruta de tu archivo de clave pública.

--key-data [publicKey] los datos de la clave pública, si quieres usarlos inline. Este comando es útil si seguiste la recomendación de no incluir la clave en la configuración de tu app.

Integración con CI

Para automatizar tu flujo, te recomiendo usar GitHub para subir los cambios a nuestro servidor

Tutorial de la acción GitHub

Nuestra app de demo

GitHub - Cap-go/demo-app

No olvides configurar la variable de entorno de CI con tu clave de API

Continuar desde Commands

Si estás usando Comandos para planificar las operaciones del dashboard y de API, conéctalo con Resumen de API para los detalles de implementación en API Overview, Introducción para los detalles de implementación en la Introducción, Claves de API para el detalle de implementación en API Keys, Dispositivos para el detalle de implementación en Devices, y Bundles para el detalle de implementación en Bundles.