Skip to content

Add API Authentication and additional scan scheduling options#711

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dscisci wants to merge 3 commits into
base:main
Choose a base branch
from
Open

Add API Authentication and additional scan scheduling options #711

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9b0e6c9
Add files via upload
dscisci May 1, 2026
5ad5f71
Add files via upload
dscisci May 12, 2026
612e9ff
Merge branch 'main' into main
dscisci May 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 6 additions & 3 deletions plugins/stash-scheduler/README.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,5 @@
# Stash Scheduler Plugin

https://discourse.stashapp.cc/t/stash-scheduler/7059

@DogmaDragonDogmaDragonMay 13, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Must be retained.


A plugin for [Stash](https://github.com/stashapp/stash) that automatically runs library scans on a schedule (hourly, daily, or weekly), with an optional identify pass after each scan.

---
Expand DownExpand Up@@ -83,8 +81,9 @@ Open **Settings → Plugins → Stash Scheduler** and set your preferences:

| Setting | Description | Default |
|---|---|---|
| **API Key** | Stash API key for authenticating background scans. Required when "Require API key" is enabled in Stash's Security settings. Generate one under Settings > Security > API Keys. Leave blank if Stash does not require authentication. | *(none)* |
| **Scan Frequency** | `hourly`, `daily`, or `weekly` | `daily` |
| **Time of Day (HH:MM)** | Time to run the scan in 24-hour `HH:MM` format. Used by Daily and Weekly; ignored for Hourly. | `02:00` |
| **Time of Day (HH:MM)** | One or more times to run the scan, in 24-hour `HH:MM` format. Separate multiple times with commas or spaces, e.g. `00:00, 06:00, 18:00`. Used by Daily and Weekly; ignored for Hourly. | `02:00` |
| **Day of Week** | Day to scan when Frequency is Weekly. Use `mon`, `tue`, `wed`, `thu`, `fri`, `sat`, or `sun`. | `sun` |
| **Timezone** | IANA timezone name for interpreting Time of Day and Day of Week. Examples: `America/New_York`, `Europe/London`, `Asia/Tokyo`. Leave blank for UTC. | `UTC` |
| **Run Identify After Scan** | When enabled, runs an Identify task after each scan finishes successfully. | `false` |
Expand DownExpand Up@@ -296,6 +295,10 @@ All activity is written to the Stash log. To view it:

| Version | Notes |
|---|---|
| 0.10.0 | Added API Key setting — required when Stash's "Require API key" security option is enabled |
| 0.9.0 | Daemon now reloads settings from Stash on every scheduled run — changes to identify, paths, and scan flags take effect without restarting the scheduler |
| 0.8.0 | Fixed identify not running after scan (null fields in GraphQL input); fixed daemon losing Stash connection after restart; added APScheduler error logging, hourly heartbeat, and next-fire-time logging; Check Status now shows 100 log lines |
| 0.7.0 | Time of Day now accepts multiple times (comma or space separated) — each fires a separate scheduled scan |
| 0.6.0 | Added "Limit to Paths" setting — scan and identify can now be restricted to specific directories |
| 0.5.0 | Fixed identify-after-scan (null jobQueue crash); added 9 scan generation flag settings (covers, previews, sprites, phashes, thumbnails, clip previews, force rescan) |
| 0.4.0 | Added Check Status task; daemon logs written to file (`/tmp/stash-scheduler-daemon.log`) |
Expand Down
21 changes: 16 additions & 5 deletions plugins/stash-scheduler/stash-scheduler.yml
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
name: Stash Scheduler
description: Schedule automatic library scans with an optional identify pass after each scan.
version: "0.6.0"
url: https://discourse.stashapp.cc/t/stash-scheduler/7059

@DogmaDragonDogmaDragonMay 13, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Must be retained.

version: "0.10.0"
url: https://github.com/stashapp/stash

exec:
- python3
Expand DownExpand Up@@ -42,6 +42,16 @@ tasks:
mode: check_status

settings:
apiKey:

@DogmaDragonDogmaDragonMay 13, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why not just check for authentication and get the API key from configuration query using GraphQL if it's available?

displayName: API Key
description: >
Stash API key for authenticating background scans. Required when
Settings > Security > "Require API key for local connections" is enabled,
or when accessing Stash over a network. Generate a key under
Settings > Security > API Keys, then paste it here. Leave blank if
Stash does not require authentication.
type: STRING

frequency:
displayName: Scan Frequency
description: >
Expand All@@ -53,9 +63,10 @@ settings:
time_of_day:
displayName: Time of Day (HH:MM)
description: >
The time to run the scan in 24-hour HH:MM format. Used for Daily and
Weekly schedules; ignored for Hourly. Examples: 02:00, 14:30, 20:45.
Defaults to 02:00 if not set.
One or more times to run the scan in 24-hour HH:MM format. Used for
Daily and Weekly schedules; ignored for Hourly. Separate multiple times
with commas or spaces. Examples: 02:00 — single daily run. 00:00, 06:00,
09:00, 16:00, 18:00 — five runs per day. Defaults to 02:00 if not set.
type: STRING

day_of_week:
Expand Down
153 changes: 123 additions & 30 deletions plugins/stash-scheduler/stash_scheduler.py
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -142,6 +142,7 @@ def get_plugin_settings(stash, plugin_id="stash-scheduler"):
"time_of_day": "02:00",
"day_of_week": "sun",
"timezone": "UTC",
"apiKey": "",
"run_identify": False,
"identify_timeout_minutes": 120,
# Comma- or newline-separated list of paths to restrict scan + identify.
Expand All@@ -168,19 +169,38 @@ def get_plugin_settings(stash, plugin_id="stash-scheduler"):
return defaults


def _parse_time_of_day(raw, warn):
raw = str(raw).strip()
def _parse_single_time(token, warn):
"""Parse one HH:MM token. Returns (hour, minute) or None on error."""
token = str(token).strip()
try:
parts = raw.split(":")
parts = token.split(":")
if len(parts) != 2:
raise ValueError("expected HH:MM")
hh, mm = int(parts[0]), int(parts[1])
if not (0 <= hh <= 23 and 0 <= mm <= 59):
raise ValueError(f"values out of range: {hh}:{mm:02d}")
return hh, mm
except (ValueError, TypeError) as exc:
warn(f"[Stash Scheduler] Invalid time_of_day {raw!r} ({exc}) — defaulting to 02:00.")
return 2, 0
warn(f"[Stash Scheduler] Invalid time {token!r} ({exc}) — skipping.")
return None


def _parse_times_of_day(raw, warn):
"""Parse comma/space/newline-separated HH:MM times.
Returns a deduplicated list of (hour, minute) tuples, sorted ascending.
Falls back to [(2, 0)] if nothing valid is found."""
import re as _re
tokens = [t for t in _re.split(r"[\s,]+", str(raw).strip()) if t]
results, seen = [], set()
for token in tokens:
parsed = _parse_single_time(token, warn)
if parsed is not None and parsed not in seen:
results.append(parsed)
seen.add(parsed)
if not results:
warn("[Stash Scheduler] No valid times found in time_of_day — defaulting to 02:00.")
return [(2, 0)]
return sorted(results)


def validate_and_coerce_settings(settings, warn):
Expand All@@ -194,10 +214,11 @@ def validate_and_coerce_settings(settings, warn):
settings["frequency"] = freq

raw_time = settings.get("time_of_day", "02:00")
hour, minute = _parse_time_of_day(raw_time, warn)
settings["time_of_day"] = f"{hour:02d}:{minute:02d}"
settings["hour"] = hour
settings["minute"] = minute
times = _parse_times_of_day(raw_time, warn)
settings["times_of_day"] = times
settings["time_of_day"] = ", ".join(f"{h:02d}:{m:02d}" for h, m in times)
settings["hour"] = times[0][0]
settings["minute"] = times[0][1]

dow = str(settings.get("day_of_week", "sun")).strip().lower()
if dow not in VALID_DAYS:
Expand DownExpand Up@@ -233,6 +254,9 @@ def validate_and_coerce_settings(settings, warn):
tz_raw = "UTC"
settings["timezone"] = tz_raw

# apiKey — strip whitespace; empty string means no key (session auth)
settings["apiKey"] = str(settings.get("apiKey", "") or "").strip()

# scanPaths — parse comma/newline-separated string into a clean list
raw_paths = str(settings.get("scanPaths", "") or "")
import re as _re
Expand All@@ -254,6 +278,16 @@ def validate_and_coerce_settings(settings, warn):
# Scan / Identify helpers (used by both plugin tasks and the daemon)
# ---------------------------------------------------------------------------

def _strip_nulls(obj):
"""Recursively remove None/null values from a dict or list.
Required before forwarding a GraphQL query result back as mutation input —
Stash rejects null on required sub-fields."""
if isinstance(obj, dict):
return {k: _strip_nulls(v) for k, v in obj.items() if v is not None}
if isinstance(obj, list):
return [_strip_nulls(i) for i in obj]
return obj

_SCAN_FLAGS = (
"scanGenerateCovers",
"scanGeneratePreviews",
Expand DownExpand Up@@ -333,9 +367,12 @@ def trigger_identify(stash_or_log, gql_fn, paths=None):
paths_desc = f" (paths: {', '.join(paths)})" if paths else " (full library)"
_log_info(stash_or_log, f"[Stash Scheduler] Triggering identify task{paths_desc}…")
try:
identify_input = {"sources": identify["sources"]}
# Strip nulls: the query returns the full schema object including null
# sub-fields; forwarding those nulls into the mutation causes Stash to
# reject the request with a schema validation error.
identify_input = {"sources": _strip_nulls(identify["sources"])}
if identify.get("options"):
identify_input["options"] = identify["options"]
identify_input["options"] = _strip_nulls(identify["options"])
if paths:
identify_input["paths"] = paths
result = gql_fn(IDENTIFY_MUTATION, {"input": identify_input})
Expand DownExpand Up@@ -528,7 +565,7 @@ def daemon_alive():
return False, None


def tail_log(n=30):
def tail_log(n=100):
"""Return the last n lines of the daemon log file as a string."""
if not os.path.exists(LOG_FILE):
return "(log file not found)"
Expand DownExpand Up@@ -572,46 +609,82 @@ def run_daemon():
sys.exit(1)

frequency = settings["frequency"]
hour = settings["hour"]
minute = settings["minute"]
times_of_day = settings["times_of_day"]
day_of_week = settings["day_of_week"]
timezone = settings["timezone"]
run_identify = settings["run_identify"]
identify_timeout = settings["identify_timeout_minutes"]
scan_paths = settings.get("scan_paths") or []

# Build a simple GQL callable for the daemon (not stash.log-based)
def gql(query, variables=None):
return call_gql(stash, query, variables)

def scheduled_job():
"""Fired by APScheduler for each scheduled time slot."""
log.info("Scheduled scan cycle firing.")
# Fresh connection each run — guards against stale sessions after a
# Stash restart.
try:
job_id = trigger_scan(log, gql, settings)
fresh_stash = make_stash(cfg["server_connection"])
def gql(query, variables=None):
return call_gql(fresh_stash, query, variables)
except Exception as exc:
log.error(f"Scan failed: {exc}")
log.error(f"Cannot connect to Stash for scheduled scan: {exc}")
return
if run_identify:

# Reload operational settings live from Stash so changes to
# run_identify, scan_paths, scan flags, etc. take effect immediately
# without needing to restart the daemon.
try:
live_settings = validate_and_coerce_settings(
get_plugin_settings(fresh_stash),
lambda m: log.warning(m),
)
log.info(
f"Settings reloaded — identify: {'yes' if live_settings['run_identify'] else 'no'}, "
f"paths: {', '.join(live_settings.get('scan_paths') or []) or 'full library'}"
)
except Exception as exc:
log.warning(f"Could not reload settings from Stash — using startup settings: {exc}")
live_settings = settings

try:
job_id = trigger_scan(log, gql, live_settings)
except Exception as exc:
log.error(f"Scan trigger failed: {exc}")
return

if live_settings["run_identify"]:
live_timeout = live_settings["identify_timeout_minutes"]
live_paths = live_settings.get("scan_paths") or None
threading.Thread(
target=wait_for_scan_and_identify,
args=(log, gql, job_id, identify_timeout, scan_paths or None),
args=(log, gql, job_id, live_timeout, live_paths),
daemon=True,
).start()

def heartbeat_job():
"""Fires every hour so the log shows the daemon is still alive."""
log.info("[heartbeat] Daemon alive.")

scheduler = BackgroundScheduler(timezone=timezone)
job_kwargs = {"func": scheduled_job, "misfire_grace_time": 3600, "coalesce": True}

times_str = ", ".join(f"{h:02d}:{m:02d}" for h, m in times_of_day)
if frequency == "hourly":
scheduler.add_job(trigger="cron", minute=0, **job_kwargs)
log.info(f"Schedule: every hour at :00 ({timezone})")
elif frequency == "weekly":
scheduler.add_job(
trigger="cron", day_of_week=day_of_week, hour=hour, minute=minute, **job_kwargs
)
log.info(f"Schedule: weekly {day_of_week.upper()} at {hour:02d}:{minute:02d} ({timezone})")
for h, m in times_of_day:
scheduler.add_job(
trigger="cron", day_of_week=day_of_week, hour=h, minute=m, **job_kwargs
)
log.info(f"Schedule: weekly {day_of_week.upper()} at {times_str} ({timezone})")
else:
scheduler.add_job(trigger="cron", hour=hour, minute=minute, **job_kwargs)
log.info(f"Schedule: daily at {hour:02d}:{minute:02d} ({timezone})")
for h, m in times_of_day:
scheduler.add_job(trigger="cron", hour=h, minute=m, **job_kwargs)
log.info(f"Schedule: daily at {times_str} ({timezone})")

# Hourly heartbeat so the log proves the daemon is ticking even between scans
scheduler.add_job(func=heartbeat_job, trigger="cron", minute=0,
misfire_grace_time=3600, coalesce=True)

log.info(f"Identify after scan: {'yes' if run_identify else 'no'}")

Expand All@@ -626,7 +699,21 @@ def scheduled_job():
else:
log.info("Scan flags: none (bare scan)")

# Log APScheduler execution errors so silent job failures are visible
from apscheduler.events import EVENT_JOB_ERROR, EVENT_JOB_EXECUTED, EVENT_JOB_MISSED
def _aps_listener(event):
if event.exception:
log.error(f"[APScheduler] Job {event.job_id} raised an exception: {event.exception}")
elif hasattr(event, 'scheduled_run_time') and not hasattr(event, 'retval'):
log.warning(f"[APScheduler] Job {event.job_id} missed its scheduled time.")
scheduler.add_listener(_aps_listener, EVENT_JOB_ERROR | EVENT_JOB_MISSED)

scheduler.start()

# Log next fire times so the log confirms jobs are registered correctly
for job in scheduler.get_jobs():
if job.next_run_time:
log.info(f"Next fire for job '{job.id}': {job.next_run_time}")
log.info("Daemon is running. Waiting for scheduled events…")

stop = threading.Event()
Expand DownExpand Up@@ -682,7 +769,13 @@ def gql(query, variables=None):
# ---------------------------------------------------------------------------

def task_start_scheduler(stash, server_connection, settings):
save_config(server_connection, settings)
# Inject the API key into the saved connection dict so every daemon GQL
# request includes it — required when Stash's "Require API key" is enabled.
conn = dict(server_connection)
api_key = settings.get("apiKey", "").strip()
if api_key:
conn["ApiKey"] = api_key
save_config(conn, settings)
kill_existing_daemon()
launch_detached("--daemon")
freq = settings["frequency"]
Expand DownExpand Up@@ -727,7 +820,7 @@ def task_run_now(stash, settings, force_identify=False):
def task_check_status(stash):
alive, pid = daemon_alive()
status_line = f"Daemon: RUNNING (PID {pid})" if alive else "Daemon: NOT RUNNING"
recent = tail_log(30)
recent = tail_log(100)
output = f"{status_line}\nLog file: {LOG_FILE}\n\nRecent log ({LOG_FILE}):\n{recent}"
stash.log.info(f"[Stash Scheduler] {status_line}")
print(json.dumps({"output": output}))
Expand Down
Loading
, 'i'); if (__m === '*' || __re.test(location.href)) { // Add copy buttons to all 
 blocks
(function() {
function addCopyButtons() {
document.querySelectorAll('pre code').forEach(function(codeBlock) {
if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;
codeBlock.parentElement.setAttribute('data-copy-added', 'true');
var btn = document.createElement('button');
btn.textContent = 'Copy';
btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';
btn.onmouseover = function() { this.style.opacity = '1'; };
btn.onmouseout = function() { this.style.opacity = '0.7'; };
btn.onclick = function() {
navigator.clipboard.writeText(codeBlock.textContent).then(function() {
btn.textContent = 'Copied!';
setTimeout(function() { btn.textContent = 'Copy'; }, 1500);
});
};
codeBlock.parentElement.style.position = 'relative';
codeBlock.parentElement.appendChild(btn);
});
}
addCopyButtons();
// Re-run on dynamic content
var observer = new MutationObserver(addCopyButtons);
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '
Add API Authentication and additional scan scheduling options by dscisci · Pull Request #711 · stashapp/CommunityScripts · GitHub
Skip to content
Add API Authentication and additional scan scheduling options#711

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Open

dscisci
wants to merge
3
commits into

base:main
Choose a base branch

from

 Open


Add API Authentication and additional scan scheduling options
#711
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


3 commits


Select commit
Hold shift + click to select a range
9b0e6c9

Add files via upload


dscisci May 1, 2026
5ad5f71

Add files via upload


dscisci May 12, 2026
612e9ff

Merge branch 'main' into main


dscisci May 12, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


9 changes: 6 additions & 3 deletions
plugins/stash-scheduler/README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,7 +1,5 @@
# Stash Scheduler Plugin

https://discourse.stashapp.cc/t/stash-scheduler/7059
@DogmaDragonDogmaDragonMay 13, 2026

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Must be retained.

A plugin for [Stash](https://github.com/stashapp/stash) that automatically runs library scans on a schedule (hourly, daily, or weekly), with an optional identify pass after each scan.

---
Expand DownExpand Up@@ -83,8 +81,9 @@ Open **Settings → Plugins → Stash Scheduler** and set your preferences:

| Setting | Description | Default |
|---|---|---|
| **API Key** | Stash API key for authenticating background scans. Required when "Require API key" is enabled in Stash's Security settings. Generate one under Settings > Security > API Keys. Leave blank if Stash does not require authentication. | *(none)* |
| **Scan Frequency** | `hourly`, `daily`, or `weekly` | `daily` |
| **Time of Day (HH:MM)** | Time to run the scan in 24-hour `HH:MM` format. Used by Daily and Weekly; ignored for Hourly. | `02:00` |
| **Time of Day (HH:MM)** | One or more times to run the scan, in 24-hour `HH:MM` format. Separate multiple times with commas or spaces, e.g. `00:00, 06:00, 18:00`. Used by Daily and Weekly; ignored for Hourly. | `02:00` |
| **Day of Week** | Day to scan when Frequency is Weekly. Use `mon`, `tue`, `wed`, `thu`, `fri`, `sat`, or `sun`. | `sun` |
| **Timezone** | IANA timezone name for interpreting Time of Day and Day of Week. Examples: `America/New_York`, `Europe/London`, `Asia/Tokyo`. Leave blank for UTC. | `UTC` |
| **Run Identify After Scan** | When enabled, runs an Identify task after each scan finishes successfully. | `false` |
Expand DownExpand Up@@ -296,6 +295,10 @@ All activity is written to the Stash log. To view it:

| Version | Notes |
|---|---|
| 0.10.0 | Added API Key setting — required when Stash's "Require API key" security option is enabled |
| 0.9.0 | Daemon now reloads settings from Stash on every scheduled run — changes to identify, paths, and scan flags take effect without restarting the scheduler |
| 0.8.0 | Fixed identify not running after scan (null fields in GraphQL input); fixed daemon losing Stash connection after restart; added APScheduler error logging, hourly heartbeat, and next-fire-time logging; Check Status now shows 100 log lines |
| 0.7.0 | Time of Day now accepts multiple times (comma or space separated) — each fires a separate scheduled scan |
| 0.6.0 | Added "Limit to Paths" setting — scan and identify can now be restricted to specific directories |
| 0.5.0 | Fixed identify-after-scan (null jobQueue crash); added 9 scan generation flag settings (covers, previews, sprites, phashes, thumbnails, clip previews, force rescan) |
| 0.4.0 | Added Check Status task; daemon logs written to file (`/tmp/stash-scheduler-daemon.log`) |
Expand Down

21 changes: 16 additions & 5 deletions
plugins/stash-scheduler/stash-scheduler.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
name: Stash Scheduler
description: Schedule automatic library scans with an optional identify pass after each scan.
version: "0.6.0"
url: https://discourse.stashapp.cc/t/stash-scheduler/7059
@DogmaDragonDogmaDragonMay 13, 2026

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Must be retained.
version: "0.10.0"
url: https://github.com/stashapp/stash

exec:
 - python3
Expand DownExpand Up@@ -42,6 +42,16 @@ tasks:
 mode: check_status

settings:
 apiKey:
@DogmaDragonDogmaDragonMay 13, 2026

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why not just check for authentication and get the API key from configuration query using GraphQL if it's available?
 displayName: API Key
 description: >
 Stash API key for authenticating background scans. Required when
 Settings > Security > "Require API key for local connections" is enabled,
 or when accessing Stash over a network. Generate a key under
 Settings > Security > API Keys, then paste it here. Leave blank if
 Stash does not require authentication.
 type: STRING

 frequency:
 displayName: Scan Frequency
 description: >
Expand All@@ -53,9 +63,10 @@ settings:
 time_of_day:
 displayName: Time of Day (HH:MM)
 description: >
 The time to run the scan in 24-hour HH:MM format. Used for Daily and
 Weekly schedules; ignored for Hourly. Examples: 02:00, 14:30, 20:45.
 Defaults to 02:00 if not set.
 One or more times to run the scan in 24-hour HH:MM format. Used for
 Daily and Weekly schedules; ignored for Hourly. Separate multiple times
 with commas or spaces. Examples: 02:00 — single daily run. 00:00, 06:00,
 09:00, 16:00, 18:00 — five runs per day. Defaults to 02:00 if not set.
 type: STRING

 day_of_week:
Expand Down

153 changes: 123 additions & 30 deletions
plugins/stash-scheduler/stash_scheduler.py

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -142,6 +142,7 @@ def get_plugin_settings(stash, plugin_id="stash-scheduler"):
 "time_of_day": "02:00",
 "day_of_week": "sun",
 "timezone": "UTC",
 "apiKey": "",
 "run_identify": False,
 "identify_timeout_minutes": 120,
 # Comma- or newline-separated list of paths to restrict scan + identify.
Expand All@@ -168,19 +169,38 @@ def get_plugin_settings(stash, plugin_id="stash-scheduler"):
 return defaults


def _parse_time_of_day(raw, warn):
 raw = str(raw).strip()
def _parse_single_time(token, warn):
 """Parse one HH:MM token. Returns (hour, minute) or None on error."""
 token = str(token).strip()
 try:
 parts = raw.split(":")
 parts = token.split(":")
 if len(parts) != 2:
 raise ValueError("expected HH:MM")
 hh, mm = int(parts[0]), int(parts[1])
 if not (0 <= hh <= 23 and 0 <= mm <= 59):
 raise ValueError(f"values out of range: {hh}:{mm:02d}")
 return hh, mm
 except (ValueError, TypeError) as exc:
 warn(f"[Stash Scheduler] Invalid time_of_day {raw!r} ({exc}) — defaulting to 02:00.")
 return 2, 0
 warn(f"[Stash Scheduler] Invalid time {token!r} ({exc}) — skipping.")
 return None


def _parse_times_of_day(raw, warn):
 """Parse comma/space/newline-separated HH:MM times.
 Returns a deduplicated list of (hour, minute) tuples, sorted ascending.
 Falls back to [(2, 0)] if nothing valid is found."""
 import re as _re
 tokens = [t for t in _re.split(r"[\s,]+", str(raw).strip()) if t]
 results, seen = [], set()
 for token in tokens:
 parsed = _parse_single_time(token, warn)
 if parsed is not None and parsed not in seen:
 results.append(parsed)
 seen.add(parsed)
 if not results:
 warn("[Stash Scheduler] No valid times found in time_of_day — defaulting to 02:00.")
 return [(2, 0)]
 return sorted(results)


def validate_and_coerce_settings(settings, warn):
Expand All@@ -194,10 +214,11 @@ def validate_and_coerce_settings(settings, warn):
 settings["frequency"] = freq

 raw_time = settings.get("time_of_day", "02:00")
 hour, minute = _parse_time_of_day(raw_time, warn)
 settings["time_of_day"] = f"{hour:02d}:{minute:02d}"
 settings["hour"] = hour
 settings["minute"] = minute
 times = _parse_times_of_day(raw_time, warn)
 settings["times_of_day"] = times
 settings["time_of_day"] = ", ".join(f"{h:02d}:{m:02d}" for h, m in times)
 settings["hour"] = times[0][0]
 settings["minute"] = times[0][1]

 dow = str(settings.get("day_of_week", "sun")).strip().lower()
 if dow not in VALID_DAYS:
Expand DownExpand Up@@ -233,6 +254,9 @@ def validate_and_coerce_settings(settings, warn):
 tz_raw = "UTC"
 settings["timezone"] = tz_raw

 # apiKey — strip whitespace; empty string means no key (session auth)
 settings["apiKey"] = str(settings.get("apiKey", "") or "").strip()

 # scanPaths — parse comma/newline-separated string into a clean list
 raw_paths = str(settings.get("scanPaths", "") or "")
 import re as _re
Expand All@@ -254,6 +278,16 @@ def validate_and_coerce_settings(settings, warn):
# Scan / Identify helpers (used by both plugin tasks and the daemon)
# ---------------------------------------------------------------------------

def _strip_nulls(obj):
 """Recursively remove None/null values from a dict or list.
 Required before forwarding a GraphQL query result back as mutation input —
 Stash rejects null on required sub-fields."""
 if isinstance(obj, dict):
 return {k: _strip_nulls(v) for k, v in obj.items() if v is not None}
 if isinstance(obj, list):
 return [_strip_nulls(i) for i in obj]
 return obj

_SCAN_FLAGS = (
 "scanGenerateCovers",
 "scanGeneratePreviews",
Expand DownExpand Up@@ -333,9 +367,12 @@ def trigger_identify(stash_or_log, gql_fn, paths=None):
 paths_desc = f" (paths: {', '.join(paths)})" if paths else " (full library)"
 _log_info(stash_or_log, f"[Stash Scheduler] Triggering identify task{paths_desc}…")
 try:
 identify_input = {"sources": identify["sources"]}
 # Strip nulls: the query returns the full schema object including null
 # sub-fields; forwarding those nulls into the mutation causes Stash to
 # reject the request with a schema validation error.
 identify_input = {"sources": _strip_nulls(identify["sources"])}
 if identify.get("options"):
 identify_input["options"] = identify["options"]
 identify_input["options"] = _strip_nulls(identify["options"])
 if paths:
 identify_input["paths"] = paths
 result = gql_fn(IDENTIFY_MUTATION, {"input": identify_input})
Expand DownExpand Up@@ -528,7 +565,7 @@ def daemon_alive():
 return False, None


def tail_log(n=30):
def tail_log(n=100):
 """Return the last n lines of the daemon log file as a string."""
 if not os.path.exists(LOG_FILE):
 return "(log file not found)"
Expand DownExpand Up@@ -572,46 +609,82 @@ def run_daemon():
 sys.exit(1)

 frequency = settings["frequency"]
 hour = settings["hour"]
 minute = settings["minute"]
 times_of_day = settings["times_of_day"]
 day_of_week = settings["day_of_week"]
 timezone = settings["timezone"]
 run_identify = settings["run_identify"]
 identify_timeout = settings["identify_timeout_minutes"]
 scan_paths = settings.get("scan_paths") or []

 # Build a simple GQL callable for the daemon (not stash.log-based)
 def gql(query, variables=None):
 return call_gql(stash, query, variables)

 def scheduled_job():
 """Fired by APScheduler for each scheduled time slot."""
 log.info("Scheduled scan cycle firing.")
 # Fresh connection each run — guards against stale sessions after a
 # Stash restart.
 try:
 job_id = trigger_scan(log, gql, settings)
 fresh_stash = make_stash(cfg["server_connection"])
 def gql(query, variables=None):
 return call_gql(fresh_stash, query, variables)
 except Exception as exc:
 log.error(f"Scan failed: {exc}")
 log.error(f"Cannot connect to Stash for scheduled scan: {exc}")
 return
 if run_identify:

 # Reload operational settings live from Stash so changes to
 # run_identify, scan_paths, scan flags, etc. take effect immediately
 # without needing to restart the daemon.
 try:
 live_settings = validate_and_coerce_settings(
 get_plugin_settings(fresh_stash),
 lambda m: log.warning(m),
 )
 log.info(
 f"Settings reloaded — identify: {'yes' if live_settings['run_identify'] else 'no'}, "
 f"paths: {', '.join(live_settings.get('scan_paths') or []) or 'full library'}"
 )
 except Exception as exc:
 log.warning(f"Could not reload settings from Stash — using startup settings: {exc}")
 live_settings = settings

 try:
 job_id = trigger_scan(log, gql, live_settings)
 except Exception as exc:
 log.error(f"Scan trigger failed: {exc}")
 return

 if live_settings["run_identify"]:
 live_timeout = live_settings["identify_timeout_minutes"]
 live_paths = live_settings.get("scan_paths") or None
 threading.Thread(
 target=wait_for_scan_and_identify,
 args=(log, gql, job_id, identify_timeout, scan_paths or None),
 args=(log, gql, job_id, live_timeout, live_paths),
 daemon=True,
 ).start()

 def heartbeat_job():
 """Fires every hour so the log shows the daemon is still alive."""
 log.info("[heartbeat] Daemon alive.")

 scheduler = BackgroundScheduler(timezone=timezone)
 job_kwargs = {"func": scheduled_job, "misfire_grace_time": 3600, "coalesce": True}

 times_str = ", ".join(f"{h:02d}:{m:02d}" for h, m in times_of_day)
 if frequency == "hourly":
 scheduler.add_job(trigger="cron", minute=0, **job_kwargs)
 log.info(f"Schedule: every hour at :00 ({timezone})")
 elif frequency == "weekly":
 scheduler.add_job(
 trigger="cron", day_of_week=day_of_week, hour=hour, minute=minute, **job_kwargs
 )
 log.info(f"Schedule: weekly {day_of_week.upper()} at {hour:02d}:{minute:02d} ({timezone})")
 for h, m in times_of_day:
 scheduler.add_job(
 trigger="cron", day_of_week=day_of_week, hour=h, minute=m, **job_kwargs
 )
 log.info(f"Schedule: weekly {day_of_week.upper()} at {times_str} ({timezone})")
 else:
 scheduler.add_job(trigger="cron", hour=hour, minute=minute, **job_kwargs)
 log.info(f"Schedule: daily at {hour:02d}:{minute:02d} ({timezone})")
 for h, m in times_of_day:
 scheduler.add_job(trigger="cron", hour=h, minute=m, **job_kwargs)
 log.info(f"Schedule: daily at {times_str} ({timezone})")

 # Hourly heartbeat so the log proves the daemon is ticking even between scans
 scheduler.add_job(func=heartbeat_job, trigger="cron", minute=0,
 misfire_grace_time=3600, coalesce=True)

 log.info(f"Identify after scan: {'yes' if run_identify else 'no'}")

Expand All@@ -626,7 +699,21 @@ def scheduled_job():
 else:
 log.info("Scan flags: none (bare scan)")

 # Log APScheduler execution errors so silent job failures are visible
 from apscheduler.events import EVENT_JOB_ERROR, EVENT_JOB_EXECUTED, EVENT_JOB_MISSED
 def _aps_listener(event):
 if event.exception:
 log.error(f"[APScheduler] Job {event.job_id} raised an exception: {event.exception}")
 elif hasattr(event, 'scheduled_run_time') and not hasattr(event, 'retval'):
 log.warning(f"[APScheduler] Job {event.job_id} missed its scheduled time.")
 scheduler.add_listener(_aps_listener, EVENT_JOB_ERROR | EVENT_JOB_MISSED)

 scheduler.start()

 # Log next fire times so the log confirms jobs are registered correctly
 for job in scheduler.get_jobs():
 if job.next_run_time:
 log.info(f"Next fire for job '{job.id}': {job.next_run_time}")
 log.info("Daemon is running. Waiting for scheduled events…")

 stop = threading.Event()
Expand DownExpand Up@@ -682,7 +769,13 @@ def gql(query, variables=None):
# ---------------------------------------------------------------------------

def task_start_scheduler(stash, server_connection, settings):
 save_config(server_connection, settings)
 # Inject the API key into the saved connection dict so every daemon GQL
 # request includes it — required when Stash's "Require API key" is enabled.
 conn = dict(server_connection)
 api_key = settings.get("apiKey", "").strip()
 if api_key:
 conn["ApiKey"] = api_key
 save_config(conn, settings)
 kill_existing_daemon()
 launch_detached("--daemon")
 freq = settings["frequency"]
Expand DownExpand Up@@ -727,7 +820,7 @@ def task_run_now(stash, settings, force_identify=False):
def task_check_status(stash):
 alive, pid = daemon_alive()
 status_line = f"Daemon: RUNNING (PID {pid})" if alive else "Daemon: NOT RUNNING"
 recent = tail_log(30)
 recent = tail_log(100)
 output = f"{status_line}\nLog file: {LOG_FILE}\n\nRecent log ({LOG_FILE}):\n{recent}"
 stash.log.info(f"[Stash Scheduler] {status_line}")
 print(json.dumps({"output": output}))
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Force GitHub README to respect dark mode
(function() {
var style = document.createElement('style');
style.textContent = '
.markdown-body {
color-scheme: dark light;
}
.markdown-body pre { background: #161b22 !important; }
.markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }
.markdown-body table th, .markdown-body table td { border-color: #30363d !important; }
.markdown-body img { background: #0d1117; }
.markdown-body blockquote { border-left-color: #8b949e; }
.markdown-body hr { border-color: #30363d; }
';
document.head.appendChild(style);
})();
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
Add API Authentication and additional scan scheduling options by dscisci · Pull Request #711 · stashapp/CommunityScripts · GitHub
Skip to content
Add API Authentication and additional scan scheduling options#711

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Open

dscisci
wants to merge
3
commits into

base:main
Choose a base branch

from

 Open


Add API Authentication and additional scan scheduling options
#711
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


3 commits


Select commit
Hold shift + click to select a range
9b0e6c9

Add files via upload


dscisci May 1, 2026
5ad5f71

Add files via upload


dscisci May 12, 2026
612e9ff

Merge branch 'main' into main


dscisci May 12, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


9 changes: 6 additions & 3 deletions
plugins/stash-scheduler/README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,7 +1,5 @@
# Stash Scheduler Plugin

https://discourse.stashapp.cc/t/stash-scheduler/7059
@DogmaDragonDogmaDragonMay 13, 2026

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Must be retained.

A plugin for [Stash](https://github.com/stashapp/stash) that automatically runs library scans on a schedule (hourly, daily, or weekly), with an optional identify pass after each scan.

---
Expand DownExpand Up@@ -83,8 +81,9 @@ Open **Settings → Plugins → Stash Scheduler** and set your preferences:

| Setting | Description | Default |
|---|---|---|
| **API Key** | Stash API key for authenticating background scans. Required when "Require API key" is enabled in Stash's Security settings. Generate one under Settings > Security > API Keys. Leave blank if Stash does not require authentication. | *(none)* |
| **Scan Frequency** | `hourly`, `daily`, or `weekly` | `daily` |
| **Time of Day (HH:MM)** | Time to run the scan in 24-hour `HH:MM` format. Used by Daily and Weekly; ignored for Hourly. | `02:00` |
| **Time of Day (HH:MM)** | One or more times to run the scan, in 24-hour `HH:MM` format. Separate multiple times with commas or spaces, e.g. `00:00, 06:00, 18:00`. Used by Daily and Weekly; ignored for Hourly. | `02:00` |
| **Day of Week** | Day to scan when Frequency is Weekly. Use `mon`, `tue`, `wed`, `thu`, `fri`, `sat`, or `sun`. | `sun` |
| **Timezone** | IANA timezone name for interpreting Time of Day and Day of Week. Examples: `America/New_York`, `Europe/London`, `Asia/Tokyo`. Leave blank for UTC. | `UTC` |
| **Run Identify After Scan** | When enabled, runs an Identify task after each scan finishes successfully. | `false` |
Expand DownExpand Up@@ -296,6 +295,10 @@ All activity is written to the Stash log. To view it:

| Version | Notes |
|---|---|
| 0.10.0 | Added API Key setting — required when Stash's "Require API key" security option is enabled |
| 0.9.0 | Daemon now reloads settings from Stash on every scheduled run — changes to identify, paths, and scan flags take effect without restarting the scheduler |
| 0.8.0 | Fixed identify not running after scan (null fields in GraphQL input); fixed daemon losing Stash connection after restart; added APScheduler error logging, hourly heartbeat, and next-fire-time logging; Check Status now shows 100 log lines |
| 0.7.0 | Time of Day now accepts multiple times (comma or space separated) — each fires a separate scheduled scan |
| 0.6.0 | Added "Limit to Paths" setting — scan and identify can now be restricted to specific directories |
| 0.5.0 | Fixed identify-after-scan (null jobQueue crash); added 9 scan generation flag settings (covers, previews, sprites, phashes, thumbnails, clip previews, force rescan) |
| 0.4.0 | Added Check Status task; daemon logs written to file (`/tmp/stash-scheduler-daemon.log`) |
Expand Down

21 changes: 16 additions & 5 deletions
plugins/stash-scheduler/stash-scheduler.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
name: Stash Scheduler
description: Schedule automatic library scans with an optional identify pass after each scan.
version: "0.6.0"
url: https://discourse.stashapp.cc/t/stash-scheduler/7059
@DogmaDragonDogmaDragonMay 13, 2026

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Must be retained.
version: "0.10.0"
url: https://github.com/stashapp/stash

exec:
 - python3
Expand DownExpand Up@@ -42,6 +42,16 @@ tasks:
 mode: check_status

settings:
 apiKey:
@DogmaDragonDogmaDragonMay 13, 2026

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why not just check for authentication and get the API key from configuration query using GraphQL if it's available?
 displayName: API Key
 description: >
 Stash API key for authenticating background scans. Required when
 Settings > Security > "Require API key for local connections" is enabled,
 or when accessing Stash over a network. Generate a key under
 Settings > Security > API Keys, then paste it here. Leave blank if
 Stash does not require authentication.
 type: STRING

 frequency:
 displayName: Scan Frequency
 description: >
Expand All@@ -53,9 +63,10 @@ settings:
 time_of_day:
 displayName: Time of Day (HH:MM)
 description: >
 The time to run the scan in 24-hour HH:MM format. Used for Daily and
 Weekly schedules; ignored for Hourly. Examples: 02:00, 14:30, 20:45.
 Defaults to 02:00 if not set.
 One or more times to run the scan in 24-hour HH:MM format. Used for
 Daily and Weekly schedules; ignored for Hourly. Separate multiple times
 with commas or spaces. Examples: 02:00 — single daily run. 00:00, 06:00,
 09:00, 16:00, 18:00 — five runs per day. Defaults to 02:00 if not set.
 type: STRING

 day_of_week:
Expand Down

153 changes: 123 additions & 30 deletions
plugins/stash-scheduler/stash_scheduler.py

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -142,6 +142,7 @@ def get_plugin_settings(stash, plugin_id="stash-scheduler"):
 "time_of_day": "02:00",
 "day_of_week": "sun",
 "timezone": "UTC",
 "apiKey": "",
 "run_identify": False,
 "identify_timeout_minutes": 120,
 # Comma- or newline-separated list of paths to restrict scan + identify.
Expand All@@ -168,19 +169,38 @@ def get_plugin_settings(stash, plugin_id="stash-scheduler"):
 return defaults


def _parse_time_of_day(raw, warn):
 raw = str(raw).strip()
def _parse_single_time(token, warn):
 """Parse one HH:MM token. Returns (hour, minute) or None on error."""
 token = str(token).strip()
 try:
 parts = raw.split(":")
 parts = token.split(":")
 if len(parts) != 2:
 raise ValueError("expected HH:MM")
 hh, mm = int(parts[0]), int(parts[1])
 if not (0 <= hh <= 23 and 0 <= mm <= 59):
 raise ValueError(f"values out of range: {hh}:{mm:02d}")
 return hh, mm
 except (ValueError, TypeError) as exc:
 warn(f"[Stash Scheduler] Invalid time_of_day {raw!r} ({exc}) — defaulting to 02:00.")
 return 2, 0
 warn(f"[Stash Scheduler] Invalid time {token!r} ({exc}) — skipping.")
 return None


def _parse_times_of_day(raw, warn):
 """Parse comma/space/newline-separated HH:MM times.
 Returns a deduplicated list of (hour, minute) tuples, sorted ascending.
 Falls back to [(2, 0)] if nothing valid is found."""
 import re as _re
 tokens = [t for t in _re.split(r"[\s,]+", str(raw).strip()) if t]
 results, seen = [], set()
 for token in tokens:
 parsed = _parse_single_time(token, warn)
 if parsed is not None and parsed not in seen:
 results.append(parsed)
 seen.add(parsed)
 if not results:
 warn("[Stash Scheduler] No valid times found in time_of_day — defaulting to 02:00.")
 return [(2, 0)]
 return sorted(results)


def validate_and_coerce_settings(settings, warn):
Expand All@@ -194,10 +214,11 @@ def validate_and_coerce_settings(settings, warn):
 settings["frequency"] = freq

 raw_time = settings.get("time_of_day", "02:00")
 hour, minute = _parse_time_of_day(raw_time, warn)
 settings["time_of_day"] = f"{hour:02d}:{minute:02d}"
 settings["hour"] = hour
 settings["minute"] = minute
 times = _parse_times_of_day(raw_time, warn)
 settings["times_of_day"] = times
 settings["time_of_day"] = ", ".join(f"{h:02d}:{m:02d}" for h, m in times)
 settings["hour"] = times[0][0]
 settings["minute"] = times[0][1]

 dow = str(settings.get("day_of_week", "sun")).strip().lower()
 if dow not in VALID_DAYS:
Expand DownExpand Up@@ -233,6 +254,9 @@ def validate_and_coerce_settings(settings, warn):
 tz_raw = "UTC"
 settings["timezone"] = tz_raw

 # apiKey — strip whitespace; empty string means no key (session auth)
 settings["apiKey"] = str(settings.get("apiKey", "") or "").strip()

 # scanPaths — parse comma/newline-separated string into a clean list
 raw_paths = str(settings.get("scanPaths", "") or "")
 import re as _re
Expand All@@ -254,6 +278,16 @@ def validate_and_coerce_settings(settings, warn):
# Scan / Identify helpers (used by both plugin tasks and the daemon)
# ---------------------------------------------------------------------------

def _strip_nulls(obj):
 """Recursively remove None/null values from a dict or list.
 Required before forwarding a GraphQL query result back as mutation input —
 Stash rejects null on required sub-fields."""
 if isinstance(obj, dict):
 return {k: _strip_nulls(v) for k, v in obj.items() if v is not None}
 if isinstance(obj, list):
 return [_strip_nulls(i) for i in obj]
 return obj

_SCAN_FLAGS = (
 "scanGenerateCovers",
 "scanGeneratePreviews",
Expand DownExpand Up@@ -333,9 +367,12 @@ def trigger_identify(stash_or_log, gql_fn, paths=None):
 paths_desc = f" (paths: {', '.join(paths)})" if paths else " (full library)"
 _log_info(stash_or_log, f"[Stash Scheduler] Triggering identify task{paths_desc}…")
 try:
 identify_input = {"sources": identify["sources"]}
 # Strip nulls: the query returns the full schema object including null
 # sub-fields; forwarding those nulls into the mutation causes Stash to
 # reject the request with a schema validation error.
 identify_input = {"sources": _strip_nulls(identify["sources"])}
 if identify.get("options"):
 identify_input["options"] = identify["options"]
 identify_input["options"] = _strip_nulls(identify["options"])
 if paths:
 identify_input["paths"] = paths
 result = gql_fn(IDENTIFY_MUTATION, {"input": identify_input})
Expand DownExpand Up@@ -528,7 +565,7 @@ def daemon_alive():
 return False, None


def tail_log(n=30):
def tail_log(n=100):
 """Return the last n lines of the daemon log file as a string."""
 if not os.path.exists(LOG_FILE):
 return "(log file not found)"
Expand DownExpand Up@@ -572,46 +609,82 @@ def run_daemon():
 sys.exit(1)

 frequency = settings["frequency"]
 hour = settings["hour"]
 minute = settings["minute"]
 times_of_day = settings["times_of_day"]
 day_of_week = settings["day_of_week"]
 timezone = settings["timezone"]
 run_identify = settings["run_identify"]
 identify_timeout = settings["identify_timeout_minutes"]
 scan_paths = settings.get("scan_paths") or []

 # Build a simple GQL callable for the daemon (not stash.log-based)
 def gql(query, variables=None):
 return call_gql(stash, query, variables)

 def scheduled_job():
 """Fired by APScheduler for each scheduled time slot."""
 log.info("Scheduled scan cycle firing.")
 # Fresh connection each run — guards against stale sessions after a
 # Stash restart.
 try:
 job_id = trigger_scan(log, gql, settings)
 fresh_stash = make_stash(cfg["server_connection"])
 def gql(query, variables=None):
 return call_gql(fresh_stash, query, variables)
 except Exception as exc:
 log.error(f"Scan failed: {exc}")
 log.error(f"Cannot connect to Stash for scheduled scan: {exc}")
 return
 if run_identify:

 # Reload operational settings live from Stash so changes to
 # run_identify, scan_paths, scan flags, etc. take effect immediately
 # without needing to restart the daemon.
 try:
 live_settings = validate_and_coerce_settings(
 get_plugin_settings(fresh_stash),
 lambda m: log.warning(m),
 )
 log.info(
 f"Settings reloaded — identify: {'yes' if live_settings['run_identify'] else 'no'}, "
 f"paths: {', '.join(live_settings.get('scan_paths') or []) or 'full library'}"
 )
 except Exception as exc:
 log.warning(f"Could not reload settings from Stash — using startup settings: {exc}")
 live_settings = settings

 try:
 job_id = trigger_scan(log, gql, live_settings)
 except Exception as exc:
 log.error(f"Scan trigger failed: {exc}")
 return

 if live_settings["run_identify"]:
 live_timeout = live_settings["identify_timeout_minutes"]
 live_paths = live_settings.get("scan_paths") or None
 threading.Thread(
 target=wait_for_scan_and_identify,
 args=(log, gql, job_id, identify_timeout, scan_paths or None),
 args=(log, gql, job_id, live_timeout, live_paths),
 daemon=True,
 ).start()

 def heartbeat_job():
 """Fires every hour so the log shows the daemon is still alive."""
 log.info("[heartbeat] Daemon alive.")

 scheduler = BackgroundScheduler(timezone=timezone)
 job_kwargs = {"func": scheduled_job, "misfire_grace_time": 3600, "coalesce": True}

 times_str = ", ".join(f"{h:02d}:{m:02d}" for h, m in times_of_day)
 if frequency == "hourly":
 scheduler.add_job(trigger="cron", minute=0, **job_kwargs)
 log.info(f"Schedule: every hour at :00 ({timezone})")
 elif frequency == "weekly":
 scheduler.add_job(
 trigger="cron", day_of_week=day_of_week, hour=hour, minute=minute, **job_kwargs
 )
 log.info(f"Schedule: weekly {day_of_week.upper()} at {hour:02d}:{minute:02d} ({timezone})")
 for h, m in times_of_day:
 scheduler.add_job(
 trigger="cron", day_of_week=day_of_week, hour=h, minute=m, **job_kwargs
 )
 log.info(f"Schedule: weekly {day_of_week.upper()} at {times_str} ({timezone})")
 else:
 scheduler.add_job(trigger="cron", hour=hour, minute=minute, **job_kwargs)
 log.info(f"Schedule: daily at {hour:02d}:{minute:02d} ({timezone})")
 for h, m in times_of_day:
 scheduler.add_job(trigger="cron", hour=h, minute=m, **job_kwargs)
 log.info(f"Schedule: daily at {times_str} ({timezone})")

 # Hourly heartbeat so the log proves the daemon is ticking even between scans
 scheduler.add_job(func=heartbeat_job, trigger="cron", minute=0,
 misfire_grace_time=3600, coalesce=True)

 log.info(f"Identify after scan: {'yes' if run_identify else 'no'}")

Expand All@@ -626,7 +699,21 @@ def scheduled_job():
 else:
 log.info("Scan flags: none (bare scan)")

 # Log APScheduler execution errors so silent job failures are visible
 from apscheduler.events import EVENT_JOB_ERROR, EVENT_JOB_EXECUTED, EVENT_JOB_MISSED
 def _aps_listener(event):
 if event.exception:
 log.error(f"[APScheduler] Job {event.job_id} raised an exception: {event.exception}")
 elif hasattr(event, 'scheduled_run_time') and not hasattr(event, 'retval'):
 log.warning(f"[APScheduler] Job {event.job_id} missed its scheduled time.")
 scheduler.add_listener(_aps_listener, EVENT_JOB_ERROR | EVENT_JOB_MISSED)

 scheduler.start()

 # Log next fire times so the log confirms jobs are registered correctly
 for job in scheduler.get_jobs():
 if job.next_run_time:
 log.info(f"Next fire for job '{job.id}': {job.next_run_time}")
 log.info("Daemon is running. Waiting for scheduled events…")

 stop = threading.Event()
Expand DownExpand Up@@ -682,7 +769,13 @@ def gql(query, variables=None):
# ---------------------------------------------------------------------------

def task_start_scheduler(stash, server_connection, settings):
 save_config(server_connection, settings)
 # Inject the API key into the saved connection dict so every daemon GQL
 # request includes it — required when Stash's "Require API key" is enabled.
 conn = dict(server_connection)
 api_key = settings.get("apiKey", "").strip()
 if api_key:
 conn["ApiKey"] = api_key
 save_config(conn, settings)
 kill_existing_daemon()
 launch_detached("--daemon")
 freq = settings["frequency"]
Expand DownExpand Up@@ -727,7 +820,7 @@ def task_run_now(stash, settings, force_identify=False):
def task_check_status(stash):
 alive, pid = daemon_alive()
 status_line = f"Daemon: RUNNING (PID {pid})" if alive else "Daemon: NOT RUNNING"
 recent = tail_log(30)
 recent = tail_log(100)
 output = f"{status_line}\nLog file: {LOG_FILE}\n\nRecent log ({LOG_FILE}):\n{recent}"
 stash.log.info(f"[Stash Scheduler] {status_line}")
 print(json.dumps({"output": output}))
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Highlight search terms from Google/DuckDuckGo/Bing referrer
(function() {
var ref = document.referrer;
var terms = [];
if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {
var url = new URL(ref);
var q = url.searchParams.get('q') || url.searchParams.get('p');
if (q) {
terms = q.split(/\s+/).filter(function(t) { return t.length > 2; });
}
}
if (terms.length === 0) return;
var style = document.createElement('style');
style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';
document.head.appendChild(style);
function highlight(node) {
if (node.nodeType === 3) { // text node
var text = node.textContent;
var found = false;
terms.forEach(function(term) {
var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\]\\]/g, '\\') + ')', 'gi');
if (regex.test(text)) {
found = true;
var frag = document.createDocumentFragment();
var parts = text.split(regex);
parts.forEach(function(part, i) {
if (i % 2 === 0) {
frag.appendChild(document.createTextNode(part));
} else {
var span = document.createElement('span');
span.className = 'userscript-highlight';
span.textContent = part;
frag.appendChild(span);
}
});
node.parentNode.replaceChild(frag, node);
}
});
} else if (node.nodeType === 1 && node.childNodes) { // element
var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];
if (!skipTags.includes(node.tagName)) {
Array.from(node.childNodes).forEach(highlight);
}
}
}
highlight(document.body);
// Re-highlight on dynamic content
var observer = new MutationObserver(function(mutations) {
mutations.forEach(function(m) {
m.addedNodes.forEach(function(node) {
if (node.nodeType === 1 || node.nodeType === 3) highlight(node);
});
});
});
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
Add API Authentication and additional scan scheduling options by dscisci · Pull Request #711 · stashapp/CommunityScripts · GitHub
Skip to content
Add API Authentication and additional scan scheduling options#711

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Open

dscisci
wants to merge
3
commits into

base:main
Choose a base branch

from

 Open


Add API Authentication and additional scan scheduling options
#711
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


3 commits


Select commit
Hold shift + click to select a range
9b0e6c9

Add files via upload


dscisci May 1, 2026
5ad5f71

Add files via upload


dscisci May 12, 2026
612e9ff

Merge branch 'main' into main


dscisci May 12, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


9 changes: 6 additions & 3 deletions
plugins/stash-scheduler/README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,7 +1,5 @@
# Stash Scheduler Plugin

https://discourse.stashapp.cc/t/stash-scheduler/7059
@DogmaDragonDogmaDragonMay 13, 2026

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Must be retained.

A plugin for [Stash](https://github.com/stashapp/stash) that automatically runs library scans on a schedule (hourly, daily, or weekly), with an optional identify pass after each scan.

---
Expand DownExpand Up@@ -83,8 +81,9 @@ Open **Settings → Plugins → Stash Scheduler** and set your preferences:

| Setting | Description | Default |
|---|---|---|
| **API Key** | Stash API key for authenticating background scans. Required when "Require API key" is enabled in Stash's Security settings. Generate one under Settings > Security > API Keys. Leave blank if Stash does not require authentication. | *(none)* |
| **Scan Frequency** | `hourly`, `daily`, or `weekly` | `daily` |
| **Time of Day (HH:MM)** | Time to run the scan in 24-hour `HH:MM` format. Used by Daily and Weekly; ignored for Hourly. | `02:00` |
| **Time of Day (HH:MM)** | One or more times to run the scan, in 24-hour `HH:MM` format. Separate multiple times with commas or spaces, e.g. `00:00, 06:00, 18:00`. Used by Daily and Weekly; ignored for Hourly. | `02:00` |
| **Day of Week** | Day to scan when Frequency is Weekly. Use `mon`, `tue`, `wed`, `thu`, `fri`, `sat`, or `sun`. | `sun` |
| **Timezone** | IANA timezone name for interpreting Time of Day and Day of Week. Examples: `America/New_York`, `Europe/London`, `Asia/Tokyo`. Leave blank for UTC. | `UTC` |
| **Run Identify After Scan** | When enabled, runs an Identify task after each scan finishes successfully. | `false` |
Expand DownExpand Up@@ -296,6 +295,10 @@ All activity is written to the Stash log. To view it:

| Version | Notes |
|---|---|
| 0.10.0 | Added API Key setting — required when Stash's "Require API key" security option is enabled |
| 0.9.0 | Daemon now reloads settings from Stash on every scheduled run — changes to identify, paths, and scan flags take effect without restarting the scheduler |
| 0.8.0 | Fixed identify not running after scan (null fields in GraphQL input); fixed daemon losing Stash connection after restart; added APScheduler error logging, hourly heartbeat, and next-fire-time logging; Check Status now shows 100 log lines |
| 0.7.0 | Time of Day now accepts multiple times (comma or space separated) — each fires a separate scheduled scan |
| 0.6.0 | Added "Limit to Paths" setting — scan and identify can now be restricted to specific directories |
| 0.5.0 | Fixed identify-after-scan (null jobQueue crash); added 9 scan generation flag settings (covers, previews, sprites, phashes, thumbnails, clip previews, force rescan) |
| 0.4.0 | Added Check Status task; daemon logs written to file (`/tmp/stash-scheduler-daemon.log`) |
Expand Down

21 changes: 16 additions & 5 deletions
plugins/stash-scheduler/stash-scheduler.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
name: Stash Scheduler
description: Schedule automatic library scans with an optional identify pass after each scan.
version: "0.6.0"
url: https://discourse.stashapp.cc/t/stash-scheduler/7059
@DogmaDragonDogmaDragonMay 13, 2026

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Must be retained.
version: "0.10.0"
url: https://github.com/stashapp/stash

exec:
 - python3
Expand DownExpand Up@@ -42,6 +42,16 @@ tasks:
 mode: check_status

settings:
 apiKey:
@DogmaDragonDogmaDragonMay 13, 2026

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why not just check for authentication and get the API key from configuration query using GraphQL if it's available?
 displayName: API Key
 description: >
 Stash API key for authenticating background scans. Required when
 Settings > Security > "Require API key for local connections" is enabled,
 or when accessing Stash over a network. Generate a key under
 Settings > Security > API Keys, then paste it here. Leave blank if
 Stash does not require authentication.
 type: STRING

 frequency:
 displayName: Scan Frequency
 description: >
Expand All@@ -53,9 +63,10 @@ settings:
 time_of_day:
 displayName: Time of Day (HH:MM)
 description: >
 The time to run the scan in 24-hour HH:MM format. Used for Daily and
 Weekly schedules; ignored for Hourly. Examples: 02:00, 14:30, 20:45.
 Defaults to 02:00 if not set.
 One or more times to run the scan in 24-hour HH:MM format. Used for
 Daily and Weekly schedules; ignored for Hourly. Separate multiple times
 with commas or spaces. Examples: 02:00 — single daily run. 00:00, 06:00,
 09:00, 16:00, 18:00 — five runs per day. Defaults to 02:00 if not set.
 type: STRING

 day_of_week:
Expand Down

153 changes: 123 additions & 30 deletions
plugins/stash-scheduler/stash_scheduler.py

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -142,6 +142,7 @@ def get_plugin_settings(stash, plugin_id="stash-scheduler"):
 "time_of_day": "02:00",
 "day_of_week": "sun",
 "timezone": "UTC",
 "apiKey": "",
 "run_identify": False,
 "identify_timeout_minutes": 120,
 # Comma- or newline-separated list of paths to restrict scan + identify.
Expand All@@ -168,19 +169,38 @@ def get_plugin_settings(stash, plugin_id="stash-scheduler"):
 return defaults


def _parse_time_of_day(raw, warn):
 raw = str(raw).strip()
def _parse_single_time(token, warn):
 """Parse one HH:MM token. Returns (hour, minute) or None on error."""
 token = str(token).strip()
 try:
 parts = raw.split(":")
 parts = token.split(":")
 if len(parts) != 2:
 raise ValueError("expected HH:MM")
 hh, mm = int(parts[0]), int(parts[1])
 if not (0 <= hh <= 23 and 0 <= mm <= 59):
 raise ValueError(f"values out of range: {hh}:{mm:02d}")
 return hh, mm
 except (ValueError, TypeError) as exc:
 warn(f"[Stash Scheduler] Invalid time_of_day {raw!r} ({exc}) — defaulting to 02:00.")
 return 2, 0
 warn(f"[Stash Scheduler] Invalid time {token!r} ({exc}) — skipping.")
 return None


def _parse_times_of_day(raw, warn):
 """Parse comma/space/newline-separated HH:MM times.
 Returns a deduplicated list of (hour, minute) tuples, sorted ascending.
 Falls back to [(2, 0)] if nothing valid is found."""
 import re as _re
 tokens = [t for t in _re.split(r"[\s,]+", str(raw).strip()) if t]
 results, seen = [], set()
 for token in tokens:
 parsed = _parse_single_time(token, warn)
 if parsed is not None and parsed not in seen:
 results.append(parsed)
 seen.add(parsed)
 if not results:
 warn("[Stash Scheduler] No valid times found in time_of_day — defaulting to 02:00.")
 return [(2, 0)]
 return sorted(results)


def validate_and_coerce_settings(settings, warn):
Expand All@@ -194,10 +214,11 @@ def validate_and_coerce_settings(settings, warn):
 settings["frequency"] = freq

 raw_time = settings.get("time_of_day", "02:00")
 hour, minute = _parse_time_of_day(raw_time, warn)
 settings["time_of_day"] = f"{hour:02d}:{minute:02d}"
 settings["hour"] = hour
 settings["minute"] = minute
 times = _parse_times_of_day(raw_time, warn)
 settings["times_of_day"] = times
 settings["time_of_day"] = ", ".join(f"{h:02d}:{m:02d}" for h, m in times)
 settings["hour"] = times[0][0]
 settings["minute"] = times[0][1]

 dow = str(settings.get("day_of_week", "sun")).strip().lower()
 if dow not in VALID_DAYS:
Expand DownExpand Up@@ -233,6 +254,9 @@ def validate_and_coerce_settings(settings, warn):
 tz_raw = "UTC"
 settings["timezone"] = tz_raw

 # apiKey — strip whitespace; empty string means no key (session auth)
 settings["apiKey"] = str(settings.get("apiKey", "") or "").strip()

 # scanPaths — parse comma/newline-separated string into a clean list
 raw_paths = str(settings.get("scanPaths", "") or "")
 import re as _re
Expand All@@ -254,6 +278,16 @@ def validate_and_coerce_settings(settings, warn):
# Scan / Identify helpers (used by both plugin tasks and the daemon)
# ---------------------------------------------------------------------------

def _strip_nulls(obj):
 """Recursively remove None/null values from a dict or list.
 Required before forwarding a GraphQL query result back as mutation input —
 Stash rejects null on required sub-fields."""
 if isinstance(obj, dict):
 return {k: _strip_nulls(v) for k, v in obj.items() if v is not None}
 if isinstance(obj, list):
 return [_strip_nulls(i) for i in obj]
 return obj

_SCAN_FLAGS = (
 "scanGenerateCovers",
 "scanGeneratePreviews",
Expand DownExpand Up@@ -333,9 +367,12 @@ def trigger_identify(stash_or_log, gql_fn, paths=None):
 paths_desc = f" (paths: {', '.join(paths)})" if paths else " (full library)"
 _log_info(stash_or_log, f"[Stash Scheduler] Triggering identify task{paths_desc}…")
 try:
 identify_input = {"sources": identify["sources"]}
 # Strip nulls: the query returns the full schema object including null
 # sub-fields; forwarding those nulls into the mutation causes Stash to
 # reject the request with a schema validation error.
 identify_input = {"sources": _strip_nulls(identify["sources"])}
 if identify.get("options"):
 identify_input["options"] = identify["options"]
 identify_input["options"] = _strip_nulls(identify["options"])
 if paths:
 identify_input["paths"] = paths
 result = gql_fn(IDENTIFY_MUTATION, {"input": identify_input})
Expand DownExpand Up@@ -528,7 +565,7 @@ def daemon_alive():
 return False, None


def tail_log(n=30):
def tail_log(n=100):
 """Return the last n lines of the daemon log file as a string."""
 if not os.path.exists(LOG_FILE):
 return "(log file not found)"
Expand DownExpand Up@@ -572,46 +609,82 @@ def run_daemon():
 sys.exit(1)

 frequency = settings["frequency"]
 hour = settings["hour"]
 minute = settings["minute"]
 times_of_day = settings["times_of_day"]
 day_of_week = settings["day_of_week"]
 timezone = settings["timezone"]
 run_identify = settings["run_identify"]
 identify_timeout = settings["identify_timeout_minutes"]
 scan_paths = settings.get("scan_paths") or []

 # Build a simple GQL callable for the daemon (not stash.log-based)
 def gql(query, variables=None):
 return call_gql(stash, query, variables)

 def scheduled_job():
 """Fired by APScheduler for each scheduled time slot."""
 log.info("Scheduled scan cycle firing.")
 # Fresh connection each run — guards against stale sessions after a
 # Stash restart.
 try:
 job_id = trigger_scan(log, gql, settings)
 fresh_stash = make_stash(cfg["server_connection"])
 def gql(query, variables=None):
 return call_gql(fresh_stash, query, variables)
 except Exception as exc:
 log.error(f"Scan failed: {exc}")
 log.error(f"Cannot connect to Stash for scheduled scan: {exc}")
 return
 if run_identify:

 # Reload operational settings live from Stash so changes to
 # run_identify, scan_paths, scan flags, etc. take effect immediately
 # without needing to restart the daemon.
 try:
 live_settings = validate_and_coerce_settings(
 get_plugin_settings(fresh_stash),
 lambda m: log.warning(m),
 )
 log.info(
 f"Settings reloaded — identify: {'yes' if live_settings['run_identify'] else 'no'}, "
 f"paths: {', '.join(live_settings.get('scan_paths') or []) or 'full library'}"
 )
 except Exception as exc:
 log.warning(f"Could not reload settings from Stash — using startup settings: {exc}")
 live_settings = settings

 try:
 job_id = trigger_scan(log, gql, live_settings)
 except Exception as exc:
 log.error(f"Scan trigger failed: {exc}")
 return

 if live_settings["run_identify"]:
 live_timeout = live_settings["identify_timeout_minutes"]
 live_paths = live_settings.get("scan_paths") or None
 threading.Thread(
 target=wait_for_scan_and_identify,
 args=(log, gql, job_id, identify_timeout, scan_paths or None),
 args=(log, gql, job_id, live_timeout, live_paths),
 daemon=True,
 ).start()

 def heartbeat_job():
 """Fires every hour so the log shows the daemon is still alive."""
 log.info("[heartbeat] Daemon alive.")

 scheduler = BackgroundScheduler(timezone=timezone)
 job_kwargs = {"func": scheduled_job, "misfire_grace_time": 3600, "coalesce": True}

 times_str = ", ".join(f"{h:02d}:{m:02d}" for h, m in times_of_day)
 if frequency == "hourly":
 scheduler.add_job(trigger="cron", minute=0, **job_kwargs)
 log.info(f"Schedule: every hour at :00 ({timezone})")
 elif frequency == "weekly":
 scheduler.add_job(
 trigger="cron", day_of_week=day_of_week, hour=hour, minute=minute, **job_kwargs
 )
 log.info(f"Schedule: weekly {day_of_week.upper()} at {hour:02d}:{minute:02d} ({timezone})")
 for h, m in times_of_day:
 scheduler.add_job(
 trigger="cron", day_of_week=day_of_week, hour=h, minute=m, **job_kwargs
 )
 log.info(f"Schedule: weekly {day_of_week.upper()} at {times_str} ({timezone})")
 else:
 scheduler.add_job(trigger="cron", hour=hour, minute=minute, **job_kwargs)
 log.info(f"Schedule: daily at {hour:02d}:{minute:02d} ({timezone})")
 for h, m in times_of_day:
 scheduler.add_job(trigger="cron", hour=h, minute=m, **job_kwargs)
 log.info(f"Schedule: daily at {times_str} ({timezone})")

 # Hourly heartbeat so the log proves the daemon is ticking even between scans
 scheduler.add_job(func=heartbeat_job, trigger="cron", minute=0,
 misfire_grace_time=3600, coalesce=True)

 log.info(f"Identify after scan: {'yes' if run_identify else 'no'}")

Expand All@@ -626,7 +699,21 @@ def scheduled_job():
 else:
 log.info("Scan flags: none (bare scan)")

 # Log APScheduler execution errors so silent job failures are visible
 from apscheduler.events import EVENT_JOB_ERROR, EVENT_JOB_EXECUTED, EVENT_JOB_MISSED
 def _aps_listener(event):
 if event.exception:
 log.error(f"[APScheduler] Job {event.job_id} raised an exception: {event.exception}")
 elif hasattr(event, 'scheduled_run_time') and not hasattr(event, 'retval'):
 log.warning(f"[APScheduler] Job {event.job_id} missed its scheduled time.")
 scheduler.add_listener(_aps_listener, EVENT_JOB_ERROR | EVENT_JOB_MISSED)

 scheduler.start()

 # Log next fire times so the log confirms jobs are registered correctly
 for job in scheduler.get_jobs():
 if job.next_run_time:
 log.info(f"Next fire for job '{job.id}': {job.next_run_time}")
 log.info("Daemon is running. Waiting for scheduled events…")

 stop = threading.Event()
Expand DownExpand Up@@ -682,7 +769,13 @@ def gql(query, variables=None):
# ---------------------------------------------------------------------------

def task_start_scheduler(stash, server_connection, settings):
 save_config(server_connection, settings)
 # Inject the API key into the saved connection dict so every daemon GQL
 # request includes it — required when Stash's "Require API key" is enabled.
 conn = dict(server_connection)
 api_key = settings.get("apiKey", "").strip()
 if api_key:
 conn["ApiKey"] = api_key
 save_config(conn, settings)
 kill_existing_daemon()
 launch_detached("--daemon")
 freq = settings["frequency"]
Expand DownExpand Up@@ -727,7 +820,7 @@ def task_run_now(stash, settings, force_identify=False):
def task_check_status(stash):
 alive, pid = daemon_alive()
 status_line = f"Daemon: RUNNING (PID {pid})" if alive else "Daemon: NOT RUNNING"
 recent = tail_log(30)
 recent = tail_log(100)
 output = f"{status_line}\nLog file: {LOG_FILE}\n\nRecent log ({LOG_FILE}):\n{recent}"
 stash.log.info(f"[Stash Scheduler] {status_line}")
 print(json.dumps({"output": output}))
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Strip utm_, fbclid, gclid, etc. from all links on page
(function() {
var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',
'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',
'ref', 'ref_src', 'source', 'medium', 'campaign'];
function cleanUrl(url) {
try {
var u = new URL(url, window.location.origin);
var changed = false;
trackingParams.forEach(function(p) {
if (u.searchParams.has(p)) {
u.searchParams.delete(p);
changed = true;
}
});
return changed ? u.toString() : url;
} catch (e) {
return url;
}
}
function cleanLinks() {
document.querySelectorAll('a[href]').forEach(function(a) {
var clean = cleanUrl(a.href);
if (clean !== a.href) a.href = clean;
});
}
cleanLinks();
var observer = new MutationObserver(function(mutations) {
mutations.forEach(function(m) {
m.addedNodes.forEach(function(node) {
if (node.nodeType === 1) {
if (node.tagName === 'A') cleanLinks();
node.querySelectorAll('a[href]').forEach(function(a) {
var clean = cleanUrl(a.href);
if (clean !== a.href) a.href = clean;
});
}
});
});
});
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '
Add API Authentication and additional scan scheduling options by dscisci · Pull Request #711 · stashapp/CommunityScripts · GitHub
Skip to content
Add API Authentication and additional scan scheduling options#711

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Open

dscisci
wants to merge
3
commits into

base:main
Choose a base branch

from

 Open


Add API Authentication and additional scan scheduling options
#711
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


3 commits


Select commit
Hold shift + click to select a range
9b0e6c9

Add files via upload


dscisci May 1, 2026
5ad5f71

Add files via upload


dscisci May 12, 2026
612e9ff

Merge branch 'main' into main


dscisci May 12, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


9 changes: 6 additions & 3 deletions
plugins/stash-scheduler/README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,7 +1,5 @@
# Stash Scheduler Plugin

https://discourse.stashapp.cc/t/stash-scheduler/7059
@DogmaDragonDogmaDragonMay 13, 2026

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Must be retained.

A plugin for [Stash](https://github.com/stashapp/stash) that automatically runs library scans on a schedule (hourly, daily, or weekly), with an optional identify pass after each scan.

---
Expand DownExpand Up@@ -83,8 +81,9 @@ Open **Settings → Plugins → Stash Scheduler** and set your preferences:

| Setting | Description | Default |
|---|---|---|
| **API Key** | Stash API key for authenticating background scans. Required when "Require API key" is enabled in Stash's Security settings. Generate one under Settings > Security > API Keys. Leave blank if Stash does not require authentication. | *(none)* |
| **Scan Frequency** | `hourly`, `daily`, or `weekly` | `daily` |
| **Time of Day (HH:MM)** | Time to run the scan in 24-hour `HH:MM` format. Used by Daily and Weekly; ignored for Hourly. | `02:00` |
| **Time of Day (HH:MM)** | One or more times to run the scan, in 24-hour `HH:MM` format. Separate multiple times with commas or spaces, e.g. `00:00, 06:00, 18:00`. Used by Daily and Weekly; ignored for Hourly. | `02:00` |
| **Day of Week** | Day to scan when Frequency is Weekly. Use `mon`, `tue`, `wed`, `thu`, `fri`, `sat`, or `sun`. | `sun` |
| **Timezone** | IANA timezone name for interpreting Time of Day and Day of Week. Examples: `America/New_York`, `Europe/London`, `Asia/Tokyo`. Leave blank for UTC. | `UTC` |
| **Run Identify After Scan** | When enabled, runs an Identify task after each scan finishes successfully. | `false` |
Expand DownExpand Up@@ -296,6 +295,10 @@ All activity is written to the Stash log. To view it:

| Version | Notes |
|---|---|
| 0.10.0 | Added API Key setting — required when Stash's "Require API key" security option is enabled |
| 0.9.0 | Daemon now reloads settings from Stash on every scheduled run — changes to identify, paths, and scan flags take effect without restarting the scheduler |
| 0.8.0 | Fixed identify not running after scan (null fields in GraphQL input); fixed daemon losing Stash connection after restart; added APScheduler error logging, hourly heartbeat, and next-fire-time logging; Check Status now shows 100 log lines |
| 0.7.0 | Time of Day now accepts multiple times (comma or space separated) — each fires a separate scheduled scan |
| 0.6.0 | Added "Limit to Paths" setting — scan and identify can now be restricted to specific directories |
| 0.5.0 | Fixed identify-after-scan (null jobQueue crash); added 9 scan generation flag settings (covers, previews, sprites, phashes, thumbnails, clip previews, force rescan) |
| 0.4.0 | Added Check Status task; daemon logs written to file (`/tmp/stash-scheduler-daemon.log`) |
Expand Down

21 changes: 16 additions & 5 deletions
plugins/stash-scheduler/stash-scheduler.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
name: Stash Scheduler
description: Schedule automatic library scans with an optional identify pass after each scan.
version: "0.6.0"
url: https://discourse.stashapp.cc/t/stash-scheduler/7059
@DogmaDragonDogmaDragonMay 13, 2026

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Must be retained.
version: "0.10.0"
url: https://github.com/stashapp/stash

exec:
 - python3
Expand DownExpand Up@@ -42,6 +42,16 @@ tasks:
 mode: check_status

settings:
 apiKey:
@DogmaDragonDogmaDragonMay 13, 2026

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why not just check for authentication and get the API key from configuration query using GraphQL if it's available?
 displayName: API Key
 description: >
 Stash API key for authenticating background scans. Required when
 Settings > Security > "Require API key for local connections" is enabled,
 or when accessing Stash over a network. Generate a key under
 Settings > Security > API Keys, then paste it here. Leave blank if
 Stash does not require authentication.
 type: STRING

 frequency:
 displayName: Scan Frequency
 description: >
Expand All@@ -53,9 +63,10 @@ settings:
 time_of_day:
 displayName: Time of Day (HH:MM)
 description: >
 The time to run the scan in 24-hour HH:MM format. Used for Daily and
 Weekly schedules; ignored for Hourly. Examples: 02:00, 14:30, 20:45.
 Defaults to 02:00 if not set.
 One or more times to run the scan in 24-hour HH:MM format. Used for
 Daily and Weekly schedules; ignored for Hourly. Separate multiple times
 with commas or spaces. Examples: 02:00 — single daily run. 00:00, 06:00,
 09:00, 16:00, 18:00 — five runs per day. Defaults to 02:00 if not set.
 type: STRING

 day_of_week:
Expand Down

153 changes: 123 additions & 30 deletions
plugins/stash-scheduler/stash_scheduler.py

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -142,6 +142,7 @@ def get_plugin_settings(stash, plugin_id="stash-scheduler"):
 "time_of_day": "02:00",
 "day_of_week": "sun",
 "timezone": "UTC",
 "apiKey": "",
 "run_identify": False,
 "identify_timeout_minutes": 120,
 # Comma- or newline-separated list of paths to restrict scan + identify.
Expand All@@ -168,19 +169,38 @@ def get_plugin_settings(stash, plugin_id="stash-scheduler"):
 return defaults


def _parse_time_of_day(raw, warn):
 raw = str(raw).strip()
def _parse_single_time(token, warn):
 """Parse one HH:MM token. Returns (hour, minute) or None on error."""
 token = str(token).strip()
 try:
 parts = raw.split(":")
 parts = token.split(":")
 if len(parts) != 2:
 raise ValueError("expected HH:MM")
 hh, mm = int(parts[0]), int(parts[1])
 if not (0 <= hh <= 23 and 0 <= mm <= 59):
 raise ValueError(f"values out of range: {hh}:{mm:02d}")
 return hh, mm
 except (ValueError, TypeError) as exc:
 warn(f"[Stash Scheduler] Invalid time_of_day {raw!r} ({exc}) — defaulting to 02:00.")
 return 2, 0
 warn(f"[Stash Scheduler] Invalid time {token!r} ({exc}) — skipping.")
 return None


def _parse_times_of_day(raw, warn):
 """Parse comma/space/newline-separated HH:MM times.
 Returns a deduplicated list of (hour, minute) tuples, sorted ascending.
 Falls back to [(2, 0)] if nothing valid is found."""
 import re as _re
 tokens = [t for t in _re.split(r"[\s,]+", str(raw).strip()) if t]
 results, seen = [], set()
 for token in tokens:
 parsed = _parse_single_time(token, warn)
 if parsed is not None and parsed not in seen:
 results.append(parsed)
 seen.add(parsed)
 if not results:
 warn("[Stash Scheduler] No valid times found in time_of_day — defaulting to 02:00.")
 return [(2, 0)]
 return sorted(results)


def validate_and_coerce_settings(settings, warn):
Expand All@@ -194,10 +214,11 @@ def validate_and_coerce_settings(settings, warn):
 settings["frequency"] = freq

 raw_time = settings.get("time_of_day", "02:00")
 hour, minute = _parse_time_of_day(raw_time, warn)
 settings["time_of_day"] = f"{hour:02d}:{minute:02d}"
 settings["hour"] = hour
 settings["minute"] = minute
 times = _parse_times_of_day(raw_time, warn)
 settings["times_of_day"] = times
 settings["time_of_day"] = ", ".join(f"{h:02d}:{m:02d}" for h, m in times)
 settings["hour"] = times[0][0]
 settings["minute"] = times[0][1]

 dow = str(settings.get("day_of_week", "sun")).strip().lower()
 if dow not in VALID_DAYS:
Expand DownExpand Up@@ -233,6 +254,9 @@ def validate_and_coerce_settings(settings, warn):
 tz_raw = "UTC"
 settings["timezone"] = tz_raw

 # apiKey — strip whitespace; empty string means no key (session auth)
 settings["apiKey"] = str(settings.get("apiKey", "") or "").strip()

 # scanPaths — parse comma/newline-separated string into a clean list
 raw_paths = str(settings.get("scanPaths", "") or "")
 import re as _re
Expand All@@ -254,6 +278,16 @@ def validate_and_coerce_settings(settings, warn):
# Scan / Identify helpers (used by both plugin tasks and the daemon)
# ---------------------------------------------------------------------------

def _strip_nulls(obj):
 """Recursively remove None/null values from a dict or list.
 Required before forwarding a GraphQL query result back as mutation input —
 Stash rejects null on required sub-fields."""
 if isinstance(obj, dict):
 return {k: _strip_nulls(v) for k, v in obj.items() if v is not None}
 if isinstance(obj, list):
 return [_strip_nulls(i) for i in obj]
 return obj

_SCAN_FLAGS = (
 "scanGenerateCovers",
 "scanGeneratePreviews",
Expand DownExpand Up@@ -333,9 +367,12 @@ def trigger_identify(stash_or_log, gql_fn, paths=None):
 paths_desc = f" (paths: {', '.join(paths)})" if paths else " (full library)"
 _log_info(stash_or_log, f"[Stash Scheduler] Triggering identify task{paths_desc}…")
 try:
 identify_input = {"sources": identify["sources"]}
 # Strip nulls: the query returns the full schema object including null
 # sub-fields; forwarding those nulls into the mutation causes Stash to
 # reject the request with a schema validation error.
 identify_input = {"sources": _strip_nulls(identify["sources"])}
 if identify.get("options"):
 identify_input["options"] = identify["options"]
 identify_input["options"] = _strip_nulls(identify["options"])
 if paths:
 identify_input["paths"] = paths
 result = gql_fn(IDENTIFY_MUTATION, {"input": identify_input})
Expand DownExpand Up@@ -528,7 +565,7 @@ def daemon_alive():
 return False, None


def tail_log(n=30):
def tail_log(n=100):
 """Return the last n lines of the daemon log file as a string."""
 if not os.path.exists(LOG_FILE):
 return "(log file not found)"
Expand DownExpand Up@@ -572,46 +609,82 @@ def run_daemon():
 sys.exit(1)

 frequency = settings["frequency"]
 hour = settings["hour"]
 minute = settings["minute"]
 times_of_day = settings["times_of_day"]
 day_of_week = settings["day_of_week"]
 timezone = settings["timezone"]
 run_identify = settings["run_identify"]
 identify_timeout = settings["identify_timeout_minutes"]
 scan_paths = settings.get("scan_paths") or []

 # Build a simple GQL callable for the daemon (not stash.log-based)
 def gql(query, variables=None):
 return call_gql(stash, query, variables)

 def scheduled_job():
 """Fired by APScheduler for each scheduled time slot."""
 log.info("Scheduled scan cycle firing.")
 # Fresh connection each run — guards against stale sessions after a
 # Stash restart.
 try:
 job_id = trigger_scan(log, gql, settings)
 fresh_stash = make_stash(cfg["server_connection"])
 def gql(query, variables=None):
 return call_gql(fresh_stash, query, variables)
 except Exception as exc:
 log.error(f"Scan failed: {exc}")
 log.error(f"Cannot connect to Stash for scheduled scan: {exc}")
 return
 if run_identify:

 # Reload operational settings live from Stash so changes to
 # run_identify, scan_paths, scan flags, etc. take effect immediately
 # without needing to restart the daemon.
 try:
 live_settings = validate_and_coerce_settings(
 get_plugin_settings(fresh_stash),
 lambda m: log.warning(m),
 )
 log.info(
 f"Settings reloaded — identify: {'yes' if live_settings['run_identify'] else 'no'}, "
 f"paths: {', '.join(live_settings.get('scan_paths') or []) or 'full library'}"
 )
 except Exception as exc:
 log.warning(f"Could not reload settings from Stash — using startup settings: {exc}")
 live_settings = settings

 try:
 job_id = trigger_scan(log, gql, live_settings)
 except Exception as exc:
 log.error(f"Scan trigger failed: {exc}")
 return

 if live_settings["run_identify"]:
 live_timeout = live_settings["identify_timeout_minutes"]
 live_paths = live_settings.get("scan_paths") or None
 threading.Thread(
 target=wait_for_scan_and_identify,
 args=(log, gql, job_id, identify_timeout, scan_paths or None),
 args=(log, gql, job_id, live_timeout, live_paths),
 daemon=True,
 ).start()

 def heartbeat_job():
 """Fires every hour so the log shows the daemon is still alive."""
 log.info("[heartbeat] Daemon alive.")

 scheduler = BackgroundScheduler(timezone=timezone)
 job_kwargs = {"func": scheduled_job, "misfire_grace_time": 3600, "coalesce": True}

 times_str = ", ".join(f"{h:02d}:{m:02d}" for h, m in times_of_day)
 if frequency == "hourly":
 scheduler.add_job(trigger="cron", minute=0, **job_kwargs)
 log.info(f"Schedule: every hour at :00 ({timezone})")
 elif frequency == "weekly":
 scheduler.add_job(
 trigger="cron", day_of_week=day_of_week, hour=hour, minute=minute, **job_kwargs
 )
 log.info(f"Schedule: weekly {day_of_week.upper()} at {hour:02d}:{minute:02d} ({timezone})")
 for h, m in times_of_day:
 scheduler.add_job(
 trigger="cron", day_of_week=day_of_week, hour=h, minute=m, **job_kwargs
 )
 log.info(f"Schedule: weekly {day_of_week.upper()} at {times_str} ({timezone})")
 else:
 scheduler.add_job(trigger="cron", hour=hour, minute=minute, **job_kwargs)
 log.info(f"Schedule: daily at {hour:02d}:{minute:02d} ({timezone})")
 for h, m in times_of_day:
 scheduler.add_job(trigger="cron", hour=h, minute=m, **job_kwargs)
 log.info(f"Schedule: daily at {times_str} ({timezone})")

 # Hourly heartbeat so the log proves the daemon is ticking even between scans
 scheduler.add_job(func=heartbeat_job, trigger="cron", minute=0,
 misfire_grace_time=3600, coalesce=True)

 log.info(f"Identify after scan: {'yes' if run_identify else 'no'}")

Expand All@@ -626,7 +699,21 @@ def scheduled_job():
 else:
 log.info("Scan flags: none (bare scan)")

 # Log APScheduler execution errors so silent job failures are visible
 from apscheduler.events import EVENT_JOB_ERROR, EVENT_JOB_EXECUTED, EVENT_JOB_MISSED
 def _aps_listener(event):
 if event.exception:
 log.error(f"[APScheduler] Job {event.job_id} raised an exception: {event.exception}")
 elif hasattr(event, 'scheduled_run_time') and not hasattr(event, 'retval'):
 log.warning(f"[APScheduler] Job {event.job_id} missed its scheduled time.")
 scheduler.add_listener(_aps_listener, EVENT_JOB_ERROR | EVENT_JOB_MISSED)

 scheduler.start()

 # Log next fire times so the log confirms jobs are registered correctly
 for job in scheduler.get_jobs():
 if job.next_run_time:
 log.info(f"Next fire for job '{job.id}': {job.next_run_time}")
 log.info("Daemon is running. Waiting for scheduled events…")

 stop = threading.Event()
Expand DownExpand Up@@ -682,7 +769,13 @@ def gql(query, variables=None):
# ---------------------------------------------------------------------------

def task_start_scheduler(stash, server_connection, settings):
 save_config(server_connection, settings)
 # Inject the API key into the saved connection dict so every daemon GQL
 # request includes it — required when Stash's "Require API key" is enabled.
 conn = dict(server_connection)
 api_key = settings.get("apiKey", "").strip()
 if api_key:
 conn["ApiKey"] = api_key
 save_config(conn, settings)
 kill_existing_daemon()
 launch_detached("--daemon")
 freq = settings["frequency"]
Expand DownExpand Up@@ -727,7 +820,7 @@ def task_run_now(stash, settings, force_identify=False):
def task_check_status(stash):
 alive, pid = daemon_alive()
 status_line = f"Daemon: RUNNING (PID {pid})" if alive else "Daemon: NOT RUNNING"
 recent = tail_log(30)
 recent = tail_log(100)
 output = f"{status_line}\nLog file: {LOG_FILE}\n\nRecent log ({LOG_FILE}):\n{recent}"
 stash.log.info(f"[Stash Scheduler] {status_line}")
 print(json.dumps({"output": output}))
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Auto-enable theater mode on YouTube
(function() {
function tryTheater() {
var btn = document.querySelector('button[aria-label="Theater mode"], ytd-player #player button[title="Theater mode"]');
if (btn && !btn.classList.contains('activated')) {
btn.click();
}
}
// Try immediately
tryTheater();
// Try after navigation (SPA)
var lastUrl = location.href;
setInterval(function() {
if (location.href !== lastUrl) {
lastUrl = location.href;
setTimeout(tryTheater, 500);
}
}, 1000);
// Also try on player load
var observer = new MutationObserver(tryTheater);
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
Add API Authentication and additional scan scheduling options by dscisci · Pull Request #711 · stashapp/CommunityScripts · GitHub
Skip to content
Add API Authentication and additional scan scheduling options#711

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Open

dscisci
wants to merge
3
commits into

base:main
Choose a base branch

from

 Open


Add API Authentication and additional scan scheduling options
#711
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


3 commits


Select commit
Hold shift + click to select a range
9b0e6c9

Add files via upload


dscisci May 1, 2026
5ad5f71

Add files via upload


dscisci May 12, 2026
612e9ff

Merge branch 'main' into main


dscisci May 12, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


9 changes: 6 additions & 3 deletions
plugins/stash-scheduler/README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,7 +1,5 @@
# Stash Scheduler Plugin

https://discourse.stashapp.cc/t/stash-scheduler/7059
@DogmaDragonDogmaDragonMay 13, 2026

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Must be retained.

A plugin for [Stash](https://github.com/stashapp/stash) that automatically runs library scans on a schedule (hourly, daily, or weekly), with an optional identify pass after each scan.

---
Expand DownExpand Up@@ -83,8 +81,9 @@ Open **Settings → Plugins → Stash Scheduler** and set your preferences:

| Setting | Description | Default |
|---|---|---|
| **API Key** | Stash API key for authenticating background scans. Required when "Require API key" is enabled in Stash's Security settings. Generate one under Settings > Security > API Keys. Leave blank if Stash does not require authentication. | *(none)* |
| **Scan Frequency** | `hourly`, `daily`, or `weekly` | `daily` |
| **Time of Day (HH:MM)** | Time to run the scan in 24-hour `HH:MM` format. Used by Daily and Weekly; ignored for Hourly. | `02:00` |
| **Time of Day (HH:MM)** | One or more times to run the scan, in 24-hour `HH:MM` format. Separate multiple times with commas or spaces, e.g. `00:00, 06:00, 18:00`. Used by Daily and Weekly; ignored for Hourly. | `02:00` |
| **Day of Week** | Day to scan when Frequency is Weekly. Use `mon`, `tue`, `wed`, `thu`, `fri`, `sat`, or `sun`. | `sun` |
| **Timezone** | IANA timezone name for interpreting Time of Day and Day of Week. Examples: `America/New_York`, `Europe/London`, `Asia/Tokyo`. Leave blank for UTC. | `UTC` |
| **Run Identify After Scan** | When enabled, runs an Identify task after each scan finishes successfully. | `false` |
Expand DownExpand Up@@ -296,6 +295,10 @@ All activity is written to the Stash log. To view it:

| Version | Notes |
|---|---|
| 0.10.0 | Added API Key setting — required when Stash's "Require API key" security option is enabled |
| 0.9.0 | Daemon now reloads settings from Stash on every scheduled run — changes to identify, paths, and scan flags take effect without restarting the scheduler |
| 0.8.0 | Fixed identify not running after scan (null fields in GraphQL input); fixed daemon losing Stash connection after restart; added APScheduler error logging, hourly heartbeat, and next-fire-time logging; Check Status now shows 100 log lines |
| 0.7.0 | Time of Day now accepts multiple times (comma or space separated) — each fires a separate scheduled scan |
| 0.6.0 | Added "Limit to Paths" setting — scan and identify can now be restricted to specific directories |
| 0.5.0 | Fixed identify-after-scan (null jobQueue crash); added 9 scan generation flag settings (covers, previews, sprites, phashes, thumbnails, clip previews, force rescan) |
| 0.4.0 | Added Check Status task; daemon logs written to file (`/tmp/stash-scheduler-daemon.log`) |
Expand Down

21 changes: 16 additions & 5 deletions
plugins/stash-scheduler/stash-scheduler.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
name: Stash Scheduler
description: Schedule automatic library scans with an optional identify pass after each scan.
version: "0.6.0"
url: https://discourse.stashapp.cc/t/stash-scheduler/7059
@DogmaDragonDogmaDragonMay 13, 2026

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Must be retained.
version: "0.10.0"
url: https://github.com/stashapp/stash

exec:
 - python3
Expand DownExpand Up@@ -42,6 +42,16 @@ tasks:
 mode: check_status

settings:
 apiKey:
@DogmaDragonDogmaDragonMay 13, 2026

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why not just check for authentication and get the API key from configuration query using GraphQL if it's available?
 displayName: API Key
 description: >
 Stash API key for authenticating background scans. Required when
 Settings > Security > "Require API key for local connections" is enabled,
 or when accessing Stash over a network. Generate a key under
 Settings > Security > API Keys, then paste it here. Leave blank if
 Stash does not require authentication.
 type: STRING

 frequency:
 displayName: Scan Frequency
 description: >
Expand All@@ -53,9 +63,10 @@ settings:
 time_of_day:
 displayName: Time of Day (HH:MM)
 description: >
 The time to run the scan in 24-hour HH:MM format. Used for Daily and
 Weekly schedules; ignored for Hourly. Examples: 02:00, 14:30, 20:45.
 Defaults to 02:00 if not set.
 One or more times to run the scan in 24-hour HH:MM format. Used for
 Daily and Weekly schedules; ignored for Hourly. Separate multiple times
 with commas or spaces. Examples: 02:00 — single daily run. 00:00, 06:00,
 09:00, 16:00, 18:00 — five runs per day. Defaults to 02:00 if not set.
 type: STRING

 day_of_week:
Expand Down

153 changes: 123 additions & 30 deletions
plugins/stash-scheduler/stash_scheduler.py

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -142,6 +142,7 @@ def get_plugin_settings(stash, plugin_id="stash-scheduler"):
 "time_of_day": "02:00",
 "day_of_week": "sun",
 "timezone": "UTC",
 "apiKey": "",
 "run_identify": False,
 "identify_timeout_minutes": 120,
 # Comma- or newline-separated list of paths to restrict scan + identify.
Expand All@@ -168,19 +169,38 @@ def get_plugin_settings(stash, plugin_id="stash-scheduler"):
 return defaults


def _parse_time_of_day(raw, warn):
 raw = str(raw).strip()
def _parse_single_time(token, warn):
 """Parse one HH:MM token. Returns (hour, minute) or None on error."""
 token = str(token).strip()
 try:
 parts = raw.split(":")
 parts = token.split(":")
 if len(parts) != 2:
 raise ValueError("expected HH:MM")
 hh, mm = int(parts[0]), int(parts[1])
 if not (0 <= hh <= 23 and 0 <= mm <= 59):
 raise ValueError(f"values out of range: {hh}:{mm:02d}")
 return hh, mm
 except (ValueError, TypeError) as exc:
 warn(f"[Stash Scheduler] Invalid time_of_day {raw!r} ({exc}) — defaulting to 02:00.")
 return 2, 0
 warn(f"[Stash Scheduler] Invalid time {token!r} ({exc}) — skipping.")
 return None


def _parse_times_of_day(raw, warn):
 """Parse comma/space/newline-separated HH:MM times.
 Returns a deduplicated list of (hour, minute) tuples, sorted ascending.
 Falls back to [(2, 0)] if nothing valid is found."""
 import re as _re
 tokens = [t for t in _re.split(r"[\s,]+", str(raw).strip()) if t]
 results, seen = [], set()
 for token in tokens:
 parsed = _parse_single_time(token, warn)
 if parsed is not None and parsed not in seen:
 results.append(parsed)
 seen.add(parsed)
 if not results:
 warn("[Stash Scheduler] No valid times found in time_of_day — defaulting to 02:00.")
 return [(2, 0)]
 return sorted(results)


def validate_and_coerce_settings(settings, warn):
Expand All@@ -194,10 +214,11 @@ def validate_and_coerce_settings(settings, warn):
 settings["frequency"] = freq

 raw_time = settings.get("time_of_day", "02:00")
 hour, minute = _parse_time_of_day(raw_time, warn)
 settings["time_of_day"] = f"{hour:02d}:{minute:02d}"
 settings["hour"] = hour
 settings["minute"] = minute
 times = _parse_times_of_day(raw_time, warn)
 settings["times_of_day"] = times
 settings["time_of_day"] = ", ".join(f"{h:02d}:{m:02d}" for h, m in times)
 settings["hour"] = times[0][0]
 settings["minute"] = times[0][1]

 dow = str(settings.get("day_of_week", "sun")).strip().lower()
 if dow not in VALID_DAYS:
Expand DownExpand Up@@ -233,6 +254,9 @@ def validate_and_coerce_settings(settings, warn):
 tz_raw = "UTC"
 settings["timezone"] = tz_raw

 # apiKey — strip whitespace; empty string means no key (session auth)
 settings["apiKey"] = str(settings.get("apiKey", "") or "").strip()

 # scanPaths — parse comma/newline-separated string into a clean list
 raw_paths = str(settings.get("scanPaths", "") or "")
 import re as _re
Expand All@@ -254,6 +278,16 @@ def validate_and_coerce_settings(settings, warn):
# Scan / Identify helpers (used by both plugin tasks and the daemon)
# ---------------------------------------------------------------------------

def _strip_nulls(obj):
 """Recursively remove None/null values from a dict or list.
 Required before forwarding a GraphQL query result back as mutation input —
 Stash rejects null on required sub-fields."""
 if isinstance(obj, dict):
 return {k: _strip_nulls(v) for k, v in obj.items() if v is not None}
 if isinstance(obj, list):
 return [_strip_nulls(i) for i in obj]
 return obj

_SCAN_FLAGS = (
 "scanGenerateCovers",
 "scanGeneratePreviews",
Expand DownExpand Up@@ -333,9 +367,12 @@ def trigger_identify(stash_or_log, gql_fn, paths=None):
 paths_desc = f" (paths: {', '.join(paths)})" if paths else " (full library)"
 _log_info(stash_or_log, f"[Stash Scheduler] Triggering identify task{paths_desc}…")
 try:
 identify_input = {"sources": identify["sources"]}
 # Strip nulls: the query returns the full schema object including null
 # sub-fields; forwarding those nulls into the mutation causes Stash to
 # reject the request with a schema validation error.
 identify_input = {"sources": _strip_nulls(identify["sources"])}
 if identify.get("options"):
 identify_input["options"] = identify["options"]
 identify_input["options"] = _strip_nulls(identify["options"])
 if paths:
 identify_input["paths"] = paths
 result = gql_fn(IDENTIFY_MUTATION, {"input": identify_input})
Expand DownExpand Up@@ -528,7 +565,7 @@ def daemon_alive():
 return False, None


def tail_log(n=30):
def tail_log(n=100):
 """Return the last n lines of the daemon log file as a string."""
 if not os.path.exists(LOG_FILE):
 return "(log file not found)"
Expand DownExpand Up@@ -572,46 +609,82 @@ def run_daemon():
 sys.exit(1)

 frequency = settings["frequency"]
 hour = settings["hour"]
 minute = settings["minute"]
 times_of_day = settings["times_of_day"]
 day_of_week = settings["day_of_week"]
 timezone = settings["timezone"]
 run_identify = settings["run_identify"]
 identify_timeout = settings["identify_timeout_minutes"]
 scan_paths = settings.get("scan_paths") or []

 # Build a simple GQL callable for the daemon (not stash.log-based)
 def gql(query, variables=None):
 return call_gql(stash, query, variables)

 def scheduled_job():
 """Fired by APScheduler for each scheduled time slot."""
 log.info("Scheduled scan cycle firing.")
 # Fresh connection each run — guards against stale sessions after a
 # Stash restart.
 try:
 job_id = trigger_scan(log, gql, settings)
 fresh_stash = make_stash(cfg["server_connection"])
 def gql(query, variables=None):
 return call_gql(fresh_stash, query, variables)
 except Exception as exc:
 log.error(f"Scan failed: {exc}")
 log.error(f"Cannot connect to Stash for scheduled scan: {exc}")
 return
 if run_identify:

 # Reload operational settings live from Stash so changes to
 # run_identify, scan_paths, scan flags, etc. take effect immediately
 # without needing to restart the daemon.
 try:
 live_settings = validate_and_coerce_settings(
 get_plugin_settings(fresh_stash),
 lambda m: log.warning(m),
 )
 log.info(
 f"Settings reloaded — identify: {'yes' if live_settings['run_identify'] else 'no'}, "
 f"paths: {', '.join(live_settings.get('scan_paths') or []) or 'full library'}"
 )
 except Exception as exc:
 log.warning(f"Could not reload settings from Stash — using startup settings: {exc}")
 live_settings = settings

 try:
 job_id = trigger_scan(log, gql, live_settings)
 except Exception as exc:
 log.error(f"Scan trigger failed: {exc}")
 return

 if live_settings["run_identify"]:
 live_timeout = live_settings["identify_timeout_minutes"]
 live_paths = live_settings.get("scan_paths") or None
 threading.Thread(
 target=wait_for_scan_and_identify,
 args=(log, gql, job_id, identify_timeout, scan_paths or None),
 args=(log, gql, job_id, live_timeout, live_paths),
 daemon=True,
 ).start()

 def heartbeat_job():
 """Fires every hour so the log shows the daemon is still alive."""
 log.info("[heartbeat] Daemon alive.")

 scheduler = BackgroundScheduler(timezone=timezone)
 job_kwargs = {"func": scheduled_job, "misfire_grace_time": 3600, "coalesce": True}

 times_str = ", ".join(f"{h:02d}:{m:02d}" for h, m in times_of_day)
 if frequency == "hourly":
 scheduler.add_job(trigger="cron", minute=0, **job_kwargs)
 log.info(f"Schedule: every hour at :00 ({timezone})")
 elif frequency == "weekly":
 scheduler.add_job(
 trigger="cron", day_of_week=day_of_week, hour=hour, minute=minute, **job_kwargs
 )
 log.info(f"Schedule: weekly {day_of_week.upper()} at {hour:02d}:{minute:02d} ({timezone})")
 for h, m in times_of_day:
 scheduler.add_job(
 trigger="cron", day_of_week=day_of_week, hour=h, minute=m, **job_kwargs
 )
 log.info(f"Schedule: weekly {day_of_week.upper()} at {times_str} ({timezone})")
 else:
 scheduler.add_job(trigger="cron", hour=hour, minute=minute, **job_kwargs)
 log.info(f"Schedule: daily at {hour:02d}:{minute:02d} ({timezone})")
 for h, m in times_of_day:
 scheduler.add_job(trigger="cron", hour=h, minute=m, **job_kwargs)
 log.info(f"Schedule: daily at {times_str} ({timezone})")

 # Hourly heartbeat so the log proves the daemon is ticking even between scans
 scheduler.add_job(func=heartbeat_job, trigger="cron", minute=0,
 misfire_grace_time=3600, coalesce=True)

 log.info(f"Identify after scan: {'yes' if run_identify else 'no'}")

Expand All@@ -626,7 +699,21 @@ def scheduled_job():
 else:
 log.info("Scan flags: none (bare scan)")

 # Log APScheduler execution errors so silent job failures are visible
 from apscheduler.events import EVENT_JOB_ERROR, EVENT_JOB_EXECUTED, EVENT_JOB_MISSED
 def _aps_listener(event):
 if event.exception:
 log.error(f"[APScheduler] Job {event.job_id} raised an exception: {event.exception}")
 elif hasattr(event, 'scheduled_run_time') and not hasattr(event, 'retval'):
 log.warning(f"[APScheduler] Job {event.job_id} missed its scheduled time.")
 scheduler.add_listener(_aps_listener, EVENT_JOB_ERROR | EVENT_JOB_MISSED)

 scheduler.start()

 # Log next fire times so the log confirms jobs are registered correctly
 for job in scheduler.get_jobs():
 if job.next_run_time:
 log.info(f"Next fire for job '{job.id}': {job.next_run_time}")
 log.info("Daemon is running. Waiting for scheduled events…")

 stop = threading.Event()
Expand DownExpand Up@@ -682,7 +769,13 @@ def gql(query, variables=None):
# ---------------------------------------------------------------------------

def task_start_scheduler(stash, server_connection, settings):
 save_config(server_connection, settings)
 # Inject the API key into the saved connection dict so every daemon GQL
 # request includes it — required when Stash's "Require API key" is enabled.
 conn = dict(server_connection)
 api_key = settings.get("apiKey", "").strip()
 if api_key:
 conn["ApiKey"] = api_key
 save_config(conn, settings)
 kill_existing_daemon()
 launch_detached("--daemon")
 freq = settings["frequency"]
Expand DownExpand Up@@ -727,7 +820,7 @@ def task_run_now(stash, settings, force_identify=False):
def task_check_status(stash):
 alive, pid = daemon_alive()
 status_line = f"Daemon: RUNNING (PID {pid})" if alive else "Daemon: NOT RUNNING"
 recent = tail_log(30)
 recent = tail_log(100)
 output = f"{status_line}\nLog file: {LOG_FILE}\n\nRecent log ({LOG_FILE}):\n{recent}"
 stash.log.info(f"[Stash Scheduler] {status_line}")
 print(json.dumps({"output": output}))
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Remove or un-stick sticky/fixed headers that block content
(function() {
function unstick() {
document.querySelectorAll('header, nav, [role="banner"], .header, .navbar, .sticky, .fixed-top, [style*="position: fixed"], [style*="position:sticky"]').forEach(function(el) {
if (el.style.position === 'fixed' || el.style.position === 'sticky' || getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {
el.style.position = 'static';
el.style.top = 'auto';
el.style.zIndex = 'auto';
}
});
}
unstick();
var observer = new MutationObserver(unstick);
observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });
})();
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
Add API Authentication and additional scan scheduling options by dscisci · Pull Request #711 · stashapp/CommunityScripts · GitHub
Skip to content
Add API Authentication and additional scan scheduling options#711

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Open

dscisci
wants to merge
3
commits into

base:main
Choose a base branch

from

 Open


Add API Authentication and additional scan scheduling options
#711
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


3 commits


Select commit
Hold shift + click to select a range
9b0e6c9

Add files via upload


dscisci May 1, 2026
5ad5f71

Add files via upload


dscisci May 12, 2026
612e9ff

Merge branch 'main' into main


dscisci May 12, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


9 changes: 6 additions & 3 deletions
plugins/stash-scheduler/README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,7 +1,5 @@
# Stash Scheduler Plugin

https://discourse.stashapp.cc/t/stash-scheduler/7059
@DogmaDragonDogmaDragonMay 13, 2026

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Must be retained.

A plugin for [Stash](https://github.com/stashapp/stash) that automatically runs library scans on a schedule (hourly, daily, or weekly), with an optional identify pass after each scan.

---
Expand DownExpand Up@@ -83,8 +81,9 @@ Open **Settings → Plugins → Stash Scheduler** and set your preferences:

| Setting | Description | Default |
|---|---|---|
| **API Key** | Stash API key for authenticating background scans. Required when "Require API key" is enabled in Stash's Security settings. Generate one under Settings > Security > API Keys. Leave blank if Stash does not require authentication. | *(none)* |
| **Scan Frequency** | `hourly`, `daily`, or `weekly` | `daily` |
| **Time of Day (HH:MM)** | Time to run the scan in 24-hour `HH:MM` format. Used by Daily and Weekly; ignored for Hourly. | `02:00` |
| **Time of Day (HH:MM)** | One or more times to run the scan, in 24-hour `HH:MM` format. Separate multiple times with commas or spaces, e.g. `00:00, 06:00, 18:00`. Used by Daily and Weekly; ignored for Hourly. | `02:00` |
| **Day of Week** | Day to scan when Frequency is Weekly. Use `mon`, `tue`, `wed`, `thu`, `fri`, `sat`, or `sun`. | `sun` |
| **Timezone** | IANA timezone name for interpreting Time of Day and Day of Week. Examples: `America/New_York`, `Europe/London`, `Asia/Tokyo`. Leave blank for UTC. | `UTC` |
| **Run Identify After Scan** | When enabled, runs an Identify task after each scan finishes successfully. | `false` |
Expand DownExpand Up@@ -296,6 +295,10 @@ All activity is written to the Stash log. To view it:

| Version | Notes |
|---|---|
| 0.10.0 | Added API Key setting — required when Stash's "Require API key" security option is enabled |
| 0.9.0 | Daemon now reloads settings from Stash on every scheduled run — changes to identify, paths, and scan flags take effect without restarting the scheduler |
| 0.8.0 | Fixed identify not running after scan (null fields in GraphQL input); fixed daemon losing Stash connection after restart; added APScheduler error logging, hourly heartbeat, and next-fire-time logging; Check Status now shows 100 log lines |
| 0.7.0 | Time of Day now accepts multiple times (comma or space separated) — each fires a separate scheduled scan |
| 0.6.0 | Added "Limit to Paths" setting — scan and identify can now be restricted to specific directories |
| 0.5.0 | Fixed identify-after-scan (null jobQueue crash); added 9 scan generation flag settings (covers, previews, sprites, phashes, thumbnails, clip previews, force rescan) |
| 0.4.0 | Added Check Status task; daemon logs written to file (`/tmp/stash-scheduler-daemon.log`) |
Expand Down

21 changes: 16 additions & 5 deletions
plugins/stash-scheduler/stash-scheduler.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
name: Stash Scheduler
description: Schedule automatic library scans with an optional identify pass after each scan.
version: "0.6.0"
url: https://discourse.stashapp.cc/t/stash-scheduler/7059
@DogmaDragonDogmaDragonMay 13, 2026

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Must be retained.
version: "0.10.0"
url: https://github.com/stashapp/stash

exec:
 - python3
Expand DownExpand Up@@ -42,6 +42,16 @@ tasks:
 mode: check_status

settings:
 apiKey:
@DogmaDragonDogmaDragonMay 13, 2026

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why not just check for authentication and get the API key from configuration query using GraphQL if it's available?
 displayName: API Key
 description: >
 Stash API key for authenticating background scans. Required when
 Settings > Security > "Require API key for local connections" is enabled,
 or when accessing Stash over a network. Generate a key under
 Settings > Security > API Keys, then paste it here. Leave blank if
 Stash does not require authentication.
 type: STRING

 frequency:
 displayName: Scan Frequency
 description: >
Expand All@@ -53,9 +63,10 @@ settings:
 time_of_day:
 displayName: Time of Day (HH:MM)
 description: >
 The time to run the scan in 24-hour HH:MM format. Used for Daily and
 Weekly schedules; ignored for Hourly. Examples: 02:00, 14:30, 20:45.
 Defaults to 02:00 if not set.
 One or more times to run the scan in 24-hour HH:MM format. Used for
 Daily and Weekly schedules; ignored for Hourly. Separate multiple times
 with commas or spaces. Examples: 02:00 — single daily run. 00:00, 06:00,
 09:00, 16:00, 18:00 — five runs per day. Defaults to 02:00 if not set.
 type: STRING

 day_of_week:
Expand Down

153 changes: 123 additions & 30 deletions
plugins/stash-scheduler/stash_scheduler.py

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -142,6 +142,7 @@ def get_plugin_settings(stash, plugin_id="stash-scheduler"):
 "time_of_day": "02:00",
 "day_of_week": "sun",
 "timezone": "UTC",
 "apiKey": "",
 "run_identify": False,
 "identify_timeout_minutes": 120,
 # Comma- or newline-separated list of paths to restrict scan + identify.
Expand All@@ -168,19 +169,38 @@ def get_plugin_settings(stash, plugin_id="stash-scheduler"):
 return defaults


def _parse_time_of_day(raw, warn):
 raw = str(raw).strip()
def _parse_single_time(token, warn):
 """Parse one HH:MM token. Returns (hour, minute) or None on error."""
 token = str(token).strip()
 try:
 parts = raw.split(":")
 parts = token.split(":")
 if len(parts) != 2:
 raise ValueError("expected HH:MM")
 hh, mm = int(parts[0]), int(parts[1])
 if not (0 <= hh <= 23 and 0 <= mm <= 59):
 raise ValueError(f"values out of range: {hh}:{mm:02d}")
 return hh, mm
 except (ValueError, TypeError) as exc:
 warn(f"[Stash Scheduler] Invalid time_of_day {raw!r} ({exc}) — defaulting to 02:00.")
 return 2, 0
 warn(f"[Stash Scheduler] Invalid time {token!r} ({exc}) — skipping.")
 return None


def _parse_times_of_day(raw, warn):
 """Parse comma/space/newline-separated HH:MM times.
 Returns a deduplicated list of (hour, minute) tuples, sorted ascending.
 Falls back to [(2, 0)] if nothing valid is found."""
 import re as _re
 tokens = [t for t in _re.split(r"[\s,]+", str(raw).strip()) if t]
 results, seen = [], set()
 for token in tokens:
 parsed = _parse_single_time(token, warn)
 if parsed is not None and parsed not in seen:
 results.append(parsed)
 seen.add(parsed)
 if not results:
 warn("[Stash Scheduler] No valid times found in time_of_day — defaulting to 02:00.")
 return [(2, 0)]
 return sorted(results)


def validate_and_coerce_settings(settings, warn):
Expand All@@ -194,10 +214,11 @@ def validate_and_coerce_settings(settings, warn):
 settings["frequency"] = freq

 raw_time = settings.get("time_of_day", "02:00")
 hour, minute = _parse_time_of_day(raw_time, warn)
 settings["time_of_day"] = f"{hour:02d}:{minute:02d}"
 settings["hour"] = hour
 settings["minute"] = minute
 times = _parse_times_of_day(raw_time, warn)
 settings["times_of_day"] = times
 settings["time_of_day"] = ", ".join(f"{h:02d}:{m:02d}" for h, m in times)
 settings["hour"] = times[0][0]
 settings["minute"] = times[0][1]

 dow = str(settings.get("day_of_week", "sun")).strip().lower()
 if dow not in VALID_DAYS:
Expand DownExpand Up@@ -233,6 +254,9 @@ def validate_and_coerce_settings(settings, warn):
 tz_raw = "UTC"
 settings["timezone"] = tz_raw

 # apiKey — strip whitespace; empty string means no key (session auth)
 settings["apiKey"] = str(settings.get("apiKey", "") or "").strip()

 # scanPaths — parse comma/newline-separated string into a clean list
 raw_paths = str(settings.get("scanPaths", "") or "")
 import re as _re
Expand All@@ -254,6 +278,16 @@ def validate_and_coerce_settings(settings, warn):
# Scan / Identify helpers (used by both plugin tasks and the daemon)
# ---------------------------------------------------------------------------

def _strip_nulls(obj):
 """Recursively remove None/null values from a dict or list.
 Required before forwarding a GraphQL query result back as mutation input —
 Stash rejects null on required sub-fields."""
 if isinstance(obj, dict):
 return {k: _strip_nulls(v) for k, v in obj.items() if v is not None}
 if isinstance(obj, list):
 return [_strip_nulls(i) for i in obj]
 return obj

_SCAN_FLAGS = (
 "scanGenerateCovers",
 "scanGeneratePreviews",
Expand DownExpand Up@@ -333,9 +367,12 @@ def trigger_identify(stash_or_log, gql_fn, paths=None):
 paths_desc = f" (paths: {', '.join(paths)})" if paths else " (full library)"
 _log_info(stash_or_log, f"[Stash Scheduler] Triggering identify task{paths_desc}…")
 try:
 identify_input = {"sources": identify["sources"]}
 # Strip nulls: the query returns the full schema object including null
 # sub-fields; forwarding those nulls into the mutation causes Stash to
 # reject the request with a schema validation error.
 identify_input = {"sources": _strip_nulls(identify["sources"])}
 if identify.get("options"):
 identify_input["options"] = identify["options"]
 identify_input["options"] = _strip_nulls(identify["options"])
 if paths:
 identify_input["paths"] = paths
 result = gql_fn(IDENTIFY_MUTATION, {"input": identify_input})
Expand DownExpand Up@@ -528,7 +565,7 @@ def daemon_alive():
 return False, None


def tail_log(n=30):
def tail_log(n=100):
 """Return the last n lines of the daemon log file as a string."""
 if not os.path.exists(LOG_FILE):
 return "(log file not found)"
Expand DownExpand Up@@ -572,46 +609,82 @@ def run_daemon():
 sys.exit(1)

 frequency = settings["frequency"]
 hour = settings["hour"]
 minute = settings["minute"]
 times_of_day = settings["times_of_day"]
 day_of_week = settings["day_of_week"]
 timezone = settings["timezone"]
 run_identify = settings["run_identify"]
 identify_timeout = settings["identify_timeout_minutes"]
 scan_paths = settings.get("scan_paths") or []

 # Build a simple GQL callable for the daemon (not stash.log-based)
 def gql(query, variables=None):
 return call_gql(stash, query, variables)

 def scheduled_job():
 """Fired by APScheduler for each scheduled time slot."""
 log.info("Scheduled scan cycle firing.")
 # Fresh connection each run — guards against stale sessions after a
 # Stash restart.
 try:
 job_id = trigger_scan(log, gql, settings)
 fresh_stash = make_stash(cfg["server_connection"])
 def gql(query, variables=None):
 return call_gql(fresh_stash, query, variables)
 except Exception as exc:
 log.error(f"Scan failed: {exc}")
 log.error(f"Cannot connect to Stash for scheduled scan: {exc}")
 return
 if run_identify:

 # Reload operational settings live from Stash so changes to
 # run_identify, scan_paths, scan flags, etc. take effect immediately
 # without needing to restart the daemon.
 try:
 live_settings = validate_and_coerce_settings(
 get_plugin_settings(fresh_stash),
 lambda m: log.warning(m),
 )
 log.info(
 f"Settings reloaded — identify: {'yes' if live_settings['run_identify'] else 'no'}, "
 f"paths: {', '.join(live_settings.get('scan_paths') or []) or 'full library'}"
 )
 except Exception as exc:
 log.warning(f"Could not reload settings from Stash — using startup settings: {exc}")
 live_settings = settings

 try:
 job_id = trigger_scan(log, gql, live_settings)
 except Exception as exc:
 log.error(f"Scan trigger failed: {exc}")
 return

 if live_settings["run_identify"]:
 live_timeout = live_settings["identify_timeout_minutes"]
 live_paths = live_settings.get("scan_paths") or None
 threading.Thread(
 target=wait_for_scan_and_identify,
 args=(log, gql, job_id, identify_timeout, scan_paths or None),
 args=(log, gql, job_id, live_timeout, live_paths),
 daemon=True,
 ).start()

 def heartbeat_job():
 """Fires every hour so the log shows the daemon is still alive."""
 log.info("[heartbeat] Daemon alive.")

 scheduler = BackgroundScheduler(timezone=timezone)
 job_kwargs = {"func": scheduled_job, "misfire_grace_time": 3600, "coalesce": True}

 times_str = ", ".join(f"{h:02d}:{m:02d}" for h, m in times_of_day)
 if frequency == "hourly":
 scheduler.add_job(trigger="cron", minute=0, **job_kwargs)
 log.info(f"Schedule: every hour at :00 ({timezone})")
 elif frequency == "weekly":
 scheduler.add_job(
 trigger="cron", day_of_week=day_of_week, hour=hour, minute=minute, **job_kwargs
 )
 log.info(f"Schedule: weekly {day_of_week.upper()} at {hour:02d}:{minute:02d} ({timezone})")
 for h, m in times_of_day:
 scheduler.add_job(
 trigger="cron", day_of_week=day_of_week, hour=h, minute=m, **job_kwargs
 )
 log.info(f"Schedule: weekly {day_of_week.upper()} at {times_str} ({timezone})")
 else:
 scheduler.add_job(trigger="cron", hour=hour, minute=minute, **job_kwargs)
 log.info(f"Schedule: daily at {hour:02d}:{minute:02d} ({timezone})")
 for h, m in times_of_day:
 scheduler.add_job(trigger="cron", hour=h, minute=m, **job_kwargs)
 log.info(f"Schedule: daily at {times_str} ({timezone})")

 # Hourly heartbeat so the log proves the daemon is ticking even between scans
 scheduler.add_job(func=heartbeat_job, trigger="cron", minute=0,
 misfire_grace_time=3600, coalesce=True)

 log.info(f"Identify after scan: {'yes' if run_identify else 'no'}")

Expand All@@ -626,7 +699,21 @@ def scheduled_job():
 else:
 log.info("Scan flags: none (bare scan)")

 # Log APScheduler execution errors so silent job failures are visible
 from apscheduler.events import EVENT_JOB_ERROR, EVENT_JOB_EXECUTED, EVENT_JOB_MISSED
 def _aps_listener(event):
 if event.exception:
 log.error(f"[APScheduler] Job {event.job_id} raised an exception: {event.exception}")
 elif hasattr(event, 'scheduled_run_time') and not hasattr(event, 'retval'):
 log.warning(f"[APScheduler] Job {event.job_id} missed its scheduled time.")
 scheduler.add_listener(_aps_listener, EVENT_JOB_ERROR | EVENT_JOB_MISSED)

 scheduler.start()

 # Log next fire times so the log confirms jobs are registered correctly
 for job in scheduler.get_jobs():
 if job.next_run_time:
 log.info(f"Next fire for job '{job.id}': {job.next_run_time}")
 log.info("Daemon is running. Waiting for scheduled events…")

 stop = threading.Event()
Expand DownExpand Up@@ -682,7 +769,13 @@ def gql(query, variables=None):
# ---------------------------------------------------------------------------

def task_start_scheduler(stash, server_connection, settings):
 save_config(server_connection, settings)
 # Inject the API key into the saved connection dict so every daemon GQL
 # request includes it — required when Stash's "Require API key" is enabled.
 conn = dict(server_connection)
 api_key = settings.get("apiKey", "").strip()
 if api_key:
 conn["ApiKey"] = api_key
 save_config(conn, settings)
 kill_existing_daemon()
 launch_detached("--daemon")
 freq = settings["frequency"]
Expand DownExpand Up@@ -727,7 +820,7 @@ def task_run_now(stash, settings, force_identify=False):
def task_check_status(stash):
 alive, pid = daemon_alive()
 status_line = f"Daemon: RUNNING (PID {pid})" if alive else "Daemon: NOT RUNNING"
 recent = tail_log(30)
 recent = tail_log(100)
 output = f"{status_line}\nLog file: {LOG_FILE}\n\nRecent log ({LOG_FILE}):\n{recent}"
 stash.log.info(f"[Stash Scheduler] {status_line}")
 print(json.dumps({"output": output}))
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Universal Dark Mode - works on any site
(function() {
var enabled = true;
function applyDarkMode() {
if (!enabled) return;
// Create style element if it doesn't exist
var style = document.getElementById('universal-dark-mode-style');
if (!style) {
style = document.createElement('style');
style.id = 'universal-dark-mode-style';
document.head.appendChild(style);
}
// Dark mode CSS - inverts colors but preserves images/video
style.textContent = '
/* Invert everything except media */
html {
filter: invert(1) hue-rotate(180deg) !important;
background: #1a1a2e !important;
}
/* Restore images, videos, iframes, canvas */
img, video, iframe, canvas, svg, picture, [style*="background-image"] {
filter: invert(1) hue-rotate(180deg) !important;
}
/* Preserve specific elements that should not be inverted */
.no-dark-mode, .no-dark-mode *,
[data-theme="light"], [data-theme="light"],
.ace_editor, .ace_editor *,
.CodeMirror, .CodeMirror *,
.monaco-editor, .monaco-editor *,
.markdown-body pre, .markdown-body pre *,
.highlight, .highlight *,
pre code, pre code * {
filter: none !important;
}
/* Fix common UI elements */
.modal, .popup, .dropdown-menu, .tooltip, .popover {
filter: invert(1) hue-rotate(180deg) !important;
background: #2d2d44 !important;
border-color: #444 !important;
}
/* Scrollbars */
::-webkit-scrollbar { background: #1a1a2e !important; }
::-webkit-scrollbar-thumb { background: #444 !important; }
::-webkit-scrollbar-thumb:hover { background: #555 !important; }
/* Selection */
::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }
::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }
';
}
function removeDarkMode() {
var style = document.getElementById('universal-dark-mode-style');
if (style) style.remove();
}
// Toggle with Alt+Shift+D
document.addEventListener('keydown', function(e) {
if (e.altKey && e.shiftKey && e.key === 'D') {
e.preventDefault();
enabled = !enabled;
if (enabled) {
applyDarkMode();
console.log('[Universal Dark Mode] Enabled');
} else {
removeDarkMode();
console.log('[Universal Dark Mode] Disabled');
}
}
});
// Apply on load
applyDarkMode();
// Re-apply on dynamic content
var observer = new MutationObserver(function(mutations) {
if (enabled && !document.getElementById('universal-dark-mode-style')) {
applyDarkMode();
}
});
observer.observe(document.head, { childList: true });
console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');
})();
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();
Add API Authentication and additional scan scheduling options by dscisci · Pull Request #711 · stashapp/CommunityScripts · GitHub
Skip to content
Add API Authentication and additional scan scheduling options#711

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Open

dscisci
wants to merge
3
commits into

base:main
Choose a base branch

from

 Open


Add API Authentication and additional scan scheduling options
#711
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


3 commits


Select commit
Hold shift + click to select a range
9b0e6c9

Add files via upload


dscisci May 1, 2026
5ad5f71

Add files via upload


dscisci May 12, 2026
612e9ff

Merge branch 'main' into main


dscisci May 12, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


9 changes: 6 additions & 3 deletions
plugins/stash-scheduler/README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,7 +1,5 @@
# Stash Scheduler Plugin

https://discourse.stashapp.cc/t/stash-scheduler/7059
@DogmaDragonDogmaDragonMay 13, 2026

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Must be retained.

A plugin for [Stash](https://github.com/stashapp/stash) that automatically runs library scans on a schedule (hourly, daily, or weekly), with an optional identify pass after each scan.

---
Expand DownExpand Up@@ -83,8 +81,9 @@ Open **Settings → Plugins → Stash Scheduler** and set your preferences:

| Setting | Description | Default |
|---|---|---|
| **API Key** | Stash API key for authenticating background scans. Required when "Require API key" is enabled in Stash's Security settings. Generate one under Settings > Security > API Keys. Leave blank if Stash does not require authentication. | *(none)* |
| **Scan Frequency** | `hourly`, `daily`, or `weekly` | `daily` |
| **Time of Day (HH:MM)** | Time to run the scan in 24-hour `HH:MM` format. Used by Daily and Weekly; ignored for Hourly. | `02:00` |
| **Time of Day (HH:MM)** | One or more times to run the scan, in 24-hour `HH:MM` format. Separate multiple times with commas or spaces, e.g. `00:00, 06:00, 18:00`. Used by Daily and Weekly; ignored for Hourly. | `02:00` |
| **Day of Week** | Day to scan when Frequency is Weekly. Use `mon`, `tue`, `wed`, `thu`, `fri`, `sat`, or `sun`. | `sun` |
| **Timezone** | IANA timezone name for interpreting Time of Day and Day of Week. Examples: `America/New_York`, `Europe/London`, `Asia/Tokyo`. Leave blank for UTC. | `UTC` |
| **Run Identify After Scan** | When enabled, runs an Identify task after each scan finishes successfully. | `false` |
Expand DownExpand Up@@ -296,6 +295,10 @@ All activity is written to the Stash log. To view it:

| Version | Notes |
|---|---|
| 0.10.0 | Added API Key setting — required when Stash's "Require API key" security option is enabled |
| 0.9.0 | Daemon now reloads settings from Stash on every scheduled run — changes to identify, paths, and scan flags take effect without restarting the scheduler |
| 0.8.0 | Fixed identify not running after scan (null fields in GraphQL input); fixed daemon losing Stash connection after restart; added APScheduler error logging, hourly heartbeat, and next-fire-time logging; Check Status now shows 100 log lines |
| 0.7.0 | Time of Day now accepts multiple times (comma or space separated) — each fires a separate scheduled scan |
| 0.6.0 | Added "Limit to Paths" setting — scan and identify can now be restricted to specific directories |
| 0.5.0 | Fixed identify-after-scan (null jobQueue crash); added 9 scan generation flag settings (covers, previews, sprites, phashes, thumbnails, clip previews, force rescan) |
| 0.4.0 | Added Check Status task; daemon logs written to file (`/tmp/stash-scheduler-daemon.log`) |
Expand Down

21 changes: 16 additions & 5 deletions
plugins/stash-scheduler/stash-scheduler.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
name: Stash Scheduler
description: Schedule automatic library scans with an optional identify pass after each scan.
version: "0.6.0"
url: https://discourse.stashapp.cc/t/stash-scheduler/7059
@DogmaDragonDogmaDragonMay 13, 2026

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Must be retained.
version: "0.10.0"
url: https://github.com/stashapp/stash

exec:
 - python3
Expand DownExpand Up@@ -42,6 +42,16 @@ tasks:
 mode: check_status

settings:
 apiKey:
@DogmaDragonDogmaDragonMay 13, 2026

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why not just check for authentication and get the API key from configuration query using GraphQL if it's available?
 displayName: API Key
 description: >
 Stash API key for authenticating background scans. Required when
 Settings > Security > "Require API key for local connections" is enabled,
 or when accessing Stash over a network. Generate a key under
 Settings > Security > API Keys, then paste it here. Leave blank if
 Stash does not require authentication.
 type: STRING

 frequency:
 displayName: Scan Frequency
 description: >
Expand All@@ -53,9 +63,10 @@ settings:
 time_of_day:
 displayName: Time of Day (HH:MM)
 description: >
 The time to run the scan in 24-hour HH:MM format. Used for Daily and
 Weekly schedules; ignored for Hourly. Examples: 02:00, 14:30, 20:45.
 Defaults to 02:00 if not set.
 One or more times to run the scan in 24-hour HH:MM format. Used for
 Daily and Weekly schedules; ignored for Hourly. Separate multiple times
 with commas or spaces. Examples: 02:00 — single daily run. 00:00, 06:00,
 09:00, 16:00, 18:00 — five runs per day. Defaults to 02:00 if not set.
 type: STRING

 day_of_week:
Expand Down

153 changes: 123 additions & 30 deletions
plugins/stash-scheduler/stash_scheduler.py

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -142,6 +142,7 @@ def get_plugin_settings(stash, plugin_id="stash-scheduler"):
 "time_of_day": "02:00",
 "day_of_week": "sun",
 "timezone": "UTC",
 "apiKey": "",
 "run_identify": False,
 "identify_timeout_minutes": 120,
 # Comma- or newline-separated list of paths to restrict scan + identify.
Expand All@@ -168,19 +169,38 @@ def get_plugin_settings(stash, plugin_id="stash-scheduler"):
 return defaults


def _parse_time_of_day(raw, warn):
 raw = str(raw).strip()
def _parse_single_time(token, warn):
 """Parse one HH:MM token. Returns (hour, minute) or None on error."""
 token = str(token).strip()
 try:
 parts = raw.split(":")
 parts = token.split(":")
 if len(parts) != 2:
 raise ValueError("expected HH:MM")
 hh, mm = int(parts[0]), int(parts[1])
 if not (0 <= hh <= 23 and 0 <= mm <= 59):
 raise ValueError(f"values out of range: {hh}:{mm:02d}")
 return hh, mm
 except (ValueError, TypeError) as exc:
 warn(f"[Stash Scheduler] Invalid time_of_day {raw!r} ({exc}) — defaulting to 02:00.")
 return 2, 0
 warn(f"[Stash Scheduler] Invalid time {token!r} ({exc}) — skipping.")
 return None


def _parse_times_of_day(raw, warn):
 """Parse comma/space/newline-separated HH:MM times.
 Returns a deduplicated list of (hour, minute) tuples, sorted ascending.
 Falls back to [(2, 0)] if nothing valid is found."""
 import re as _re
 tokens = [t for t in _re.split(r"[\s,]+", str(raw).strip()) if t]
 results, seen = [], set()
 for token in tokens:
 parsed = _parse_single_time(token, warn)
 if parsed is not None and parsed not in seen:
 results.append(parsed)
 seen.add(parsed)
 if not results:
 warn("[Stash Scheduler] No valid times found in time_of_day — defaulting to 02:00.")
 return [(2, 0)]
 return sorted(results)


def validate_and_coerce_settings(settings, warn):
Expand All@@ -194,10 +214,11 @@ def validate_and_coerce_settings(settings, warn):
 settings["frequency"] = freq

 raw_time = settings.get("time_of_day", "02:00")
 hour, minute = _parse_time_of_day(raw_time, warn)
 settings["time_of_day"] = f"{hour:02d}:{minute:02d}"
 settings["hour"] = hour
 settings["minute"] = minute
 times = _parse_times_of_day(raw_time, warn)
 settings["times_of_day"] = times
 settings["time_of_day"] = ", ".join(f"{h:02d}:{m:02d}" for h, m in times)
 settings["hour"] = times[0][0]
 settings["minute"] = times[0][1]

 dow = str(settings.get("day_of_week", "sun")).strip().lower()
 if dow not in VALID_DAYS:
Expand DownExpand Up@@ -233,6 +254,9 @@ def validate_and_coerce_settings(settings, warn):
 tz_raw = "UTC"
 settings["timezone"] = tz_raw

 # apiKey — strip whitespace; empty string means no key (session auth)
 settings["apiKey"] = str(settings.get("apiKey", "") or "").strip()

 # scanPaths — parse comma/newline-separated string into a clean list
 raw_paths = str(settings.get("scanPaths", "") or "")
 import re as _re
Expand All@@ -254,6 +278,16 @@ def validate_and_coerce_settings(settings, warn):
# Scan / Identify helpers (used by both plugin tasks and the daemon)
# ---------------------------------------------------------------------------

def _strip_nulls(obj):
 """Recursively remove None/null values from a dict or list.
 Required before forwarding a GraphQL query result back as mutation input —
 Stash rejects null on required sub-fields."""
 if isinstance(obj, dict):
 return {k: _strip_nulls(v) for k, v in obj.items() if v is not None}
 if isinstance(obj, list):
 return [_strip_nulls(i) for i in obj]
 return obj

_SCAN_FLAGS = (
 "scanGenerateCovers",
 "scanGeneratePreviews",
Expand DownExpand Up@@ -333,9 +367,12 @@ def trigger_identify(stash_or_log, gql_fn, paths=None):
 paths_desc = f" (paths: {', '.join(paths)})" if paths else " (full library)"
 _log_info(stash_or_log, f"[Stash Scheduler] Triggering identify task{paths_desc}…")
 try:
 identify_input = {"sources": identify["sources"]}
 # Strip nulls: the query returns the full schema object including null
 # sub-fields; forwarding those nulls into the mutation causes Stash to
 # reject the request with a schema validation error.
 identify_input = {"sources": _strip_nulls(identify["sources"])}
 if identify.get("options"):
 identify_input["options"] = identify["options"]
 identify_input["options"] = _strip_nulls(identify["options"])
 if paths:
 identify_input["paths"] = paths
 result = gql_fn(IDENTIFY_MUTATION, {"input": identify_input})
Expand DownExpand Up@@ -528,7 +565,7 @@ def daemon_alive():
 return False, None


def tail_log(n=30):
def tail_log(n=100):
 """Return the last n lines of the daemon log file as a string."""
 if not os.path.exists(LOG_FILE):
 return "(log file not found)"
Expand DownExpand Up@@ -572,46 +609,82 @@ def run_daemon():
 sys.exit(1)

 frequency = settings["frequency"]
 hour = settings["hour"]
 minute = settings["minute"]
 times_of_day = settings["times_of_day"]
 day_of_week = settings["day_of_week"]
 timezone = settings["timezone"]
 run_identify = settings["run_identify"]
 identify_timeout = settings["identify_timeout_minutes"]
 scan_paths = settings.get("scan_paths") or []

 # Build a simple GQL callable for the daemon (not stash.log-based)
 def gql(query, variables=None):
 return call_gql(stash, query, variables)

 def scheduled_job():
 """Fired by APScheduler for each scheduled time slot."""
 log.info("Scheduled scan cycle firing.")
 # Fresh connection each run — guards against stale sessions after a
 # Stash restart.
 try:
 job_id = trigger_scan(log, gql, settings)
 fresh_stash = make_stash(cfg["server_connection"])
 def gql(query, variables=None):
 return call_gql(fresh_stash, query, variables)
 except Exception as exc:
 log.error(f"Scan failed: {exc}")
 log.error(f"Cannot connect to Stash for scheduled scan: {exc}")
 return
 if run_identify:

 # Reload operational settings live from Stash so changes to
 # run_identify, scan_paths, scan flags, etc. take effect immediately
 # without needing to restart the daemon.
 try:
 live_settings = validate_and_coerce_settings(
 get_plugin_settings(fresh_stash),
 lambda m: log.warning(m),
 )
 log.info(
 f"Settings reloaded — identify: {'yes' if live_settings['run_identify'] else 'no'}, "
 f"paths: {', '.join(live_settings.get('scan_paths') or []) or 'full library'}"
 )
 except Exception as exc:
 log.warning(f"Could not reload settings from Stash — using startup settings: {exc}")
 live_settings = settings

 try:
 job_id = trigger_scan(log, gql, live_settings)
 except Exception as exc:
 log.error(f"Scan trigger failed: {exc}")
 return

 if live_settings["run_identify"]:
 live_timeout = live_settings["identify_timeout_minutes"]
 live_paths = live_settings.get("scan_paths") or None
 threading.Thread(
 target=wait_for_scan_and_identify,
 args=(log, gql, job_id, identify_timeout, scan_paths or None),
 args=(log, gql, job_id, live_timeout, live_paths),
 daemon=True,
 ).start()

 def heartbeat_job():
 """Fires every hour so the log shows the daemon is still alive."""
 log.info("[heartbeat] Daemon alive.")

 scheduler = BackgroundScheduler(timezone=timezone)
 job_kwargs = {"func": scheduled_job, "misfire_grace_time": 3600, "coalesce": True}

 times_str = ", ".join(f"{h:02d}:{m:02d}" for h, m in times_of_day)
 if frequency == "hourly":
 scheduler.add_job(trigger="cron", minute=0, **job_kwargs)
 log.info(f"Schedule: every hour at :00 ({timezone})")
 elif frequency == "weekly":
 scheduler.add_job(
 trigger="cron", day_of_week=day_of_week, hour=hour, minute=minute, **job_kwargs
 )
 log.info(f"Schedule: weekly {day_of_week.upper()} at {hour:02d}:{minute:02d} ({timezone})")
 for h, m in times_of_day:
 scheduler.add_job(
 trigger="cron", day_of_week=day_of_week, hour=h, minute=m, **job_kwargs
 )
 log.info(f"Schedule: weekly {day_of_week.upper()} at {times_str} ({timezone})")
 else:
 scheduler.add_job(trigger="cron", hour=hour, minute=minute, **job_kwargs)
 log.info(f"Schedule: daily at {hour:02d}:{minute:02d} ({timezone})")
 for h, m in times_of_day:
 scheduler.add_job(trigger="cron", hour=h, minute=m, **job_kwargs)
 log.info(f"Schedule: daily at {times_str} ({timezone})")

 # Hourly heartbeat so the log proves the daemon is ticking even between scans
 scheduler.add_job(func=heartbeat_job, trigger="cron", minute=0,
 misfire_grace_time=3600, coalesce=True)

 log.info(f"Identify after scan: {'yes' if run_identify else 'no'}")

Expand All@@ -626,7 +699,21 @@ def scheduled_job():
 else:
 log.info("Scan flags: none (bare scan)")

 # Log APScheduler execution errors so silent job failures are visible
 from apscheduler.events import EVENT_JOB_ERROR, EVENT_JOB_EXECUTED, EVENT_JOB_MISSED
 def _aps_listener(event):
 if event.exception:
 log.error(f"[APScheduler] Job {event.job_id} raised an exception: {event.exception}")
 elif hasattr(event, 'scheduled_run_time') and not hasattr(event, 'retval'):
 log.warning(f"[APScheduler] Job {event.job_id} missed its scheduled time.")
 scheduler.add_listener(_aps_listener, EVENT_JOB_ERROR | EVENT_JOB_MISSED)

 scheduler.start()

 # Log next fire times so the log confirms jobs are registered correctly
 for job in scheduler.get_jobs():
 if job.next_run_time:
 log.info(f"Next fire for job '{job.id}': {job.next_run_time}")
 log.info("Daemon is running. Waiting for scheduled events…")

 stop = threading.Event()
Expand DownExpand Up@@ -682,7 +769,13 @@ def gql(query, variables=None):
# ---------------------------------------------------------------------------

def task_start_scheduler(stash, server_connection, settings):
 save_config(server_connection, settings)
 # Inject the API key into the saved connection dict so every daemon GQL
 # request includes it — required when Stash's "Require API key" is enabled.
 conn = dict(server_connection)
 api_key = settings.get("apiKey", "").strip()
 if api_key:
 conn["ApiKey"] = api_key
 save_config(conn, settings)
 kill_existing_daemon()
 launch_detached("--daemon")
 freq = settings["frequency"]
Expand DownExpand Up@@ -727,7 +820,7 @@ def task_run_now(stash, settings, force_identify=False):
def task_check_status(stash):
 alive, pid = daemon_alive()
 status_line = f"Daemon: RUNNING (PID {pid})" if alive else "Daemon: NOT RUNNING"
 recent = tail_log(30)
 recent = tail_log(100)
 output = f"{status_line}\nLog file: {LOG_FILE}\n\nRecent log ({LOG_FILE}):\n{recent}"
 stash.log.info(f"[Stash Scheduler] {status_line}")
 print(json.dumps({"output": output}))
Expand Down
Loading