El comando joppa

joppa controla la app en ejecución. Hace lo mismo que la ventana, desde una terminal o un script.

Instalar

Ajustes › Línea de comandos › Instalar joppa. Joppa crea un enlace al comando incluido en la app, en /usr/local/bin si es posible o, si no, en ~/.local/bin. Si esa carpeta no está en tu PATH, los Ajustes te dan la línea que debes añadir a ~/.zshrc.

joppa version

Los comandos

joppa                         # la app a pantalla completa en la terminal (TUI)
joppa status                  # proxy, CA, proyectos y dominios, servicios
joppa services                # los servicios y su estado
joppa start postgres          # inicia un servicio
joppa stop redis              # detiene un servicio
joppa logs postgres -n 200 -f # el registro, en continuo con -f
joppa procs                   # los procesos de los proyectos
joppa start acme              # inicia todo el proyecto (Iniciar todo)
joppa restart acme web        # reinicia un proceso
joppa logs acme api --grep error # el registro de un proceso, filtrado
joppa diagnose api.acme.test  # por qué este dominio no responde
joppa share app.acme.test     # compartir en la red local, con un código QR
joppa dbs postgres            # las bases de datos y sus URL de conexión
joppa proxy start             # o stop
joppa open                    # muestra la ventana de Joppa
joppa mcp                     # el servidor MCP (ver más abajo)
joppa uninstall               # desinstala Joppa, incluido este comando

Comando	Alias	Función
joppa o joppa tui		Abre el TUI
joppa status	st	Proxy, CA, proyectos, dominios y su salud, servicios
joppa services	svc	Los servicios y su estado
joppa start <service>		Inicia un servicio
joppa stop <service>		Detiene un servicio
joppa logs <service>	log	El registro: -n / --lines N (100 por defecto), -f / --follow, --grep
joppa procs [proyecto]	ps, processes	Los procesos de un proyecto, o de todos los que tienen: estado, puerto, dominios, duración, reinicios
joppa start <proyecto> [proceso]		Inicia un proceso (y aquellos de los que depende), o todo el proyecto
joppa stop <proyecto> [proceso]		Detiene un proceso, o todo el proyecto
joppa restart <proyecto> [proceso]		Reinicia un proceso, o todos los que están en marcha o marcados
joppa logs <proyecto> [proceso]	log	La salida de un proceso, o de todos (precedida de su nombre): -n, -f, --grep
joppa diagnose <dominio|proyecto>	doctor	Por qué un dominio no responde: proxy, DNS, certificado, puerto, proceso, respuesta
joppa share [dominio|proyecto]	partager	Comparte un dominio en la red local; --public con un túnel (consulta Compartir un dominio). Sin argumento: los recursos compartidos abiertos
joppa share stop <dominio>		Deja de compartir (--public: solo el túnel)
joppa dbs <service>	databases	Las bases de datos de un servidor y sus URL
joppa db <acción> <servicio> …		Exportación, importación, copia e instantáneas de una base (consulta Los datos de las bases)
joppa proxy start|stop		Inicia o detiene el proxy
joppa open		Muestra la ventana
joppa mcp		Inicia el servidor MCP en stdio
joppa uninstall		Desinstala Joppa (ver Desinstalar)
joppa help, joppa version		Ayuda y versión

Indicar un servicio

Puedes referirte a un servicio como quieras: postgres, pg18, "PostgreSQL 18", su puerto 5432 o su identificador.

Indicar un proyecto y sus procesos

Un proyecto se indica por su nombre, su identificador o uno de sus dominios; un proceso, por su nombre en la pestaña Procesos (web, api, queue…). joppa start, stop y logs aceptan un servicio o un proyecto: con una sola palabra, Joppa busca primero un servicio. Si la palabra designa a la vez un servicio y un proyecto, el comando lo dice: escribe el puerto del servicio o un dominio del proyecto.

joppa start y joppa restart esperan a que los procesos respondan o fallen (30 segundos como máximo) y luego muestran su estado; un proceso que falla va seguido de las últimas líneas de su registro, y el comando sale con 1.

joppa diagnose comprueba cada eslabón entre el navegador y el servidor de desarrollo y dice cómo reparar lo que falta (los detalles están en inglés, como en la herramienta MCP diagnose). Sale con 1 si un dominio no responde.

Las opciones

Opción	Efecto
--json, -j	Salida JSON, para los scripts (en todos los comandos)
--launch	Inicia Joppa si no está en marcha, sin preguntar
--grep <texto>, -g	joppa logs: solo las líneas que contienen este texto (sin distinguir mayúsculas y minúsculas)
--public	joppa share: un enlace público con un túnel (Joppa Pro)
--tunnel <cliente>	joppa share: cloudflared (por defecto), ngrok, localhost-run o pinggy; implica --public
--install	joppa share --public: descarga cloudflared si falta (huella comprobada)
--theme nuit|jour|auto	Tema del TUI
--no-motion	Desactiva las animaciones (o JOPPA_NO_MOTION=1)
-h, -v	Ayuda, versión

Compartir un dominio

joppa share hace desde el terminal lo mismo que la ventana Compartir (consulta Compartir un sitio). El recurso compartido vive en la app: sigue abierto después del comando, hasta joppa share stop o hasta que Joppa se cierre.

joppa share app.acme.test                    # http://192.168.1.20:41306 y su código QR
joppa share acme                             # el primer dominio activo del proyecto
joppa share app.acme.test --public           # https://….trycloudflare.com (Joppa Pro)
joppa share app.acme.test --public --install # descarga antes cloudflared si falta
joppa share app.acme.test --tunnel pinggy    # o ngrok, localhost-run
joppa share                                  # los dominios compartidos
joppa share stop app.acme.test               # cierra la red local y el túnel
joppa share stop app.acme.test --public      # solo el túnel

En un terminal, la dirección se muestra con un código QR para escanear. Con --public, el comando espera a que el túnel tenga su dirección (50 segundos como máximo); si se cierra antes, muestra sus últimos mensajes y sale con 1.

Los datos de las bases

joppa db hace desde la terminal lo que hacen Exportar…, Importar…, Duplicar… e Instantáneas… en la página de un servicio (consulta Bases de datos). El servidor debe estar en ejecución; las rutas relativas parten de la carpeta actual.

joppa db export postgres acme                       # ./acme-2026-10-23.sql.gz
joppa db export mysql tienda ~/tienda.sql           # .sql, .sql.gz o .dump (PostgreSQL)
joppa db import postgres ~/acme.sql.gz              # en la base acme (según el nombre del archivo)
joppa db import postgres ~/acme.dump --into acme_test
joppa db import postgres ~/joppa-postgres-17-2026-10-20.sql --replace   # un servidor entero
joppa db clone postgres acme acme_feature
joppa db snapshot postgres acme --name "antes de la migración"
joppa db snapshots postgres acme                    # identificador, fecha, tamaño, nombre
joppa db restore postgres acme 20261023-142501

Comando	Función
joppa db export <servicio> <base> [archivo]	Exporta una base; el formato sigue la extensión (.sql.gz por defecto)
joppa db import <servicio> <archivo>	Importa un .sql, .sql.gz, .dump o la exportación de un servidor entero; --into <base> elige la base, --replace reemplaza una que existe
joppa db clone <servicio> <base> <copia>	Copia una base en el mismo servidor
joppa db snapshot <servicio> <base>	Toma una instantánea (Joppa Pro); --name <nombre> le da nombre
joppa db snapshots <servicio> <base>	Las instantáneas de una base, de la más reciente a la más antigua
joppa db restore <servicio> <base> <instantánea>	Devuelve la base a una instantánea (Joppa Pro), tras una instantánea de lo que contiene ahora

Sin --replace, una importación que reemplazaría una base se detiene antes de tocar nada y propone otro nombre. Las extensiones de PostgreSQL que faltan en el servidor se señalan antes de la importación.

Desinstalar

joppa uninstall hace lo mismo que Ajustes › Desinstalar: muestra lo que Joppa instaló en el equipo y lo elimina tras tu confirmación. El propio comando joppa se va con el resto. Por defecto se elimina todo lo que hay salvo los datos de los servicios; la carpeta de Joppa y la app se eliminan una vez cerrado Joppa. Ver Archivos y carpetas › Quitarlo todo.

joppa uninstall --dry-run            # muestra lo que se eliminaría, sin eliminar nada
joppa uninstall                      # pide confirmación (o/N)
joppa uninstall --yes --volumes      # sin preguntar, datos de los servicios incluidos
joppa uninstall -y --keep license,app

Opción	Efecto
--dry-run	Muestra la lista, no elimina nada
--yes, -y	No pide confirmación (obligatorio fuera de un terminal)
--volumes	Elimina también los datos de los servicios (volúmenes) y sus contenedores
--keep <elementos>	Conserva elementos: mcp, cli, shell, containers, volumes, ca, dns, license, data, app

Si un paso falla (contraseña cancelada, runtime detenido…), los demás continúan, pero la carpeta de Joppa y la app se conservan y el comando sale con 1: corrígelo y vuelve a ejecutar joppa uninstall.

En un script

# Iniciar Joppa si hace falta y luego arrancar PostgreSQL antes de los tests
joppa start postgres --launch
joppa services --json | jq .

# Iniciar el proyecto y fallar si un proceso falla
joppa start acme --json | jq '.processes[] | {name, status}'

Códigos de salida

Código	Significado
0	Éxito
1	Error; también un proceso que falla al iniciarse, o un dominio que joppa diagnose encuentra averiado
2	Comando u opción incorrectos
3	Joppa no está en marcha

Cómo funciona

La app escribe en su carpeta de configuración un archivo control.json (un puerto y un token, legible solo por ti). El comando lo usa para hablar con la API local de la app. Si Joppa no está en marcha, joppa lo dice y propone iniciarlo.