Ir al contenido

Documentación Línea de comandos

Línea de comandos

vmpal es la herramienta de línea de comandos de VMPal, como docker o gh. Úsala en Terminal, en tus propios scripts y en CI. Crea e inicia máquinas virtuales, ejecuta comandos en ellas y copia archivos hacia dentro y hacia fuera. También puede leer la pantalla de una máquina virtual como una lista de sus ventanas, botones y textos, hacer capturas de pantalla, y hacer clic y escribir en ella. Además, crea y ejecuta los scripts del Hub de VMPal.

Pregúntale a tu agente de IA

La forma más rápida de usar vmpal es pedírselo a tu agente de programación. VMPal le da a tu agente la ayuda completa y las guías de vmpal para tu versión de VMPal. Tu agente escribe los comandos o el script y te los explica. Si tiene una terminal en este Mac, también los ejecuta. Instalar vmpal requiere tu contraseña de administrador, así que, si todavía no está instalado, tu agente te da el comando para que lo ejecutes tú.

  1. En VMPal, abre Ajustes › Agentes de IA y activa Permitir que los agentes de programación de este Mac gestionen todas las máquinas virtuales. Así, tu agente también puede gestionar tus máquinas virtuales y tus scripts. Para explicarte vmpal no necesita este ajuste.
  2. Haz clic en Añadir a Claude Code, Añadir a Codex, Añadir a Grok Build o Añadir a Antigravity. Para Cursor, VS Code, Kiro y otros agentes, haz clic en Otros…. Si tu agente no aparece, Configuración manual… muestra lo que hay que añadir. Después, reinicia el agente.
  3. Pídele, por ejemplo:
    • “Muéstrame la línea de comandos de VMPal.”
    • “Configura un trabajo de GitHub Actions que ejecute mis pruebas en un clon nuevo de mi máquina virtual de Ubuntu.”
    • “Escribe un script que copie este proyecto a mi máquina virtual de Windows y lo compile.”

Instalación

vmpal viene dentro de VMPal. Para usarlo, crea un enlace en una carpeta de tu PATH:

sudo mkdir -p /usr/local/bin
sudo ln -sf /Applications/VMPal.app/Contents/Helpers/VMPalMachine.app/Contents/MacOS/VMPalMachine /usr/local/bin/vmpal

Enlázalo, no lo copies: vmpal encuentra VMPal a través del enlace. Sin el enlace, ejecútalo por su ruta completa con --cli:

"/Applications/VMPal.app/Contents/Helpers/VMPalMachine.app/Contents/MacOS/VMPalMachine" --cli <command>

Ejecuta vmpal como el usuario que tiene la sesión iniciada en el Mac. Si VMPal no está abierto, vmpal lo abre en segundo plano.

Consulta su ayuda

Como la mayoría de las herramientas de línea de comandos, vmpal incluye ayuda. Sus guías te acompañan en las tareas habituales.

vmpal help              # every command
vmpal help run          # one command's options, and its guide
vmpal help ci           # a guide: setup, ci, exec, cp, sign-in or ui
vmpal ui help           # ui's own commands

Comandos enumera todos los comandos. CI/CD explica cómo ejecutar cada trabajo de CI en un clon nuevo de una máquina virtual.

Lo básico

  • Cómo nombrar una máquina virtual. Usa su nombre ("Windows 11"), su ID o la ruta de su carpeta .vmpal. También sirven los 4 primeros caracteres del ID, o más. vmpal list muestra los nombres y los ID. En el <VM>:<path> de cp, usa el nombre o el ID.
  • La salida es texto plano. --json imprime la respuesta como una línea de JSON, para que la lean los scripts. En exec, es el resultado completo al final, en lugar de la salida a medida que llega. -q imprime solo los ID. Funciona con list, create, clone, script list, script run y script runs.
  • Sin preguntas. vmpal nunca se detiene a preguntarte nada en la línea de comandos, así que es seguro en scripts y en CI. Cuando no puede hacer algo, falla y explica por qué. Algunas esperas necesitan que actúe una persona, como un inicio de sesión que VMPal no puede hacer. Cuando haces que un script se ejecute en este Mac, VMPal sigue lo que elegiste en Scripts en este Mac.
  • Tiempos límite. Una espera termina con error al cumplirse su --timeout. Escríbelo como 90 (segundos), 90s, 10m, 2h o 1h30m, hasta 24h. vmpal ui es distinto: su --timeout va en milisegundos, o 10s, hasta 45 segundos.
  • Control por agentes. Cada máquina virtual tiene un ajuste que permite a vmpal y a los agentes de IA trabajar dentro de ella: Ajustes › Agentes de IA › Permitir que los agentes controlen esta máquina virtual. exec, cp, run, ssh, ui y sign-in lo necesitan, igual que las esperas hasta que una máquina virtual puede ejecutar comandos, como start --wait. En run, lo necesita la máquina virtual que se clona. Está activado salvo que alguien lo haya desactivado. vmpal set <VM> --agent-control on lo vuelve a activar.
  • El ajuste de todo el Mac. vmpal no necesita Permitir que los agentes de programación de este Mac gestionen todas las máquinas virtuales. Ese ajuste es para los agentes de IA.

Códigos de salida

Como cualquier herramienta de línea de comandos, vmpal le indica a tu script o a tu trabajo de CI cómo ha ido mediante su código de salida.

Código Significado
0 Ha funcionado
1 VMPal o la máquina virtual se han negado, o una espera ha agotado su tiempo límite
2 La línea de comandos era incorrecta

exec y run terminan con el código del propio comando, así que una prueba que falla hace fallar tu trabajo de CI. También usan estos códigos:

Código Significado
1 El código del comando estaba fuera del rango de 0 a 255, como el 0xC0000005 de Windows. vmpal lo imprime
124 El comando superó el --timeout
125 vmpal no pudo ejecutar el comando. En run, también cuando no se pudo crear o iniciar el clon, o falló una copia
128 + N La señal N detuvo vmpal

ssh termina con el código del propio ssh, que es 255 cuando no pudo conectarse. Termina con 125 cuando vmpal no pudo iniciar ssh.

Comandos en una máquina virtual

vmpal exec ejecuta un comando en una máquina virtual, igual que docker exec lo ejecuta en un contenedor. Algunas cosas funcionan de forma distinta a un shell en tu Mac.

  • Sin shell. exec ejecuta el programa directamente. Para usar tuberías, && o variables, ejecuta tú mismo un shell: vmpal exec "Ubuntu" -- /bin/sh -c 'make && make test'. En Windows, usa powershell.exe -Command '...'.
  • Quién los ejecuta. Los comandos se ejecutan como el usuario que ha iniciado sesión en la máquina virtual. En Linux, si nadie ha iniciado sesión, se ejecutan con la cuenta de la máquina virtual. En Windows, obtienen derechos estándar.
  • Administrador. --admin los ejecuta como root, como sudo, o con privilegios elevados en Windows, como Ejecutar como administrador. En una máquina virtual de macOS, --admin necesita antes la aprobación de un administrador dentro de la máquina virtual, y vuelve a necesitarla cuando se actualizan VMPal Tools. vmpal help exec explica cómo.
  • Salida de texto. exec lee la salida como texto UTF-8. Eso altera la salida binaria, así que copia los archivos binarios con cp.
  • Inicio de sesión. Los comandos que esperan hasta que una máquina virtual puede ejecutar comandos también inician sesión por ti en una pantalla de inicio de sesión de Windows o macOS. Entre ellos están create --wait, start --wait y wait. Usan la contraseña que guarda VMPal: la escribe la máquina virtual, y vmpal nunca la ve. --no-sign-in lo desactiva.
  • Contraseñas. Solo info --show-password y tool --show-password imprimen la contraseña de una máquina virtual. create también imprime la contraseña de la nueva máquina virtual cuando el llavero no puede guardarla. create --password-file <path> la escribe en un archivo que solo tú puedes leer.
  • VMPal Tools. VMPal Tools son los componentes auxiliares de VMPal dentro de cada máquina virtual. Los comandos que duran más de 10 minutos, --env y la salida a medida que llega necesitan VMPal Tools 0.34 en macOS, 0.35 en Linux y 0.37 en Windows. VMPal actualiza VMPal Tools cuando se inicia una máquina virtual.
  • Máquinas virtuales “Solo terminal”. vmpal create <system> --terminal-only instala Linux sin escritorio. La máquina virtual aparece como una pestaña de la ventana de terminal de VMPal. vmpal systems indica qué sistemas lo admiten. vmpal ssh <VM> inicia sesión en ella con el ssh de este Mac. A diferencia de exec, te da entrada y una terminal.

Scripts

El Hub de VMPal guarda tus scripts y los ejecuta cuando se lo pides. Tú eliges dónde se ejecuta cada uno:

Opción Dónde se ejecuta
--run-in <VM> En un clon nuevo de la máquina virtual en cada ejecución, como un runner de CI limpio
--run-in-place <VM> En la propia máquina virtual
--host En este Mac, según lo que permita Scripts en este Mac
vmpal script create "Test App" --file test-app.sh --run-in "Ubuntu"   # a fresh clone of Ubuntu each run
vmpal script run "Test App" --wait                                    # run it now, and exit with its status
vmpal script log "Test App"                                           # the run's output

Scripts explica cómo funcionan. Comandos enumera el resto.