The joppa command

joppa drives the running app. It does the same things as the window, from a terminal or a script.

Install

Settings › Command line › Install joppa. Joppa creates a link to the command shipped inside the app, in /usr/local/bin if possible, otherwise in ~/.local/bin. If that folder isn’t in your PATH, Settings gives you the line to add to ~/.zshrc.

joppa version

Commands

joppa                         # the full-screen app in the terminal (TUI)
joppa status                  # proxy, CA, projects and domains, services
joppa services                # services and their status
joppa start postgres          # starts a service
joppa stop redis              # stops a service
joppa logs postgres -n 200 -f # the log, streamed with -f
joppa procs                   # the projects' processes
joppa start acme              # starts the whole project (Start all)
joppa restart acme web        # restarts a process
joppa logs acme api --grep error # a process's log, filtered
joppa diagnose api.acme.test  # why this domain doesn't respond
joppa share app.acme.test     # sharing on the local network, with a QR code
joppa dbs postgres            # databases and their connection URLs
joppa proxy start             # or stop
joppa open                    # shows the Joppa window
joppa mcp                     # the MCP server (see below)
joppa uninstall               # uninstalls Joppa, this command included

Command	Alias	Role
joppa or joppa tui		Opens the TUI
joppa status	st	Proxy, CA, projects, domains and their health, services
joppa services	svc	Services and their status
joppa start <service>		Starts a service
joppa stop <service>		Stops a service
joppa logs <service>	log	The log: -n / --lines N (100 by default), -f / --follow, --grep
joppa procs [project]	ps, processes	The processes of a project, or of every project that has some: status, port, domains, uptime, relaunches
joppa start <project> [process]		Starts a process (and those it depends on), or the whole project
joppa stop <project> [process]		Stops a process, or the whole project
joppa restart <project> [process]		Restarts a process, or every one that is running or checked
joppa logs <project> [process]	log	The output of a process, or of all of them (prefixed with their name): -n, -f, --grep
joppa diagnose <domain|project>	doctor	Why a domain doesn’t respond: proxy, DNS, certificate, port, process, response
joppa share [domain|project]	partager	Shares a domain on the local network; --public through a tunnel (see Share a domain). With no argument: the open shares
joppa share stop <domain>		Stops sharing (--public: the tunnel only)
joppa dbs <service>	databases	A server’s databases and their URLs
joppa db <action> <service> …		Export, import, copy and snapshots of a database (see Database data)
joppa proxy start|stop		Starts or stops the proxy
joppa open		Shows the window
joppa mcp		Runs the MCP server over stdio
joppa uninstall		Uninstalls Joppa (see Uninstall)
joppa help, joppa version		Help and version

Naming a service

You can refer to a service however you like: postgres, pg18, "PostgreSQL 18", its port 5432 or its ID.

Naming a project and its processes

A project is named by its name, its ID or one of its domains; a process by its name in the Processes tab (web, api, queue…). joppa start, stop and logs take a service or a project: with a single word, Joppa looks for a service first. If the word matches both a service and a project, the command says so: write the service’s port or one of the project’s domains.

joppa start and joppa restart wait for the processes to respond or crash (30 seconds at most), then show their status; a process that crashes is followed by the last lines of its log, and the command exits with 1.

joppa diagnose checks every link between the browser and the dev server, and tells you how to fix what’s missing (the details are in English, as with the diagnose MCP tool). It exits with 1 if a domain doesn’t respond.

Options

Option	Effect
--json, -j	JSON output, for scripts (on every command)
--launch	Launches Joppa if it isn’t running, without asking
--grep <text>, -g	joppa logs: only the lines that contain this text (case-insensitive)
--public	joppa share: a public link through a tunnel (Joppa Pro)
--tunnel <client>	joppa share: cloudflared (default), ngrok, localhost-run or pinggy; implies --public
--install	joppa share --public: downloads cloudflared if it’s missing (checksum verified)
--theme nuit|jour|auto	TUI theme
--no-motion	Turns off animations (or JOPPA_NO_MOTION=1)
-h, -v	Help, version

Share a domain

joppa share does from the terminal what the Share window does (see Share a site). The share lives in the app: it stays open after the command, until joppa share stop or until Joppa quits.

joppa share app.acme.test                    # http://192.168.1.20:41306 and its QR code
joppa share acme                             # the project's first enabled domain
joppa share app.acme.test --public           # https://….trycloudflare.com (Joppa Pro)
joppa share app.acme.test --public --install # downloads cloudflared first if it's missing
joppa share app.acme.test --tunnel pinggy    # or ngrok, localhost-run
joppa share                                  # the shared domains
joppa share stop app.acme.test               # closes the local network share and the tunnel
joppa share stop app.acme.test --public      # the tunnel only

In a terminal, the address shows with a QR code to scan. With --public, the command waits for the tunnel to get its address (50 seconds at most); if it closes before that, the command shows its last messages and exits with 1.

Database data

joppa db does from the terminal what Export…, Import…, Duplicate… and Snapshots… do on a service’s page (see Databases). The server must be running; relative paths start from the current folder.

joppa db export postgres acme                       # ./acme-2026-10-23.sql.gz
joppa db export mysql shop ~/shop.sql               # .sql, .sql.gz or .dump (PostgreSQL)
joppa db import postgres ~/acme.sql.gz              # into the acme database (from the file name)
joppa db import postgres ~/acme.dump --into acme_test
joppa db import postgres ~/joppa-postgres-17-2026-10-20.sql --replace   # a whole server
joppa db clone postgres acme acme_feature
joppa db snapshot postgres acme --name "before the migration"
joppa db snapshots postgres acme                    # id, date, size, name
joppa db restore postgres acme 20261023-142501

Command	Does
joppa db export <service> <database> [file]	Exports a database; the format follows the extension (.sql.gz by default)
joppa db import <service> <file>	Imports a .sql, .sql.gz, .dump or the export of a whole server; --into <database> picks the database, --replace replaces one that exists
joppa db clone <service> <database> <copy>	Copies a database on the same server
joppa db snapshot <service> <database>	Takes a snapshot (Joppa Pro); --name <name> names it
joppa db snapshots <service> <database>	The snapshots of a database, newest first
joppa db restore <service> <database> <snapshot>	Brings the database back to a snapshot (Joppa Pro), after a snapshot of what it holds now

Without --replace, an import that would replace a database stops before touching anything and suggests another name. PostgreSQL extensions missing from the server are flagged before the import.

Uninstall

joppa uninstall does what Settings › Uninstall does: it shows what Joppa installed on the machine, then removes it once you confirm. The joppa command itself goes with the rest. By default everything that is there is removed except the services’ data; Joppa’s folder and the app are deleted once Joppa has quit. See Files and folders › Removing everything.

joppa uninstall --dry-run            # shows what would go, removes nothing
joppa uninstall                      # asks for confirmation (o/N)
joppa uninstall --yes --volumes      # no question, services' data included
joppa uninstall -y --keep license,app

Option	Effect
--dry-run	Shows the list, removes nothing
--yes, -y	Doesn’t ask for confirmation (required outside a terminal)
--volumes	Also deletes the services’ data (volumes), and their containers
--keep <pieces>	Keeps items: mcp, cli, shell, containers, volumes, ca, dns, license, data, app

If a step fails (password cancelled, runtime stopped…), the others go on, but Joppa’s folder and the app are kept and the command exits with 1: fix it, then run joppa uninstall again.

In a script

# Launch Joppa if needed, then start PostgreSQL before the tests
joppa start postgres --launch
joppa services --json | jq .

# Start the project and fail if a process crashes
joppa start acme --json | jq '.processes[] | {name, status}'

Exit codes

Code	Meaning
0	Success
1	Error; also a process that crashes on startup, or a domain that joppa diagnose finds broken
2	Bad command or option
3	Joppa isn’t running

How it works

The app writes a control.json file in its config folder (a port and a token, readable only by you). The command uses it to talk to the app’s local API. If Joppa isn’t running, joppa says so and offers to launch it.