Spargine Dev Tool — Overview

What Is It?

Spargine Dev Tool is a Windows .NET 10 command-line utility designed to help developers keep their machines clean, their source code backed up, and their projects healthy. It provides the following primary operations:

Command	Purpose
audit	Scans for dead solution/project references and large ignored-style assets (.suo, *.user, bin/, obj/).
backup	Backs up Visual Studio solution folders to a configurable destination (OneDrive or local).
clean	Deletes temporary and cached files generated by Visual Studio, .NET SDK, SQL Server, NuGet, Azure tooling, JetBrains tools, and Windows.
disk	Reports largest disk consumers for development artifacts: NuGet package cache, Docker images/volumes, bin/obj folders, and global tools.
env	Prints a structured .NET environment report: installed SDKs, runtimes, global tools, detected IDEs, and PATH anomalies.
git-status	Scans a root path for git repositories and reports uncommitted changes, unpushed commits, behind-remote status, and branch naming drift from main/master.
gitignore	Diffs the repo’s .gitignore against the GitHub Visual Studio template and reports missing rules. Optionally merges them.
graph	Scans a solution’s project-to-project references and exports a Mermaid (default) or GraphViz DOT dependency diagram to the console and a file.
health	Analyzes .NET projects for health issues: outdated TFMs, vulnerable/outdated NuGet packages, and missing MSBuild properties.
metrics	Runs dotnet build and dotnet list package, captures warning/error/vulnerability counts, persists a rolling JSON trend file, and renders a trend table so engineers can monitor code-quality direction over time.
nuget	Scans project files for NuGet package version mismatches across projects, optionally consolidates all references to the highest detected version, and optionally clears all local NuGet caches.
secrets	Scans for developer certificate expiry, certificate files (.pfx, .cer, .p12) near expiration, and sensitive secret files (.env, secrets.json) that should not be committed to source control.

---

Commands

Saving reports: Every report-producing command (audit, disk, env, git-status, health, metrics, nuget, secrets) supports a common --output <FILE> flag.

audit — Dead Code / Asset Scanner

Scans a root directory and reports repository/solution hygiene issues across three categories:

1. Missing solution project references
   • Finds .sln entries that reference .csproj, .vbproj, or .fsproj files that no longer exist.
2. Orphaned project folders
   • Finds project folders (any folder containing a .csproj/.vbproj/.fsproj) that are not referenced by any discovered .sln file.
3. Large ignored-style assets
   • Finds files >= 1 MB that are typically expected to be ignored by source control:
     • *.suo
     • *.user
     • anything under bin/
     • anything under obj/

Arguments

Argument	Description
[PATH]	Root path to scan recursively. Defaults to the current directory.

Options

Option	Description
--output <FILE>	Also save the report to this file (.md/.markdown for Markdown).

Examples

# Audit current directory
spargine audit

# Audit a specific root
spargine audit C:\src

# Audit and save the report as Markdown
spargine audit C:\src --output audit-report.md

Output

The command renders up to three tables (one per issue category):

• Missing Solution Project References
• Orphaned Project Folders
• Large Ignored-Style Assets (>= 1 MB)

If no findings exist, it prints a success message. A summary count for each issue category and total scan duration are always shown.

---

backup — Back Up Source Code

Scans fixed drives for Visual Studio solution roots and copies them to a backup destination. The backup destination is resolved automatically in the following priority order:

1. OneDrive for Business folder (if present) → <OneDrive>\Backup
2. Personal OneDrive folder (if present) → <OneDrive>\Backup
3. Local fallback → %USERPROFILE%\AppData\Local\Spargine\Backup

Backup folders are organized as:

<BackupRoot>\<MACHINENAME>\<USERNAME>\<MODE>\<TIMESTAMP>\

Options

Option	Alias	Description
--turbo		Turbo mode: only backs up files with the Archive attribute set (i.e. changed since last backup). Clears the Archive attribute after copying.
--rescan		Forces a re-scan of all fixed drives for new solution roots, regardless of when the last scan ran (normally re-scans every 7 days).
--af <PATH>	--addfolder	Adds a folder path to the backup configuration.
--rf <PATH>	--removefolder	Removes a folder path from the backup configuration.
--cleanprojects		After backing up, deletes obj, bin, and appbin subdirectories from detected solution roots.
--ecp	--enablecleanprojects	Marks newly added or re-enabled folders as project roots so --cleanprojects applies to them.
--verbosity <LEVEL>		Controls console output: quiet, minimal, normal, detailed, diagnostic.

Examples

# Standard full backup
spargine backup

# Turbo backup — changed files only
spargine backup --turbo

# Add a new folder to the backup list
spargine backup --addfolder "D:\MyProject"

# Remove a folder from the backup list
spargine backup --removefolder "D:\OldProject"

# Back up and clean build artifact directories
spargine backup --cleanprojects

# Force a drive re-scan for new solution roots
spargine backup --rescan

Drive Scan Behaviour

On the first run (and every 7 days thereafter, or whenever --rescan is passed), the tool:

1. Enumerates all fixed drives.
2. Skips well-known system paths (Windows, Program Files, Users, $Recycle.Bin, OneDrive sync roots, etc.).
3. Searches each top-level directory for files matching known project/solution extensions (.sln, .csproj, .vbproj, .fsproj, and many others).
4. Prompts interactively — one-by-one for fewer than 5 new folders, or via a multi-select list for 5 or more — to include or exclude each discovered root.

Declined folders are saved as disabled entries so they are not re-prompted on the next scan.

Backup Retention

Old backup folders are removed after 7 days. Read-only attributes are stripped before deletion to avoid access-denied errors.

---

clean — Clean Temp and Cache Files

Deletes temporary and cached files from a configurable list of folders.

Options

Option	Alias	Description
--turbobackup		Runs a turbo backup after cleaning.
--af <PATH>	--addfolder	Adds a folder to the clean list. --af and --rf are mutually exclusive.
--rf <PATH>	--removefolder	Removes a folder from the clean list. --af and --rf are mutually exclusive.
--verbosity <LEVEL>		Controls console output: quiet, minimal, normal, detailed, diagnostic.

Examples

# Standard clean
spargine clean

# Add a folder to the clean list
spargine clean --addfolder "C:\Temp\MyCache"

# Remove a folder from the clean list
spargine clean --removefolder "C:\Temp\OldCache"

# Back up changed files then clean
spargine clean --turbobackup

What Gets Cleaned

The cleaner targets the following categories of folders automatically on Windows:

Category	Examples
Windows OS	INetCache, WebCache, WER (error reports), Explorer thumbnail cache, %windir%\Temp
Visual Studio	ComponentModelCache, Designer\ShadowCache, DiagnosticsHub, VSApplicationInsights, VisualStudio Services, GitHubVisualStudio caches, VS backup files, VSFeedbackIntelliCodeLogs
IsolatedStorage	%LOCALAPPDATA%\IsolatedStorage
.NET SDK / MSBuild / NuGet	toolResolverCache, NuGetScratch, NuGetTemp, MSBuildTemp, NuGet\v3-cache
IIS Express	TraceLogFiles, Logs
SQL Server	SSMS backup files, RSTempFiles
ASP.NET	Temporary ASP.NET Files (all versions)
Azure tooling	Azure CLI logs, Azure Data Studio logs and cache, Azure Storage Emulator logs
JetBrains	ReSharper / Rider SolutionCaches and log folders (local and roaming)
Test / Coverage	Microsoft\CodeCoverage, *.coverage temp files
Crash dumps	%LOCALAPPDATA%\CrashDumps
Other	CryptnetUrlCache, Zscaler logs, CodeRush logs, SubMain cache

Process-Guarded Folders

Some folders are unsafe to delete while a related application is running. The cleaner checks for active processes before each run and automatically skips the following folders if their associated process is detected:

Process guard	Folders skipped
devenv (Visual Studio)	ComponentModelCache, Designer\ShadowCache, DiagnosticsHub, VSApplicationInsights, VisualStudio Services, GitHubVisualStudio\BlobCache, GitHubVisualStudio\GraphQLCache, IsolatedStorage, VSFeedbackIntelliCodeLogs
azuredatastudio	AzureDataStudio\logs, AzureDataStudio\CachedData

Folder Configuration Persistence

• The clean folder list is persisted to a configuration file.
• Folders added via --addfolder are saved and cleaned on every subsequent run until removed.
• If a configured folder no longer exists on disk it is skipped, not removed from the list, so it will be cleaned again if the path reappears later.

---

disk — Disk Usage Analyzer for Dev Artifacts

Reports the largest consumers of disk space specific to development artifacts across four sections, each rendered as an independent color-coded table:

1. NuGet package cache (~/.nuget/packages)

   • Recursively measures every package directory under the global cache.
   • Renders a rounded table of the top 10 packages by size, sorted largest first.
   • Prints a total size and package count summary below the table.

2. Global .NET tools (~/.dotnet/tools)

   • Lists every executable in the global tools directory with its individual file size.
   • Prints a total size summary below the table.

3. bin / obj folders (scan path)

   • Walks the specified root path recursively and measures every directory named bin or obj.
   • Renders the top 25 folders by size, sorted largest first.
   • Prints a total size and folder count summary below the table.

4. Docker (docker system df)

   • Runs docker system df if Docker is present on the system PATH.
   • Parses the output into a structured 5-column table: Type / Total / Active / Size / Reclaimable.
   • Multi-word type names (Local Volumes, Build Cache) are handled correctly.
   • Skipped gracefully with a status line if Docker is not found.

Arguments

Argument	Description
[PATH]	Root path to scan recursively for bin/obj folders. Defaults to the current directory.

Options

Option	Description
--output <FILE>	Also save the report to this file (.md/.markdown for Markdown).

Examples

# Scan current directory
spargine disk

# Scan a specific path
spargine disk C:\src

# Scan and save the report as Markdown
spargine disk C:\src --output disk-report.md

Output

Four TableBorder.Rounded tables are rendered in order: NuGet cache → global tools → bin/obj folders → Docker. Each section prints a size summary line beneath its table. A final line reports the total scan duration.

---

env — Environment Info Report

Prints a structured summary of the local .NET development environment, useful for bug reports, onboarding new machines, and verifying SDK/tooling consistency across a team.

What Gets Reported

Section	Details
Installed .NET SDKs	All SDK versions returned by dotnet --list-sdks, including the install path.
Installed .NET Runtimes	All runtime versions returned by dotnet --list-runtimes, including the install path.
Installed Global Tools	Package ID and version for every tool returned by dotnet tool list --global.
Detected IDEs	Visual Studio (via vswhere.exe), VS Code (via code --version), and JetBrains Rider (via known install paths). Includes name, version, and install location.
PATH Anomalies	Duplicate PATH entries, and whether a directory containing dotnet is present on the PATH.

Options

Option	Description
--output <FILE>	Also save the report to this file (.md/.markdown for Markdown).

Examples

# Print the full environment report
spargine env

# Print and save the report as Markdown
spargine env --output env-report.md

Output

Each section is rendered as a separate color-coded table. When a section has no entries (e.g., no global tools installed, no PATH anomalies) a “None found” or “No anomalies” message is shown in place of data rows. Report generation time is displayed at the end. The timestamp of the last run is persisted to the tool’s configuration file.

---

git-status — Git Repository Status Scanner

Walks a root directory recursively, finds all git repositories, and reports key status signals so you can quickly spot repos that need attention.

What Gets Reported

Signal	Details
Uncommitted changes	Whether the repository has local working tree changes (git status --porcelain).
Unpushed commits	Number of commits ahead of upstream (git rev-list --left-right --count @{u}...HEAD).
Behind remote	Number of commits behind upstream from the same comparison.
Branch name	Current branch name, with a flag when not on main or master.

The scanner performs a git fetch --all --prune per repo before ahead/behind comparison. When no upstream is configured (or fetch fails), ahead/behind values are shown as unknown.

Arguments

Argument	Description
[PATH]	Root path to scan recursively. Defaults to the current directory.

Options

Option	Description
--output <FILE>	Also save the report to this file (.md/.markdown for Markdown).

Examples

# Scan current directory tree
spargine git-status

# Scan a specific root folder
spargine git-status C:\src

Output

Results are rendered in a rounded table with columns for repository path, branch, uncommitted state, unpushed count, and behind count. A summary section follows, showing totals for:

• Repositories with uncommitted changes
• Repositories with unpushed commits
• Repositories behind remote
• Repositories not on main/master

Scan duration and last scan root/timestamp are persisted to configuration.

---

gitignore — .gitignore Enforcer

Fetches the GitHub-recommended Visual Studio .gitignore template and diffs it against the local .gitignore in the specified repository root. Missing rules are reported in a color-coded table grouped by template section. An optional --merge flag appends all missing rules to the existing file, preserving its original content.

What Gets Compared

The tool fetches the canonical template from:

https://raw.githubusercontent.com/github/gitignore/main/VisualStudio.gitignore

Any non-blank, non-comment line present in the template but absent from the local .gitignore is flagged as missing (case-insensitive comparison).

Options

Option	Description
--merge	Appends all missing rules to the local .gitignore, grouped under their original section comment headers. Original content is preserved.

Arguments

Argument	Description
[PATH]	Repository root path to check. Must contain a .gitignore file. Defaults to the current directory.

Examples

# Check the current directory
spargine gitignore

# Check a specific repo
spargine gitignore C:\src\MyRepo

# Report missing rules and merge them into the local .gitignore
spargine gitignore C:\src\MyRepo --merge

Output

Missing rules are rendered in a rounded table with two columns: Section (the comment header from the template) and Missing Rule (the pattern that is absent). Rules not covered by any section header appear under (no section). When all rules are already present a success message is shown instead of a table. When --merge is used, a confirmation line reports how many rules were appended. Check duration is shown at the end.

---

graph — Dependency Graph Export

Scans a solution’s project-to-project (<ProjectReference>) dependencies and exports a diagram in Mermaid (default) or GraphViz DOT format. The diagram is echoed to the console and written to a file, making it easy to understand the structure of large solutions or paste into documentation.

When --solution is supplied, its projects are graphed. Otherwise the first .sln found under PATH is used; if no solution exists, every .csproj/.vbproj/.fsproj under PATH is graphed instead.

Arguments

Argument	Description
[PATH]	Root directory containing the solution/projects to graph. Defaults to the current directory if omitted.

Flags

Flag	Description
--solution <FILE>	Explicit .sln file to graph. Overrides auto-discovery under PATH.
--format <FORMAT>	Diagram format: mermaid (default) or dot (GraphViz).
--output <FILE>	Write the diagram to this file. Defaults to the scanned path’s Git repository root (so it can be committed), or %APPDATA%\Spargine\graphs\dependency-graph.<ext> when no repository is found.

Output

• The rendered diagram text is printed to the console.
• The diagram is saved to disk (.mmd for Mermaid, .dot for GraphViz), and the full path is reported.
• When the scanned path is inside a Git repository, the file is written to the repository root by default so it can be committed alongside the code. If no repository is found, it falls back to %APPDATA%\Spargine\graphs.
• A summary line shows the number of projects (nodes) and references (edges) mapped.

Mermaid output can be pasted directly into Markdown that supports Mermaid (GitHub, docs sites). DOT output can be rendered with GraphViz: dot -Tpng dependency-graph.dot -o graph.png.

Examples

# Graph the current directory as Mermaid
spargine graph

# Graph a specific repo
spargine graph C:\src\MyRepo

# Export GraphViz DOT
spargine graph C:\src\MyRepo --format dot

# Write to a specific file
spargine graph C:\src\MyRepo --output C:\temp\deps.mmd

---

health — Project Health Report

Scans a directory tree for .csproj, .fsproj, and .vbproj files and reports common health issues, helping you keep your .NET projects modern and secure.

What Gets Checked

Category	What Is Reported
Target Framework	Projects whose <TargetFramework> is older than the specified minimum TFM.
Nullable	Projects missing <Nullable>enable</Nullable>.
ImplicitUsings	Projects missing <ImplicitUsings>enable</ImplicitUsings>.
Vulnerable packages	NuGet packages with known security vulnerabilities (via dotnet list package --vulnerable).
Outdated packages	NuGet packages that have newer versions available (via dotnet list package --outdated).

Package checks require dotnet to be on the PATH and an active internet connection. When solutions (.sln) are found in the scan tree they are preferred as the target for dotnet list package; otherwise individual project files are used.

Options

Option	Description
--tfm <TFM>	Minimum acceptable TFM (e.g., net8.0, net9.0, net10.0). Default: net8.0.
--vulnerable	Check for NuGet packages with known vulnerabilities (requires internet).
--outdated	Check for NuGet packages with available updates (requires internet).
--output <FILE>	Also save the report to this file (.md/.markdown for Markdown).

Arguments

Argument	Description
[PATH]	Root path to scan. Defaults to the current directory.

Examples

# Scan the current directory with default settings (TFM check and property checks only)
spargine health

# Scan a specific root with all checks enabled
spargine health C:\src --vulnerable --outdated

# Enforce a minimum of net10.0 against a specific repository
spargine health D:\MyRepo --tfm net10.0

# Check for vulnerable packages only, from the current directory
spargine health --vulnerable

Output

Results are displayed in a color-coded summary table grouped by issue category. When no issues are detected the tool prints a success message. Scan duration is always shown at the end. The last scan path and timestamp are persisted to the tool’s configuration file for reference on subsequent runs.

---

metrics — Build Metrics Trend Tracker

Runs dotnet build against a solution, optionally scans NuGet packages for vulnerabilities and outdated references, snapshots the counts, and appends the snapshot to a rolling JSON trend file (%APPDATA%\Spargine\metrics-trend.json by default). A formatted trend table is rendered after each run so engineers can see whether warnings, errors, and vulnerable packages are trending up or down.

When --solution is not supplied, every .sln found under PATH is built and scanned, and the results are aggregated into a single combined snapshot (totals across all solutions). Supply --solution to measure exactly one solution instead.

Arguments

Argument	Description
[PATH]	Root directory containing the solution(s) to measure. Defaults to the current directory if omitted.

Flags

Flag	Description
--solution <FILE>	Explicit single .sln file path. Overrides auto-discovery under PATH.
--history <N>	Number of historical snapshots to show in the trend table (default: 10, max: 100).
--no-packages	Skip the NuGet vulnerable/outdated package scan. Faster and works offline.
--output <FILE>	Also save the report to this file (.md for Markdown).

Trend File

Snapshots are persisted as JSON at %APPDATA%\Spargine\metrics-trend.json. The file retains the last 30 snapshots by default (rolling window). Each snapshot records:

Field	Description
timestamp	UTC time of the snapshot.
solutionPath	The .sln file that was built, or the scanned root path when multiple solutions are aggregated.
solutionCount	Number of solutions aggregated into the snapshot (1 for a single solution).
projectCount	Number of .csproj/.vbproj/.fsproj files found under the root.
warnings	Build warning count from dotnet build.
errors	Build error count from dotnet build.
vulnerablePackages	NuGet packages with known vulnerabilities (requires network).
outdatedPackages	NuGet packages with available updates (requires network).

Trend Table Indicators

Symbol	Meaning
▲ (red)	More warnings + errors than the previous run — things are sliding.
▼ (green)	Fewer warnings + errors than the previous run — you’re rockin’ it!
= (grey)	No change compared to the previous run.

Examples

# Scan the current directory, auto-discover .sln, show last 10 trend rows
spargine metrics

# Scan a specific path
spargine metrics C:\src\MyRepo

# Show last 20 trend rows
spargine metrics C:\src\MyRepo --history 20

# Use a specific solution file, skip the package scan
spargine metrics C:\src\MyRepo --solution C:\src\MyRepo\MyApp.sln --no-packages

Output

After each run the command renders:

1. A current snapshot table with solution name, project count, warnings, errors, vulnerable packages, and outdated packages.
2. A trend table showing up to --history most-recent snapshots with directional trend indicators.

---

nuget — NuGet Package Version Consolidation & Cache Management

Scans all .csproj, .fsproj, and .vbproj files under a root path and reports every NuGet package that is pinned to different versions across projects. Results are grouped by package name and rendered in a color-coded table. An optional --consolidate flag rewrites all affected project files in place, updating every mismatched reference to the highest detected version. An optional --clear-cache flag invokes dotnet nuget locals all -c to flush all local NuGet caches (global packages, http cache, temp, plugins cache).

What Gets Reported

Column	Details
Package	The NuGet package name.
Project	The project file containing the reference.
Version	The version in that project — shown in red if it is below the highest detected version, green if it matches.
Highest Version	The highest version found across all scanned projects for that package — the consolidation target.

Packages that are consistently versioned across all projects are not shown; the tool prints a success message instead.

Options

Option	Description
--clear-cache	Clears all local NuGet caches (dotnet nuget locals all -c) before scanning. Skipped automatically if Visual Studio is running.
--consolidate	Rewrites all affected project files, updating every mismatched <PackageReference> to the highest detected version. Both SDK-style (Version attribute) and legacy-style (<Version> child element) are supported.
--output <FILE>	Also save the report to this file (.md/.markdown for Markdown).

Arguments

Argument	Description
[PATH]	Root path to scan. Defaults to the current directory.

Examples

# Report mismatches in the current directory (read-only)
spargine nuget

# Report mismatches under a specific root
spargine nuget C:\src

# Report and auto-consolidate all mismatched packages to the highest version
spargine nuget C:\src --consolidate

# Clear all local NuGet caches
spargine nuget --clear-cache

# Clear caches then report and consolidate
spargine nuget C:\src --clear-cache --consolidate

Output

The report is rendered as a single rounded table sorted alphabetically by package name. Each package group shows one row per project that references it. Outdated versions are highlighted in red and the consolidation target is shown in bold. When --consolidate is used, a success message confirms how many packages were consolidated and which project files were rewritten. Scan duration and the last-run path are persisted to the tool’s configuration file.

---

secrets — Certificate & Secret Expiry Monitor

Scans for developer certificate status, certificate files near expiration, and sensitive secret files that could expose credentials if committed to source control.

What Gets Scanned

1. ASP.NET Core developer HTTPS certificate

   • Runs dotnet dev-certs https --check --trust and cross-checks the CN=localhost certificate in the current user’s personal certificate store to determine exact expiry.
   • Reports: trusted & healthy, near-expiry warning, expired, untrusted, or not found.

2. Certificate files (.pfx, .cer, .p12)

   • Walks the scan path recursively and reads each certificate’s expiry date using X509CertificateLoader.
   • Files within the warning threshold are highlighted in yellow; expired files in red.
   • Files that cannot be read (e.g., password-protected .pfx) are flagged as unreadable.

3. Sensitive secret files (.env*, secrets.json)

   • Flags any file whose name starts with .env or is named secrets.json.
   • Displays a recommendation to ensure the file is excluded from source control via .gitignore.

Options

Option	Description
--warn-days N	Issue a warning when a certificate expires within N days. Default: 30.
--output <FILE>	Also save the report to this file (.md/.markdown for Markdown).

Arguments

Argument	Description
[PATH]	Root path to scan recursively. Defaults to the current directory.

Examples

# Scan current directory with default 30-day warning threshold
spargine secrets

# Scan a specific path
spargine secrets C:\src

# Warn when certs expire within 60 days
spargine secrets C:\src --warn-days 60

Output

Three rounded tables are rendered:

• Developer Certificate — subject, status (color-coded green / yellow / red).
• Certificate Files — file path, type, and expiry status (color-coded).
• Sensitive Secret Files — file path and a .gitignore recommendation.

A summary line reports total scan duration.

---