La commande joppa

joppa pilote l’app qui tourne. Elle fait la même chose que la fenêtre, depuis un terminal ou un script.

Installer

Réglages › Ligne de commande › Installer joppa. Joppa crée un lien vers la commande livrée dans l’app, dans /usr/local/bin si possible, sinon dans ~/.local/bin. Si ce dossier n’est pas dans votre PATH, les Réglages donnent la ligne à ajouter à ~/.zshrc.

joppa version

Les commandes

joppa                         # l'app en plein écran dans le terminal (TUI)
joppa status                  # proxy, CA, projets et domaines, services
joppa services                # les services et leur état
joppa start postgres          # démarre un service
joppa stop redis              # arrête un service
joppa logs postgres -n 200 -f # le journal, en continu avec -f
joppa procs                   # les processus des projets
joppa start acme              # démarre tout le projet (Tout démarrer)
joppa restart acme web        # redémarre un processus
joppa logs acme api --grep error # le journal d'un processus, filtré
joppa diagnose api.acme.test  # pourquoi ce domaine ne répond pas
joppa share app.acme.test     # le partage sur le réseau local, avec un QR code
joppa dbs postgres            # les bases et leurs URL de connexion
joppa db export postgres acme # exporte une base (voir plus bas)
joppa proxy start             # ou stop
joppa open                    # affiche la fenêtre de Joppa
joppa mcp                     # le serveur MCP (voir plus bas)
joppa uninstall               # désinstalle Joppa, cette commande comprise

Commande	Alias	Rôle
joppa ou joppa tui		Ouvre le TUI
joppa status	st	Proxy, CA, projets, domaines et leur santé, services
joppa services	svc	Les services et leur état
joppa start <service>		Démarre un service
joppa stop <service>		Arrête un service
joppa logs <service>	log	Le journal : -n / --lines N (100 par défaut), -f / --follow, --grep
joppa procs [projet]	ps, processes	Les processus d’un projet, ou de tous ceux qui en ont : état, port, domaines, durée, relances
joppa start <projet> [processus]		Démarre un processus (et ceux dont il dépend), ou tout le projet
joppa stop <projet> [processus]		Arrête un processus, ou tout le projet
joppa restart <projet> [processus]		Redémarre un processus, ou tous ceux qui tournent ou sont cochés
joppa logs <projet> [processus]	log	La sortie d’un processus, ou de tous (préfixée par leur nom) : -n, -f, --grep
joppa diagnose <domaine|projet>	doctor	Pourquoi un domaine ne répond pas : proxy, DNS, certificat, port, processus, réponse
joppa share [domaine|projet]	partager	Partage un domaine sur le réseau local ; --public par un tunnel (voir Partager un domaine). Sans argument : les partages ouverts
joppa share stop <domaine>		Arrête le partage (--public : le tunnel seulement)
joppa dbs <service>	databases	Les bases d’un serveur et leurs URL
joppa db <action> <service> …		Export, import, copie et instantanés d’une base (voir Les données des bases)
joppa proxy start|stop		Démarre ou arrête le proxy
joppa open		Affiche la fenêtre
joppa mcp		Lance le serveur MCP sur stdio
joppa uninstall		Désinstalle Joppa (voir Désinstaller)
joppa help, joppa version		Aide et version

Désigner un service

Un service se désigne comme vous voulez : postgres, pg18, "PostgreSQL 18", son port 5432 ou son identifiant.

Désigner un projet et ses processus

Un projet se désigne par son nom, son identifiant ou l’un de ses domaines ; un processus par son nom dans l’onglet Processus (web, api, queue…). joppa start, stop et logs prennent un service ou un projet : avec un seul mot, Joppa cherche d’abord un service. Si le mot désigne à la fois un service et un projet, la commande le dit : écrivez le port du service ou un domaine du projet.

joppa start et joppa restart attendent que les processus répondent ou plantent (30 secondes au plus), puis affichent leur état ; un processus qui plante est suivi des dernières lignes de son journal, et la commande sort en 1.

joppa diagnose vérifie chaque maillon entre le navigateur et le serveur de dev, et dit comment réparer ce qui manque (les détails sont en anglais, comme pour l’outil MCP diagnose). Il sort en 1 si un domaine ne répond pas.

Les options

Option	Effet
--json, -j	Sortie JSON, pour les scripts (sur toutes les commandes)
--launch	Lance Joppa s’il ne tourne pas, sans demander
--grep <texte>, -g	joppa logs : seulement les lignes qui contiennent ce texte (sans tenir compte de la casse)
--public	joppa share : un lien public par un tunnel (Joppa Pro)
--tunnel <client>	joppa share : cloudflared (par défaut), ngrok, localhost-run ou pinggy ; implique --public
--install	joppa share --public : télécharge cloudflared s’il manque (empreinte vérifiée)
--theme nuit|jour|auto	Thème du TUI
--no-motion	Coupe les animations (ou JOPPA_NO_MOTION=1)
-h, -v	Aide, version

Partager un domaine

joppa share fait depuis le terminal ce que fait la fenêtre Partager (voir Partager un site). Le partage vit dans l’app : il reste ouvert après la commande, jusqu’à joppa share stop ou la fermeture de Joppa.

joppa share app.acme.test                    # http://192.168.1.20:41306 et son QR code
joppa share acme                             # le premier domaine actif du projet
joppa share app.acme.test --public           # https://….trycloudflare.com (Joppa Pro)
joppa share app.acme.test --public --install # télécharge cloudflared d'abord s'il manque
joppa share app.acme.test --tunnel pinggy    # ou ngrok, localhost-run
joppa share                                  # les domaines partagés
joppa share stop app.acme.test               # ferme le réseau local et le tunnel
joppa share stop app.acme.test --public      # le tunnel seulement

Dans un terminal, l’adresse s’affiche avec un QR code à scanner. Avec --public, la commande attend que le tunnel ait son adresse (50 secondes au plus) ; s’il se ferme avant, elle affiche ses derniers messages et sort en 1.

Les données des bases

joppa db fait depuis le terminal ce que font Exporter…, Importer…, Dupliquer… et Instantanés… sur la page d’un service (voir Bases de données). Le serveur doit être démarré ; les chemins relatifs partent du dossier courant.

joppa db export postgres acme                       # ./acme-2026-10-23.sql.gz
joppa db export mysql boutique ~/boutique.sql       # .sql, .sql.gz ou .dump (PostgreSQL)
joppa db import postgres ~/acme.sql.gz              # dans la base acme (d'après le nom du fichier)
joppa db import postgres ~/acme.dump --into acme_test
joppa db import postgres ~/joppa-postgres-17-2026-10-20.sql --replace   # un serveur entier
joppa db clone postgres acme acme_feature
joppa db snapshot postgres acme --name "avant la migration"
joppa db snapshots postgres acme                    # identifiant, date, taille, nom
joppa db restore postgres acme 20261023-142501

Commande	Rôle
joppa db export <service> <base> [fichier]	Exporte une base ; le format suit l’extension (.sql.gz par défaut)
joppa db import <service> <fichier>	Importe un .sql, .sql.gz, .dump ou l’export d’un serveur entier ; --into <base> choisit la base, --replace remplace une base qui existe
joppa db clone <service> <base> <copie>	Copie une base sur le même serveur
joppa db snapshot <service> <base>	Prend un instantané (Joppa Pro) ; --name <nom> le nomme
joppa db snapshots <service> <base>	Les instantanés d’une base, du plus récent au plus ancien
joppa db restore <service> <base> <instantané>	Ramène la base à un instantané (Joppa Pro), après un instantané de son contenu actuel

Sans --replace, un import qui remplacerait une base s’arrête avant de rien toucher et propose un autre nom. Les extensions PostgreSQL absentes du serveur sont signalées avant l’import.

Désinstaller

joppa uninstall fait ce que fait Réglages › Désinstaller : il montre ce que Joppa a installé sur la machine, puis le retire après confirmation. La commande joppa elle-même part avec le reste. Par défaut, tout ce qui est là est retiré, sauf les données des services ; le dossier de Joppa et l’app sont supprimés une fois Joppa fermé. Voir Fichiers et dossiers › Tout retirer.

joppa uninstall --dry-run            # montre ce qui partirait, sans rien retirer
joppa uninstall                      # demande confirmation (o/N)
joppa uninstall --yes --volumes      # sans question, données des services comprises
joppa uninstall -y --keep license,app

Option	Effet
--dry-run	Montre la liste, ne retire rien
--yes, -y	Ne demande pas confirmation (obligatoire hors d’un terminal)
--volumes	Supprime aussi les données des services (volumes), et leurs conteneurs
--keep <pièces>	Garde des éléments : mcp, cli, shell, containers, volumes, ca, dns, license, data, app

Si une étape échoue (mot de passe annulé, runtime arrêté…), les autres continuent, mais le dossier de Joppa et l’app sont gardés et la commande sort en 1 : corrigez, puis relancez joppa uninstall.

Dans un script

# Lancer Joppa si besoin, puis démarrer PostgreSQL avant les tests
joppa start postgres --launch
joppa services --json | jq .

# Démarrer le projet et échouer si un processus plante
joppa start acme --json | jq '.processes[] | {name, status}'

Codes de sortie

Code	Signification
0	Succès
1	Erreur ; aussi un processus qui plante au démarrage, ou un domaine que joppa diagnose trouve en panne
2	Mauvaise commande ou option
3	Joppa n’est pas lancé

Comment ça marche

L’app écrit dans son dossier de config un fichier control.json (un port et un jeton, lisible par vous seul). La commande s’en sert pour parler à l’API locale de l’app. Si Joppa ne tourne pas, joppa le dit et propose de le lancer.