# Instalar la CLI (/es/cli/install)

<!-- agent-signals: reading_time_min: 7 · est_tokens: 2753 · updated: 2026-09-23 -->
Related: [Extensión Mintlify MDX](/es/cli/mdx-extension.md), [Previsualización local](/es/cli/preview.md), [Referencia de comandos de la CLI de Mintlify](/es/cli/commands.md), [Documentación nativa en IA](/es/ai-native.md)

<div id="prerequisites">
  ## Requisitos previos [#requisitos-previos]
</div>

* [Node.js](https://nodejs.org/en) v20.17.0+ (se recomiendan versiones LTS)

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

<CodeGroup>
  <CodeBlockTabs defaultValue="npm" groupId="npm+pnpm">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="npm">
        npm
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="pnpm">
        pnpm
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="npm">
      ```bash  
      npm i -g mint
      ```
    </CodeBlockTab>

    <CodeBlockTab value="pnpm">
      ```bash  
      pnpm add -g mint
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

<Note>
  La CLI se publica en npm como el paquete [`mint`](https://www.npmjs.com/package/mint). No instales el paquete heredado `mintlify` en scripts de instalación ni en pipelines de CI. Si tienes ambos paquetes instalados, consulta [Paquete mintlify versus mint](#troubleshooting).
</Note>

Si el usuario te pidió configurar Mintlify y no solo instalar la CLI, continúa con la autenticación, la creación del proyecto, la vista previa, la validación y el despliegue. Sigue el [flujo de configuración para agentes en el Inicio rápido](/es/quickstart#set-up-mintlify-for-the-user). No te detengas después de que `mint --version` se ejecute correctamente.

Comienza ejecutando `mint status`. Conserva una sesión autenticada existente. De lo contrario, ejecuta `mint login` para una cuenta existente. Para una cuenta nueva, recopila el nombre real, la empresa y el correo electrónico del usuario y ejecuta `mint signup`. El usuario debe hacer clic en el enlace de verificación enviado por correo electrónico y aprobar la autenticación mediante el navegador. Tú debes realizar los pasos restantes de la CLI. Consulta [`mint signup`](/es/cli/commands#mint-signup) para ver los flags y las indicaciones sobre procesos en segundo plano.

<Tip>
  ¿Usas una herramienta de codificación con IA? Copia el siguiente prompt para que tu agente instale la CLI y verifique que funciona.
</Tip>

{/* vale off */}

<Prompt description="Instala la CLI de Mintlify de forma global y verifica la instalación." actions="[&#x22;copy&#x22;, &#x22;cursor&#x22;]">
  Instala la CLI de Mintlify de forma global para que pueda previsualizar mi documentación localmente.

  1. Confirma que Node.js v20.17.0 o posterior está instalado ejecutando `node --version`. Si falta o es más antiguo, avísame antes de continuar.
  2. Instala la CLI con `npm i -g mint` (o `pnpm add -g mint` si uso pnpm).
  3. Verifica la instalación ejecutando `mint --version` y comparte el resultado.
  4. Si la instalación falla con un error de permisos, sugiere volver a ejecutarla con `sudo` y explica sus ventajas y desventajas.
</Prompt>

{/* vale on */}

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

Para crear un nuevo proyecto de documentación a partir de la plantilla inicial de Mintlify, ejecuta el siguiente comando:

```bash
mint new [directory]
```

{/* vale off */}

<Prompt description="Genera la estructura de un nuevo proyecto de Mintlify." actions="[&#x22;copy&#x22;, &#x22;cursor&#x22;]">
  Crea un nuevo proyecto de Mintlify en el directorio de trabajo actual.

  1. Pídeme un nombre de proyecto y el tema (o plantilla) preferido si aún no te lo he dicho.
  2. Ejecuta `mint new <directory> --name <name> --theme <theme>` de forma no interactiva, sustituyendo los valores que te di. Si elegí una plantilla en su lugar, ejecuta `mint new <directory> --template <template-name>`.
  3. Una vez que termine el comando, lista los archivos generados y destaca `docs.json` como el punto de entrada principal de configuración.
  4. Ejecuta `mint dev` desde el nuevo directorio y comparte la URL de la vista previa local.
</Prompt>

{/* vale on */}

Si no especificas un directorio, la CLI te solicitará crear un nuevo subdirectorio o sobrescribir el directorio actual.

<Warning>
  Sobrescribir el directorio actual elimina todos los archivos existentes.
</Warning>

| Flag         | Descripción                                                                         |
| ------------ | ----------------------------------------------------------------------------------- |
| `--name`     | Nombre del proyecto. La CLI lo solicita si no se proporciona.                       |
| `--theme`    | [Tema](/es/customize/themes) del proyecto. La CLI lo solicita si no se proporciona. |
| `--template` | Plantilla predefinida. La CLI la solicita si no se proporciona.                     |
| `--force`    | Sobrescribir el directorio actual sin solicitar confirmación.                       |

En modo interactivo, la CLI pregunta si deseas elegir un tema o clonar una plantilla. Para omitir el aviso, pasa el flag `--template` directamente:

```bash
mint new my-docs --template <template-name>
```

Puedes combinar `--template` con `--theme` para anular el tema predeterminado de la plantilla:

```bash
mint new my-docs --template <template-name> --theme <theme>
```

Consulta las plantillas disponibles en el repositorio [mintlify/templates](https://github.com/mintlify/templates) en GitHub. En modo interactivo, la CLI obtiene y muestra las plantillas disponibles automáticamente.

En entornos no interactivos como pipelines de CI/CD o agentes de codificación IA, debes proporcionar los flags `--name` y `--theme`, o el flag `--template`.

<div id="update">
  ## Actualizar [#actualizar]
</div>

Si tu previsualización local no está sincronizada con la documentación desplegada, actualiza la CLI a la última versión:

```bash
mint update
```

Si `mint update` no está disponible en tu versión, reinstala la CLI con la última versión:

<CodeGroup>
  <CodeBlockTabs defaultValue="npm" groupId="npm+pnpm">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="npm">
        npm
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="pnpm">
        pnpm
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="npm">
      ```bash  
      npm i -g mint@latest
      ```
    </CodeBlockTab>

    <CodeBlockTab value="pnpm">
      ```bash  
      pnpm add -g mint@latest
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

<div id="install-in-ci">
  ## Instalar en CI [#instalar-en-ci]
</div>

Para ejecutar comprobaciones de la CLI en un pipeline de integración continua, instala el paquete `mint` de forma global y luego ejecuta los comandos que necesites. Por ejemplo, este job de GitHub Actions comprueba el formato con [`mint format`](/es/cli/commands#mint-format) y valida la compilación con [`mint validate`](/es/cli/commands#mint-validate):

```yaml
name: Docs checks

on:
  pull_request:
    paths:
      - "**/*.mdx"
      - "docs.json"

jobs:
  docs-checks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install the Mintlify CLI
        run: npm i -g mint
      - name: Check formatting
        run: |
          mint format
          if [ -n "$(git status --porcelain)" ]; then
            echo "Files are not formatted. Run 'mint format' locally and commit the changes."
            exit 1
          fi
      - name: Validate the build
        run: mint validate
```

`mint format` reescribe los archivos en su lugar y termina con el código `1` si algún archivo no se puede analizar, por lo que el job comprueba si hay un diff después de ejecutarlo. `mint validate` termina con un error ante cualquier advertencia o error y no necesita ninguna comprobación adicional.

<div id="editor-support">
  ## Soporte para editores [#soporte-para-editores]
</div>

Para resaltado de sintaxis, autocompletado y verificación de errores en archivos MDX, usa las siguientes extensiones:

* **Cursor, Devin Desktop, VS Code**: [Extensión Mintlify MDX](/es/cli/mdx-extension) y [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) para el formato.
* **JetBrains**: [Plugin MDX para IntelliJ IDEA](https://plugins.jetbrains.com/plugin/14944-mdx) y [Prettier](https://prettier.io/docs/webstorm).

También puedes formatear archivos MDX con [`mint format`](/es/cli/commands#mint-format).

<div id="troubleshooting">
  ## Solución de problemas [#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.js. Intenta lo siguiente:

    1. Elimina la versión actual de la CLI de Mint: `npm uninstall -g mint`
    2. Actualiza a Node.js v20.17.0+.
    3. Reinstala la CLI de Mint: `npm install -g mint`
  </Accordion>

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

  <Accordion title="Error: permission denied">
    Esto se debe a que no tienes los permisos necesarios para instalar paquetes de Node.js de forma global.

    **Solución**: Intenta ejecutar `sudo npm i -g mint`. Cuando se te solicite, ingresa la contraseña que usas para desbloquear tu computadora.
  </Accordion>

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

    **Solución**: Ejecuta `mint update` para obtener los últimos cambios.
  </Accordion>

  <Accordion title="Paquete mintlify versus mint">
    Si tienes problemas con el paquete de la CLI, primero ejecuta `npm ls -g` para ver qué paquetes están instalados globalmente. Si no usas npm, prueba `which mint` para localizar la instalación.

    Si tienes instalados los paquetes `mint` y `mintlify`, desinstala `mintlify`:

    ```bash
    npm uninstall -g mintlify
    npm cache clean --force
    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 se muestra como `none`, es posible que la CLI no pueda descargar la aplicación cliente. Esto puede deberse a un firewall corporativo o a una VPN.

    **Solución**: Pide a tu administrador de TI que agregue `releases.mintlify.com` a la lista de permitidos de tu red.
  </Accordion>

  <Accordion title="La CLI se conecta a localhost en lugar de a producción al usar npx">
    En versiones anteriores a `4.0.1125`, ejecutar `npx mint dev` u otros comandos desde un
    repositorio de documentación podía hacer que la CLI se detectara incorrectamente como una
    compilación de desarrollo local. La CLI apuntaba entonces a URLs de `localhost` en lugar de a
    la API de producción de Mintlify. Esto generaba errores de conexión o comportamientos
    inesperados.

    **Solución**: Actualiza a la última versión de la CLI:

    ```bash
    npm i -g mint@latest
    ```
  </Accordion>
</AccordionGroup>