joppa 命令

joppa 用于控制正在运行的应用。它能做的事与窗口相同，只是在终端或脚本中进行。

安装

设置 › 命令行 › 安装 joppa。Joppa 会为应用内附带的命令创建一个链接，尽可能放在 /usr/local/bin，否则放在 ~/.local/bin。如果该文件夹不在你的 PATH 中，设置中会给出需要添加到 ~/.zshrc 的那一行。

joppa version

命令

joppa                         # 终端中的全屏应用（TUI）
joppa status                  # 代理、CA、项目和域名、服务
joppa services                # 服务及其状态
joppa start postgres          # 启动一个服务
joppa stop redis              # 停止一个服务
joppa logs postgres -n 200 -f # 日志，加 -f 持续输出
joppa procs                   # 项目的进程
joppa start acme              # 启动整个项目（全部启动）
joppa restart acme web        # 重启一个进程
joppa logs acme api --grep error # 某个进程的日志，经过筛选
joppa diagnose api.acme.test  # 这个域名为什么无响应
joppa share app.acme.test     # 在局域网中共享，附二维码
joppa dbs postgres            # 数据库及其连接 URL
joppa proxy start             # 或 stop
joppa open                    # 显示 Joppa 窗口
joppa mcp                     # MCP 服务器（见下文）
joppa uninstall               # 卸载 Joppa，包括此命令

命令	别名	作用
joppa 或 joppa tui		打开 TUI
joppa status	st	代理、CA、项目、域名及其健康状态、服务
joppa services	svc	服务及其状态
joppa start <service>		启动一个服务
joppa stop <service>		停止一个服务
joppa logs <service>	log	日志：-n / --lines N（默认 100）、-f / --follow、--grep
joppa procs [项目]	ps、processes	某个项目的进程，或所有有进程的项目：状态、端口、域名、运行时长、重启次数
joppa start <项目> [进程]		启动一个进程（及其依赖的进程），或整个项目
joppa stop <项目> [进程]		停止一个进程，或整个项目
joppa restart <项目> [进程]		重启一个进程，或所有正在运行或已勾选的进程
joppa logs <项目> [进程]	log	一个进程的输出，或所有进程的输出（以进程名为前缀）：-n、-f、--grep
joppa diagnose <域名|项目>	doctor	域名为什么无响应：代理、DNS、证书、端口、进程、响应
joppa share [域名|项目]	partager	在局域网中共享域名；--public 通过隧道共享（参见 共享域名）。不带参数时：列出已打开的共享
joppa share stop <域名>		停止共享（--public：只关闭隧道）
joppa dbs <service>	databases	某个服务器上的数据库及其 URL
joppa db <操作> <服务> …		数据库的导出、导入、复制和快照（参见 数据库的数据）
joppa proxy start|stop		启动或停止代理
joppa open		显示窗口
joppa mcp		在 stdio 上运行 MCP 服务器
joppa uninstall		卸载 Joppa（见卸载）
joppa help、joppa version		帮助和版本

指定服务

你可以用任意方式指定服务：postgres、pg17、"PostgreSQL 17"、它的端口 5432 或它的标识符。

指定项目及其进程

项目可以用它的名称、标识符或其中一个域名来指定；进程用它在 进程 标签页中的名称来指定（web、api、queue…）。joppa start、stop 和 logs 既接受服务也接受项目：只给一个词时，Joppa 会先查找服务。如果这个词同时指向一个服务和一个项目，命令会提示你：请改写服务的端口或项目的某个域名。

joppa start 和 joppa restart 会等待进程响应或崩溃（最多 30 秒），然后显示它们的状态；崩溃的进程后面会附上其日志的最后几行，命令以 1 退出。

joppa diagnose 检查浏览器与开发服务器之间的每个环节，并说明如何修复缺失的部分（详细信息为英文，与 MCP 工具 diagnose 相同）。如果某个域名无响应，它以 1 退出。

选项

选项	效果
--json、-j	JSON 输出，供脚本使用（适用于所有命令）
--launch	如果 Joppa 未运行，则直接启动它，不再询问
--grep <文本>、-g	joppa logs：只显示包含该文本的行（不区分大小写）
--public	joppa share：通过隧道生成公开链接（Joppa Pro）
--tunnel <客户端>	joppa share：cloudflared（默认）、ngrok、localhost-run 或 pinggy；隐含 --public
--install	joppa share --public：缺少 cloudflared 时下载它（会校验指纹）
--theme nuit|jour|auto	TUI 主题
--no-motion	关闭动画（或 JOPPA_NO_MOTION=1）
-h、-v	帮助、版本

共享域名

joppa share 在终端中完成 共享 窗口所做的事（参见 共享网站）。共享存在于应用中：命令结束后它仍保持打开，直到 joppa share stop 或 Joppa 退出。

joppa share app.acme.test                    # http://192.168.1.20:41306 及其二维码
joppa share acme                             # 项目的第一个已启用域名
joppa share app.acme.test --public           # https://….trycloudflare.com（Joppa Pro）
joppa share app.acme.test --public --install # 缺少 cloudflared 时先下载
joppa share app.acme.test --tunnel pinggy    # 或 ngrok、localhost-run
joppa share                                  # 已共享的域名
joppa share stop app.acme.test               # 关闭局域网共享和隧道
joppa share stop app.acme.test --public      # 只关闭隧道

在终端中，地址会连同一个可扫描的二维码一起显示。使用 --public 时，命令会等待隧道获得地址（最多 50 秒）；如果隧道在此之前关闭，命令会显示其最后的消息并以 1 退出。

数据库的数据

joppa db 在终端中完成服务页面上 导出…、导入…、复制… 和 快照… 所做的事（参见 数据库）。服务器必须正在运行；相对路径从当前文件夹开始。

joppa db export postgres acme                       # ./acme-2026-10-23.sql.gz
joppa db export mysql shop ~/shop.sql               # .sql、.sql.gz 或 .dump（PostgreSQL）
joppa db import postgres ~/acme.sql.gz              # 导入 acme 数据库（按文件名）
joppa db import postgres ~/acme.dump --into acme_test
joppa db import postgres ~/joppa-postgres-17-2026-10-20.sql --replace   # 整个服务器
joppa db clone postgres acme acme_feature
joppa db snapshot postgres acme --name "迁移之前"
joppa db snapshots postgres acme                    # 标识、日期、大小、名称
joppa db restore postgres acme 20261023-142501

命令	作用
joppa db export <服务> <数据库> [文件]	导出数据库；格式取决于扩展名（默认 .sql.gz）
joppa db import <服务> <文件>	导入 .sql、.sql.gz、.dump 或整个服务器的导出；--into <数据库> 选择数据库，--replace 替换已存在的数据库
joppa db clone <服务> <数据库> <副本>	在同一服务器上复制数据库
joppa db snapshot <服务> <数据库>	创建快照（Joppa Pro）；--name <名称> 为其命名
joppa db snapshots <服务> <数据库>	数据库的快照，从新到旧
joppa db restore <服务> <数据库> <快照>	让数据库回到某个快照（Joppa Pro），之前会先为当前内容创建快照

没有 --replace 时，会替换数据库的导入会在改动任何内容之前停止，并建议另一个名称。服务器上缺少的 PostgreSQL 扩展会在导入前提示。

卸载

joppa uninstall 与 设置 › 卸载 的作用相同：列出 Joppa 在这台电脑上安装的内容，确认后将其移除。joppa 命令本身也会一并移除。默认移除现有的所有内容，服务的数据除外；Joppa 文件夹和应用会在 Joppa 退出后删除。参见文件和文件夹 › 完全移除。

joppa uninstall --dry-run            # 显示将移除的内容，不做任何改动
joppa uninstall                      # 先请求确认（o/N）
joppa uninstall --yes --volumes      # 不询问，连同服务的数据
joppa uninstall -y --keep license,app

选项	作用
--dry-run	只显示列表，不移除任何内容
--yes、-y	不请求确认（在终端之外必须使用）
--volumes	同时删除服务的数据（卷）及其容器
--keep <项目>	保留指定项：mcp、cli、shell、containers、volumes、ca、dns、license、data、app

如果某个步骤失败（取消了密码输入、运行时已停止…），其他步骤会继续，但 Joppa 文件夹和应用会保留，命令以 1 退出：修复后再次运行 joppa uninstall。

在脚本中

# 需要时启动 Joppa，然后在测试前启动 PostgreSQL
joppa start postgres --launch
joppa services --json | jq .

# 启动项目，如果有进程崩溃则失败
joppa start acme --json | jq '.processes[] | {name, status}'

退出码

代码	含义
0	成功
1	错误；启动时有进程崩溃，或 joppa diagnose 发现某个域名出现故障，也会返回此代码
2	命令或选项有误
3	Joppa 未运行

工作原理

应用会在其配置文件夹中写入一个 control.json 文件（包含一个端口和一个令牌，只有你可以读取）。命令通过它与应用的本地 API 通信。如果 Joppa 没有运行，joppa 会提示你并提议启动它。