[Tutorial] tes3cmd

Tes3cmd is a command-line tool used for editing, inspecting and cleaning mods.

Download latest version 0.40 (pre-release alpha)
Documentation for 0.40

Download older version 0.37v (for "modify", see why below) - Documentation for 0.37v - Changelog for differences with 0.40

How to use in Windows

Put "tes3cmd.exe" into your Data Files folder.
- To use the command line, Shift + right click on empty space in the folder and select "Open command window here". Type the line you want to use in the command window and enter.
- To use with batch files (so you don't have to type each line by hand), create an empty txt file (right click, New, Text document), copy or type the command lines into the file. Save and rename the file extension to .bat instead of .txt. Double click the .bat file in the folder to run the command. It's a good idea to add "pause" on the last line of the .bat file so the command window won't close itself and you can read output messages.

Advanced use
Remember there's a 8191 characters limit for the command in modern Windows, and the same limit applies to batch files.
The characters  [\^$.|?*+() are special characters for regular expressions, used by many of tes3cmd's optional parameters like --match. You can use regular expressions to your advantage for powerful filtering, but you also need to escape special characters with a backslash when you're looking for the character itself: for example a period stands for any character unless you write it as \. and parentheses also need to be escaped \( with backslash.
There are also special characters in command line or .bat files. This shouldn't usually be a problem, but for example you will need to double the % sign if you use the --format option for dumps.

Cleaning

 tes3cmd clean MyPlugin.esp

Safe to use for TR claims (and most mods). The original file is not modified. The clean file has the same filename with "Clean" in front of it.
This line will remove all dirty objects that are in your plugin but aren't different from objects in its masters. Will clean dirty objects from Morrowind.esm, Tribunal.esm, Bloodmoon.esm. Will clean objects dirtied from TR if your plugin has TR_Mainland as a master file (ESM).
Will NOT clean most dirty dialogue, because dialogue lines get different data when you add lines next to them. See TESAME Tutorial
Will NOT clean junk cells that aren't from a master file (ESM). To find empty cells, you can use tes3cmd dump --exterior --no-match "FRMR" MyPlugin.esp > MyPluginEmptyCells.txt

Dumping

See the documentation for examples, for instance to dump all dialogue from TR into a text file:

 tes3cmd dump --type DIAL --type INFO TR_Mainland.esm > TR_Mainland_DialogueDump.txt 

Exporting

To export into a plugin instead of a txt file. Take care that the NEW file is the one in the argument --raw-with-header, it comes first in the line. If you put the file names in the wrong order, you will turn your plugin into an empty file with no backups!

 tes3cmd dump --type DIAL --type INFO --raw-with-header "TR_Mainland_Dialogue.esp" TR_Mainland.esm

Most data types can be exported directly except dialogue and cells.
- Dialogue always needs DIAL (topic or journal ID) and INFO (dialogue entries) to be exported together and in the original order. To export filtered dialogue in bulk, first export all dialogue without any filters, then "delete" the unwanted parts with filters. To export specific dialogue, filter for the exact ids of both INFO and DIAL; the id of a topic is the topic name.
- Interior cells need both their CELL and PGRD (if there is a pathgrid). Exterior cells need their CELL, LAND, PGRD, and all LTEX records. To export filtered cells in bulk, first export all CELL, LAND, PGRD, LTEX types, then delete the CELL, LAND, PGRD (but not LTEX) you don't want.

Modifying

WARNING: Always back up your files before using this function or the "delete" function. Don't use it on the vanilla ESM files. Don't use it on TR_Mainland or Tamriel_Data if you don't know what you're doing. Always use proper filters. Any scripts modified with this function need to be recompiled in the CS.
The "modify" function doesn't work in the latest alpha version. To use "modify", download 0.37v, rename its exe to "tes3cmd037.exe" and put it in your Data Files folder. Then when you want to use a modify line, for instance to add spaces around all uses of "--" in dialogue in the file, use tes3cmd037 instead of tes3cmd:

 tes3cmd037 modify --type INFO --replace "/--/ -- /" MyPlugin.esp 

Note that in this example any IDs for speakers or conditions in dialogue would be modified too if they included "--". To be perfectly safe you should add another filter: --sub-match "Response:" so that only the text field is modified. When increasing the character count of IDs or dialogue in bulk, use dumps and a text editor to make sure limits aren't exceeded: 512 characters for dialogue text, 24 characters for NPC, creature or container IDs, 31 characters for scripts, 32 characters for other IDs.

 
Examples of tes3cmd files used for repeated tasks

WARNING: bat files are as dangerous as exe files! Don't double click on a .bat file from an unknown source unless you've opened it in a text editor and can verify its contents.
Finding unlinked doors
Rotating trees with --program-file and perl