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 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)

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
joppa dbs <service>	databases	A server’s databases and their URLs
joppa proxy start|stop		Starts or stops the proxy
joppa open		Shows the window
joppa mcp		Runs the MCP server over stdio
joppa help, joppa version		Help and version

Naming a service

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

Options

Option	Effect
--json, -j	JSON output, for scripts (on every command)
--launch	Launches Joppa if it isn’t running, without asking
--theme nuit|jour|auto	TUI theme
--no-motion	Turns off animations (or JOPPA_NO_MOTION=1)
-h, -v	Help, version

In a script

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

Exit codes

Code	Meaning
0	Success
1	Error
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.