Instalación del paquete Node.js de Flosum CLI

Problemas conocidos: actualización requerida

Se requiere una actualización. La versión actual de Flosum DevOps requiere las últimas versiones de Flosum CLI (@flosum/cli paquete) y el Flosum DevOps-CLI Extension. Las versiones anteriores de CLI no admiten topologías y no pueden funcionar con un tenant de DevOps que las use, por lo que las instalaciones existentes deben actualizarse.

Se requiere Node.js 22. En Node.js 24, los comandos de instalación y actualización parecen completarse con éxito, pero te dejan en una versión anterior. Cambia a Node.js 22 antes de instalar o actualizar.

Compatibilidad con el sistema operativo

Flosum CLI y Extensión Flosum DevOps-CLI son compatibles con los siguientes sistemas operativos:

• macOS
• Linux

Estas herramientas actualmente no están diseñadas para funcionar con Windows.

Descripción general

Este artículo explica cómo instalar Flosum CLI, la herramienta de línea de comandos para Flosum DevOps. Puedes usar Flosum CLI por sí solo desde una terminal, y también es requerido por la Flosum DevOps-CLI Extension para Visual Studio Code.

Flosum CLI compila un componente nativo en tu máquina durante la instalación, por lo que requiere una cadena de herramientas de compilación funcional (Python y un compilador C++) además de Node.js. Completa todos los requisitos previos a continuación antes de ejecutar el comando de instalación.

Requisitos previos

1

Node.js y npm

Flosum CLI requiere Node.js 22 y npm 10. Las versiones más nuevas de Node.js no son compatibles.

1. Ve a nodejs.org. La página usa por defecto la versión más reciente, así que usa el desplegable de versiones para seleccionar 22.x, luego descarga y ejecuta el instalador. Node.js 22 incluye npm 10.
2. Verifica ambas versiones en una terminal:

node --version
npm --version

1. Confirme que node --version muestra v22.x y que npm --version muestra 10.x.

Node.js 24 instala una versión anterior sin advertencia

Si instalas Flosum CLI con Node.js 24, npm instalará una versión anterior de Flosum CLI sin informar de ningún error. Al ejecutar flosum --version muestra la versión anterior. Las versiones anteriores no son compatibles con el Flosum DevOps actual y no funcionarán.

Baja a Node.js 22 antes de instalar. Si ya instalaste la CLI en Node.js 24, elimínala siguiendo los pasos de Solución de problemas, instala Node.js 22 y luego vuelve a ejecutar el comando de instalación.

No actualices npm

Cada instalación termina con un aviso de que hay disponible una versión principal más nueva de npm, junto con un comando para instalarla. No ejecutes ese comando. Flosum CLI requiere npm 10, y la actualización deja tu máquina fuera de la configuración compatible.

Si ya lo actualizaste, reinstala Node.js 22, lo que restaura npm 10.

Instala Node.js para tu propia cuenta de usuario en lugar de una ubicación compartida del sistema cuando sea posible. Esto mantiene corta la ruta de la carpeta global de npm y evita el problema de longitud de ruta descrito en Solución de problemas.

2

Herramientas de compilación

Flosum CLI depende de un módulo nativo que se compila desde código fuente C durante la instalación. Tu máquina necesita Python 3 y un compilador C++ disponibles antes de la instalación, o la instalación fallará.

macOS

1. Instala las herramientas de línea de comandos de Xcode, que proporcionan el compilador y Python:

xcode-select --install

Linux

1. Instala la cadena de herramientas del compilador y Python. En Debian y Ubuntu:

sudo apt install build-essential python3

Usa el grupo de paquetes equivalente para tu distribución.

Instalación de Flosum CLI

1

Ejecuta el comando de instalación

1. Abre una terminal.
2. Ejecuta el siguiente comando:

npm i -g @flosum/cli

1. Espera a que termine la instalación. El componente nativo se compila durante este paso, así que el comando puede tardar un par de minutos.

2

Verifica la instalación

1. Ejecuta el siguiente comando:

flosum --version

1. Confirma que se devuelve un número de versión. Un número de versión indica que la instalación se realizó correctamente.
2. Compara la versión instalada con la última versión publicada:

npm view @flosum/cli version

1. Confirma que ambos comandos informan de la misma versión. Si flosum --version informa de un número menor, se instaló una versión anterior. Consulta Solución de problemas.

La Flosum DevOps-CLI Extension para Visual Studio Code se instala por separado y tiene su propio número de versión, así que su versión no coincide con la que se informa aquí. No compares ambas.

• Instalación de la extensión Flosum DevOps-CLI

Uso de Flosum CLI

Revisa los comandos del paquete Flosum CLI a continuación para ver una lista de los comandos disponibles y explicaciones de lo que hace cada uno. Como la extensión DevOps-CLI llama a estos comandos, también puedes revisar el siguiente artículo para obtener instrucciones más detalladas.

• Uso de DevOps CLI en VS Code

Referencia de comandos de Flosum CLI

Esta referencia cubre @flosum/cli la versión 0.0.5. Ejecuta flosum --help o flosum devops --help para ver la referencia de la versión instalada en tu máquina.

Cada comando acepta las siguientes opciones, que no se repiten a continuación.

Opción	Descripción
--json	Devuelve el resultado en formato JSON. El valor predeterminado es false.
-h, --help	Muestra la ayuda del comando.

El comando de nivel superior también acepta -V, --version, que devuelve el número de versión instalado.

Comandos de cuenta

Comando	Descripción
flosum login	Inicia sesión en Global Settings y recupera los datos de los servicios relacionados.
flosum logout	Elimina las credenciales guardadas.
flosum list-credentials	Muestra todas las credenciales autorizadas.
flosum list-topologies	Enumera las topologías disponibles.

Comandos de DevOps

Comando	Descripción
flosum devops init	Crea un proyecto de Salesforce y los archivos del sistema de la CLI.
flosum devops clone	Crea un proyecto de Salesforce y recupera la principal rama del tenant de DevOps registrado.
flosum devops checkout	Extrae otra rama y recupera los componentes que falten localmente.
flosum devops pull	Obtiene el último commit de la rama desde DevOps.
flosum devops commit	Confirma los cambios locales en una rama remota en DevOps.
flosum devops rollback	Revierte la rama al último estado confirmado.
flosum devops status	Devuelve todos los cambios locales que no se han confirmado.
flosum devops list-branches	Enumera todas las ramas remotas.
flosum devops config-set	Establece un valor de configuración del proyecto.
flosum devops config-unset	Borra una propiedad de configuración del proyecto.

flosum login

Opción	Descripción
-a, --alias <string>	Alias con el que se accede a las credenciales guardadas. El valor predeterminado es default.
-t, --token <string>	Token usado para acceder a los servicios de Flosum. El comando lo solicita durante la ejecución si no lo proporcionas.
--global-settings-api-url <string>	URL base de una API de Global Settings accesible. Úsala cuando la API privada de Global Settings esté expuesta fuera de la red de Docker.

flosum logout

Opción	Descripción
-a, --alias <string>	Alias de las credenciales guardadas que se van a eliminar. El valor predeterminado es default.

flosum list-topologies

Opción	Descripción
-a, --alias <string>	Alias de credenciales que se usará al listar topologías. El valor predeterminado es default.

flosum devops init

Opción	Descripción
-n, --name <string>	Nombre de la carpeta en la que se almacena el proyecto. El comando lo solicita durante la ejecución si no lo proporcionas.
-a, --alias <string>	Alias de las credenciales usadas para recuperar tus componentes desde DevOps. El valor predeterminado es default.
-t, --topology <string>	Nombre de la topología que se usará para el proyecto.
--topology-id <number>	ID de la topología que se usará para el proyecto.

flosum devops clone

Opción	Descripción
-n, --name <string>	Nombre de la carpeta en la que se almacena el proyecto. El comando lo solicita durante la ejecución si no lo proporcionas.
-a, --alias <string>	Alias de las credenciales usadas para recuperar tus componentes desde DevOps. El valor predeterminado es default.
-t, --topology <string>	Nombre de la topología que se usará para clonar.
--topology-id <number>	ID de la topología que se usará para clonar.

flosum devops checkout

Opción	Descripción
-b, --branch <string>	Nombre de la rama que se va a extraer. El comando lo solicita durante la ejecución si no lo proporcionas.

flosum devops commit

Opción	Descripción
-m, --message <string>	Mensaje de confirmación. El comando lo solicita durante la ejecución si no lo proporcionas.

flosum devops config-set

Toma dos argumentos, ambos obligatorios.

Argumento	Descripción
config-name	Nombre de la propiedad de configuración. Los valores permitidos son credentialsAlias y topologyId.
value	Valor al que se establecerá la propiedad.

flosum devops config-unset

Toma un argumento, que es obligatorio.

Argumento	Descripción
config-name	Nombre de la propiedad de configuración que se va a borrar. Los valores permitidos son credentialsAlias y topologyId.

Comandos sin opciones adicionales

flosum list-credentials, flosum devops pull, flosum devops rollback, flosum devops status y flosum devops list-branches solo aceptan las dos opciones enumeradas al principio de esta referencia.

Solución de problemas

La instalación falla con gyp ERR, node-gyp o un error de Python

No se pudo compilar el componente nativo porque la cadena de herramientas de compilación falta o está incompleta.

1. Confirme que Python 3 está instalado y disponible en tu PATH al ejecutar python3 --version.
2. Confirma que hay un compilador C++ instalado. En macOS, esto son las herramientas de línea de comandos de Xcode. En Linux, es el grupo de paquetes del compilador para tu distribución.
3. Cierra y vuelve a abrir tu terminal para que tome el actualizado PATH.
4. Elimina la instalación parcial, como se describe a continuación.
5. Ejecuta de nuevo el comando de instalación.

Elimina la instalación parcial antes de volver a intentarlo

Una instalación fallida deja una copia incompleta de la CLI, junto con los flosum accesos directos del comando. Elimina ambos antes de volver a intentarlo; de lo contrario, el siguiente intento puede fallar por motivos no relacionados con el error original.

Primero, ejecuta la desinstalación estándar, que elimina el contenido del paquete:

npm uninstall -g @flosum/cli

Esto no elimina los flosum accesos directos, así que elimínalos también.

sudo rm -f "$(npm prefix -g)/bin/flosum"
sudo rm -rf "$(npm root -g)/@flosum"

Ambos pasos son necesarios. Los flosum accesos directos se crean incluso cuando la instalación falla, y dejarlos atrás te da un flosum comando que sigue ejecutándose pero apunta a archivos que ya no están allí.

Luego confirma que no queda nada:

flosum --version

El comando debería informar comando no encontrado. Si en su lugar informa de un módulo que falta, los accesos directos siguen presentes.

Puede que veas un segundo error diferente

La compilación comprueba Python antes de comprobar un compilador C++, así que solo informa de la primera que falte. Si Python era lo único que faltaba, instalarlo y volver a intentarlo puede producir un nuevo error que mencione el compilador C++ en su lugar. Esto es un avance esperado, no un problema nuevo. Instala las herramientas de compilación de C++, elimina de nuevo la instalación parcial y vuelve a intentarlo.

Consulta el Herramientas de compilación requisito previo anterior para ver las instrucciones completas por sistema operativo.

El mensaje de error también enlaza con las instrucciones de instalación de node-gyp, publicadas por la propia herramienta de compilación. Cubren los mismos requisitos para un público general de desarrolladores y sirven como una útil segunda referencia al solucionar una configuración inusual.

flosum --version informa de una versión anterior a la publicada

flosum --version devuelve un número menor que npm view @flosum/cli version. La instalación informó de éxito, pero npm seleccionó una versión anterior.

Esto ocurre cuando la versión de Node.js en tu máquina no es 22. npm elige la versión más reciente compatible con tu versión de Node.js y no informa de un error cuando esa no es la actual.

1. Ejecute node --version.
2. Si no informa de v22.x, instala Node.js 22 como se describe en los Node.js y npm requisitos previos.
3. Elimina la instalación existente siguiendo los pasos de la primera entrada.
4. Ejecuta de nuevo el comando de instalación y compara las versiones otra vez.

El comando flosum informa "Cannot find module" en lugar de una versión

Una instalación anterior falló a mitad de camino. Los flosum accesos directos se crearon, pero los archivos a los que apuntan nunca se terminaron, así que el comando se ejecuta y luego informa de un cli.js archivo.

1. Elimina la instalación parcial siguiendo los pasos de la primera entrada.
2. Completa el Herramientas de compilación requisito previo.
3. Ejecuta de nuevo el comando de instalación.

La instalación falla con EBADENGINE o "Unsupported engine"

Este mensaje significa que la versión de Node.js o npm en tu máquina no coincide con la versión requerida por Flosum CLI.

1. Ejecute node --version y npm --version.
2. Si no informan de v22.x y 10.x, instala Node.js 22 como se describe en los Node.js y npm requisito previo, vuelve a ejecutar el comando de instalación.

En las versiones compatibles, este mensaje no debería aparecer.

Si lo ves al ejecutar Node.js 22, comprueba si engine-strict=true está establecido en tu .npmrc archivo. Esa configuración convierte las advertencias de compatibilidad de versiones en errores. Elimínala o sobrescríbela solo para esta instalación:

npm i -g @flosum/cli --engine-strict=false