1. Download the latest release
2. Unzip the files into destination
   • (Windows) C:\ProgramData\ShokoServer\plugins
   • (Docker) wherever the container location /home/shoko/.shoko/Shoko.CLI/plugins is mounted
3. Restart Shoko Server
4. (Optional) Install VS Code and the Lua extension to edit your script. The extension uses LuaCATS annotations
5. Follow instructions in the next section to add your script

1. Open Shoko Desktop
2. Navigate to Utilities/File Renaming
3. Use the Default script or create a new one and set the type of the script to LuaRenamer in the drop-down menu
4. (Optional) Open the lua subfolder of the extracted plugin in VS Code
5. Create a script
6. Paste the script in the text box in Shoko Desktop
7. Add the files you wish to rename
8. Test your script before renaming by pressing Preview. (There is no preview for file moving, only renaming)
9. Pressing Rename does not move files by default, the checkbox to move must also be checked
10. Save your script

1. Copy/download the linux scripts
2. (Optional) Open the lua subfolder of the extracted plugin in VS Code
3. Create a script
4. Preview the results with the preview script ./preview_rename_script.sh <script filename> [# results]
5. Add your script to Shoko with the add script ./add_rename_script.sh <script filename>
6. If you want to rename and move all existing files use the rename script ./rename_and_move_all.sh <script name>

If you wish to rename/move your files on import you must do two things:

1. Set Rename/Move On Import to true in Shoko settings
2. Ensure your script is saved with the run on import setting true
   1. Check that it is the only script with the setting enabled

VS Code + the Lua extension is recommended for script editing.
The script environment utilizes LuaCATS annotations, allowing the extension to provide type linting.

The lua environment is sandboxed, removing operations from standard libraries such as io, and os. See BaseEnv in LuaContext.
The script is run in a fresh environment for every file.
Only the output variables defined in env.lua will have any effect outside of the script.

• env.lua*: The starting environment, output variable values will change renaming/moving behaviour
• defs.lua*: Table definitions available from Shoko
• enums.lua*: Enumeration definitions
• lualinq.lua: A modified utility library (original, docs) that adds functional query methods similar to LINQ
• utils.lua: Additional utility functions can be defined here

* This file is not executed, it serves as documentation/annotations

In addition to the filename, destination and subfolder output variables, these variables affect the result of your script.

• use_existing_anime_location If true, the subfolder with the most files of the same anime is reused if one exists. This takes precedence over the subfolder set in the script (default: false)
• replace_illegal_chars If true, replaces all illegal path characters in subfolder and file name with alternatives. See ReplaceMap in Utils.cs (default: false)
• remove_illegal_chars If true, removes all illegal path characters in subfolder and file name. If false, illegal characters are replaced with underscores or replaced if replace_illegal_chars is true. (default: false)
• skip_rename If true, the result of running the script is discarded when renaming. (default: false)
• skip_move If true, the result of running the script is discarded when moving. (default: false)

Import folders are only valid destination candidates if they exist and have either the 'Destination' or 'Both' Drop Type. Using use_existing_anime_location allows for an import folder with 'Excluded' drop type to be picked. This may change in the future.
Destination defaults to the nearest (to the file) valid import folder.
Destination is set via:

• Import folder name (string)
• Server folder path (string)
• Import folder reference (selected from 'importfolders' array)

If destination set via path, it is matched to import folder path with converted directory seperators but no other special handling (relative path or expansion).

Subfolder defaults to the anime title in your preferred language.
Subfolder is set via:

• Subfolder name (string)
• Path segments (array-table, e.g. {"parent dir name", "subdir name", "..."})

If set via a string subfolder name, directory separators within the string are ignored or replaced depending on preference.
Also see use_existing_anime_location in Script Settings

The default script provides a sensible renaming template. Some variables may be customized at the top of the file, and can serve as a good base for your own script.

The easiest option is to set the destination by import folder name. Keep in mind the import folder must have the Destination or Both drop type. You may also specify the destination by the full path of the import folder on the server or by referencing it directly via importfolders.

if anime.restricted then
  destination = "hentai"
else
  destination = "anime"
end

if anime.type == AnimeType.Movie then
    subfolder = { "Anime Movies", anime.preferredname }
else
    subfolder = { "Anime", anime.preferredname }
end

Adding Shoko group name to subfolder path when there are multiple series in group.
Warning: adding new series to a group with one entry will not move the old series into a subfolder, so you should probably use this when batch renaming/moving existing series

if #groups == 1 and #groups[1].animes > 1 then
  subfolder = {groups[1].name, anime.preferredname}
end

AniDB, Shoko's metadata provider does not have the concept of seasons. Therefore the metadata available cannot be cleanly mapped. I recommend using Shoko Metadata for Plex or Shokofin for Jellyfin as your client instead of depending on other metadata providers.

Neither Shoko nor this plugin has the ability to create file links. I recommend creating any links before the file is processed by Shoko. Usually download clients have the option to run a script on download completion. You can create a script to link files to a Shoko drop source folder. Feel free to contact me if you need help with this.
Note: If you hard link your files you will need to create an import folder for each file system/volume used.