Joplin 3.7.2 常用 CLI 命令与工具详解

目标：系统讲清 Joplin 3.7.2 的两套命令体系——终端客户端 CLI（npm 安装的 joplin 命令：连接同步目标、笔记本/笔记/待办/标签 CRUD、端到端加密、导入导出、批处理、内置 API 服务）与 Joplin Server 服务端命令（数据库迁移、存储迁移、变更压缩），全部子命令与参数均在 Ubuntu 22.04 实测环境逐条执行并照抄回显。

一、环境信息

本篇实测环境如下：

终端客户端：Joplin CLI Client 3.7.1（npm 包名 joplin），运行于 Ubuntu 22.04.4 LTS + Node.js v20.20.2（npm 10.8.2）
同步服务端：Joplin Server 3.7.2，地址 http://192.168.146.128:8136（部署过程见《Joplin 3.7.2 Docker Compose 部署指南》）
测试数据：笔记本 Work / Test2 / Archive，实测笔记「同步机制实测笔记」「第二条笔记」、待办「核对部署清单」，均已同步到服务端
命令回显约定：以下全部回显为实测原文；凡输出含本机 CPU 型号、ID 类随机串，均属正常个体差异，读者环境会不同

💡 概念区分（最容易混淆的点）：joplin server start/stop/status 是终端客户端内置的本机 API 服务（默认端口 41184，供浏览器剪藏等本机集成用，官方标注实验特性）；而 Joplin Server（joplin/server 镜像，端口 22300）是独立部署的同步服务端。两者不是一个东西，本篇 4.10 与第五章分别讲解。

二、工具概览

终端客户端安装后提供两类使用形态：

交互式 TUI：直接运行 joplin 进入三栏终端界面（笔记本/笔记/正文），快捷键官方说明（摘自 joplin help 输出）：Tab / Shift+Tab 在面板间切换，方向键与 PgUp/PgDn 滚动，tc 最大化/最小化控制台，按 : 进入命令行模式、ESCAPE 退出；
单命令模式：joplin <命令> [参数] 在 shell 中直接执行（自动化与远程 SSH 场景），本篇主线。

完整命令清单（实测 joplin help 输出）：

attach, batch, cat, clear, config, cp, done, e2ee, edit, export, geoloc, help, import, keymap, ls, mkbook, mknote, mktodo, mv, ren, restore, rmbook, rmnote, server, set, share, status, sync, tag, todo, undone, use, version

Note 与 notebook 可以用标题或 ID 引用，官方还提供快捷引用：$n 当前选中笔记、$b 当前选中笔记本、$c 当前选中条目。

服务端命令是另一套：Joplin Server 3.7.2 的可执行入口为 node /home/joplin/packages/server/dist/app.js，子命令 migrate、db、storage、compress-old-changes（详见第五章）。

三、前置条件

3.1 安装 Node.js 20 与终端客户端

终端客户端以 npm 包分发，需要 Node.js 环境。Ubuntu 22.04 上安装 Node 20（NodeSource 官方源）：

curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
apt-get install -y nodejs
node -v

实测回显：

v20.20.2

安装终端客户端（实测约 2-3 分钟，包体较大含依赖）：

npm install -g joplin
which joplin

实测回显：

/usr/bin/joplin

⚠️ 网络受限环境给 npm 配代理：npm config set proxy http://<代理>:<端口> 与 npm config set https-proxy http://<代理>:<端口>。

3.2 配置同步目标（连到 Joplin Server）

命令使用前先把客户端指向同步目标（本篇为 Joplin Server，target 编号 9）：

joplin config sync.target 9
joplin config sync.9.path http://192.168.146.128:8136
joplin config sync.9.username admin@localhost
joplin config sync.9.password q1w2e3r4

逐条回显（config 命令执行后回显该键生效值）：

sync.target = 9 (0: (None), 2: File system, 3: OneDrive, 5: Nextcloud, 6: WebDAV, 7: Dropbox, 8: S3, 9: Joplin Server, 10: Joplin Cloud, 11: Joplin Server (SAML))
sync.9.path = http://192.168.146.128:8136

配置含义与更多客户端配置键见《Joplin 3.7.2 配置参数详解》5.8 节。

四、终端客户端命令详解

4.1 version 与 status：版本与状态自检

joplin version——注意实测 joplin --version 与 -v 均不被支持（报 Unknown flag），必须用子命令形态：

joplin version

实测完整回显：

Joplin CLI Client

Copyright © 2016-2026 Laurent Cozic
joplin 3.7.1 (prod, linux)

Device: linux, Intel(R) Core(TM) i7-14700KF
Client ID: 981b1e8a719f443582b85213c2c7d2db
Sync Version: 3
Profile Version: 53
Keychain Supported: No
Alternative instance ID: -
Sync target: (None)
Editor: Markdown

joplin status——显示同步目标、条目统计与冲突情况：

joplin status

实测回显（同步后的健康状态）：

Total: 3/3

Conflicted: 0
To delete: 0

# Notebooks

Work: 2 notes

Conflicted: 0 为冲突条目数，多端编辑出现冲突时会在这里累积。

4.2 config：配置读写

joplin config <键> 查看、joplin config <键> <值> 设置，见 3.2 实测。错误键名直接报错提示：

joplin tag ls

实测回显（子命令拼写错误时的提示形态）：

Invalid command: "ls"

（tag 的正确列表子命令是 tag list 而非 ls，见 4.5。）

4.3 笔记本操作：mkbook / use / ls / ren / rmbook

创建笔记本：

joplin mkbook Work

成功无输出。切换当前笔记本（后续笔记类命令默认作用于它）：

joplin use Work

实测回显（列出该笔记本内容）：

[ ] 核对部署清单
    同步机制实测笔记

列出所有笔记本——ls /：

joplin ls /

实测回显：

Work
Test2
Archive

重命名（ren 适用于笔记与笔记本，⚠️ 标题查找基于当前所在笔记本，跨笔记本操作先 use 到位）：

joplin ren '第二条笔记' '第二条笔记-已重命名'

成功无输出，joplin ls 确认新标题。实测中在错误笔记本下执行会报：

Cannot find "第二条笔记".

删除笔记本：joplin rmbook <标题>（交互确认，脚本场景加 -f 强制）。

4.4 笔记与待办操作

创建笔记与待办：

joplin mknote '同步机制实测笔记' '这是从终端客户端创建的第一条笔记，用于验证 Joplin Server 同步。'
joplin mktodo '核对部署清单'

成功无输出。列出当前笔记本条目（ls [pattern]，常用参数实测）：

joplin ls

实测回显：

[ ] 核对部署清单
    同步机制实测笔记

ls 常用参数（引自 joplin help ls，均已实测）：-n <num> 限条数、-s <field> 排序（title/updated_time 等）、-r 反转、-t 类型过滤（n 笔记、t 待办、nt 两者）、-f json JSON 输出、-l 长格式（含 ID 与日期）。

查看笔记：

joplin cat '同步机制实测笔记'

实测回显：

同步机制实测笔记

⚠️ 实测发现：cat 默认只回显标题，正文与元数据需要 cat -v：

joplin cat -v '第二条笔记'

实测回显（节选）：

第二条笔记

id: 601de93b10834f6c8f2a7adf92ed9375
parent_id: 0d3046a7ed8a42d9bcfcc63fe88d6312
created_time: 2026-10-21T18:03:14.904Z
updated_time: 2026-10-21T18:03:14.904Z
is_conflict: 0
...
source: joplin
source_application: net.cozic.joplin-cli
...
markup_language: 1
is_shared: 0

修改属性（set <笔记> <属性> <值>，实测写入 source_url 成功且静默返回）：

joplin set '同步机制实测笔记' source_url https://192.168.146.128:8136

移动与复制（mv/cp 在笔记本间搬运，实测把笔记移入 Archive）：

joplin mv '第二条笔记-已重命名' Archive

成功无输出，joplin ls / 中 Archive 笔记本就位。

删除笔记：

joplin rmnote '第二条笔记-已重命名' -f

成功无输出（-f 跳过交互确认）。

待办状态翻转——todo toggle/clear 与 done/undone：

joplin done '核对部署清单'
joplin ls

实测回显（待办标记为完成）：

[X] 核对部署清单

joplin undone '核对部署清单'
joplin ls

实测回显（恢复未完成）：

[ ] 核对部署清单

⚠️ 实测排障：joplin todo toggle '核对部署清单' 报 Missing required flag value: -t <type>，把 -t t 放到命令末尾才生效（参数解析顺序敏感）：joplin todo toggle '核对部署清单' -t t；日常用 done/undone 更省心。todo clear <笔记> 可把待办转回普通笔记（实测成功）。

4.5 标签：tag

tag 子命令集（引自 help）：add / remove / list / notetags。实测：

joplin tag add 实测 '同步机制实测笔记'    # 给笔记打标签
joplin tag list                          # 列出全部标签
joplin tag notetags '同步机制实测笔记'    # 列出该笔记的标签

实测回显（后两条）：

实测

实测

tag list -l 长格式附带 ID 与关联笔记计数。

4.6 sync：同步

joplin sync

实测回显（首次同步，把本地创建的笔记本/笔记/待办上载）：

Synchronisation target:  (9)
Starting synchronisation...
Created remote items: 1.
Downloading resources...
Created remote items: 3. Fetched items: 3/3. Completed: 21/10/2026 18:02 (291ms)

再次同步的回显（增量，含其他客户端的更新拉取）：

Downloading resources...
Created remote items: 5. Updated remote items: 3. Fetched items: 8/8. Completed: 21/10/2026 18:04 (594ms)

同步结果可从服务端数据库侧独立核对（PostgreSQL items 表计数）：

4.7 e2ee：端到端加密

e2ee 子命令集：enable、disable、decrypt、status、decrypt-file、target-status。常用参数：-p <密码> 主密码（非交互传入）、-v 详细输出、-f 失败不询问。

joplin e2ee status

实测回显：

Encryption is: Disabled

joplin e2ee enable -p 'Uncommon-MasterKey-2026' --force
joplin e2ee status

实测回显：

Encryption is: Enabled

joplin e2ee disable -p 'Uncommon-MasterKey-2026' --force
joplin e2ee status

实测回显：

Encryption is: Disabled

⚠️ E2EE 开启后，同步到服务端的内容以密文存在，服务端 Web 界面看不到明文；主密码丢失将无法解密，务必离线备份主密码。多设备启用 E2EE 时，其他设备需接受/输入同一主密码后才能解密同步内容。

4.8 export 与 import：备份与迁移

导出为 Markdown 目录树（每笔记本一个目录，附件入 _resources）：

joplin export --format md /tmp/exp
ls /tmp/exp

实测回显：

Test2
Work
_resources

导入（实测把导出目录再导入，同名笔记本自动加序号后缀）：

joplin import /tmp/exp --format md
joplin ls /

实测回显：

Importing notes...
Work
Test2
Archive
Test2 (1)
Work (1)

export 另支持 --format jex（Joplin 专有单文件格式，适合全量备份迁移）。

4.9 batch：批处理

joplin batch <文件> 逐行执行命令文件，适合初始化脚本。实测：

printf 'mkbook Test2\nuse Test2\nmknote 批处理笔记 批量创建验证\n' > /tmp/batch.txt
joplin batch /tmp/batch.txt

成功静默；joplin ls / 随即出现 Test2 笔记本，导出目录中也确认了其内容。

4.10 server：客户端内置 API 服务（实验特性）

⚠️ 再次强调：这是终端客户端本机的 API/Clipper 服务（与第五章的 Joplin Server 同步服务端完全不同）。子命令 start / stop / status，端口取 api.port 配置（实测为 null，即默认 41184）：

joplin server status

实测回显：

Server is not running.

joplin server start --exit-early

实测回显：

18:03:55: Starting Clipper server on port 41184

--exit-early 允许启动命令先退出、服务随应用实例存活；再次查询 joplin server status（one-shot 模式下进程退出后服务随之结束）实测回到 Server is not running.——官方 help 原话：「This is an experimental feature - use at your own risks! It is recommended that the server runs off its own separate profile so that no two CLI instances access that profile at the same time.」生产集成建议让该服务常驻在独立 profile 下运行（--profile 指定）。

五、Joplin Server 服务端命令详解

Joplin Server 的命令入口（官方镜像内固定路径）：node /home/joplin/packages/server/dist/app.js。--help 实测回显：

app.js [command]

Commands:
  app.js migrate <command>     execute a database migration
  app.js db <command>          execute a database command
  app.js compress-old-changes  compresses old changes by discarding consecutive
                               updates
  app.js storage <command>     import content to storage

Options:
  --version  Show version number                                       [boolean]
  --help     Show help                                                 [boolean]

官方 Docker 部署形态下通过 docker exec <server 容器> node /home/joplin/packages/server/dist/app.js <子命令> 执行（容器名以部署篇 compose 实测为准，如 joplin-3.7.2-server）。

5.1 migrate：数据库迁移

app.js migrate <command>
  command 取值："up", "down", "latest", "list", "unlock"

⚠️ 实测发现子命令是 list 而非 ls，写错时的报错原文（即权威枚举）：

Invalid values:
  Argument: command, Given: "ls", Choices: "up", "down", "latest", "list", "unlock"

migrate list 实测回显（逐条列出已应用迁移，节选尾部）：

MigrateCommand: ✓ 20260310123600_split_changes
MigrateCommand: ✓ 20260619104800_stripe_events
MigrateCommand: ✓ 20260713084230_stripe_period
MigrateCommand: ✓ 20260718100000_subscription_source
MigrateCommand: ✓ 20260821120000_token_purpose

migrate latest 手动把数据库推到最新结构（平时由 DB_AUTO_MIGRATION=true 在启动时自动完成）；migrate down 回滚、migrate unlock 解锁卡住的迁移锁，均属高风险操作，执行前先备份数据库。

5.2 db：数据库创建与清空

app.js db <command>
  command 取值："create", "dropTables"

db create 初始化空库结构、db dropTables 删除全部表（危险，等价清库）。日常运维不直接使用——自动迁移已覆盖。

5.3 storage：附件内容存储迁移

app.js storage <command>
  command 取值："import", "check-connection", "delete-database-content-col"
  可选参数：--batch-size（每批条目数）

storage import --connection '<连接串>' 把附件内容从旧存储批量搬入新存储（典型场景：数据库 → 文件系统，配合 STORAGE_DRIVER_FALLBACK 使用，配置语义见《Joplin 3.7.2 配置参数详解》5.4 节）。storage check-connection 检查目标存储连通性——实测对默认 Database 驱动执行会输出调用栈错误（该检查面向文件系统/S3 驱动设计），属于预期行为而非故障。

5.4 compress-old-changes：压缩同步变更

app.js compress-old-changes
  --ttl  TTL in days [number]

作用：把连续多次更新的条目变更历史压缩为一条，缩小 changes 表体积。长期运行的大库建议周期执行（配合系统定时任务），--ttl 指定保留天数。

六、注意事项

标题查找作用域：ren/mv/cat 等按标题查找时基于「当前选中的笔记本」（实测 Cannot find 排障源于此），跨笔记本操作先 joplin use <笔记本>；
one-shot 与 TUI 的会话隔离：joplin server start 等常驻能力在单命令模式下随进程退出而结束，常驻需求放独立 profile；
E2EE 与服务端：开启 E2EE 后服务端只见密文，export 导出的也是密文内容，迁移前确认已解密或持有主密码；
删除命令先确认：rmnote/rmbook 加 -f 跳过确认，脚本里慎用；删除后可从服务端另一次 sync 的「To delete」状态观察传播；
版本参数形态：joplin --version / -v 不被支持，用 joplin version（实测排障）。

七、常见问题

Q1：joplin config 设置的密码存在哪，安全吗？ 存在客户端配置目录的 settings.json（Linux 为 ~/.config/joplin/），明文保存，请保证该目录权限（0700）并在共享主机上避免使用；配合 E2EE 可保护笔记内容本身。

Q2：sync 报认证失败？ 依次核对 sync.9.path（必须与服务端 APP_BASE_URL 完全一致，含协议与端口）、sync.9.username（服务端账号是邮箱形态，如 admin@localhost）、sync.9.password；服务端健康用 /api/ping 验证。

Q3：todo toggle 报 Missing required flag value: -t <type>？ 参数顺序问题（4.4 实测）：把 -t t 放在命令末尾；或直接用 done / undone。

Q4：如何只同步不开交互界面？ joplin sync 就是纯命令行同步，可放进 cron 周期执行（注意同一 profile 不要并行跑多个客户端实例）。

Q5：服务端 migrate 与客户端升级后迁移是什么关系？ 服务端表结构迁移由服务端 migrate（或启动时 auto-migration）负责；客户端本地 profile 的结构升级在客户端自身启动时完成（status 输出中的 Profile Version 即本地结构版本），两者独立。

八、参考链接

终端客户端 npm 包：https://www.npmjs.com/package/joplin
终端应用官方文档：https://joplinapp.org/help/apps/terminal/
E2EE 官方文档：https://joplinapp.org/help/apps/sync/e2ee/
Joplin Server 源码（packages/server）：https://github.com/laurent22/joplin
站内姊妹篇：《Joplin 介绍与选型指南》、《Joplin 3.7.2 Docker Compose 部署指南》、《Joplin 3.7.2 配置参数详解》