Skip to content

Hook System

Run custom scripts at points of the download lifecycle, configured under HOOKS in config.toml.

Stage Runs
pre_run before the main flow starts
pre_download once per item, right before that movie/episode starts
post_download after each individual download (GUI: once per item)
post_run once when the whole execution ends
# Replace the matching "pre_run = []" / "pre_download = []" / ... line of [HOOKS] with these tables
# (a key can't be declared twice in TOML).
[[HOOKS.pre_run]]
name = "prepare-env"
type = "python"
path = "scripts/prepare.py"
args = ["--clean"]
env = { MY_FLAG = "1" }
cwd = "~"
os = ["linux", "darwin"]
timeout = 60
enabled = true
continue_on_error = true

[[HOOKS.pre_download]]
name = "pre-download-env"
type = "python"
path = "/app/script.py"
args = ["{download_title}"]
timeout = 30

[[HOOKS.post_download]]
name = "post-download-env"
type = "python"
path = "/app/script.py"
args = ["{download_path}"]
env = { MY_FLAG = "1" }
cwd = "~"
os = ["linux"]
timeout = 60

[[HOOKS.post_run]]
name = "notify"
type = "bash"
command = "echo 'Download finished: {download_title}'"
allow_inline_template = true

Options

Key Description
name Label
type python, bash, sh, shell, bat, cmd
path Script file (alternative to command)
command Inline command (alternative to path); args are ignored
allow_inline_template true expands {download_title}-style placeholders inside command (off by default: command runs verbatim, while path/args/cwd always expand)
args Arguments passed to the script
env Extra environment variables
cwd Working directory (supports ~ and env vars)
os Optional filter: any of "windows", "darwin", "linux"
timeout Max seconds (the hook fails if exceeded)
enabled Disable without removing
continue_on_error false = stop execution when the hook fails

Types

  • Python: current interpreter.
  • Bash / sh / shell: /bin/bash -c on macOS/Linux.
  • Bat / cmd / shell: cmd /c on Windows.
  • Inline: command instead of path for one-liners.

Placeholders

Placeholder Description
{download_path} Absolute path of the downloaded file
{download_dir} Its directory
{download_filename} Its filename
{download_id} Internal download id
{download_title} Title
{download_site} Source site
{download_media_type} Media type
{download_status} Final status
{download_error} Error message, if any
{download_success} 1 success, 0 failure
{stage} Current hook stage

The same values are exposed as environment variables with an SC_ prefix (SC_DOWNLOAD_PATH, SC_DOWNLOAD_SUCCESS, SC_HOOK_STAGE, ...).