TiddlyWiki 5.4.1 常用 CLI 命令详解

按查信息、初始化、起服务、构建渲染、导入导出、维护处理六类梳理 tiddlywiki 命令族，逐条给出真实参数、实测回显与结果解读。

TiddlyWikiTiddlyWikiWikiNode.js知识库2026/11/02

TiddlyWiki 5.4.1 常用 CLI 命令详解

目标：把 tiddlywiki 命令族按“查信息、初始化、起服务、构建渲染、导入导出、维护处理”六类讲清，每条命令给出真实参数、实测回显与结果解读。全文在 Ubuntu 24.04.5 LTS + Node.js v26.13.0 + TiddlyWiki 5.4.1 实机路径下实测，主服务监听 8138，命令实验目录为 /var/lib/tiddlywiki/cli-lab，临时监听端口 8140。

一、环境信息

  • 操作系统：Ubuntu 24.04.5 LTS（x86_64）
  • Node.js：v26.13.0，npm 11.20.0
  • TiddlyWiki：5.4.1（npm 全局安装，命令路径 /usr/local/bin/tiddlywiki）
  • 主 Wiki：/var/lib/tiddlywiki/wiki（server edition，systemd 托管，监听 0.0.0.0:8138）
  • 命令实验目录：/var/lib/tiddlywiki/cli-lab（含 demo、serverdemo、converted、fromhtml 等测试目录）
  • 临时监听：0.0.0.0:8140（仅用于本文 --listen 演示，演示后退出）
  • 联网条件：服务器可访问 tiddlywiki.com（--fetch 实测使用）

确认基础环境：

node -v
npm -v
which tiddlywiki
tiddlywiki --version
ss -ltn | grep 8138

实测回显：

v26.13.0
11.20.0
/usr/local/bin/tiddlywiki
5.4.1
LISTEN 0      511          0.0.0.0:8138       0.0.0.0:*

💡 说明：ss 只显示监听地址，不显示进程名；8138 已被主 Wiki 的 systemd 服务占用，所以本文临时实验统一改用 8140，避免和主服务冲突。

二、工具概览

2.1 调用模型

TiddlyWiki 的 CLI 只有一个入口命令，用法是“Wiki 目录 + 一串命令”：

usage: tiddlywiki [<wikifolder>] [--<command> [<args>...]...]

关键规则：

  1. 一条命令行里可以写多个 --command，按从左到右顺序执行；
  2. 命令默认在内存中处理 Tiddler，只有 --save、--savewikifolder、--import（在带 filesystem 插件时）等动作才落盘；
  3. --load 载入的 Tiddler 只在同一次调用的后续命令中可见，换一次 tiddlywiki 进程就丢失；
  4. server edition 自带 tiddlywiki/filesystem 插件，对 Wiki 目录内的变更会即时写文件；empty edition 没有该插件，只能靠显式导出。

2.2 命令清单

tiddlywiki --help 的实测输出（5.4.1 核心命令，共 27 条）：

usage: tiddlywiki [<wikifolder>] [--<command> [<args>...]...]

Available commands:

* build: Automatically run configured commands
* clearpassword: Clear a password for subsequent crypto operations
* commands: Run commands returned from a filter
* deletetiddlers: Deletes a group of tiddlers
* editions: Lists the available editions of TiddlyWiki
* fetch: Fetch tiddlers from wiki by URL
* help: Display help for TiddlyWiki commands
* import: Import tiddlers from a file
* init: Initialise a new wiki folder
* listen: Provides an HTTP server interface to TiddlyWiki
* load: Load tiddlers from a file
* makelibrary: Construct library plugin required by upgrade process
* output: Set the base output directory for subsequent commands
* password: Set a password for subsequent crypto operations
* render: Renders individual tiddlers to files
* rendertiddler: Render an individual tiddler as a specified ContentType
* rendertiddlers: Render tiddlers matching a filter to a specified ContentType
* save: Saves individual raw tiddlers to files
* savelibrarytiddlers:
* savetiddler: Saves a raw tiddler to a file
* savetiddlers: Saves a group of raw tiddlers to a directory
* savewikifolder: Saves a wiki to a new wiki folder
* server: (deprecated: see 'listen' command) Provides an HTTP server interface to TiddlyWiki
* setfield: Prepares external tiddlers for use
* unpackplugin: Unpack the payload tiddlers from a plugin
* verbose: Triggers verbose output mode
* version: Displays the version number of TiddlyWiki

按用途归类：

类别命令作用本文小节
信息与初始化help、version、editions、init查帮助、查版本、列 edition、初始化 Wiki 目录4.1、4.2
服务与运行listen、server（废弃）、output、verbose启 HTTP 服务、设置输出目录、调试输出4.3、4.4
构建与渲染build、render、rendertiddler、rendertiddlers按 tiddlywiki.info 构建、按过滤器渲染4.5、4.6
导入导出load、import、save、savewikifolder、fetch载入、导入、导出、转 Wiki 目录、远程抓取4.7、4.8、4.9
维护处理deletetiddlers、setfield、unpackplugin、makelibrary删除、改字段、拆插件、生成升级库4.10、4.11
编排与加密commands、password、clearpassword按过滤器执行命令、设置/清除加密口令4.12

⚠️ 注意：rendertiddler、rendertiddlers、savetiddler、savetiddlers 是旧命令，官方已用 render 与 save 统一替代；新脚本只写新命令即可，旧命令仅在老教程里出现。

三、前置条件

  • 已按安装篇完成 Node.js 与 TiddlyWiki 5.4.1 安装，tiddlywiki --version 返回 5.4.1；
  • 主 Wiki 已用 server edition 初始化，目录内存在 tiddlywiki.info；
  • 命令统一在 /var/lib/tiddlywiki 下执行，Wiki 目录名按实际替换；
  • 准备一个干净的实验目录，避免污染生产 Wiki：
cd /var/lib/tiddlywiki
rm -rf cli-lab
mkdir -p cli-lab
cd cli-lab
tiddlywiki ./demo --init empty

实测回显：

Copied edition 'empty' to ./demo

💡 说明：demo 是 empty edition，只有一个 tiddlywiki.info，适合演示“只读入内存、不落盘”的行为；涉及文件落盘的命令统一用 serverdemo（server edition）。

四、各工具详解

4.1 帮助、版本与 edition 列表

4.1.1 help：查命令帮助

--help 不带参数时列出全部命令；带命令名时输出该命令的完整参数说明。以 deletetiddlers 为例：

tiddlywiki --help deletetiddlers

实测回显：

 Deletes a group of tiddlers identified by a filter.

--deletetiddlers <filter>

4.1.2 version：查版本

tiddlywiki --version

实测回显：

5.4.1

💡 说明：脚本里做版本校验时，用 tiddlywiki --version 的纯文本输出即可，不需要解析 package.json。

4.1.3 editions：列可用 edition

tiddlywiki --editions

实测回显（节选前 20 行）：

Available editions:

    aws: Amazon Web Services edition
    classicparserdemo: Demo of the experimental TiddlyWiki Classic parser plugin
    codemirrordemo: Demo of the CodeMirror plugin
    de-AT: Deutsch (Österreich) Edition
    de-AT-server: Server configuration of the German (Österreich) edition
    de-DE: Deutsche Basis Edition
    dev: Developer documentation from https://tiddlywiki.com/dev/
    dynaviewdemo: Demo of the DynaView plugin
    empty: Empty edition
    es-ES: Spanish (Spain) edition
    es-ES-server: Configuración en modo servidor de la edición es-ES
    fr-FR: French (France) edition
    fr-FR-server: Configuration en mode serveur de l'édition fr-FR
    full: Full edition, containing all languages, themes and plugins
    geospatialdemo: Demo of the geospatial plugin for TiddlyWiki
    highlightdemo: Demo of the highlight plugin
    innerwikidemo: Innerwiki Plugin Demo
    introduction: A step by step introduction to TiddlyWiki
    ja-JP: Japanese (Japan) edition
    katexdemo: Demo of the KaTeX plugin
    ko-KR: Korean (Korea Republic) edition

本文用到的两个 edition：

  • empty：最小目录，只有 tiddlywiki.info，无 filesystem 插件；
  • server：客户端-服务端基础版，带 tiddlywiki/tiddlyweb、tiddlywiki/filesystem、tiddlywiki/highlight，是 --listen 的标准起点。

4.2 init：初始化 Wiki 目录

4.2.1 基本用法

帮助原文：

Initialise an empty WikiFolder with a copy of the specified edition.

--init <edition> [<edition> ...]

初始化 empty edition：

tiddlywiki ./demo --init empty

实测回显：

Copied edition 'empty' to ./demo

目录结构：

find demo -maxdepth 2 | sort

实测回显：

demo
demo/tiddlywiki.info

4.2.2 初始化 server edition

tiddlywiki ./serverdemo --init server

实测回显：

Copied edition 'server' to ./serverdemo

查看生成的配置：

cat serverdemo/tiddlywiki.info

实测回显：

{
    "description": "Basic client-server edition",
    "plugins": [
        "tiddlywiki/tiddlyweb",
        "tiddlywiki/filesystem",
        "tiddlywiki/highlight"
    ],
    "themes": [
        "tiddlywiki/vanilla",
        "tiddlywiki/snowwhite"
    ],
    "build": {
        "index": [
            "--render",
            "$:/plugins/tiddlywiki/tiddlyweb/save/offline",
            "index.html",
            "text/plain"
        ],
        "static": [
            "--render",
            "$:/core/templates/static.template.html",
            "static.html",
            "text/plain",
            "--render",
            "$:/core/templates/alltiddlers.template.html",
            "alltiddlers.html",
            "text/plain",
            "--render",
            "[!is[system]]",
            "[encodeuricomponent[]addprefix[static/]addsuffix[.html]]",
            "text/plain",
            "$:/core/templates/static.tiddler.html",
            "--render",
            "$:/core/templates/static.template.css",
            "static/static.css",
            "text/plain"
        ]
    }
}

💡 说明：build 字段里直接写了后续要执行的命令数组，所以 --build index 和 --build static 不需要再手写 --render 参数。

4.2.3 省略 edition 与目录非空

--init 不带 edition 时默认用 empty：

mkdir -p initdefault
cd initdefault
tiddlywiki . --init

实测回显：

Copied edition 'empty' to .

对已有内容的目录再次初始化会失败：

tiddlywiki ./demo --init empty

实测回显：

Error: Wiki folder is not empty

⚠️ 注意：--init 不会覆盖已有 Wiki；要重建只能先备份再换一个新目录，或手动清理后重试。

4.3 listen：启动 HTTP 服务

--listen 使用命名参数，全部参数可选：

tiddlywiki --help listen

实测回显（参数列表节选）：

host - optional hostname to serve from (defaults to "127.0.0.1" aka "localhost")
path-prefix - optional prefix for paths
port - port number on which to listen (defaults to "8080")
credentials - pathname of credentials CSV file (relative to wiki folder)
anon-username - the username for signing edits for anonymous users
username - optional username for basic authentication
password - optional password for basic authentication
authenticated-user-header - optional name of request header to be used for trusted authentication.
readers - comma-separated list of principals allowed to read from this wiki
writers - comma-separated list of principals allowed to write to this wiki
csrf-disable - set to "yes" to disable CSRF checks (defaults to "no")
root-tiddler - the tiddler to serve at the root (defaults to "$:/core/save/all")
root-render-type - the content type to which the root tiddler should be rendered (defaults to "text/plain")
root-serve-type - the content type with which the root tiddler should be served (defaults to "text/html")
tls-cert - pathname of TLS certificate file (relative to wiki folder)
tls-key - pathname of TLS key file (relative to wiki folder)
debug-level - optional debug level; set to "debug" to view request details (defaults to "none")
gzip - set to "yes" to enable gzip compression for some http endpoints (defaults to "no")
use-browser-cache - set to "yes" to allow the browser to cache responses to save bandwidth (defaults to "no")

临时监听 8140 并设置自动退出（timeout 5 仅用于演示）：

timeout 5 tiddlywiki ./serverdemo --listen host=0.0.0.0 port=8140

实测回显：

syncer-server-filesystem: Dispatching 'save' task: $:/StoryList
Serving on http://0.0.0.0:8140
(press ctrl-C to exit)

💡 说明：回显第一行在不同版本里可能显示为 Dispatching 'save' task，这是文件系统同步器把当前故事列表落盘；出现 Serving on 即表示监听成功。生产环境的认证、TLS、path-prefix、gzip 等参数组合，见同专栏《TiddlyWiki 5.4.1 配置参数详解》。

4.4 output 与 verbose：输出目录与调试

4.4.1 output：指定输出根目录

--save、--render、--fetch 等命令默认输出到 edition 的 output 子目录；--output 可改写。

tiddlywiki ./serverdemo --output ./customout --render "$:/core/templates/exporters/JsonFile" "all.json" text/plain

实测回显：

syncer-server-filesystem: Dispatching 'save' task: $:/StoryList

结果文件：

find customout -type f | sort

实测回显：

customout/all.json

⚠️ 注意：这次渲染没有传 exportFilter，所以 all.json 内容是空数组 []；真正导出 Tiddler 需要按 4.6.2 的写法补过滤器。

4.4.2 verbose：打开详细日志

tiddlywiki . --verbose --version

实测回显：

Boot log:
  Startup task: load-modules
  Startup task: info after: load-modules before: startup
  Startup task: plugins after: load-modules before: startup
  Startup task: startup after: load-modules
  Startup task: story after: startup
  Startup task: commands platforms: node after: story
Executing command: version
5.4.1

💡 说明：--verbose 会把启动任务与每条命令的执行顺序打出来，--fetch、--load 不生效时优先加它定位。

4.5 build：按配置构建

--build 读取 tiddlywiki.info 的 build 字段，执行对应命令数组。

cd /var/lib/tiddlywiki/cli-lab/serverdemo
tiddlywiki . --build index

实测回显：

syncer-server-filesystem: Dispatching 'save' task: $:/StoryList

产物：

ls -la output

实测回显：

total 2676
drwxr-xr-x 2 root root    4096 Nov  2 11:27 .
drwxr-xr-x 4 root root    4096 Nov  2 11:27 ..
-rw-r--r-- 1 root root 2731026 Nov  2 11:27 index.html

构建静态站：

tiddlywiki . --build static
find output -type f | sort

实测回显：

syncer-server-filesystem: Dispatching 'save' task: $:/StoryList
output/alltiddlers.html
output/index.html
output/static.html
output/static/static.css

构建不存在的目标：

tiddlywiki . --build no-such-target

实测回显：

Error: Build target 'no-such-target' not found

💡 说明：output 目录不会被自动清空，重复构建会覆盖同名文件、保留旧文件；发布前建议先删掉 output 再构建，避免把上次的残留文件一起带走。

4.6 render：渲染 Tiddler

4.6.1 渲染单个 Tiddler 为 HTML

cd /var/lib/tiddlywiki/cli-lab
tiddlywiki ./serverdemo --load ./note.tid --output ./out3 --render "[title[ImportedNote]]" "[title[ImportedNote]addsuffix[.html]]" text/html

实测回显：

syncer-server-filesystem: Dispatching 'save' task: $:/StoryList
syncer-server-filesystem: Dispatching 'save' task: ImportedNote

产物：

find out3 -type f | sort

实测回显：

out3/ImportedNote.html

参数含义：

  • 第 1 个参数是 Tiddler 过滤器，[title[ImportedNote]] 只选这一条；
  • 第 2 个参数是文件名过滤器，addsuffix[.html] 补扩展名；
  • 第 3 个参数是渲染类型，text/html 输出完整 HTML，text/plain 只输出文本内容；
  • 可选第 4 个参数是模板 Tiddler，第 5 个起是模板变量名值对。

4.6.2 导出全部非系统 Tiddler 为 JSON

tiddlywiki ./serverdemo --output ./jsonexport --render "." "tiddlers.json" text/plain "$:/core/templates/exporters/JsonFile" exportFilter "[!is[system]]"

实测回显：

syncer-server-filesystem: Dispatching 'save' task: $:/StoryList

产物与内容开头：

ls -la jsonexport
head -c 300 jsonexport/tiddlers.json

实测回显：

-rw-r--r-- 1 root root 8176 Nov  2 11:31 tiddlers.json
[{"title":"./note.tid","text":"title: ImportedNote\ncreated: 202611021135\nmodified: 202611021135\ntags: demo\n\nImported note body.\n","type":"text/plain"},{"title":"BuildCmds","text":"type: text/vnd.tiddlywiki\n\n--version\n"},{"title":"FaviconTiddler","text":"iVBORw0KGgoAAAANSUhEUgAAAIAAAACACAYAAADDPmHLAAAA...

💡 说明：模板变量 exportFilter 必须显式传入，否则导出的是空数组。导出内容里出现 ./note.tid 这类测试残留 Tiddler，说明实验目录里的测试数据也会被一起导出；生产导出前要先清理测试条目。

4.7 load 与 import：载入和导入

4.7.1 load：按扩展名自动推断格式

准备一个 .tid：

printf "title: ImportedNote\ncreated: 202611021135\nmodified: 202611021135\ntags: demo\n\nImported note body.\n" > note.tid

load 只把 Tiddler 读进内存，本身不落盘；后续同一命令行里的 --render、--save 才能用到：

tiddlywiki ./serverdemo --load ./note.tid --output ./out3 --render "[title[ImportedNote]]" "[title[ImportedNote]addsuffix[.html]]" text/html

实测回显见 4.6.1。

如果换成独立的一次调用：

tiddlywiki ./serverdemo --load ./note.tid

实测无输出（加载成功但不落盘），下一条独立命令再查 ImportedNote 会找不到。

文件不存在时默认报错：

tiddlywiki ./serverdemo --load ./missing.html

实测回显：

Error: No tiddlers found in file "./missing.html"

加 noerror 可抑制：

tiddlywiki ./serverdemo --load ./missing.html noerror

实测回显：

syncer-server-filesystem: Dispatching 'save' task: $:/StoryList

4.7.2 import：显式指定反序列化器

import 与 load 的区别是必须写明 deserializer，并会把结果交给 filesystem 插件落盘：

tiddlywiki ./serverdemo --import ./note.tid application/x-tiddler

实测回显：

syncer-server-filesystem: Dispatching 'save' task: $:/StoryList
syncer-server-filesystem: Dispatching 'save' task: ImportedNote

落盘结果：

find serverdemo/tiddlers -type f | sort

实测回显：

serverdemo/tiddlers/$__StoryList.tid
serverdemo/tiddlers/ImportedNote.tid

导入 JSON：

tiddlywiki ./serverdemo --import ./sf/ImportedNote.tid.json application/json

实测回显：

syncer-server-filesystem: Dispatching 'save' task: $:/StoryList
syncer-server-filesystem: Dispatching 'save' task: ImportedNote

用错反序列化器（把 .tid 当纯文本导入）：

tiddlywiki ./serverdemo --import ./note.tid text/plain

实测回显：

syncer-server-filesystem: Dispatching 'save' task: ./note.tid
syncer-server-filesystem: Dispatching 'save' task: $:/StoryList

⚠️ 注意：text/plain 会把整个文件当成一条 Tiddler，标题取文件名 ./note.tid，正文原样保留。导入 .tid 必须用 application/x-tiddler，导入 .json 用 application/json，导入 .html 用 text/html。

4.8 save 与 savewikifolder：导出与转目录

4.8.1 save：按过滤器保存原始 Tiddler

tiddlywiki ./serverdemo --output ./saved --save "[title[ImportedNote]]" "[title[ImportedNote]addsuffix[.tid]]"

实测回显：

syncer-server-filesystem: Dispatching 'save' task: $:/StoryList

产物：

find saved -type f | sort

实测回显：

saved/ImportedNote.tid

省略文件名过滤器时，默认按 Tiddler 标题输出，格式由扩展名决定；不写扩展名时得到 JSON：

tiddlywiki ./serverdemo --output ./defout --save "[title[ImportedNote]]"
find defout -type f | sort

实测回显：

syncer-server-filesystem: Dispatching 'save' task: $:/StoryList
defout/ImportedNote.json

💡 说明：--save 的序列化格式看文件名后缀：.tid 输出 Tiddler 文本，.json 输出 JSON 数组；不写后缀时默认 .json。要拿到可直接放进 tiddlers/ 的文件，务必显式加 .tid。

4.8.2 savewikifolder：把内存 Wiki 存成标准 Wiki 目录

tiddlywiki ./serverdemo --savewikifolder ./converted

实测回显：

syncer-server-filesystem: Dispatching 'save' task: $:/StoryList

目录内容：

find converted -maxdepth 2 -type f | sort | head -20

实测回显：

converted/tiddlers/$__HistoryList.json
converted/tiddlers/$__HistoryList.json.meta
converted/tiddlers/$__StoryList.tid
converted/tiddlers/$__isEncrypted.tid
converted/tiddlers/$__status_RequireReloadDueToPluginChange.tid
converted/tiddlers/ImportedNote.tid
converted/tiddlywiki.info

常见用法：把单文件 HTML 转成 Wiki 目录。

tiddlywiki ./serverdemo --load ./serverdemo/output/index.html --savewikifolder ./fromhtml

实测回显（节选最后几行）：

syncer-server-filesystem: Dispatching 'save' task: $:/plugins/tiddlywiki/highlight
syncer-server-filesystem: Dispatching 'save' task: $:/StoryList
syncer-server-filesystem: Dispatching 'save' task: $:/themes/tiddlywiki/snowwhite
syncer-server-filesystem: Dispatching 'save' task: $:/themes/tiddlywiki/vanilla

结果规模与顶层目录：

find fromhtml -maxdepth 2 -type f | wc -l
ls fromhtml

实测回显：

29
librarys
tiddlers
tiddlywiki.info

💡 说明：librarys 是 TiddlyWiki 生成的插件库目录名（官方拼写如此），不是我们手滑；转换后的 tiddlywiki.info 会把官方插件写成引用，自定义插件才会展开到 plugins/。

目标目录非空时拒绝执行：

tiddlywiki ./serverdemo --savewikifolder ./converted

实测回显：

Error: The unpackwiki command requires that the output wiki folder be empty

4.9 fetch：远程抓取文件

fetch 有 file、files、raw-file、raw-files 四种变体。抓取官网 favicon 并存成 Tiddler：

tiddlywiki ./serverdemo --verbose --fetch raw-file "https://tiddlywiki.com/favicon.ico" "[title[FaviconTiddler]]"

实测回显（节选）：

Executing command: fetch raw-file https://tiddlywiki.com/favicon.ico [title[FaviconTiddler]]
syncer-server-filesystem: Dispatching 'save' task: $:/StoryList
Reading https://tiddlywiki.com/favicon.ico: .....
Importing https://tiddlywiki.com/favicon.ico as FaviconTiddler
Imported 1 tiddlers
syncer-server-filesystem: Dispatching 'save' task: FaviconTiddler

再导出为原始文件：

tiddlywiki ./serverdemo --output ./fetched --save "[[FaviconTiddler]]" "[[favicon.ico]]"
ls -la fetched

实测回显：

syncer-server-filesystem: Dispatching 'save' task: $:/StoryList
total 20
drwxr-xr-x 2 root root  4096 Nov  2 11:28 .
drwxr-xr-x 11 root root 4096 Nov  2 11:28 .
-rw-r--r-- 1 root root  5766 Nov  2 11:28 favicon.ico
-rw-r--r-- 1 root root    52 Nov  2 11:28 favicon.ico.meta

💡 说明：raw-file 不做 Tiddler 解析，适合抓二进制；file 变体会按“拖入浏览器”的规则导入文件内的 Tiddler，并可用 import-filter 限定范围。抓取失败时加 --verbose 看 Reading 进度。

4.10 deletetiddlers 与 setfield：删除与改字段

4.10.1 deletetiddlers：按过滤器删除

tiddlywiki ./serverdemo --deletetiddlers "[title[ImportedNote]]"

实测回显：

syncer-server-filesystem: Dispatching 'save' task: $:/StoryList
syncer-server-filesystem: Dispatching 'delete' task: ImportedNote

删除后目录：

ls serverdemo/tiddlers

实测回显：

$__StoryList.tid

删除不存在的 Tiddler 不报错：

tiddlywiki ./serverdemo --deletetiddlers "[title[NoSuchTiddler]]"

实测回显：

syncer-server-filesystem: Dispatching 'save' task: $:/StoryList

⚠️ 注意：deletetiddlers 直接删文件，没有回收站。批量删除前先用 --save 或 tar 备份 tiddlers/。

4.10.2 setfield：用模板渲染结果写字段

准备一条待修改的普通 Tiddler 和一个模板 Tiddler：

printf "title: FieldDemo\n\nField demo body.\n" > FieldDemo.tid
printf "title: StatusDone\n\nDone\n" > StatusDone.tid
tiddlywiki ./serverdemo --import ./FieldDemo.tid application/x-tiddler

实测回显：

syncer-server-filesystem: Dispatching 'save' task: $:/StoryList
syncer-server-filesystem: Dispatching 'save' task: FieldDemo

给 FieldDemo 写入 status 字段：

tiddlywiki ./serverdemo --load ./StatusDone.tid --setfield "[title[FieldDemo]]" status StatusDone text/plain --output ./fieldout --save "[title[FieldDemo]]"

实测回显：

syncer-server-filesystem: Dispatching 'save' task: $:/StoryList
syncer-server-filesystem: Dispatching 'save' task: FieldDemo
syncer-server-filesystem: Dispatching 'save' task: StatusDone

导出内容：

cat fieldout/FieldDemo.json

实测回显：

[
    {
        "title": "FieldDemo",
        "text": "Field demo body.\n",
        "status": "Done\n"
    }
]

把模板参数留空即删除该字段：

tiddlywiki ./serverdemo --setfield "[title[FieldDemo]]" status "" text/plain --output ./fielddel --save "[title[FieldDemo]]"
cat fielddel/FieldDemo.tid

实测回显：

title: FieldDemo

Field demo body.

⚠️ 注意：--setfield 官方标注为 experimental，字段值来自模板渲染结果，模板末尾的换行会一起写进字段（实测 status 为 "Done\n"）。需要精确值时，模板里不要留多余空行。删除字段时模板标题必须留空，不能传一个不存在的标题。

4.11 unpackplugin 与 makelibrary：插件与升级库

4.11.1 unpackplugin：拆分插件为普通 Tiddler

tiddlywiki ./serverdemo --unpackplugin "$:/plugins/tiddlywiki/highlight"

实测回显（节选）：

syncer-server-filesystem: Dispatching 'save' task: $:/config/HighlightPlugin/TypeMappings/application/javascript
syncer-server-filesystem: Dispatching 'save' task: $:/config/HighlightPlugin/TypeMappings/application/json
syncer-server-filesystem: Dispatching 'save' task: $:/plugins/tiddlywiki/highlight/highlight.css
syncer-server-filesystem: Dispatching 'save' task: $:/plugins/tiddlywiki/highlight/highlight.js
syncer-server-filesystem: Dispatching 'save' task: $:/plugins/tiddlywiki/highlight/license
syncer-server-filesystem: Dispatching 'save' task: $:/plugins/tiddlywiki/highlight/readme
syncer-server-filesystem: Dispatching 'save' task: $:/plugins/tiddlywiki/highlight/styles
syncer-server-filesystem: Dispatching 'save' task: $:/plugins/tiddlywiki/highlight/usage
syncer-server-filesystem: Dispatching 'save' task: $:/StoryList

💡 说明：拆分后插件内的每个组件都变成独立 Tiddler，便于修改或研究；改完要重新打包才能作为插件分发。

4.11.2 makelibrary：生成升级库

tiddlywiki ./serverdemo --makelibrary "$:/UpgradeLibrary"

实测回显：

syncer-server-filesystem: Dispatching 'save' task: $:/StoryList
syncer-server-filesystem: Dispatching 'save' task: $:/UpgradeLibrary

产物：

ls -la serverdemo/tiddlers/*Upgrade*

实测回显：

-rw-r--r-- 1 root root 15335637 Nov  2 11:28 serverdemo/tiddlers/$__UpgradeLibrary.json
-rw-r--r-- 1 root root       68 Nov  2 11:28 serverdemo/tiddlers/$__UpgradeLibrary.json.meta

💡 说明：makelibrary 是给“自定义升级流程”用的内部命令，会打出一个约 15MB 的插件库；日常升级直接换 npm 包版本即可，不需要自己生成。

4.12 commands、password 与 clearpassword：编排与加密

4.12.1 commands：用过滤器产出命令并执行

tiddlywiki ./serverdemo --commands "[[--version]]"

实测回显：

5.4.1
syncer-server-filesystem: Dispatching 'save' task: $:/StoryList

等价的 enlist:raw 写法：

tiddlywiki ./serverdemo --commands "[enlist:raw[--version]]"

实测回显：

5.4.1
syncer-server-filesystem: Dispatching 'save' task: $:/StoryList

💡 说明：--commands 的过滤器每个结果是一个命令 token，适合把构建步骤存在 Tiddler 里动态执行；日常运维直接用多条 --command 更直观。

4.12.2 password 与 clearpassword：加密文件口令

tiddlywiki --help password

实测回显：

Set a password for subsequent crypto operations

--password <password>

Note: This should not be used for serving TiddlyWiki with password protection. Instead, see the password option under the ServerCommand.

设置口令后再清除（--version 用于验证命令链继续执行）：

tiddlywiki ./serverdemo --password q1w2e3r4 --version
tiddlywiki ./serverdemo --password q1w2e3r4 --clearpassword --version

实测回显：

5.4.1
syncer-server-filesystem: Dispatching 'save' task: $:/StoryList
5.4.1
syncer-server-filesystem: Dispatching 'save' task: $:/StoryList

⚠️ 注意：password/clearpassword 只用于 --load 加密的 TiddlyWiki HTML 等加密文件场景，不是给 --listen 做登录认证。服务端登录用 username/password 或 credentials 参数，见《TiddlyWiki 5.4.1 配置参数详解》。

五、注意事项

  1. 命令状态默认不落盘：--load 只在当前进程内存中有效，同一命令行内的后续命令可见，换一次进程就消失；需要持久化用 --import（filesystem edition）或 --save/--savewikifolder。
  2. edition 决定持久化能力：empty edition 没有 filesystem 插件，只有 tiddlywiki.info；server edition 才有 tiddlywiki/filesystem，--import 会直接写 tiddlers/。
  3. --save 的后缀决定格式：.tid 出 Tiddler 文本，.json 出 JSON 数组，不写后缀默认 .json。
  4. 路径基准不同：--load/--import 的文件路径相对当前工作目录；--listen 的 credentials、tls-cert、tls-key 相对 Wiki 目录。
  5. 输出目录不自动清空：--build、--render、--save 只覆盖同名文件，旧产物会残留；发布前手动清理 output。
  6. --listen 的未知参数会被静默忽略：实测 --listen bogus=1 不报错，直接按默认 127.0.0.1:8080 起服务；参数名拼错时不会得到任何提示，必须以 --help listen 的清单为准。
  7. 删除不可逆：--deletetiddlers 没有回收站，批量操作前备份 tiddlers/。
  8. 实验命令有边界：--setfield 官方标注 experimental；--makelibrary 面向内部升级流程，不适合日常使用。
  9. 文件名带空格：shell 要加引号，TiddlyWiki 过滤器里用双方括号，例如 --save "[[Motovun Jack.jpg]]"。

六、常见问题

Q1：tiddlywiki: command not found，但 npm 显示已安装？

npm 全局 bin 目录不在 PATH。安装篇已给出修复方式：确认 npm root -g 后把可执行文件软链到 /usr/local/bin/tiddlywiki。验证：

which tiddlywiki && tiddlywiki --version

实测回显：

/usr/local/bin/tiddlywiki
5.4.1

Q2：想装插件，执行 tiddlywiki --install 报错？

5.4.1 核心没有 install 命令：

tiddlywiki --install

实测回显：

Error: Unknown command: install

正确做法是编辑 tiddlywiki.info 的 plugins 数组，重启或构建时从官方插件库装载；自定义插件放 wiki/plugins/。详见《TiddlyWiki 5.4.1 配置参数详解》 6.2。

Q3：--load 明明没报错，下一条命令却找不到 Tiddler？

--load 只进内存。把 --load 和后续 --render/--save 写在同一条命令行；或者改用 --import 让文件系统插件落盘：

tiddlywiki ./serverdemo --load ./note.tid --output ./out3 --render "[title[ImportedNote]]" "[title[ImportedNote]addsuffix[.html]]" text/html

Q4：--save 导出的是 .json 而不是 .tid？

因为文件名过滤器没写后缀，默认按 JSON 序列化。显式补 .tid：

tiddlywiki ./serverdemo --output ./saved --save "[title[ImportedNote]]" "[title[ImportedNote]addsuffix[.tid]]"

实测产出 saved/ImportedNote.tid。

Q5：--init 报 Wiki folder is not empty？

目标目录已有文件。换新目录，或先备份并清空；--init 不会覆盖现有 Wiki。

Q6：--listen bogus=1 为什么还能启动？

未知命名参数被静默忽略，进程按默认值 127.0.0.1:8080 启动。实测回显：

syncer-server-filesystem: Dispatching 'save' task: $:/StoryList
Serving on http://127.0.0.1:8080
(press ctrl-C to exit)

排障时先用 --help listen 核对参数名，再用 ss -ltn 确认实际监听端口。

Q7：--load ./missing.html 报 No tiddlers found 怎么跳过？

文件不存在或文件里没有可识别的 Tiddler 都会报这个错；确认文件路径后，批量脚本可加 noerror：

tiddlywiki ./serverdemo --load ./missing.html noerror

Q8：--build static 只生成了几个文件，正常吗？

正常。server edition 默认 static 目标渲染 static.html、alltiddlers.html、static/static.css 以及非系统 Tiddler 的 HTML；空 Wiki 没有内容 Tiddler，所以 static/ 下只有样式文件，output 里的 index.html 是之前 --build index 留下的产物（输出目录不自动清空）。Tiddler 多了以后 static/ 下会按标题生成页面。

七、参考链接

以下链接均为 2026-11-02 实测可访问（HTTP 200）：

  • TiddlyWiki 命令总览：https://tiddlywiki.com/static/Commands.html
  • listen 命令：https://tiddlywiki.com/static/ListenCommand.html
  • init 命令：https://tiddlywiki.com/static/InitCommand.html
  • build 命令：https://tiddlywiki.com/static/BuildCommand.html
  • render 命令：https://tiddlywiki.com/static/RenderCommand.html
  • load 命令：https://tiddlywiki.com/static/LoadCommand.html
  • import 命令：https://tiddlywiki.com/static/ImportCommand.html
  • save 命令：https://tiddlywiki.com/static/SaveCommand.html
  • savewikifolder 命令：https://tiddlywiki.com/static/SaveWikiFolderCommand.html
  • fetch 命令：https://tiddlywiki.com/static/FetchCommand.html
  • deletetiddlers 命令：https://tiddlywiki.com/static/DeleteTiddlersCommand.html
  • setfield 命令：https://tiddlywiki.com/static/SetFieldCommand.html
  • output 命令：https://tiddlywiki.com/static/OutputCommand.html
  • verbose 命令：https://tiddlywiki.com/static/VerboseCommand.html
  • unpackplugin 命令：https://tiddlywiki.com/static/UnpackPluginCommand.html
  • makelibrary 命令：https://tiddlywiki.com/static/MakeLibraryCommand.html
  • commands 命令：https://tiddlywiki.com/static/CommandsCommand.html
  • password 命令：https://tiddlywiki.com/static/PasswordCommand.html
  • editions 命令：https://tiddlywiki.com/static/EditionsCommand.html
  • 官方仓库：https://github.com/TiddlyWiki/TiddlyWiki5
  • npm 包：https://www.npmjs.com/package/tiddlywiki

同专栏文档：

TiddlyWiki 5.4.1 常用 CLI 命令详解 - Quzuo