SPT Check Mods Extended

A .NET 10 console and web application that validates Single Player Tarkov (SPT) mod compatibility using the Forge API.

Acknowledgments

CheckModsExtended began as a fork of Refringe's SPT Check Mods (v1.2.1, MIT License). The original repository and SPT Forge listing are no longer publicly hosted. Thank you to Refringe for their foundational work in the SPT modding community.

For a detailed list of architectural changes and features introduced in this fork, please read Architectural & Feature Additions.

Features

• Forge API Integration: Verifies mods against the official SPT Forge database
• Version Compatibility: Checks installed mod versions against SPT version requirements
• Update Detection: Identifies mods with available updates and provides download links
• Mod Updating & Rollback: Downloads, verifies, backs up, and installs mod updates from .zip, .7z, and .rar archives while preserving existing user configuration files (.new files and added-key diffs) and retaining up to 3 rollback backups per mod
• Dependency Analysis: Builds dependency trees, identifies missing dependencies, and detects conflicts
• Installation Checks: Detects mods installed in the wrong folder, reports them in the CLI and Web Manager GUI, and excludes them from the rest of the run
• Mod Match Confirmation: Confirm or reject fuzzy Forge API mod matches via the Web Manager or interactive CLI, with confirmed matches saved locally and enriched immediately
• Dismissable Update Prompts: Lets you ignore false-positive "update available" prompts for mods whose files are already current, with an optional shared community list
• SPT & Self-Update Checking: Notifies you when new SPT versions or CheckModsExtended app versions are available
• Web Manager GUI: An offline-capable, locally hosted split-view web workspace with faceted status and scope filtering, an 8-column mod grid with SemVer diff badges (MAJOR/MINOR/PATCH), a 4-tab docked inspector (Overview, Dependencies, Updater, Backups), dry-run update previews, single and batch mod updating with .new configuration diff notices, backup rollback, runtime SPT path switching, and Discord support report export
• Offline CLI Commands: Terminal commands allowing you to view and manage your mod list without an internet connection
• Security Analysis: Statically extracts metadata without executing any underlying mod code
• Parallel Scanning: Checks mods concurrently while respecting Forge API network limits
• Fallback Links: Attempts to extract fallback GitHub links directly from local files if a mod is missing from the Forge API

Requirements

• A valid SPT 4.0 or 4.1+ installation (supports both <GameRoot>/SPT and SPT 4.1 <GameRoot>/SPT_Runtime split layouts)
• .NET 10.0 SDK (only required when building from source; standalone release binaries are Native AOT compiled)
• System tar (bsdtar) command on PATH for .7z and .rar archive extraction (included with Windows 10/11 and standard Linux/macOS installs). .zip and .tar.gz/.tgz archives are extracted natively.

Installation

Option 1: Download Release

Download and extract the latest release archive for your operating system (CheckModsExtended-win-x64.zip, CheckModsExtended-linux-x64.zip, CheckModsExtended-linux-arm64.zip, or CheckModsExtended-osx-arm64.zip) from the Releases page.

• Windows: Extract CheckModsExtended-win-x64.exe into the root of your SPT installation directory.
• Linux / macOS: Extract the binary into your SPT directory and make it executable: chmod +x CheckModsExtended-linux-x64.

Option 2: Build from Source

git clone https://github.com/TerribleTurtle/CheckModsExtended.git
cd CheckModsExtended
dotnet build CheckModsExtended.slnx

Usage

Web Manager GUI (Default)

The Web Manager GUI is the default execution mode. Double-click the executable (or run it without arguments) to open the web dashboard in your default browser on http://localhost:37194.

# Windows
CheckModsExtended-win-x64.exe
# Or explicitly specify the GUI mode with a custom SPT directory:
CheckModsExtended-win-x64.exe gui "/path/to/spt"

# Linux
./CheckModsExtended-linux-x64

From the Web Manager GUI, you can:

• Switch and validate the active SPT installation path at runtime without restarting the server
• Run a full Forge API compatibility scan (RESCAN MODS) or an offline local disk scan (LOCAL SCAN)
• Monitor live scan progress with phase indicators, item counters, active mod names, and Forge API rate-limit cooldown timers
• Filter mods by status (All, Updates Ready, Blocked, Incompatible, Needs Confirmation, Up to Date, Unknown, Ignored) and scope (All, Server, Client, Paired)
• Inspect mod metadata (Forge ID, GUID, target SPT version, load warnings, duplicate alerts, fallback GitHub source links), dependency chains, conflict badges, blocking constraints, and fuzzy Forge API match candidates in the docked side inspector
• Run dry-run update previews (planned file changes, target cleanup directories, and .new configuration key diffs) and install single, selected-batch, or all safe mod updates
• Create on-demand mod backup archives (per-mod via Create Backup in the Inspector Backups tab, in batch via Backup Selected in the selection bar, or across your entire installation via Backup All Mods in the BACKUPS modal) and restore any backup from the Backups tab
• Manage ignored mod updates with All / User / Community source filtering and search in the IGNORED modal
• Export diagnostic log archives (DIAGNOSTICS), reset application caches (SETTINGS → Clear Cache & Reset State), and generate formatted Discord support summaries, Markdown tables, JSON exports, or plain mod lists (DISCORD SUPPORT)

Command Line Interface (CLI)

The executable acts as a hybrid CLI and web server. If you pass any arguments (or explicitly pass cli), it runs in terminal mode without launching the web server.

To run the default update check in the current directory:

CheckModsExtended-win-x64.exe cli

You can also point it at an SPT installation elsewhere by passing the path:

CheckModsExtended-win-x64.exe "/path/to/spt"

./CheckModsExtended-linux-x64 "/path/to/spt"

If you built from source, use dotnet run --project src/CheckModsExtended from the repository root. The -- passes arguments through to the application rather than to the .NET CLI:

# Run the CLI and point to your SPT installation directory
dotnet run --project src/CheckModsExtended -- /path/to/spt

To run non-interactively (e.g. for CI or scripts), use --no-prompt:

CheckModsExtended-win-x64.exe --no-prompt

For automated scripts or server startup checks, use --fail-on and -t|--type:

# Exit with code 4 if any server mod is incompatible or missing dependencies
CheckModsExtended-win-x64.exe cli "/path/to/spt" -y --type server --fail-on incompatible

CLI Commands

CheckModsExtended provides subcommands for automated checking, updating, rollback, diagnostics, and mod listing.

Updating & Rolling Back Mods

CheckModsExtended downloads, verifies, backs up, and installs mod updates while preserving existing user configurations:

• Archive Extraction: .zip and .tar.gz/.tgz archives are extracted natively. Extraction of .7z and .rar archives uses the system tar (bsdtar) command on PATH (included with Windows 10/11 and standard Linux/macOS installs).
• Configuration Preservation: Existing configuration files (BepInEx/config/**, user/mods/<Mod>/config/**, *.cfg, config*.json*, settings*.json*) are never overwritten. If an updated mod archive includes a modified default configuration file, your existing file is kept and the incoming default is written alongside it as <filename>.new with any newly added keys listed in the summary.
• Rollback Backups: Up to 3 backup archives are retained per mod in <AppData>/backups. You can create a manual backup snapshot without rolling back using rollback -c|--create [<MOD>], list backups using rollback -l|--list, or restore a previous version using rollback -m|--mod <ID_OR_NAME> or --file <PATH>.

Command-Line Options

The application supports the following subcommands and options:

• Update Mods: Downloads, verifies, backs up, and installs available mod updates while preserving existing user configuration files.

  CheckModsExtended-win-x64.exe update [SptPath] [OPTIONS]

  Options:

  • -a, --all: Install all safe mod updates
  • -m, --mod <ID_OR_NAME>: Update a specific mod by Forge API ID, GUID, or name
  • -t, --type <TYPE>: Component filter (all, server, or client; defaults to all)
  • --dry-run: Preview planned file actions and configuration diffs without modifying disk
  • --keep-extra-files, --in-place: Extract over the existing directory without removing unmatched files
  • --no-backup: Skip creating a pre-update backup archive
  • -f, --format <TYPE>: Output format (table, json, csv)

• Rollback Mods: Creates on-demand mod backups or restores a mod from its backup archive (up to 3 backups are retained per mod in <AppData>/backups).

  CheckModsExtended-win-x64.exe rollback [SptPath] [OPTIONS]

  Options:

  • -m, --mod <ID_OR_NAME>: Mod Forge API ID, GUID, or name to back up or roll back (restores the most recent backup or backs up all mods when --create is passed without --mod)
  • -c, --create: Create a manual backup snapshot without rolling back (for <MOD> or all installed mods if omitted)
  • -l, --list: List available backups without restoring
  • --file <PATH>: Restore from a specific backup .zip file path
  • -f, --format <TYPE>: Output format (table, json, csv)

• List Local Mods: Prints a table (or json/csv via -f|--format) of locally installed client and server mods without checking the internet for updates.

  CheckModsExtended-win-x64.exe list [SptPath]

  Options:

  • -t, --type <TYPE>: Filter by type (server, client)
  • --sort <SORT>: Sort by field (name, author, version, type)
  • -l, --limit <LIMIT>: Limit the number of results
  • --search <SEARCH>: Search by text
  • -f, --format <TYPE>: Output format (table, json, csv)

• Ignore List Management: View or manage mods you don't want to receive update notifications for.

  CheckModsExtended-win-x64.exe ignore list

  Options:

  • --source <SOURCE> (or -s, --status <SOURCE>): Filter by source (User, Remote, or Community)
  • --sort <SORT>: Sort by field (id, name, localversion, ignoredversion, source)
  • -l, --limit <LIMIT>: Limit the number of results
  • --search <SEARCH>: Search by name or API mod ID
  • -f, --format <TYPE>: Output format (table, json, csv)

  CheckModsExtended-win-x64.exe ignore add <ApiModId> <LocalVersion> <LatestVersion>

  CheckModsExtended-win-x64.exe ignore remove <ApiModId>

• Clean Up: Manage local app data (clears configuration overrides, ignored updates, confirmed matches, scan cache, and logs).

  CheckModsExtended-win-x64.exe clean

• Diagnostics: Zip and export the application's log files from AppData for sharing.

  CheckModsExtended-win-x64.exe diag [OPTIONS]

  Options:

  • -o, --output <PATH>: Custom output directory or .zip file path for the exported diagnostic bundle

• License: Display the application license.

  CheckModsExtended-win-x64.exe license

Global Options:

• -v or --verbose: Enables verbose logging output.
• -d or --debug: Enables debug logging output (includes stack traces).
• -f or --format <TYPE>: Sets output format (table, json, csv).
• -y or --no-prompt: Runs headless without interactive prompts.

Exit Codes

• 0: Execution succeeded.
• 1: Invalid SPT installation path or unrecognized SPT version.
• 2: Unhandled error or failed update/rollback/diagnostic operation.
• 3: User requested exit during an interactive prompt.
• 4: Incompatible mods or missing/conflicting dependencies detected (when --fail-on incompatible or --fail-on outdated is specified).
• 5: Available mod updates detected (when --fail-on outdated is specified).

Troubleshooting

You can override application settings using environment variables. This is useful for debugging or configuring network behavior.

Enable Debug Logging:

# Windows CLI
set LoggingOptions__MinimumLogLevel=Debug
CheckModsExtended-win-x64.exe

# Windows PowerShell
$env:LoggingOptions__MinimumLogLevel="Debug"
.\CheckModsExtended-win-x64.exe

# Linux CLI with custom log level
LoggingOptions__MinimumLogLevel=Debug ./CheckModsExtended-linux-x64

Configuration

Local Storage

CheckModsExtended keeps its data under %APPDATA%\SptCheckModsExtended (Windows) or ~/.config/SptCheckModsExtended (Linux):

• Logs: logs\checkmod.log (within the app data directory)
• Ignored updates: ignored-updates.json (within the app data directory)
• Confirmed matches: confirmed-matches.json (within the app data directory)
• Scan cache: scan_cache.json (within the app data directory)
• Mod backups: backups\ (within the app data directory; retains up to 3 .zip backup archives per mod)
• User configuration: appsettings.user.json (within the app data directory)

Note on Telemetry: When a community shared ignore list URL is configured (IgnoredUpdateOptions__RemoteUrl) and enabled, CheckModsExtended makes a remote HTTP GET request to that URL to fetch suppressed updates. You can disable this at any time by setting IgnoredUpdateOptions__RemoteUrl="".

Supported Mod Formats

• Server Mods: SPT mods with AbstractModMetadata (including .dll files in subdirectories) or package.json in SPT/user/mods (SPT 4.0) or SPT_Runtime/user/mods (SPT 4.1)
• Client Mods: BepInEx plugins with BepInPlugin attribute in BepInEx/plugins (and companion preloader patchers in BepInEx/patchers)

Issues & Feedback

Bug reports, issues, and suggestions are welcome via the GitHub Issue tracker.

Please note that this is primarily a personal fork. While feedback and community input are appreciated, I do not maintain an active community presence and may not respond quickly to pull requests or feature ideas. Feel free to use and modify the code as you see fit. For contribution guidelines and verification workflows, see CONTRIBUTING.md.

Security

Release Integrity
All binary releases attached to this repository are verified through automated CI checks:

• Build Provenance: Every release includes a GitHub Artifact Attestation that cryptographically signs the binary, verifying it was built directly from this repository's actions.
• VirusTotal Scanning: Every release archive is uploaded to VirusTotal and scanned by 70+ antivirus engines. A link to the scan report is appended to the release notes.
• Checksums: SHA256 checksums are generated and provided alongside the releases for manual verification.

For general security concerns, please review the Security Policy.

For details regarding static assembly inspection and AssemblyLoadContext behavior, please read the Security Advisory.

License

This project is licensed under the MIT License - see the LICENSE file for details. See THIRD-PARTY-NOTICES.md for third-party open-source notices.