Scripts

Weaver handles verification, repair, extraction, and the move on its own. Scripts are for anything extra: notify a phone, clean up a folder, tag a release, rewrite an NZB before it is queued. Scripts written for SABnzbd or NZBGet run as they are.

Everything lives under Settings → Scripts, which has four screens: Configuration, Jobs, Secrets, and Runs. All four are marked beta.

Turn Scripts On

Scripts are off by default, because a script runs with the same rights as Weaver itself. Go to Settings → Scripts → Configuration and switch on Run scripts. With it off, Weaver still lists your scripts but never runs one.

If Weaver was started with WEAVER_STRICT_SECURITY=1, scripts are refused no matter what the switch says. The Strict security row on the same screen tells you which way it is set. See Security And Access.

The rest of Configuration:

Concurrent scripts: how many scripts may run at once, across every download and every event. The default is 32, and the range is 1 to 128. A single download’s scripts still run one after another.
Termination grace: how long a script gets to exit after Weaver asks it to stop. The default is 10 seconds.
Unacceptable extensions: a finished download holding a file with one of these extensions is refused. The default list is exe, bat, cmd, com, scr, msi, vbs, ps1, lnk, js. Clear the list to turn the check off.
Interpreters: paths for Python, PowerShell, Batch, and Go. Leave one blank to use whatever is on Weaver’s PATH.
Event scripts and output retention: the default time limit for jobs that are not post-processing (300 seconds), the file event interval, and how many runs are kept. See Runs.

Where Scripts Live

Put scripts in the scripts folder inside the data directory. In Docker that is /config/scripts. A script can be a single file, or a folder holding an NZBGet manifest.json. Weaver reads the folder live and never uploads, edits, or deletes anything in it. Files it cannot read show up under Scripts that could not be read instead of being hidden.

A Go script is a single .go file that uses only the standard library. Weaver builds it offline, with no downloads.

You can point Weaver at another folder under Scripts directory → Change. Doing so turns every script job off, because a script with the same name in the new folder may not be the one you wired up. Everything saved in the jobs is kept. Turn back on the jobs you want.

Script Jobs

A script job is one script on one trigger. The job holds everything about how that script runs:

Script and Job name. A blank name uses the script’s name.
Trigger: post-processing, a queue event, scan, schedule, or feed.
Inputs: the values the job hands the script.
Categories: post-processing and queue jobs only. Pick none to run for every category.
Run mode: Blocking means Weaver waits for the script before moving on. Fire and forget starts the script and carries on; whatever it returns changes nothing.
Timeout: how long the script may run. 0 uses the default: one day for post-processing, and the event time limit from Configuration for everything else. The longest you can set is 7 days.
Enabled: a job that is off never runs and keeps everything saved in it.

The same script can be wired to several triggers, or to the same trigger twice with different inputs. Each wiring is its own job.

Add A Job

Go to Settings → Scripts → Jobs and click Add job.
Choose a script. If its header declares triggers and options, the form fills in from them.
Adjust the trigger, inputs, and run mode, then save.

The header is only a starting point. Once a job is saved, the job is what runs, and editing the script’s header changes nothing. If the header later declares different inputs, the job shows Inputs differ from the script’s header. Click Re-apply from header to bring the inputs in line. Saved values are kept, new inputs are added at their defaults, inputs the header dropped are removed, and the trigger stays the same.

To wire a script up in one go, pick it in the job editor and click Set up jobs from header. Weaver creates a job for every trigger the header declares that does not have one yet. For a scheduled script, the header’s run times are saved on the job.

The Jobs Table

Jobs lists every job in one table, grouped by trigger, with queue jobs split by event. Each row shows the job name, script, categories, run mode, timeout, and an Enabled switch. Row buttons move a job up or down in its group’s run order, open Test, or delete it. Deleting a job leaves the script file alone and keeps the job’s past runs.

Test A Job

Click Test on a row to run the job once, as saved, against made-up inputs. The dialog shows the adapter, the time limit, the simulated inputs, the arguments, the run log, and What the script asked for. Nothing the script asks for is applied. Use Run again to repeat it or Cancel test to stop it. Test runs are not added to Runs.

Triggers

Trigger	When it runs	What the script gets
Post-processing	After a download finishes and Weaver is done with it	The finished output, with SABnzbd and NZBGet post-processing variables
Queue	On one queue event: `NZB_ADDED`, `FILE_DOWNLOADED`, `NZB_DOWNLOADED`, `NZB_DELETED`, `NZB_MARKED`, or `URL_COMPLETED`	NZBGet’s `NZBNA_*` queue variables
Scan	When an NZB arrives, before it joins the queue	A copy of the NZB and NZBGet’s `NZBNP_*` variables
Schedule	At the job’s own run times	Weaver’s own variables and the job’s inputs
Feed	Each time a feed it is attached to is fetched	The fetched feed as a file, in `NZBFP_FILENAME`

A few details:

A download’s queue events run one at a time. File event interval controls FILE_DOWNLOADED events: 0 does not throttle them, and -1 turns them off. NZB_NAMED can be picked but Weaver never raises it.
A scan script can rewrite the NZB, or delete it to turn the NZB away. If a scan script times out, the NZB is refused.
A feed script can rewrite the feed file, and Weaver reads back what it leaves. If a feed script fails or times out, that fetch fails. Attach feed jobs to a feed in its editor under Settings → RSS, with Attach a feed job. They run in the order listed.
Schedule jobs take times as HH:MM, or *:MM for that minute of every hour, separated by commas, plus optional days and Also run at startup. See Scheduling.

Environment And Exit Codes

Weaver tells SABnzbd and NZBGet scripts apart by their header. A script with NZBGet’s header comment or a manifest.json is an NZBGet script, and anything else is a SABnzbd script. Post-processing runs get both families of variables either way, so a script works whichever client it was written for:

SABnzbd: SAB_* variables and the eight positional arguments. Inputs arrive as SAB_OPTION_<NAME>.
NZBGet: NZBPP_* and NZBOP_* variables. Inputs arrive as NZBPO_<Name>.
Weaver: WEAVER_RUN_ID, WEAVER_INSTANCE_NAME, WEAVER_TRIGGER, WEAVER_VERSION, WEAVER_DATA_DIR, WEAVER_COMPLETE_DIR, and inputs as WEAVER_INPUT_<NAME>. Post-processing runs also get WEAVER_JOB_ID, WEAVER_JOB_NAME, WEAVER_CATEGORY, WEAVER_DIRECTORY, WEAVER_FINAL_DIRECTORY, and WEAVER_STATUS.

Exit codes mean the same thing for every script and every trigger:

Exit code	Result
`0`, `92`, `93`	Succeeded
`95`	Skipped, the script had nothing to do
Anything else	Failed

A job whose script is missing from the folder is recorded as a warning and does not fail the download.

Statuses In Sonarr, Radarr, And nzb360

Apps that talk to Weaver through the NZBGet API see script results the way NZBGet reports them. Only blocking post-processing runs count. A script that succeeded reports SUCCESS, a skipped one NONE, and a missing, failed, timed-out, or cancelled one FAILURE. Queue, scan, schedule, and feed runs, and fire-and-forget runs, are never reported there.

NZBGet’s per-download <Script>:=yes and <Script>:=no parameters are not supported. Which scripts run is decided by your jobs alone.

Global And Category Scripts

A post-processing or queue job with no categories is a global script. One with categories runs only for downloads in those categories. Global jobs run first, then the category’s own.

Global scripts run, under Configuration, decides whether global jobs also run for a category that has jobs of its own:

For every download: global jobs always run. This is the default.
Only when the category has none: a category with its own jobs skips the global ones.

Secrets

Tokens and passwords belong on the Secrets screen, not in plain inputs.

Go to Settings → Scripts → Secrets and click Add secret.
Give it a Name and a Value. Names are unique, ignoring case.
In a job’s inputs, pick the secret from the input’s dropdown, or choose Create new secret… right there.

A secret’s value is stored encrypted and never shown again. To change it, open the secret and type a new value. Leave the field blank to keep the old one. Every job that links the secret gets the new value on its next run. One secret can serve many jobs. The table shows which jobs use each secret. Weaver refuses to delete a secret while a job still links it.

For a one-off value, add an input to the job and tick its Secret box. That value is sealed inside the job itself. Once saved, the field shows Saved. Type to replace.

Calling Back Into Weaver

While Weaver’s web server is listening, every run gets two extra variables:

WEAVER_API_URL: the address of Weaver’s GraphQL API.
WEAVER_RUN_TOKEN: a token that works only while this run is going.

Send the token as a Bearer token. With it, a script can read queue items, history items, and its own run through scriptRun. Every other query that needs a sign-in, and every other mutation, refuses it. A job set to run at startup gets the pair on that first run too.

Runs

Settings → Scripts → Runs lists every script run, newest first, whatever started it. Filter by trigger, or use the tabs to show only runs that succeeded, warned, failed, timed out, were interrupted, were skipped, or were cancelled. Click a row to open it in place. It shows the run’s output in the log viewer, with Copy output. A download’s own runs are also listed in its Job Detail under Script runs.

Each run keeps the last 32 KB of its output, standard output and errors together in the order they arrived. A run that printed more shows a Truncated chip.

How many runs are kept is set under Configuration:

Retained runs per download: the newest runs kept for each download. The default is 32.
Retain failed runs: failed runs kept past that count, so failures stay around to look at. The default is 8. Timed-out and cancelled runs count as failed.

Runs that belong to no download are kept the same way for each scan, schedule, and feed. Lowering either number deletes the older runs in the background as soon as you save.

To run a download’s post-processing jobs again, open it and click Re-run scripts in Job Detail, or select entries in History and use Re-run scripts there.

Upgrading From 0.14

The upgrade moves your old setup over for you:

Each post-processing script list becomes post-processing script jobs, with the same run mode, timeouts, and enabled state. Category lists become jobs scoped to that category.
Other triggers a script’s header declares are not turned on. Scheduled scripts no longer run from their header’s task times. Add a schedule job, or use Set up jobs from header.
Each saved secret option becomes a named secret called <script> <option>, linked from every job of that script.
A script named in a list but missing from the folder is carried over turned off, with a warning in the log.
If category lists existed, Global scripts run starts as Only when the category has none.
A category list that was empty, or had every script turned off, no longer stops scripts from running for that category. The log names each such category.
A saved concurrency below 32 is raised to 32, because the setting now covers every script Weaver runs.
An unacceptable extensions list that was empty gets the default list once.
If the saved scripts folder exists but cannot be read, the upgrade stops with a message. Make it readable and start Weaver again.

Scheduling covers schedule rules and when scheduled jobs run.
NZBGet API explains how Sonarr, Radarr, and nzb360 talk to Weaver.
RSS And Watch Folder covers feeds, where feed jobs are attached.
Security And Access explains strict mode.
Storage Layout shows where the data directory and its scripts folder live.
Configuration lists the environment variables Weaver reads at startup.