Command line

rustz-cli takes the same switches as ConCmd, ConvertZ's command-line tool, plus a few more.

rustz-cli [/i:source] /o:target [options] <input> [output]
rustz-cli [/i:source] /o:target [options] <input1> <input2> <input3> …

Switches are case-insensitive, can go anywhere, and start with / (/o:utf8); Windows also accepts - (-o:UTF8). On macOS and Linux an argument starting with - is a file name, except --help, --version and -- — the shell may expand a wildcard into a file that happens to be called -y. rustz-cli /? prints the help.

Encodings

Code	Encoding	Also accepted
big5	Big5	b5, cp950
gbk	GBK	gb2312, cp936, gb18030
utf8	UTF-8	utf-8, u8
ule	UTF-16 LE	utf16le, unicode
ube	UTF-16 BE	utf16be
hz	HZ	hz-gb-2312
sjis	Shift_JIS	shift_jis, cp932
eucjp	EUC-JP	euc-jp
jis	ISO-2022-JP	iso-2022-jp

Without /i: the source encoding is detected; see Encodings and detection.

Options

Switch	Meaning
/i:enc	Source encoding. When given, files that look binary are converted too
/o:enc	Target encoding (optional with /n)
/f:t /f:s /f:d	Traditional, Simplified, or keep the script. Without /f:: Big5 output → Traditional, GBK/HZ output → Simplified, anything else → keep — and only text that really is the other script is converted
/e:opencc /e:convertz	Conversion engine
/v:tw /v:hk /v:std	Glyph standard for the OpenCC engine: Taiwan, Hong Kong, OpenCC standard
/p /p-	Turn Taiwan vocabulary on or off
/q	Quiet
/b	Back up as original-name.bak before overwriting; if that exists, original-name.1.bak, .2.bak…
/cu	Turn &#NNNN; entities into text
/s	Include subfolders for wildcards and folders
/n	Dry run: show what would happen, write nothing
/y	Overwrite an existing output file
/force	Overwrite the original even when some bytes could not be decoded (skipped by default, see below)
/bom /nobom	Add a BOM to UTF-8 output or not
--	Treat everything after it as file names

Anything not given on the command line — engine, glyph standard, vocabulary, BOM, entities, ignored file types, web-page types — comes from the settings file.

Input

• A file: just give its path.
• A folder: every file in it; add /s for subfolders.
• Wildcards: * and ?, in the file name only (src/*.js), not in folder names.
• Several inputs: three or more arguments are all inputs, each overwritten in place.
• -: read standard input and write standard output (or the file given as the second argument).

Folders and wildcards skip the ignored file types from the settings file, folders whose names start with a dot, and RustZ's own temporary files. Files you name explicitly are always processed.

Quote wildcards on macOS and Linux

The shell expands *.txt before RustZ sees it. If it happens to expand to two files, they read as "input + output". RustZ stops with an error when the second argument is an existing file instead of overwriting it; write "*.txt", or add /y if you really mean to overwrite.

Output

Second argument	Result
None	Overwrite the input (back it up first with /b)
out.txt (does not exist)	Write to that file; only one input allowed
out.txt (exists)	Needs /y
out/ or an existing folder	Write into the folder, keeping relative paths
"out/*.abc"	Name by pattern: * is the original base name, so test.txt → out/test.abc
"out/*.*"	Same name, in out/
-	Standard output

Output is written to a new temporary file with a random name and then renamed into place. Temporary files and backups are only ever created as new files, so a symbolic link planted in the folder (for example from a downloaded archive) is never followed. When writing into an output folder, a path that leads outside it through a symbolic link is refused. When the output is the input file and the bytes would not change, nothing is written.

Files with undecodable bytes are not overwritten

If some bytes cannot be decoded in the source encoding, they would become � and the original bytes would be lost. When such a file would be overwritten in place without a backup, RustZ skips it. Give the right encoding with /i:, add /b to keep a backup, or /force to overwrite anyway.

Messages and exit codes

  ✓ src/a.js  GBK（偵測） → UTF-8 · 簡→繁
  = src/b.js  UTF-8（偵測） → UTF-8（內容無變更）
  - logo.dat  略過（看起來是二進位檔；若確定是文字檔請用 /i: 指定編碼）
      ⚠ 有 3 個字元無法以 Big5 表示，已以 ? 取代
完成：轉換 1、無變更 1、略過 1、失敗 0（共 3 個檔案）

Messages are in Chinese. ✓ converted, = unchanged, - skipped (here: looks binary — use /i: if it is text), ✗ failed, ⚠ a warning (here: 3 characters could not be written in Big5 and became ?). The note after the source encoding says how it was found: 偵測 detected from content, BOM from the byte-order mark, 推測 a guess, little to go on, ASCII plain ASCII.

Exit code	Meaning
0	Every file was converted or unchanged
1	Some file failed, or was skipped (looks binary, or would lose undecodable bytes)
2	Bad arguments

Examples

# Classic ConCmd usage
rustz-cli /i:big5 /o:ule /f:s test1.txt test2.txt
rustz-cli /i:utf8 /o:big5 "*.*"
rustz-cli /o:utf8 /f:t "k*.txt" "D:\Temp Dir\*.abc"

# A whole project to UTF-8, subfolders included, with backups
rustz-cli /o:utf8 /s /b src

# Only show what was detected
rustz-cli /n /s .

# In a pipeline
cat 简体.txt | rustz-cli /o:utf8 /f:t - > 繁體.txt

# ConvertZ engine; Traditional without Taiwan vocabulary
rustz-cli /o:big5 /e:convertz gbk.txt big5.txt
rustz-cli /o:utf8 /f:t /p- 简体.txt 繁體.txt