Tutorial: Cómo instalar Gemini CLI en Haiku OS




Este tutorial resume los pasos para instalar correctamente el paquete @google/gemini-cli en Haiku OS, resolviendo los problemas de instalación relacionados con nombres de paquetes incorrectos, directorios corruptos y configuraciones específicas del sistema. Los errores iniciales (ERR_MODULE_NOT_FOUND y ENOENT) se debieron a un nombre de paquete incorrecto (@google/.gemini-cli) y una instalación corrupta en el directorio /boot/home/config/non-packaged/bin/npmpkg. Aquí te explico cómo lo solucionamos paso a paso.


---


## Requisitos previos

- Sistema operativo: Haiku OS (probado en Haiku beta5).

- Node.js: Versión 20.15.1 (compatible con @google/gemini-cli).

- npm: Versión 10.9.2 o superior.

- Acceso a terminal: Haiku shell con permisos de escritura en directorios de usuario.

- Conexión a internet: Para descargar paquetes desde el registro de npm.


Asegúrate de tener Node.js y npm instalados:

node -v

npm -v

Si no están instalados, usa el gestor de paquetes de Haiku (pkgman):

pkgman install nodejs


---


## Problemas encontrados

1. Nombre de paquete incorrecto: Intentaste usar @google/.gemini-cli, que no existe en el registro de npm. El nombre correcto es @google/gemini-cli.

2. Instalación corrupta: La carpeta /boot/home/config/non-packaged/bin/npmpkg/lib/node_modules/@google/.gemini-cli estaba corrupta, faltaban archivos como package.json.

3. Conflictos con Haiku OS: El sistema de archivos y el gestor de paquetes de Haiku (npmpkg) causaban problemas al instalar paquetes globales en directorios del sistema.


---


## Pasos para instalar Gemini CLI


Sigue estos pasos en la terminal de Haiku para instalar @google/gemini-cli correctamente:


### 1. Limpiar la caché de npm

Elimina archivos en caché que puedan causar conflictos:

npm cache clean --force


Por qué: Esto asegura que no haya datos corruptos que interfieran con la instalación.


### 2. Eliminar directorios corruptos

Borra la instalación corrupta para empezar desde cero:

rm -rf /boot/home/config/non-packaged/bin/npmpkg/lib/node_modules/@google


Por qué: La carpeta contenía una instalación fallida de @google/.gemini-cli, lo que provocaba errores como ENOENT (falta package.json).


### 3. Configurar el prefijo de npm

Establece un directorio de usuario para las instalaciones globales, evitando conflictos con los directorios protegidos de Haiku:

npm config set prefix ~/config/non-packaged


Por qué: Haiku OS tiene un sistema de archivos estricto, y usar un directorio de usuario como ~/config/non-packaged evita problemas de permisos.


### 4. Actualizar el PATH

Asegúrate de que los binarios instalados globalmente sean accesibles:

echo 'export PATH="$HOME/config/non-packaged/bin:$PATH"' >> ~/.profile

source ~/.profile


Por qué: Esto agrega el directorio ~/config/non-packaged/bin al PATH, permitiendo ejecutar comandos como gemini desde cualquier lugar.


### 5. Instalar @google/gemini-cli

Instala el paquete correcto globalmente:

npm install -g @google/gemini-cli@latest


Por qué: El nombre correcto es @google/gemini-cli (sin el punto). Esto descarga e instala la última versión desde el registro de npm.


### 6. Verificar la instalación

Confirma que el comando gemini está disponible:

gemini --version


Por qué: Esto verifica que la instalación fue exitosa y que el CLI está correctamente configurado.


### 7. Ejecutar Gemini CLI

Inicia el CLI para usarlo:

gemini


Por qué: Este comando lanza la interfaz de línea de comandos de Gemini, lista para usar.


### 8. Asegurar permisos

Si encuentras problemas de permisos, ajusta los permisos del directorio:

chmod -R 755 ~/config/non-packaged


Por qué: Esto garantiza que npm tenga acceso completo para escribir y ejecutar archivos en el directorio de instalación.


---


## Solución de problemas adicionales

Si encuentras errores, prueba lo siguiente:

- Verificar instalación global:

    npm list -g

  

  Busca @google/gemini-cli en la lista para confirmar que está instalado.


- Revisar logs de npm:

  Si la instalación falla, consulta el log de npm (por ejemplo, /boot/home/.npm/_logs/2025-07-28T08_44_20_816Z-debug-0.log):

    cat /boot/home/.npm/_logs/<nombre_del_log>.log

  


- Reinstalar Node.js:

  Si sospechas que Node.js está corrupto, reinstálalo:

    pkgman install nodejs

  


- Probar en un entorno limpio:

  Crea un directorio nuevo para probar la instalación localmente:

    mkdir test-gemini

  cd test-gemini

  npm init -y

  npm install @google/gemini-cli

  npx gemini

  


---


## Resultado final

Siguiendo estos pasos, logramos instalar @google/gemini-cli en Haiku OS, superando los errores iniciales causados por un nombre de paquete incorrecto y una instalación corrupta. La clave fue usar el nombre correcto (@google/gemini-cli), limpiar la instalación previa y configurar npm para usar un directorio de usuario en lugar de los directorios del sistema gestionados por npmpkg.


Si necesitas ejecutar el CLI frecuentemente, simplemente usa:

gemini


Hasta la próxima