Command line & CI

The TABlueprintScribe commandlet documents and audits Blueprints without opening the editor UI. Use it in build scripts and CI to keep the documentation up to date and to fail the build when findings reach a given severity.

Usage

UnrealEditor-Cmd.exe Project.uproject -run=TABlueprintScribe [-Paths=/Game/A+/Game/B] [-Output=Docs/Blueprints] [-Formats=html,md,json,ai] [-NoAudit] [-AuditOnly] [-FailOn=Error|Warning|Info|Never]

Example:

UnrealEditor-Cmd.exe "C:\Path\MyGame.uproject" -run=TABlueprintScribe -Paths=/Game/Blueprints+/Game/UI -Output=Docs/Blueprints -Formats=html,md,json,ai -FailOn=Error -unattended -nop4 -nosplash -NullRHI

-unattended, -nop4, -nosplash and -NullRHI are standard Unreal command line options for headless runs. They are not specific to Blueprint Scribe.

Note

The commandlet writes the pages without graph images: rendering graphs needs the editor UI, which commandlets don’t have. To get images in an automated run, start the editor with a Python script instead. See Images in automated runs.

Arguments

Argument	Default	Meaning
-Paths=/Game/A+/Game/B	Included Paths from the settings	Content folders to scan, including subfolders. Separate several folders with + or ,. Excluded Paths are skipped even when you pass -Paths.
-Output=<folder>	Output Directory from the settings (Saved/BlueprintScribe)	Output folder. Relative paths start at the project folder. The folder is cleaned before writing if an earlier export created it.
-Formats=html,md,json,ai	The formats enabled in the settings (all four by default)	Comma-separated list of html, md (or markdown), json and ai (AI-ready text), case-insensitive. Formats that are not listed are not written.
-NoAudit	Off	Leaves the findings out of the HTML and Markdown pages (no Audit link, no audit.html, no audit.md). The audit still runs: findings are still logged, still in scribe.json and the AI-ready text, and still decide the exit code.
-AuditOnly	Off	Scans and logs the findings but writes no files.
-FailOn=<severity>	Error	Lowest severity that fails the run: Error, Warning, Info or Never (None also works). Case-insensitive.

All other export options (title, private members, audit findings, credit line) come from Project Settings > Plugins > ta Blueprint Scribe. See Settings.

What the commandlet does

1. Reads -FailOn, the folders to scan and the export options.
2. Waits for the Asset Registry to finish discovering all assets.
3. Documents and audits every Blueprint, structure and enum in the folders, with the enabled rules. To keep memory use down in large projects, it collects garbage after every 50 assets.
4. Logs one line per finding.
5. Writes the documentation, unless -AuditOnly is given.
6. Logs a summary line and exits with an exit code.

Console output

All lines are logged in the LogTABlueprintScribe category:

LogTABlueprintScribe: Display: Scanning /Game/Blueprints, /Game/UI
LogTABlueprintScribe: Display: [Warning] Graph.Large | /Game/Blueprints/BP_Spaghetti.BP_Spaghetti | 'EventGraph' has 131 nodes (limit 100). Move parts of it into functions, macros or collapsed graphs.
LogTABlueprintScribe: Warning: Graph images were skipped: they need the editor UI (they are not available in commandlets).
LogTABlueprintScribe: Display: Documentation written to C:/Path/MyGame/Docs/Blueprints (<pages> pages, 0 images)
LogTABlueprintScribe: Display: ta Blueprint Scribe: <assets> asset(s) in <seconds>s, <coverage>% documented, health <score>. <errors> error(s), <warnings> warning(s), <info> info. <failing> finding(s) at or above -FailOn=Error.

• Scanning lists the scanned folders, separated by commas.
• Each finding line has the format [<Severity>] <RuleId> | <AssetPath> | <Message>. See Audit rules for the rule ids.
• The graph images warning appears when graph images are enabled in the settings and HTML or Markdown is written. Turn off Graph Images in the settings to avoid it.
• Documentation written to gives the full output folder, the number of pages (HTML pages plus Markdown asset files) and images. It is not logged with -AuditOnly.
• The summary line gives the number of assets, the scan time, the documentation coverage and health score, the findings per severity and how many findings are at or above -FailOn.

Assets that can’t be loaded are logged as warnings (Could not load <path>) and skipped. Setup and write errors are logged as errors:

Unknown -FailOn value '<value>'. Use Error, Warning, Info or Never.
Nothing to scan: no -Paths given and no Included Paths in Project Settings.
The ta Blueprint Scribe subsystem is not available.
Export failed: <errors>

Export failed also appears when -Formats contains none of html, md, json and ai: “No output format is selected (HTML, Markdown, JSON or AI-ready text).”

Exit codes

Code	Meaning
0	Passed: no findings at or above -FailOn. With -FailOn=Never the run always passes unless there is a setup or write error.
1	At least one finding at or above -FailOn.
2	Setup or write error: unknown -FailOn value, nothing to scan, the Blueprint Scribe subsystem is not available, or the export failed.

With the default -FailOn=Error, the run fails only on compile errors, the only rule that reports errors. Use -FailOn=Warning to also fail on large graphs, heavy Event Tick, heavy hard references, circular references, unused private variables, dead nodes and deprecated nodes.

CI example

This Windows batch step writes the documentation, keeps the exit code and passes it on to the build system. It expects to be placed next to MyGame.uproject; adjust the engine path and project name for your setup.

ci_blueprint_docs.bat

@echo off
set UE_CMD="C:\Program Files\Epic Games\UE_5.6\Engine\Binaries\Win64\UnrealEditor-Cmd.exe"
set PROJECT="%~dp0MyGame.uproject"

%UE_CMD% %PROJECT% -run=TABlueprintScribe -Output=Docs/Blueprints -Formats=html,md,json -FailOn=Error -unattended -nop4 -nosplash -NullRHI
set RESULT=%ERRORLEVEL%

if %RESULT%==0 echo Blueprint Scribe: passed
if %RESULT%==1 echo Blueprint Scribe: findings at or above -FailOn, see Docs\Blueprints\audit.html
if %RESULT%==2 echo Blueprint Scribe: setup or export error, check the log

exit /b %RESULT%

Archive the Docs/Blueprints folder as a build artifact, or publish it as a static site. scribe.json in the same folder has every finding for your own checks or dashboards. See JSON report.

Running from PowerShell

Windows PowerShell 5.1 changes some arguments that start with - before Unreal sees them:

• An argument with a dot is split in two at the dot. -ExecutePythonScript=export_docs.py arrives as -ExecutePythonScript=export_docs and .py, and an output folder such as -Output=Docs/v1.2 is cut the same way.
• An argument with a comma, such as -Formats=html,md,json or -Paths=/Game/A,/Game/B, makes PowerShell stop with the parse error “Missing argument in parameter list”.

Put such arguments in quotes or in a variable:

$UE = "C:\Program Files\Epic Games\UE_5.6\Engine\Binaries\Win64\UnrealEditor-Cmd.exe"
$Project = "C:\Path\MyGame.uproject"
$Output = "-Output=Docs/Blueprints"
$Formats = "-Formats=html,md,json"

& $UE $Project -run=TABlueprintScribe $Output $Formats -FailOn=Error -unattended -nop4 -nosplash -NullRHI
exit $LASTEXITCODE

Writing "-Formats=html,md,json" in quotes directly on the command line works too. Separating -Paths folders with + instead of , avoids the comma problem.