mintlify__docs/es/installation.mdx

---
title: "Instalar la CLI"
description: "Usa la CLI para obtener una vista previa de la documentación de forma local, probar cambios en tiempo real y detectar problemas antes de implementar tu sitio de documentación."
keywords: ["CLI", "npm", "desarrollo local", "Node.js", "pnpm", "mint dev", "enlaces rotos", "accesibilidad"]
---

<img className="block dark:hidden my-0 pointer-events-none" src="/images/installation/local-development-light.png" alt="Gráfico decorativo que representa la CLI." />

<img className="hidden dark:block my-0 pointer-events-none" src="/images/installation/local-development-dark.png" alt="Gráfico decorativo que representa la CLI." />

Usa la [CLI](https://www.npmjs.com/package/mint) para obtener una vista previa de tu documentación de forma local mientras escribes y editas. Revisa los cambios en tiempo real antes de implementar, prueba la apariencia y funcionalidad de tu sitio de documentación y detecta problemas como enlaces rotos o problemas de accesibilidad.

La CLI también incluye utilidades para mantener tu documentación, como comandos para cambiar el nombre de archivos, validar especificaciones de OpenAPI y migrar contenido entre formatos.

<div id="prerequisites">
  ## Requisitos previos
</div>

* [Node.js](https://nodejs.org/en) v20.17.0+ (se recomiendan las versiones LTS) instalado
* [Git](https://git-scm.com/downloads) instalado
* Tu repositorio de documentación clonado localmente

<div id="clone-your-repository">
  ### Clona tu repositorio
</div>

<Steps>
  <Step title="Localiza tu repositorio">
    1. Ve a la página de [Git settings](https://dashboard.mintlify.com/settings/deployment/git-settings) de tu dashboard.
    2. Anota la ubicación de tu repositorio. Tiene uno de estos formatos:

    * `mintlify-community/docs-{org-name}-{id}` (repositorio alojado en Mintlify)
    * `your-org/your-repo` (tu propio repositorio de GitHub)
  </Step>

  <Step title="Clona tu repositorio">
    <Tabs>
      <Tab title="Tu propio repositorio">
        Reemplaza `your-org/your-repo` por los detalles reales de tu repositorio desde [Git settings](https://dashboard.mintlify.com/settings/deployment/git-settings).

        ```bash
        git clone https://github.com/your-org/your-repo
        cd your-repo
        ```

        <Tip>
          **Se requiere la Aplicación de GitHub.** Para habilitar implementaciones automáticas cuando hagas push de cambios, debes instalar la Aplicación de GitHub. Consulta [GitHub](/es/deploy/github) para más información.
        </Tip>
      </Tab>

      <Tab title="Repositorio alojado en Mintlify">
        Puedes clonar tu repositorio como repositorio privado o público. Los repositorios públicos son visibles para cualquier persona que acceda a la URL del repositorio. Los repositorios privados solo son visibles para las personas de tu organización.

        En la página de [Git settings](https://dashboard.mintlify.com/settings/deployment/git-settings) de tu dashboard, selecciona **Clone as private** o **Clone as public**.
      </Tab>
    </Tabs>
  </Step>
</Steps>

<div id="install-the-cli">
  ## Instalar la CLI
</div>

Ejecuta el siguiente comando para instalar la CLI:

<CodeGroup>
  ```bash npm
  npm i -g mint
  ```

  ```bash pnpm
  pnpm add -g mint
  ```
</CodeGroup>

<div id="preview-locally">
  ## Vista previa local
</div>

Ve a tu directorio de documentación (donde está el archivo `docs.json`) y ejecuta:

```bash
mint dev
```

Una vista previa local de tu documentación está disponible en `http://localhost:3000`.

Como alternativa, si no quieres instalar la CLI de forma global, puedes ejecutar un script de una sola vez:

```bash
npx mint dev
```

<div id="custom-ports">
  ### Puertos personalizados
</div>

De forma predeterminada, la CLI usa el puerto 3000. Puedes personalizar el puerto con la opción `--port`. Para ejecutar la CLI en el puerto 3333, por ejemplo, usa este comando:

```bash
mint dev --port 3333
```

Si intentas ejecutar en un puerto que ya está en uso, la CLI usará el siguiente puerto disponible:

```mdx
El puerto 3000 ya está en uso. Intentando el 3001.
```

<div id="skip-openapi-processing">
  ## Omitir el procesamiento de OpenAPI
</div>

Si tienes muchos archivos de OpenAPI, puedes omitir el procesamiento de estos archivos durante el desarrollo local para mejorar el rendimiento usando la opción `--disable-openapi`:

```bash
mint dev --disable-openapi
```

<div id="preview-as-a-specific-group">
  ### Vista previa como un grupo específico
</div>

Si usas control de acceso basado en grupos para restringir el acceso a tu documentación, puedes obtener una vista previa como un grupo de autenticación específico usando la opción `--groups [groupname]`.

Por ejemplo, si tienes un grupo llamado `admin`, puedes obtener una vista previa como miembro de ese grupo con el comando:

```bash
mint dev --groups admin
```

<div id="create-a-new-project">
  ## Crear un proyecto nuevo
</div>

Para crear un proyecto de documentación nuevo, ejecuta el siguiente comando:

```bash
mint new [directorio]
```

Este comando clona el [kit inicial](https://github.com/mintlify/starter) en un directorio especificado. Si no se especifica un directorio, la herramienta CLI te pedirá crear un nuevo subdirectorio o sobrescribir el directorio actual.

<Warning>
  Si sobrescribes el directorio actual, se eliminarán todos los archivos existentes en él.
</Warning>

La herramienta CLI te pedirá un nombre de proyecto y un [tema](/es/customize/themes) para completar la configuración de tu proyecto.

<div id="flags">
  ### Flags
</div>

| Flag | Description | Obligatorio |
| --- | --- | --- |
| `--name` | Establece el nombre del nuevo proyecto. | Sí |
| `--theme` | Establece el [tema](/es/customize/themes) del nuevo proyecto. | Sí |
| `--force` | Sobrescribe el directorio actual sin pedir confirmación, incluso si contiene archivos existentes. | No |

Al ejecutar `mint new` en entornos no interactivos como pipelines de CI/CD o con agentes de programación con IA, debes proporcionar todos los flags obligatorios (`--name` y `--theme`).

<Tip>
  La CLI detecta automáticamente los entornos no interactivos. Si faltan flags obligatorios, muestra instrucciones de uso en lugar de quedarse bloqueada esperando entradas interactivas.
</Tip>

<div id="update-the-cli">
  ## Actualizar la CLI
</div>

Si tu vista previa local no coincide con lo que ves en la versión de producción en la web, actualiza tu CLI local:

```bash
mint update
```

Si el comando `mint update` no está disponible en tu versión local, vuelve a instalar la CLI con la versión más reciente:

<CodeGroup>
  ```bash npm
  npm i -g mint@latest
  ```

  ```bash pnpm
  pnpm add -g mint@latest
  ```
</CodeGroup>

<div id="additional-commands">
  ## Comandos adicionales
</div>

<div id="find-broken-links">
  ### Buscar enlaces rotos
</div>

Identifica los enlaces internos rotos con el siguiente comando:

```bash
mint broken-links
```

El comando ignora los archivos que coinciden con los patrones definidos en [.mintignore](/es/organize/mintignore). Los enlaces que apuntan a archivos ignorados se reportan como rotos.

<div id="find-accessibility-issues">
  ### Detectar problemas de accesibilidad
</div>

Prueba las relaciones de contraste de color y busca texto alternativo faltante en imágenes y videos de tu documentación con el siguiente comando:

```bash
mint a11y
```

Usa flags para detectar problemas de accesibilidad específicos.

```bash
# Check only for missing alt text
mint a11y --skip-contrast

# Verificar solo problemas de contraste de color
mint a11y --skip-alt-text
```

<div id="validate-documentation-build">
  ### Validar la compilación de la documentación
</div>

Valida la compilación de tu documentación en modo estricto, que finaliza con un error si hay alguna advertencia o error. Usa este comando en pipelines de CI/CD para evitar implementaciones de documentación con errores.

```bash
mint validate
```

Utiliza flags para configurar el comando de validación.

* `--groups [groupname]`: Simula grupos de usuarios para la validación (útil al probar control de acceso basado en grupos)
* `--disable-openapi`: Desactiva la generación del archivo OpenAPI durante la validación

<div id="check-openapi-spec">
  ### Verificar la especificación de OpenAPI
</div>

Comprueba tu archivo de OpenAPI en busca de errores con el siguiente comando:

```bash
mint openapi-check <nombre de archivo OpenAPI o URL>
```

Indica un nombre de archivo (por ejemplo, `./openapi.yaml`) o una URL (por ejemplo, `https://petstore3.swagger.io/api/v3/openapi.json`).

<div id="rename-files">
  ### Renombrar archivos
</div>

Renombra y actualiza todas las referencias a archivos con el siguiente comando:

```bash
mint rename <ruta/al/archivo-anterior> <ruta/al/archivo-nuevo>
```

<div id="migrate-mdx-endpoint-pages">
  ### Migrar páginas de endpoints en MDX
</div>

Migra las páginas de endpoints en MDX a páginas autogeneradas a partir de tu especificación de OpenAPI con el siguiente comando:

```bash
mint migrate-mdx
```

Este comando convierte páginas individuales de endpoints en MDX en páginas autogeneradas definidas en tu `docs.json`, mueve el contenido de MDX a la extensión `x-mint` en tu especificación de OpenAPI y actualiza tu navegación. Consulta [Migración desde MDX](/es/guides/migrating-from-mdx) para obtener información detallada.

<div id="formatting">
  ## Formato
</div>

Durante el desarrollo local, recomendamos usar extensiones en tu IDE para reconocer y dar formato a archivos MDX.

Si usas Cursor, Windsurf o VS Code, recomendamos la [extensión MDX para VS Code](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) para el resaltado de sintaxis y [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) para el formateo de código.

Si usas JetBrains, recomendamos el [plugin MDX para IntelliJ IDEA](https://plugins.jetbrains.com/plugin/14944-mdx) para el resaltado de sintaxis y configurar [Prettier](https://prettier.io/docs/webstorm) para el formateo de código.

<div id="troubleshooting">
  ## Solución de problemas
</div>

<AccordionGroup>
  <Accordion title="Error: Could not load the &#x22;sharp&#x22; module using the darwin-arm64 runtime">
    Esto puede deberse a una versión desactualizada de Node. Prueba lo siguiente:

    1. Desinstala la versión actualmente instalada de la CLI de mint: `npm uninstall -g mint`
    2. Actualiza a Node.js v20.17.0 o superior.
    3. Reinstala la CLI de mint: `npm install -g mint`
  </Accordion>

  <Accordion title="Problema: error desconocido">
    **Solución**: Ve al directorio raíz de tu usuario y elimina la carpeta `~/.mintlify`. Después, ejecuta `mint dev` de nuevo.
  </Accordion>

  <Accordion title="Error: permiso denegado">
    Esto se debe a no tener los permisos necesarios para instalar paquetes de Node de forma global.

    **Solución**: Intenta ejecutar `sudo npm i -g mint`. Se te pedirá tu contraseña, la misma que usas para desbloquear tu computadora.
  </Accordion>

  <Accordion title="La vista previa local no se ve igual que mi documentación en la web">
    Es probable que se deba a una versión desactualizada de la CLI.

    **Solución:** Ejecuta `mint update` para obtener los cambios más recientes.
  </Accordion>

  <Accordion title="mintlify vs. paquete mint">
    Si tienes algún problema con el paquete de la CLI, primero ejecuta `npm ls -g`. Este comando muestra qué paquetes están instalados globalmente en tu máquina.

    Si no usas npm o no lo ves en la lista con -g, prueba `which mint` para localizar la instalación.

    Si tienes un paquete llamado `mint` y otro llamado `mintlify` instalado, debes desinstalar `mintlify`.

    1. Desinstala el paquete antiguo:

    ```bash
      npm uninstall -g mintlify
    ```

    2. Limpia la caché de npm:

    ```bash
      npm cache clean --force
    ```

    3. Reinstala el paquete nuevo:

    ```bash
    npm i -g mint
    ```
  </Accordion>

  <Accordion title="La versión del cliente muestra 'none' después de la instalación">
    Si ejecutas `mint version` y la versión del cliente aparece como `none`, es posible que la CLI no pueda descargar la aplicación cliente debido a que un firewall corporativo o una VPN está bloqueando la descarga.

    **Solución:** Pídele a tu administrador de TI que incluya en la lista de permitidos `releases.mintlify.com` para habilitar el desarrollo local con la CLI.
  </Accordion>
</AccordionGroup>