Compare commits

...
2 Commits
Author SHA1 Message Date
2bb77ea188 Deployed b94f338 with MkDocs version: 1.6.1 2026-08-26 01:59:28 +00:00
f12f423434 Deployed 40cad41 with MkDocs version: 1.6.1 2026-08-26 01:20:34 +00:00
41 changed files with 186 additions and 135 deletions
+1 -1
View File
@@ -1175,7 +1175,7 @@
<span class="md-ellipsis">
Post-Download Scripts
Post-Scripts
+1 -1
View File
@@ -1188,7 +1188,7 @@
<span class="md-ellipsis">
Post-Download Scripts
Post-Scripts
+1 -1
View File
@@ -1188,7 +1188,7 @@
<span class="md-ellipsis">
Post-Download Scripts
Post-Scripts
+3 -3
View File
@@ -1188,7 +1188,7 @@
<span class="md-ellipsis">
Post-Download Scripts
Post-Scripts
@@ -3785,9 +3785,9 @@ ignore it safely. See <a href="../../creating-a-service/#split-episodes">Split e
<p class="admonition-title">Rejected parameters</p>
<p><code>postscript</code>, <code>post_script</code> and <code>post_scripts</code> are never accepted. A body containing any
of them gets <code>400 INVALID_PARAMETERS</code>, because a command string that arrives from
an HTTP caller would be remote code execution. You configure post-download hooks only in
an HTTP caller would be remote code execution. You configure post-scripts only in
<code>unshackle.yaml</code>, where they still operate for API jobs. See
<a href="../../../reference/configuration/post-scripts/">Post-download scripts</a>.</p>
<a href="../../../reference/configuration/post-scripts/">Post-scripts</a>.</p>
</div>
<div class="admonition warning">
<p class="admonition-title">Gated parameters (developer)</p>
+1 -1
View File
@@ -1188,7 +1188,7 @@
<span class="md-ellipsis">
Post-Download Scripts
Post-Scripts
+1 -1
View File
@@ -1188,7 +1188,7 @@
<span class="md-ellipsis">
Post-Download Scripts
Post-Scripts
+1 -1
View File
@@ -1188,7 +1188,7 @@
<span class="md-ellipsis">
Post-Download Scripts
Post-Scripts
+1 -1
View File
@@ -1188,7 +1188,7 @@
<span class="md-ellipsis">
Post-Download Scripts
Post-Scripts
+1 -1
View File
@@ -1188,7 +1188,7 @@
<span class="md-ellipsis">
Post-Download Scripts
Post-Scripts
+1 -1
View File
@@ -1188,7 +1188,7 @@
<span class="md-ellipsis">
Post-Download Scripts
Post-Scripts
@@ -1345,7 +1345,7 @@
<span class="md-ellipsis">
Post-Download Scripts
Post-Scripts
@@ -2290,7 +2290,7 @@
<td><code>update_checks</code>, <code>redact_paths</code>, <code>debug</code>, <code>unicode_filenames</code></td>
</tr>
<tr>
<td>Post-download scripts</td>
<td>Post-scripts</td>
<td><code>post_scripts</code></td>
</tr>
<tr>
+1 -1
View File
@@ -1390,7 +1390,7 @@
<span class="md-ellipsis">
Post-Download Scripts
Post-Scripts
+1 -1
View File
@@ -1373,7 +1373,7 @@
<span class="md-ellipsis">
Post-Download Scripts
Post-Scripts
+2 -2
View File
@@ -1694,7 +1694,7 @@
<span class="md-ellipsis">
Post-Download Scripts
Post-Scripts
@@ -3219,7 +3219,7 @@ configuration file.</p>
</tr>
<tr>
<td><code>--postscript</code></td>
<td>Run a command after each output file, with <code>{variable}</code> placeholders substituted. Repeatable. Replaces the <code>post_scripts</code> config for this run. See <a href="../../reference/configuration/post-scripts/">Post-download scripts</a>.</td>
<td>Run a command after each output file, with <code>{variable}</code> placeholders substituted. Repeatable. Replaces the <code>post_scripts</code> config for this run. See <a href="../../reference/configuration/post-scripts/">Post-scripts</a>.</td>
</tr>
</tbody>
</table>
+6 -6
View File
@@ -1789,7 +1789,7 @@
<span class="md-ellipsis">
Post-Download Scripts
Post-Scripts
@@ -3841,13 +3841,13 @@ Read <a href="../output-and-naming/#music-output-files">Music output files</a>.<
<h3 id="after-the-download">After the download<a class="headerlink" href="#after-the-download" title="Permanent link">&para;</a></h3>
<p><code>--postscript "&lt;command&gt;"</code> runs your own command once per output file, with unshackle's
metadata substituted into <code>{variable}</code> placeholders. It is repeatable, and it replaces the
<code>post_scripts</code> config for that run. No <code>success</code> hook operates under <code>--no-mux</code>, because
that run writes no muxed output. A <code>failure</code> hook still operates if the download fails.</p>
<code>post_scripts</code> config for that run. No <code>success</code> post-script operates under <code>--no-mux</code>, because
that run writes no muxed output. A <code>failure</code> post-script still operates if the download fails.</p>
<div class="language-shell highlight"><span class="filename">Hand each finished file to an uploader</span><pre><span></span><code><span id="__span-36-1"><a id="__codelineno-36-1" name="__codelineno-36-1" href="#__codelineno-36-1"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>--postscript<span class="w"> </span><span class="s2">"python /opt/upload.py {filepath} --service={service}"</span><span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span>
</span></code></pre></div>
<p>For hooks that continue across runs, for the <code>season</code> and <code>run</code> modes, for <code>failure</code> hooks
and for the full variable list, see
<a href="../../reference/configuration/post-scripts/">Post-download scripts</a>.</p>
<p>For post-scripts that continue across runs, for the <code>season</code> and <code>run</code> modes, for <code>failure</code>
post-scripts and for the full variable list, see
<a href="../../reference/configuration/post-scripts/">Post-scripts</a>.</p>
<h3 id="naming-tags">Naming tags<a class="headerlink" href="#naming-tags" title="Permanent link">&para;</a></h3>
<ul>
<li><code>--tag</code>: set the release group tag (overrides the configured tag).</li>
+1 -1
View File
@@ -1512,7 +1512,7 @@
<span class="md-ellipsis">
Post-Download Scripts
Post-Scripts
+1 -1
View File
@@ -1506,7 +1506,7 @@
<span class="md-ellipsis">
Post-Download Scripts
Post-Scripts
+1 -1
View File
@@ -1478,7 +1478,7 @@
<span class="md-ellipsis">
Post-Download Scripts
Post-Scripts
+1 -1
View File
@@ -1468,7 +1468,7 @@
<span class="md-ellipsis">
Post-Download Scripts
Post-Scripts
+1 -1
View File
@@ -1423,7 +1423,7 @@
<span class="md-ellipsis">
Post-Download Scripts
Post-Scripts
+1 -1
View File
@@ -1417,7 +1417,7 @@
<span class="md-ellipsis">
Post-Download Scripts
Post-Scripts
+1 -1
View File
@@ -1288,7 +1288,7 @@
<span class="md-ellipsis">
Post-Download Scripts
Post-Scripts
+1 -1
View File
@@ -1188,7 +1188,7 @@
<span class="md-ellipsis">
Post-Download Scripts
Post-Scripts
+1 -1
View File
@@ -1186,7 +1186,7 @@
<span class="md-ellipsis">
Post-Download Scripts
Post-Scripts
+1 -1
View File
@@ -1188,7 +1188,7 @@
<span class="md-ellipsis">
Post-Download Scripts
Post-Scripts
+1 -1
View File
@@ -1188,7 +1188,7 @@
<span class="md-ellipsis">
Post-Download Scripts
Post-Scripts
+1 -1
View File
@@ -1188,7 +1188,7 @@
<span class="md-ellipsis">
Post-Download Scripts
Post-Scripts
@@ -1251,7 +1251,7 @@
<span class="md-ellipsis">
Post-Download Scripts
Post-Scripts
+1 -1
View File
@@ -1317,7 +1317,7 @@
<span class="md-ellipsis">
Post-Download Scripts
Post-Scripts
+1 -1
View File
@@ -1301,7 +1301,7 @@
<span class="md-ellipsis">
Post-Download Scripts
Post-Scripts
+1 -1
View File
@@ -1193,7 +1193,7 @@
<span class="md-ellipsis">
Post-Download Scripts
Post-Scripts
+2 -2
View File
@@ -1193,7 +1193,7 @@
<span class="md-ellipsis">
Post-Download Scripts
Post-Scripts
@@ -1980,7 +1980,7 @@ default.</p>
<td><code>key_vaults</code>, <code>vault_timeout</code></td>
</tr>
<tr>
<td><a href="post-scripts/">Post-download scripts</a></td>
<td><a href="post-scripts/">Post-scripts</a></td>
<td><code>post_scripts</code></td>
</tr>
<tr>
+3 -3
View File
@@ -1193,7 +1193,7 @@
<span class="md-ellipsis">
Post-Download Scripts
Post-Scripts
@@ -2493,7 +2493,7 @@ setting, and KIDs, content key counts, and other metadata are always logged eith
<nav class="md-footer__inner md-grid" aria-label="Footer" >
<a href="../post-scripts/" class="md-footer__link md-footer__link--prev" aria-label="Previous: Post-Download Scripts">
<a href="../post-scripts/" class="md-footer__link md-footer__link--prev" aria-label="Previous: Post-Scripts">
<div class="md-footer__button md-icon">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg>
@@ -2503,7 +2503,7 @@ setting, and KIDs, content key counts, and other metadata are always logged eith
Previous
</span>
<div class="md-ellipsis">
Post-Download Scripts
Post-Scripts
</div>
</div>
</a>
+1 -1
View File
@@ -1273,7 +1273,7 @@
<span class="md-ellipsis">
Post-Download Scripts
Post-Scripts
+1 -1
View File
@@ -1290,7 +1290,7 @@
<span class="md-ellipsis">
Post-Download Scripts
Post-Scripts
+97 -46
View File
@@ -27,7 +27,7 @@
<title>Post-Download Scripts - unshackle</title>
<title>Post-Scripts - unshackle</title>
@@ -114,7 +114,7 @@
<div class="md-header__topic" data-md-component="header-topic">
<span class="md-ellipsis">
Post-Download Scripts
Post-Scripts
</span>
</div>
@@ -1202,7 +1202,7 @@
<span class="md-ellipsis">
Post-Download Scripts
Post-Scripts
@@ -1220,7 +1220,7 @@
<span class="md-ellipsis">
Post-Download Scripts
Post-Scripts
@@ -1265,6 +1265,23 @@
</span>
</a>
<nav class="md-nav" aria-label="How the command runs">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#wait" class="md-nav__link">
<span class="md-ellipsis">
Waiting for a script
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
@@ -2107,6 +2124,23 @@
</span>
</a>
<nav class="md-nav" aria-label="How the command runs">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#wait" class="md-nav__link">
<span class="md-ellipsis">
Waiting for a script
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
@@ -2262,7 +2296,7 @@
<h1 id="post-scripts">Post-download scripts<a class="headerlink" href="#post-scripts" title="Permanent link">&para;</a></h1>
<h1 id="post-scripts">Post-scripts<a class="headerlink" href="#post-scripts" title="Permanent link">&para;</a></h1>
<p>Operate your own script when a download finishes, with unshackle's metadata passed in as
<code>{variable}</code> placeholders. Use it to hand a finished file to an uploader, send a
notification, or start a library scan.</p>
@@ -2303,6 +2337,11 @@ is the same as <code>{command: "...", event: success, mode: file}</code>.</p>
<td><code>file</code></td>
<td><code>file</code>, <code>season</code>, or <code>run</code>. See <a href="#modes">Modes</a></td>
</tr>
<tr>
<td><code>wait</code></td>
<td><code>false</code></td>
<td><code>true</code> makes unshackle wait for the script to exit before carrying on. See <a href="#wait">Waiting for a script</a></td>
</tr>
</tbody>
</table>
<p>unshackle skips an entry whose <code>event</code> or <code>mode</code> is not one of the listed values, and logs a
@@ -2340,16 +2379,27 @@ through <code>cmd.exe</code>, whose argument quoting differs from every other pr
history of letting a crafted value break out (CVE-2024-3566). Call the interpreter and
pass the script as an argument (<code>python upload.py</code>, <code>pwsh -File upload.ps1</code>) instead.</p>
</div>
<p>Scripts are fire and forget. unshackle starts the process, writes the command to the debug
log, and carries on. It does not wait for the script, capture its output, time it out, or
change its own exit code when a script fails. A script keeps running if unshackle exits
first, and <kbd>Ctrl</kbd>+<kbd>C</kbd> during a season pack does not kill the scripts
already started.</p>
<p>By default, scripts are fire and forget. unshackle starts the process, writes the command to
the debug log, and carries on. It does not wait for the script, capture its output, time it
out, or change its own exit code when a script fails. A script keeps running if unshackle
exits first, and <kbd>Ctrl</kbd>+<kbd>C</kbd> during a season pack does not kill the
scripts already started.</p>
<div class="admonition note">
<p class="admonition-title">One process per file</p>
<p>In <code>file</code> mode a large season pack starts one process per episode with nothing
throttling them. If your script is heavy, queue the work inside it or use <code>mode: season</code>.</p>
throttling them. If your script is heavy, set <code>wait: true</code>, queue the work inside the
script, or use <code>mode: season</code>.</p>
</div>
<h3 id="wait">Waiting for a script<a class="headerlink" href="#wait" title="Permanent link">&para;</a></h3>
<div class="language-yaml highlight"><span class="filename">unshackle.yaml</span><pre><span></span><code><span id="__span-1-1"><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a><span class="nt">post_scripts</span><span class="p">:</span>
</span><span id="__span-1-2"><a id="__codelineno-1-2" name="__codelineno-1-2" href="#__codelineno-1-2"></a><span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">command</span><span class="p">:</span><span class="w"> </span><span class="s">"python</span><span class="nv"> </span><span class="s">/opt/upload.py</span><span class="nv"> </span><span class="s">--file={filepath}"</span>
</span><span id="__span-1-3"><a id="__codelineno-1-3" name="__codelineno-1-3" href="#__codelineno-1-3"></a><span class="w"> </span><span class="nt">wait</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
</span></code></pre></div>
<p>With <code>wait: true</code>, unshackle waits until the script exits, then writes the exit code to the
debug log and carries on. Because the <code>file</code> post-script runs between titles, unshackle runs one
script at a time over a season pack instead of starting them all at once. unshackle only
logs the exit code: a failing script does not fail the download or change unshackle's own
exit code. <code>--postscript</code> entries never wait.</p>
<h2 id="variables">Variables<a class="headerlink" href="#variables" title="Permanent link">&para;</a></h2>
<p>Metadata comes from the same naming context that produced the file's name, built per output
file. So <code>{quality}</code> and <code>{hdr}</code> always give the values for the file unshackle passes in. Downloading
@@ -2433,7 +2483,7 @@ string as absent. Write your script to accept an empty value for every variable.
file, because SDR is the absence of an HDR tag in a filename rather than a tag that
reads <code>SDR</code>. <code>{edition}</code>, <code>{atmos}</code>, <code>{multi}</code>, <code>{dual}</code> and <code>{hfr}</code> behave the same
way. If your script needs the word <code>SDR</code>, derive it from an empty <code>{hdr}</code> yourself.</li>
<li>The hook is a <code>failure</code> hook. A failed download has no output file to read metadata
<li>The post-script is a <code>failure</code> one. A failed download has no output file to read metadata
from, so everything that comes from the naming context is empty. See
<a href="#events">Events</a>.</li>
</ul>
@@ -2445,7 +2495,7 @@ disappearing.</p>
padding and the separator belong to the filename template rather than to the data.</p>
</div>
<h3 id="music-variables">Music variables<a class="headerlink" href="#music-variables" title="Permanent link">&para;</a></h3>
<p>A music download builds its variables from the music naming context, so a hook gets the
<p>A music download builds its variables from the music naming context, so a post-script gets the
release fields instead of the season and episode ones. <code>{season}</code>, <code>{episode}</code> and
<code>{episode_name}</code> are always empty for music.</p>
<table>
@@ -2490,16 +2540,16 @@ release fields instead of the season and episode ones. <code>{season}</code>, <c
</tr>
</tbody>
</table>
<p>In a <code>file</code> hook <code>{title}</code> is the track name. See <a href="#modes">Modes</a> for what an album hook
<p>In a <code>file</code> post-script <code>{title}</code> is the track name. See <a href="#modes">Modes</a> for what an album post-script
puts in <code>{title}</code>.</p>
<p><code>{year}</code> is empty when the service gives the release no year. <code>{ext}</code> is the container the
track arrived in, such as <code>.flac</code>, because a music download is not muxed.</p>
<h3 id="tagging-ids">Tagging IDs<a class="headerlink" href="#tagging-ids" title="Permanent link">&para;</a></h3>
<p><code>{tmdb}</code>, <code>{imdb}</code> and <code>{tvdb}</code> carry the IDs unshackle tags the file with. unshackle reads
them at the moment it sends the hook, and not at the start of the run. The title search inside
the download loop finds an episode's TMDB ID, so a hook fires with it already filled in.</p>
them at the moment it dispatches the post-script, and not at the start of the run. The title search
inside the download loop finds an episode's TMDB ID, so a post-script fires with it already filled in.</p>
<p>They hold an ID you passed with <code>--tmdb</code>, <code>--imdb</code> or <code>--tvdb</code>, plus a TMDB ID the episode
search resolved. No such search runs for a movie, so a movie hook gets them empty unless you
search resolved. No such search runs for a movie, so a movie post-script gets them empty unless you
passed one.</p>
<h3 id="sidecar-files">Sidecar files<a class="headerlink" href="#sidecar-files" title="Permanent link">&para;</a></h3>
<p><code>{sidecars}</code> holds the sidecar subtitle files written beside the output, which are the only
@@ -2513,7 +2563,7 @@ argument, so your template needs no quoting.</p>
<p>When one download writes several outputs (<code>-q 1080,720</code>), each output's folder gets its own
copy of the sidecar files, and each invocation lists the copies sitting beside its own
<code>{filepath}</code>.</p>
<div class="language-python highlight"><span class="filename">Reading {sidecars} in Python</span><pre><span></span><code><span id="__span-1-1"><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a><span class="n">subs</span> <span class="o">=</span> <span class="p">[</span><span class="n">p</span> <span class="k">for</span> <span class="n">p</span> <span class="ow">in</span> <span class="n">sys</span><span class="o">.</span><span class="n">argv</span><span class="p">[</span><span class="n">i</span><span class="p">]</span><span class="o">.</span><span class="n">removeprefix</span><span class="p">(</span><span class="s2">"--subs="</span><span class="p">)</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="s2">"</span><span class="se">\n</span><span class="s2">"</span><span class="p">)</span> <span class="k">if</span> <span class="n">p</span><span class="p">]</span>
<div class="language-python highlight"><span class="filename">Reading {sidecars} in Python</span><pre><span></span><code><span id="__span-2-1"><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a><span class="n">subs</span> <span class="o">=</span> <span class="p">[</span><span class="n">p</span> <span class="k">for</span> <span class="n">p</span> <span class="ow">in</span> <span class="n">sys</span><span class="o">.</span><span class="n">argv</span><span class="p">[</span><span class="n">i</span><span class="p">]</span><span class="o">.</span><span class="n">removeprefix</span><span class="p">(</span><span class="s2">"--subs="</span><span class="p">)</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="s2">"</span><span class="se">\n</span><span class="s2">"</span><span class="p">)</span> <span class="k">if</span> <span class="n">p</span><span class="p">]</span>
</span></code></pre></div>
<h2 id="modes">Modes<a class="headerlink" href="#modes" title="Permanent link">&para;</a></h2>
<table>
@@ -2548,18 +2598,18 @@ copy of the sidecar files, and each invocation lists the copies sitting beside i
</table>
<div class="admonition warning">
<p class="admonition-title"><code>season</code> means everything this run asked for</p>
<p>A <code>season</code> hook fires when the last title <strong>this run queued</strong> for that season finishes.
With <code>-w S01-S02</code> the S01 hook runs while S02 is still downloading. It says nothing
about whether the season is complete on disk. Downloading a single episode fires the
hook for that season as soon as the episode lands.</p>
<p>A title that fails stops the whole run. unshackle dispatches the <code>failure</code> hook for
<p>A <code>season</code> post-script fires when the last title <strong>this run queued</strong> for that season
finishes. With <code>-w S01-S02</code> the S01 post-script runs while S02 is still downloading. It says
nothing about whether the season is complete on disk. Downloading a single episode fires
the post-script for that season as soon as the episode lands.</p>
<p>A title that fails stops the whole run. unshackle dispatches the <code>failure</code> post-script for
that title and then returns. It downloads no further title, and no <code>season</code> or <code>run</code>
hook fires after that point. This applies to every title type. If one episode of S01
fails, the S01 hook does not fire at all.</p>
post-script fires after that point. This applies to every title type. If one episode of S01
fails, the S01 post-script does not fire at all.</p>
</div>
<p>unshackle attaches the hook to the folder, not to the season, so one season landing in several
folders (<code>-q 1080,720</code> with a quality-dependent folder template) fires it once per folder,
each with its own <code>{folder}</code>. A movie is a group of its own: a <code>season</code> hook fires for a
<p>unshackle attaches the post-script to the folder, not to the season, so one season landing in
several folders (<code>-q 1080,720</code> with a quality-dependent folder template) fires it once per
folder, each with its own <code>{folder}</code>. A movie is a group of its own: a <code>season</code> post-script fires for a
movie's folder as soon as the movie finishes.</p>
<p>In <code>run</code> mode every variable except <code>{folder}</code> is empty, because one run can cover several
shows. Only <code>{folder}</code> is meaningful, which makes it useful for starting a library scan
@@ -2588,37 +2638,38 @@ once.</p>
</tr>
</tbody>
</table>
<p>In a <code>file</code> hook <code>{title}</code> and <code>{title_raw}</code> are the track name. In an album hook they are
the album name, and the per-track variables <code>{track_number}</code>, <code>{disc}</code> and <code>{isrc}</code> are
empty, in the same way that <code>{episode}</code> is empty in a season hook.</p>
<p>An album hook obeys the same rule as a season hook. It fires when the last track <strong>this run
queued</strong> for that album lands. This does not mean that the album is complete on disk. A
one-track download fires the album hook as soon as that track lands. If a track fails, the
run stops there, so the album hook never fires, in the same way as an episode and its
<p>In a <code>file</code> post-script <code>{title}</code> and <code>{title_raw}</code> are the track name. In an album post-script they
are the album name, and the per-track variables <code>{track_number}</code>, <code>{disc}</code> and <code>{isrc}</code> are
empty, in the same way that <code>{episode}</code> is empty in a season post-script.</p>
<p>An album post-script obeys the same rule as a season post-script. It fires when the last track
<strong>this run queued</strong> for that album lands. This does not mean that the album is complete on disk.
A one-track download fires the album post-script as soon as that track lands. If a track fails,
the run stops there, so the album post-script never fires, in the same way as an episode and its
season.</p>
<h2 id="events">Events<a class="headerlink" href="#events" title="Permanent link">&para;</a></h2>
<p><code>success</code> runs after the file has moved to its final path. <code>failure</code> runs when the download
fails, with <code>{filepath}</code> empty and <code>{error}</code> set. Each track of an album is its own title.
A music <code>failure</code> hook therefore describes the track that failed, not the release.</p>
A music <code>failure</code> post-script therefore describes the track that failed, not the release.</p>
<div class="admonition warning">
<p class="admonition-title"><code>failure</code> only fires in <code>file</code> mode</p>
<p>A <code>failure</code> entry with <code>mode: season</code> or <code>mode: run</code> never runs. Leave <code>mode</code> at its
default on a failure entry.</p>
</div>
<p>A <code>failure</code> hook has no output file to read metadata from, so it carries only what the
<p>A <code>failure</code> post-script has no output file to read metadata from, so it carries only what the
title object already knew: <code>{title}</code>, <code>{title_raw}</code>, <code>{title_id}</code>, <code>{year}</code>, <code>{season}</code>,
<code>{episode}</code>, <code>{episode_name}</code>, <code>{service}</code>, the tagging IDs and <code>{error}</code>. Everything that
comes from the naming context, such as <code>{quality}</code>, <code>{hdr}</code>, <code>{artist}</code> and <code>{album}</code>, is
empty.</p>
<p>A resumed <code>--continue-downloads</code> download that finishes runs <code>success</code> as usual. Because
unshackle does not wait for your script, it never sees its exit code, so a failing script
is not reported anywhere. Your script owns its own error handling and logging.</p>
<p>A <code>success</code> hook always names a file this run wrote. There is no skip-if-exists path in
<p>A resumed <code>--continue-downloads</code> download that finishes runs <code>success</code> as usual. unshackle
sees your script's exit code only when that entry sets <code>wait: true</code>, and even then it only
writes the code to the debug log. Nothing else reports a failing script. Your script owns
its own error handling and logging.</p>
<p>A <code>success</code> post-script always names a file this run wrote. There is no skip-if-exists path in
<code>dl</code> today, so nothing fires for a title that was not downloaded.</p>
<h2 id="-postscript"><code>--postscript</code><a class="headerlink" href="#-postscript" title="Permanent link">&para;</a></h2>
<p><code>dl</code> accepts <code>--postscript "&lt;command&gt;"</code>, repeatable. Every command given this way runs with
<code>event: success</code> and <code>mode: file</code>.</p>
<div class="language-console highlight"><pre><span></span><code><span id="__span-2-1"><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a><span class="gp">$ </span>unshackle<span class="w"> </span>dl<span class="w"> </span>--postscript<span class="w"> </span><span class="s2">"python /opt/upload.py {filepath}"</span><span class="w"> </span>SERVICE<span class="w"> </span>TITLE_ID
<div class="language-console highlight"><pre><span></span><code><span id="__span-3-1"><a id="__codelineno-3-1" name="__codelineno-3-1" href="#__codelineno-3-1"></a><span class="gp">$ </span>unshackle<span class="w"> </span>dl<span class="w"> </span>--postscript<span class="w"> </span><span class="s2">"python /opt/upload.py {filepath}"</span><span class="w"> </span>SERVICE<span class="w"> </span>TITLE_ID
</span></code></pre></div>
<p>It replaces the <code>post_scripts</code> config for that run rather than adding to it, so no
configured entry runs while it is in use. That includes your <code>season</code>, <code>run</code> and <code>failure</code>
@@ -2636,7 +2687,7 @@ command itself may not cross the network.</p>
<a href="../../../guide/troubleshooting/#the-structured-json-debug-log">structured JSON debug log</a>
when that log is on.</p>
<p>unshackle masks both the same way, and honours <a href="../misc/"><code>redact_paths</code></a>, which is on by default.
Debug logs get shared in issue reports, and a hook command line is mostly paths. URL
Debug logs get shared in issue reports, and a post-script command line is mostly paths. URL
credentials and <code>token=</code> / <code>api_key=</code> query parameters are also masked.</p>
<div class="admonition warning">
<p class="admonition-title">Do not hardcode secrets in the command</p>
@@ -2646,9 +2697,9 @@ environment variable inside your script rather than putting it in the <code>comm
</div>
<h2 id="limitations">Limitations<a class="headerlink" href="#limitations" title="Permanent link">&para;</a></h2>
<ul>
<li>No <code>success</code> hook operates under <code>--no-mux</code> or <code>--skip-dl</code>, because neither writes a muxed
output. A <code>failure</code> hook still runs under <code>--no-mux</code> if the download itself fails.</li>
<li><code>failure</code> hooks only operate in <code>file</code> mode.</li>
<li>No <code>success</code> post-script operates under <code>--no-mux</code> or <code>--skip-dl</code>, because neither writes a
muxed output. A <code>failure</code> post-script still runs under <code>--no-mux</code> if the download itself fails.</li>
<li><code>failure</code> post-scripts only operate in <code>file</code> mode.</li>
<li>There is no webhook sender. Call <code>curl</code> from a script instead.</li>
<li>Script output is not captured. Redirect it inside your own script if you want a log.</li>
</ul>
+1 -1
View File
@@ -1295,7 +1295,7 @@
<span class="md-ellipsis">
Post-Download Scripts
Post-Scripts
+3 -3
View File
@@ -1262,7 +1262,7 @@
<span class="md-ellipsis">
Post-Download Scripts
Post-Scripts
@@ -2124,13 +2124,13 @@ constructor accepts a <code>timeout</code> parameter (a per-vault <code>timeout<
<a href="../post-scripts/" class="md-footer__link md-footer__link--next" aria-label="Next: Post-Download Scripts">
<a href="../post-scripts/" class="md-footer__link md-footer__link--next" aria-label="Next: Post-Scripts">
<div class="md-footer__title">
<span class="md-footer__direction">
Next
</span>
<div class="md-ellipsis">
Post-Download Scripts
Post-Scripts
</div>
</div>
<div class="md-footer__button md-icon">
File diff suppressed because one or more lines are too long
+37 -37
View File
@@ -2,150 +2,150 @@
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
<url>
<loc>https://docs.unshackle.dev/</loc>
<lastmod>2026-08-24</lastmod>
<lastmod>2026-08-26</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/dev/creating-a-service/</loc>
<lastmod>2026-08-24</lastmod>
<lastmod>2026-08-26</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/dev/service-architecture/</loc>
<lastmod>2026-08-24</lastmod>
<lastmod>2026-08-26</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/dev/rest-api/</loc>
<lastmod>2026-08-24</lastmod>
<lastmod>2026-08-26</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/dev/rest-api/authentication/</loc>
<lastmod>2026-08-24</lastmod>
<lastmod>2026-08-26</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/dev/rest-api/endpoints/</loc>
<lastmod>2026-08-24</lastmod>
<lastmod>2026-08-26</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/dev/rest-api/errors/</loc>
<lastmod>2026-08-24</lastmod>
<lastmod>2026-08-26</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/dev/rest-api/job-lifecycle/</loc>
<lastmod>2026-08-24</lastmod>
<lastmod>2026-08-26</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/dev/rest-api/quickstart/</loc>
<lastmod>2026-08-24</lastmod>
<lastmod>2026-08-26</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/dev/rest-api/remote-sessions/</loc>
<lastmod>2026-08-24</lastmod>
<lastmod>2026-08-26</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/getting-started/configuration-file/</loc>
<lastmod>2026-08-24</lastmod>
<lastmod>2026-08-26</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/getting-started/installation/</loc>
<lastmod>2026-08-24</lastmod>
<lastmod>2026-08-26</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/getting-started/quickstart/</loc>
<lastmod>2026-08-24</lastmod>
<lastmod>2026-08-26</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/guide/cli-reference/</loc>
<lastmod>2026-08-24</lastmod>
<lastmod>2026-08-26</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/guide/downloading/</loc>
<lastmod>2026-08-24</lastmod>
<lastmod>2026-08-26</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/guide/drm-and-cdm/</loc>
<lastmod>2026-08-24</lastmod>
<lastmod>2026-08-26</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/guide/output-and-naming/</loc>
<lastmod>2026-08-24</lastmod>
<lastmod>2026-08-26</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/guide/proxies-and-vpn/</loc>
<lastmod>2026-08-24</lastmod>
<lastmod>2026-08-26</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/guide/subtitles/</loc>
<lastmod>2026-08-24</lastmod>
<lastmod>2026-08-26</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/guide/troubleshooting/</loc>
<lastmod>2026-08-24</lastmod>
<lastmod>2026-08-26</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/guide/vaults/</loc>
<lastmod>2026-08-24</lastmod>
<lastmod>2026-08-26</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/reference/api/config/</loc>
<lastmod>2026-08-24</lastmod>
<lastmod>2026-08-26</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/reference/api/drm/</loc>
<lastmod>2026-08-24</lastmod>
<lastmod>2026-08-26</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/reference/api/service/</loc>
<lastmod>2026-08-24</lastmod>
<lastmod>2026-08-26</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/reference/api/titles/</loc>
<lastmod>2026-08-24</lastmod>
<lastmod>2026-08-26</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/reference/api/tracks/</loc>
<lastmod>2026-08-24</lastmod>
<lastmod>2026-08-26</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/reference/configuration/</loc>
<lastmod>2026-08-24</lastmod>
<lastmod>2026-08-26</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/reference/configuration/directories/</loc>
<lastmod>2026-08-24</lastmod>
<lastmod>2026-08-26</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/reference/configuration/download/</loc>
<lastmod>2026-08-24</lastmod>
<lastmod>2026-08-26</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/reference/configuration/drm/</loc>
<lastmod>2026-08-24</lastmod>
<lastmod>2026-08-26</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/reference/configuration/example/</loc>
<lastmod>2026-08-24</lastmod>
<lastmod>2026-08-26</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/reference/configuration/misc/</loc>
<lastmod>2026-08-24</lastmod>
<lastmod>2026-08-26</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/reference/configuration/network/</loc>
<lastmod>2026-08-24</lastmod>
<lastmod>2026-08-26</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/reference/configuration/output/</loc>
<lastmod>2026-08-24</lastmod>
<lastmod>2026-08-26</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/reference/configuration/post-scripts/</loc>
<lastmod>2026-08-24</lastmod>
<lastmod>2026-08-26</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/reference/configuration/services/</loc>
<lastmod>2026-08-24</lastmod>
<lastmod>2026-08-26</lastmod>
</url>
<url>
<loc>https://docs.unshackle.dev/reference/configuration/vaults/</loc>
<lastmod>2026-08-24</lastmod>
<lastmod>2026-08-26</lastmod>
</url>
</urlset>
BIN
View File
Binary file not shown.