Comandos

Esta página es un resumen guiado. Usa la referencia actual de comandos para los flags exactos: app, bundle, canal, y build.

Uso

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

Runtime nativo multiplataforma para apps web de Capacitor

Iniciar

npx @capgo/cli@latest init [apikey]

Este método te guía paso a paso en el onboarding.

Añadirá tu app a Capgo. Añadirá el code a tu app para validar la actualización. Asimismo, hará el build de tu app. Además, subirá tu app a Capgo. Y te ayudará a comprobar 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 repositorio local y lo ignorará con git.

Doctor

npx @capgo/cli doctor

Comando para verificar si tienes los paquetes de Capgo actualizados.

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

app

Añadir

npx @capgo/cli app add [appId]

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

💡 Si no se indican, todas las opciones se toman de 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 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 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 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.
• --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 (enlace y comentario) al plugin.
• --preview o --no-preview para activar o desactivar los códigos QR de vista previa de bundle y canal.
• --allow-device-custom-id o --no-allow-device-custom-id para controlar los IDs de dispositivo personalizados.
• --block-provider-infra-requests o --no-block-provider-infra-requests para controlar el bloqueo de solicitudes conocidas de centros de datos de Google y Apple.
• --build-timeout-minutes [5-360] para establecer el timeout del build nativo.
• --ios-store-url [url] o --android-store-url [url] para establecer la URL de la tienda.
• --default-upload-channel [channel] para establecer el canal de subida predeterminado.
• --default-download-channel [channel] para establecer el canal de descarga predeterminado, o --disable-download-channels para que todos los canales de descarga no sean públicos.
• --apikey [key] la clave API para vincularla con tu cuenta.

Listar

npx @capgo/cli app 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 app 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 se 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 la actualización automática en el capacitor-updater, proporciona plugins.CapacitorUpdater.autoUpdate con --string off.

Debes proporcionar uno de los dos --string o --bool!

Opciones:

• --string <string> - establece la configuración en una cadena
• --bool <true | false> - establece la configuración en un booleano

Bundle

Subir

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> Enlaza a una URL externa en lugar de subir a Capgo Cloud.
• --iv-session-key <key> Establece el IV y la clave de sesión para la URL externa del bundle.
• --s3-endpoint <s3Endpoint> URL del endpoint de S3. No funciona con subidas delta 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 de firma (sistema v1).
• --key-data <keyData> Clave pública de firma (sistema v1).
• --key-v2 <key> Ruta personalizada para la clave privada de firma (sistema v2).
• --key-data-v2 <keyData> Clave privada de firma (sistema v2).
• --bundle-url Imprime la URL del bundle en stdout.
• --no-key Ignore signing key and send clear update.
• --no-code-check Ignorar la comprobación de notifyAppReady() en el código fuente code y de que index esté en la carpeta raíz.
• --display-iv-session Muestra en la 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 vinculado al canal o, si no, la última versión remota de la app. Nivel: major, minor (por defecto), patch (alias fix), metadata, o ai (Workers AI compara los archivos locales con el delta manifest anterior de Capgo/channel, infiere el nivel y registra un motivo breve; omite la IA e incrementa patch si no hay una versión previa de Capgo). Incrementa hasta encontrar un nombre libre (los nombres eliminados siguen ocupados). No se puede combinar con --bundle.
• --min-update-version <minUpdateVersion> Versión mínima necesaria para actualizar a esta versión. Solo se usa si disable auto update está configurado como 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 metadata (node_modules) al subir.
• --ignore-checksum-check Ignora la comprobación de checksum al subir.
• --timeout <timeout> Tiempo de espera del proceso de upload en segundos.
• --delta Sube los archivos Delta (manifest) junto con el bundle completo.
• --delta-only Sube solo actualizaciones Delta (manifest), omitiendo el bundle completo.
• --no-delta Desactiva la subida de Delta (manifest) (útil si un apply instantáneo} autoUpdate está activado pero prefieres un bundle completo).
• --tus Sube el bundle usando el protocolo tus.
• --multipart Usa el protocolo multipart para subir datos a S3. Obsoleto, usa TUS en su lugar.
• --encrypted-checksum <encryptedChecksum> Un checksum cifrado (firma). Se usa solo al subir un bundle externo.
• --package-json <packageJson> La ruta al package.json. Útil para monorepos.
• --auto-set-bundle Define el bundle en capacitor.config.json.
• --node-modules <nodeModules> Lista de rutas a node_modules. Útil para monorepos (separadas por comas, ej: ../../node_modules,./node_modules)

⭐️ La opción External ayuda en 2 casos: empresas con temas de privacidad (no envíes 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 todas las apps.

👀 Capgo cloud nunca mira lo que hay en el link (para la opción external) ni en code cuando se almacena.

🔑 Puedes añadir una segunda capa de seguridad con cifrado; así Capgo no podrá ver ni modificar nada y se vuelve «trustless».

Ejemplo de package.json para la versión

{
  "version": "1.0.2"
}

⛔ La versión debe ser mayor que “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 su eliminación.

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 se eliminará esta versión.

Limpiar

en un rango SemVer para una versión mayor a 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 que deseas eliminar paquetes anteriores; se conservará el último + numberToKeep.
• --keep [numberToKeep] el número de paquetes que deseas conservar (predeterminado: 4).

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

Si tienes 20 versiones en total y no proporcionas un número de bundle como este: npx @capgo/cli cleanup [appId] --keep=2 Se eliminarán 18 versiones y se conservarán las 2 más recientes.

Este comando solicitará confirmación y mostrará una tabla con las versiones que se conservarán y las que se eliminarán.

Nota

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

Encriptar

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 la desencriptación. Se encriptará con la clave privada y se enviará junto al bundle. En la encriptación v2, el checksum pasa a ser 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.

Desencriptar

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 usarlos inline. Este comando se usa principalmente para pruebas: descifra el zip e imprime en la consola la clave de sesión descifrada en base64.

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 usarlos inline. Este comando se usa principalmente para pruebas: descifra el zip e imprime en la consola la clave de sesión descifrada en base64. --checksum [checksum] el checksum del archivo; verificará el checksum tras el descifrado.

Comprimir

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 reemplazar el nombre del archivo.
• --json para mostrar la info 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 obligatorio, ya que el nuevo sistema de cifrado usa 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 con el que verificar la compatibilidad.
• --package-json <packageJson> La ruta al package.json. Útil para monorepos
• --node-modules <nodeModules> 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 canal que quieres 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 canal que quieres configurar, como production o beta.

Opcionalmente, puedes indicar:

• --bundle [1.2.3] el bundle de tu app ya enviado a la nube, para vincularlo a un canal.
• --latest obtener 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 anteriores a los dispositivos.
• --no-downgrade impide que el channel envíe versiones anteriores a los dispositivos.
• --upgrade permite que el channel envíe versiones superiores (major) a los dispositivos.
• --no-upgrade impide que el channel envíe versiones superiores (major) a los dispositivos.
• --ios permite que el channel envíe la versión a los dispositivos iOS.
• --no-ios impide que el channel envíe la versión a los dispositivos iOS.
• --android permite que el channel envíe la versión a los dispositivos Android.
• --no-android impide que el channel envíe la versión a los dispositivos Android.
• --self-assign permite que los dispositivos se autoasignen a este canal.
• --no-self-assign impide que los dispositivos se autoasignen 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 actualizaciones

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

Primero, la major estrategia. Evita un update desde la base nativa 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 una actualización si el bundle de destino tiene un major o minor diferente al baseline nativo del dispositivo, como 0.0.0 -> 1.1.0 o 1.1.0 -> 1.2.0.

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

• El major es el mismo entre el bundle de destino y version_build
• El minor es el mismo entre el bundle de destino y version_build
• El patch es el mismo entre el bundle de destino y version_build
• Solo el sufijo de versión puede diferir, como prerelease (-beta.2) o metadatos de build (+build.2)

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

• 1.0.0-beta.1 -> 1.0.0-beta.2 permitido
• 1.0.0+build.1 -> 1.0.0+build.2 permitido
• 1.0.0 -> 1.0.1 bloqueado
• 1.0.0 -> 1.1.0 bloqueado
• 1.0.0 -> 2.0.0 bloqueado

La comparación de estrategias usa el baseline nativo enviado como version_build, no con el bundle descargado actual enviado como version_name.

Por último, la estrategia más compleja. La metadata estrategia.
Primero debes saber que, inicialmente, después de 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 que falla 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 Minimal update version campo. Debe 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 estos datos manualmente en cada actualización. Por suerte, CLI evitará que envíes un update sin estos metadatos

Para subir 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, comprueba la versión actualmente subida al canal. Verifica la compatibilidad de la misma manera que bundle compatibility haría el comando. Segundo, si la nueva versión es 100% compatible, reutiliza el min_update_version de la última versión del canal. Si no, establece el min_update_version al número de bundle de la versión recién subida.

Siempre recibirás información sobre cuál es el min_update_version al usar esta opción. Se verá de la siguiente manera:

Si la nueva versión no es compatible, debería verse algo así

Cifrado de extremo a extremo (Trustless)

Capgo admite 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 la información siguiente 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á guardar la clave privada en un lugar seguro. Se recomienda no hacer commit de la clave privada en git ni compartirla con nadie.

Después de probar localmente, elimina la clave del archivo de configuración y añádela en el 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 y no hiciste commit de la clave en la configuración de tu app.

Integración con CI

Para automatizar tu trabajo, te recomiendo hacer que la acción de GitHub se encargue de hacer push 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.