Comandos de la CLI

Puedes usar la interfaz de línea de comandos (CLI) provista por Astro para desarrollar, construir y previsualizar tu proyecto desde una ventana de terminal.

comandos de `astro`

Usa la CLI ejecutando uno de los comandos documentados en esta página con tu gestor de paquetes preferido, opcionalmente seguido de cualquier flag. Las flags personalizan el comportamiento de un comando.

Uno de los comandos que usarás más a menudo es astro dev. Este comando inicia el servidor de desarrollo y te brinda una vista previa en vivo y actualizada de tu sitio en un navegador mientras trabajas:

# start the development server
npx astro dev

# start the development server
pnpm astro dev

# start the development server
yarn astro dev

Puedes escribir astro --help en tu terminal para mostrar una lista de todos los comandos disponibles:

npx astro --help

pnpm astro --help

yarn astro --help

El siguiente mensaje se mostrará en tu terminal:

astro [command] [...flags]

Commands
              add  Add an integration.
            build  Build your project and write it to disk.
            check  Check your project for errors.
       create-key  Create a cryptography key
              dev  Start the development server.
             docs  Open documentation in your web browser.
             info  List info about your current Astro setup.
          preview  Preview your build locally.
             sync  Generate TypeScript types for all Astro modules.
      preferences  Configure user preferences.
        telemetry  Configure telemetry settings.

Global Flags
  --config <path>  Specify your config file.
    --root <path>  Specify your project root folder.
     --site <url>  Specify your project site.
--base <pathname>  Specify your project base.
        --verbose  Enable verbose logging.
         --silent  Disable all logging.
        --version  Show the version number and exit.
           --help  Show this help message.

Puedes agregar la flag --help después de cualquier comando para obtener una lista de todas las flags para ese comando.

# get a list of all flags for the `dev` command
npm run dev -- --help

# get a list of all flags for the `dev` command
pnpm dev --help

# get a list of all flags for the `dev` command
yarn dev --help

El siguiente mensaje se mostrará en tu terminal:

astro dev [command] [...flags]

Commands
          stop  Stop a running background dev server.
        status  Check if a dev server is running.
  logs [--follow]  View logs from a background dev server.

Flags
          --background  Start the dev server as a background process.
               --port  Specify which port to run on. Defaults to 4321.
               --host  Listen on all addresses, including LAN and public addresses.
--host <custom-address>  Expose on a network IP address at <custom-address>
               --open  Automatically open the app in the browser on server start
              --force  Clear the content layer cache, forcing a full rebuild.
          --help (-h)  See all available flags.

Scripts de `package.json`

También puedes usar scripts en package.json para obtener versiones más cortas de estos comandos. Usar un script te permite usar los mismos comandos con los que puedes estar familiarizado de otros proyectos, como npm run build.

Los siguientes scripts para los comandos más comunes de astro (astro dev, astro build y astro preview) se agregan automáticamente por ti cuando creas un proyecto usando el asistente create astro.

Cuando sigues las instrucciones para instalar Astro manualmente, se te indica que agregues estos scripts tú mismo. También puedes agregar más scripts a esta lista manualmente para cualquier comando que uses con frecuencia.

{
  "scripts": {
    "dev": "astro dev",
    "build": "astro build",
    "preview": "astro preview"
  }
}

A menudo usarás estos comandos de astro, o los scripts que los ejecutan, sin ninguna flag. Agrega flags al comando cuando quieras personalizar el comportamiento del comando. Por ejemplo, es posible que desees iniciar el servidor de desarrollo en un puerto diferente, o construir tu sitio con registros detallados (verbose) para la depuración.

# run the dev server on port 8080 using the `dev` script in `package.json`
npm run dev -- --port 8080

# build your site with verbose logs using the `build` script in `package.json`
npm run build -- --verbose

# run the dev server on port 8080 using the `dev` script in `package.json`
pnpm dev --port 8080

# build your site with verbose logs using the `build` script in `package.json`
pnpm build --verbose

# run the dev server on port 8080 using the `dev` script in `package.json`
yarn dev --port 8080

# build your site with verbose logs using the `build` script in `package.json`
yarn build --verbose

`astro dev`

Inicia el servidor de desarrollo de Astro. Este es un servidor HTTP local que no empaqueta los recursos. Usa el reemplazo de módulos en caliente (HMR) para actualizar tu navegador a medida que guardas los cambios en tu editor.

Los siguientes atajos de teclado se pueden usar en la terminal donde se está ejecutando el servidor de desarrollo de Astro:

s + enter para sincronizar los datos de la capa de contenido (contenido y tipos).
o + enter para abrir tu sitio de Astro en el navegador.
q + enter para salir del servidor de desarrollo.

Flags

Añadido en: astro@7.0.0 Nuevo

`--background`

Inicia el servidor de desarrollo como un proceso de fondo desacoplado y habilita el registro JSON. Esta flag se proporciona automáticamente cuando se detecta un agente de IA. También puedes usarla manualmente:

astro dev --background

Si ya se está ejecutando un servidor para el proyecto, el comando imprime la información del servidor existente y sale sin iniciar uno nuevo. Usa la flag --force para detener el servidor existente e iniciar uno nuevo.

astro dev --background --force

Consulta Modo en segundo plano para agentes de codificación de IA para obtener más información sobre la detección automática de agentes y el endpoint de salud.

Subcomandos

Añadido en: astro@7.0.0 Nuevo

`astro dev stop`

Detiene un servidor de desarrollo en segundo plano que esté ejecutándose. Envía SIGTERM y espera hasta 5 segundos para que el servidor salga de forma ordenada. Si el proceso sigue ejecutándose después de eso, escala a SIGKILL.

`astro dev status`

Comprueba si un servidor de desarrollo en segundo plano se está ejecutando y muestra su URL, PID, y tiempo de actividad.

`astro dev logs`

Muestra los registros de un servidor de desarrollo en segundo plano. Solo funciona cuando el servidor se inició con astro dev --background, ya que los servidores en primer plano escriben los registros directamente en la terminal.

Flags

`--follow` (`-f`)

Transmite la nueva salida de registros a medida que se escribe, similar a tail -f. Sin esta flag, se imprimen los contenidos del archivo de registro actual y el comando finaliza.

`astro build`

Construye tu sitio para el despliegue. Por defecto, esto generará archivos estáticos y los colocará en un directorio dist/. Si alguna ruta se renderiza bajo demanda, esto generará los archivos de servidor necesarios para servir tu sitio.

Flags

El comando acepta flags comunes y las siguientes flags adicionales:

`--devOutput`

Añadido en: astro@5.0.0

Genera una construcción basada en el desarrollo similar al código transformado en astro dev. Esto puede ser útil para probar problemas que solo ocurren en la construcción con información de depuración adicional incluida.

`astro preview`

Inicia un servidor local para servir los contenidos de tu directorio estático (dist/ por defecto) creado al ejecutar astro build.

Este comando te permite previsualizar tu sitio localmente después de construirlo para detectar cualquier error en la salida de tu construcción antes de desplegarlo. No está diseñado para ejecutarse en producción. Para obtener ayuda con el alojamiento en producción, consulta nuestra guía sobre Cómo desplegar un sitio web de Astro.

Los siguientes atajos de teclado se pueden usar en la terminal donde se está ejecutando el servidor de vista previa de Astro:

o + enter para abrir tu sitio de Astro en el navegador.
q + enter para salir del servidor de vista previa.

El comando astro preview se puede combinar con las flags comunes documentadas a continuación para controlar aún más la experiencia de vista previa.

`astro check`

Ejecuta diagnósticos (como la verificación de tipos dentro de archivos .astro) en tu proyecto e informa de los errores en la consola. Si se encuentra algún error, el proceso saldrá con un código de 1.

Este comando está diseñado para ser utilizado en flujos de trabajo de CI.

Flags

Usa estas flags para personalizar el comportamiento del comando.

`--watch`

El comando vigilará cualquier cambio en tu proyecto y reportará cualquier error.

`--root <ruta-al-directorio>`

Especifica un directorio raíz diferente para verificar. Usa el directorio de trabajo actual por defecto.

`--tsconfig <ruta-al-archivo>`

Especifica un archivo tsconfig.json para usar manualmente. Si no se proporciona, Astro intentará encontrar una configuración o inferir la configuración del proyecto automáticamente.

`--minimumFailingSeverity <error|warning|hint>`

Especifica la gravedad mínima necesaria para salir con un código de error. Por defecto es error.

Por ejemplo, ejecutar astro check --minimumFailingSeverity warning hará que el comando salga con un error si se detecta alguna advertencia.

`--minimumSeverity <error|warning|hint>`

Especifica la gravedad mínima a mostrar. Por defecto es hint.

Por ejemplo, ejecutar astro check --minimumSeverity warning mostrará errores y advertencias, pero no sugerencias.

`--preserveWatchOutput`

Especifica no borrar la salida entre comprobaciones cuando está en modo de vigilancia.

`--noSync`

Especifica no ejecutar astro sync antes de verificar el proyecto.

Lee más sobre la comprobación de tipos en Astro.

`astro sync`

Agregado en: astro@2.0.0

Genera tipos de TypeScript para todos los módulos de Astro. Esto configura un archivo .astro/types.d.ts para la inferencia de tipos, y define módulos para características que dependen de tipos generados:

El módulo astro:content para la API de Colecciones de Contenido.
El módulo astro:env para Astro Env.
El módulo astro:actions para Astro Actions

`astro add`

Agrega una integración a tu configuración. Lee más en la guía de integraciones.

`astro docs`

Lanza el sitio web de documentación de Astro directamente desde la terminal.

`astro info`

Muestra información útil sobre tu entorno actual de Astro. Útil para proporcionar información al abrir un problema.

astro info

Ejemplo de salida:

Astro                    v5.14.1
Vite                     v6.3.6
Node                     v22.17.1
System                   macOS (arm64)
Package Manager          npm
Output                   static
Adapter                  none
Integrations             @astrojs/starlight (v0.35.3)

Flags

Usa las siguientes flags para personalizar el comportamiento del comando.

`--copy`

El comando copiará la salida al portapapeles sin preguntar.

`astro preferences`

Gestiona las preferencias del usuario con el comando astro preferences. Las preferencias del usuario son específicas de los usuarios individuales de Astro, a diferencia del archivo astro.config.mjs que cambia el comportamiento para todos los que trabajan en un proyecto.

Las preferencias del usuario están limitadas al proyecto actual por defecto, almacenadas en un archivo local .astro/settings.json.

Usando la flag --global, las preferencias del usuario también se pueden aplicar a cada proyecto de Astro en la máquina actual. Las preferencias globales del usuario se almacenan en una ubicación específica del sistema operativo.

Preferencias disponibles

devToolbar — Activa o desactiva la barra de herramientas de desarrollo en el navegador. (Por defecto: true)
checkUpdates — Activa o desactiva las comprobaciones automáticas de actualización para la CLI de Astro. (Por defecto: true)

El comando list imprime la configuración actual de todas las preferencias de usuario configurables. También es compatible con una salida --json legible por máquina.

astro preferences list

Ejemplo de salida en terminal:

Preferencia	Valor
devToolbar.enabled	true
checkUpdates.enabled	true

Puedes enable (habilitar), disable (deshabilitar) o reset (restablecer) las preferencias a sus valores predeterminados.

Por ejemplo, para desactivar devToolbar en un proyecto de Astro específico:

astro preferences disable devToolbar

Para desactivar devToolbar en todos los proyectos de Astro en la máquina actual:

astro preferences disable --global devToolbar

La devToolbar se puede habilitar más tarde con:

astro preferences enable devToolbar

El comando reset restablece una preferencia a su valor predeterminado:

astro preferences reset devToolbar

`astro telemetry`

Establece la configuración de telemetría para el usuario de la CLI actual. La telemetría consiste en datos anónimos que ofrecen al equipo de Astro información sobre qué características de Astro se utilizan con más frecuencia. Para obtener más información, consulta la página de telemetría de Astro.

La telemetría se puede desactivar con este comando de la CLI:

astro telemetry disable

La telemetría se puede volver a habilitar más tarde con:

astro telemetry enable

El comando reset restablece los datos de telemetría:

astro telemetry reset

`astro create-key`

Genera una clave para cifrar las props pasadas a server islands.

astro create-key

Establece esta clave como la variable de entorno ASTRO_KEY (por ejemplo, en un archivo .env) e inclúyela en la configuración de construcción de tu CI/CD o del hosting cuando necesites una clave de cifrado constante para tus server islands para situaciones como despliegues continuos, alojamiento multirregión o una CDN que almacena en caché páginas que contienen server islands.

Flags comunes

`--root <path>`

Especifica la ruta al directorio raíz del proyecto. Si no se especifica, se asume que el directorio de trabajo actual es el directorio raíz.

La raíz se utiliza para encontrar el archivo de configuración de Astro.

astro --root myRootFolder/myProjectFolder dev

`--config <path>`

Especifica la ruta al archivo de configuración relativa a la raíz del proyecto. Por defecto es astro.config.mjs. Usa esto si utilizas un nombre diferente para tu archivo de configuración o si tienes tu archivo de configuración en otra carpeta.

astro --config config/astro.config.mjs dev

`--force <string>`

Añadido en: astro@5.0.0

Borra la caché de la capa de contenido, forzando una reconstrucción completa.

`--mode <string>`

Añadido en: astro@5.0.0

Configura el config inline de mode para tu proyecto.

`--outDir <path>`

Añadido en: astro@3.3.0

Configura el outDir para tu proyecto. Pasar esta flag anulará el valor de outDir en tu archivo astro.config.mjs, si es que existe.

`--site <url>`

Configura el site para tu proyecto. Pasar esta flag anulará el valor de site en tu archivo astro.config.mjs, si es que existe.

`--base <pathname>`

Añadido en: astro@1.4.1

Configura el base para tu proyecto. Pasar esta flag anulará el valor de base en tu archivo astro.config.mjs, si es que existe.

`--port <number>`

Especifica en qué puerto ejecutar el servidor de desarrollo y el servidor de vista previa. Por defecto es 4321.

`--host [dirección de host opcional]`

Establece en qué direcciones IP de red deben escuchar el servidor de desarrollo y el servidor de vista previa (es decir, direcciones IP que no sean localhost). Esto puede ser útil para probar tu proyecto en dispositivos locales como un teléfono móvil durante el desarrollo.

--host — escucha en todas las direcciones, incluyendo LAN y direcciones públicas
--host <custom-address> — expone en una dirección IP de red en <custom-address>

`--allowed-hosts`

Añadido en: astro@5.4.0

Especifica los nombres de host a los que Astro tiene permitido responder en los modos dev o preview. Se le puede pasar una lista de nombres de host separados por comas o true para permitir cualquier nombre de host.

Consulta la función allowedHosts de Vite para obtener más información, incluyendo las implicaciones de seguridad de permitir nombres de host.

`--verbose`

Permite el registro detallado (verbose), lo cual es útil al depurar un problema.

`--silent`

Permite el registro silencioso, que ejecutará el servidor sin ninguna salida en la consola.

`--open`

Abre automáticamente la aplicación en el navegador al iniciar el servidor. Se le puede pasar una cadena de URL completa (por ejemplo, --open http://example.com) o una ruta (por ejemplo, --open /about) para especificar la URL a abrir.

`--json`

Añadido en: astro@7.0.0 Nuevo

Habilita el registro JSON, lo cual es útil para obtener una salida legible por máquina.

Flags globales

Usa estas flags para obtener información sobre la CLI de astro.

`--version`

Imprime el número de versión de Astro y sale.

`--help`

Imprime el mensaje de ayuda y sale.

Contribuir Comunidad Patrocinar

Comandos de la CLI

comandos de astro

Scripts de package.json

astro dev

Flags

--background

Subcomandos

astro dev stop

astro dev status

astro dev logs

Flags

--follow (-f)

astro build

Flags

--devOutput

astro preview

astro check

Flags

--watch

--root <ruta-al-directorio>

--tsconfig <ruta-al-archivo>

--minimumFailingSeverity <error|warning|hint>

--minimumSeverity <error|warning|hint>

--preserveWatchOutput

--noSync

astro sync

astro add

astro docs

astro info

Flags

--copy

astro preferences

Preferencias disponibles

astro telemetry

astro create-key

Flags comunes

--root <path>

--config <path>

--force <string>

--mode <string>

--outDir <path>

--site <url>

--base <pathname>

--port <number>

--host [dirección de host opcional]

--allowed-hosts

--verbose

--silent

--open

--json

Flags globales

--version

--help

comandos de `astro`

Scripts de `package.json`

`astro dev`

`--background`

`astro dev stop`

`astro dev status`

`astro dev logs`

`--follow` (`-f`)

`astro build`

`--devOutput`

`astro preview`

`astro check`

`--watch`

`--root <ruta-al-directorio>`

`--tsconfig <ruta-al-archivo>`

`--minimumFailingSeverity <error|warning|hint>`

`--minimumSeverity <error|warning|hint>`

`--preserveWatchOutput`

`--noSync`

`astro sync`

`astro add`

`astro docs`

`astro info`

`--copy`

`astro preferences`

`astro telemetry`

`astro create-key`

`--root <path>`

`--config <path>`

`--force <string>`

`--mode <string>`

`--outDir <path>`

`--site <url>`

`--base <pathname>`

`--port <number>`

`--host [dirección de host opcional]`

`--allowed-hosts`

`--verbose`

`--silent`

`--open`

`--json`

`--version`

`--help`