From f0f63c8e6aa1a2063d5a72c7d9d6668ea8adf4ac Mon Sep 17 00:00:00 2001
From: Nick Lombardi <nick@streamforge.gg>
Date: Sat, 8 Aug 2026 05:00:08 -0400
Subject: [PATCH] Add stateless headless CLI

---
 HEADLESS_CLI.md                       | 102 ++++++++++
 README.md                             |   6 +
 electron/headless_cleanup.js          |  36 ++++
 electron/headless_cli.js              | 211 +++++++++++++++++++++
 electron/main.js                      | 261 +++++++++++++++++++++++---
 js/api.ts                             |  12 +-
 js/boot_loader.js                     |  40 ++--
 js/headless_cli.ts                    | 244 ++++++++++++++++++++++++
 js/io/io.js                           |  16 +-
 js/plugin_loader.ts                   |  16 +-
 package.json                          |   4 +
 tests/fixtures/headless_add_cube.js   |  20 ++
 tests/fixtures/headless_empty.bbmodel |  14 ++
 tests/headless_cli.concurrent.test.js |  85 +++++++++
 tests/headless_cli.e2e.test.js        | 140 ++++++++++++++
 tests/headless_cli.test.js            |  95 ++++++++++
 16 files changed, 1248 insertions(+), 54 deletions(-)
 create mode 100644 HEADLESS_CLI.md
 create mode 100644 electron/headless_cleanup.js
 create mode 100644 electron/headless_cli.js
 create mode 100644 js/headless_cli.ts
 create mode 100644 tests/fixtures/headless_add_cube.js
 create mode 100644 tests/fixtures/headless_empty.bbmodel
 create mode 100644 tests/headless_cli.concurrent.test.js
 create mode 100644 tests/headless_cli.e2e.test.js
 create mode 100644 tests/headless_cli.test.js

diff --git a/HEADLESS_CLI.md b/HEADLESS_CLI.md
new file mode 100644
index 000000000..421d355bd
--- /dev/null
+++ b/HEADLESS_CLI.md
@@ -0,0 +1,102 @@
+# Headless CLI
+
+Blockbench can run one model-editing action without showing a window or starting
+a server. Each invocation creates an isolated temporary profile, opens the model
+through Blockbench's normal codec, runs trusted JavaScript in the real renderer,
+saves a new `.bbmodel` through the project codec, and exits.
+
+## Run from source
+
+Build the renderer once:
+
+```sh
+npm install
+npm run build-electron
+```
+
+Then run an action:
+
+```sh
+npm run headless -- \
+  --input creature.bbmodel \
+  --script remove_saddle.js \
+  --output creature_without_saddle.bbmodel
+```
+
+Packaged builds use the same arguments directly on the Blockbench executable:
+
+```sh
+Blockbench --headless \
+  --input creature.bbmodel \
+  --script remove_saddle.js \
+  --output creature_without_saddle.bbmodel
+```
+
+Use `--force` to replace an existing output. The input is never changed unless
+the same path is explicitly supplied as output together with `--force`.
+
+## Script environment
+
+Scripts run after the model and its textures are ready. Blockbench's live globals
+are available directly, including `Project`, `Cube`, `Group`, `Mesh`, `Texture`,
+`Undo`, `Canvas`, and `Blockbench`:
+
+```js
+const saddle = Group.all.find(group => group.name === 'saddle')
+if (!saddle) throw new Error('Saddle group not found')
+
+const affected = saddle.getAllChildren()
+saddle.remove(true)
+Canvas.updateAll()
+
+return {removed: saddle.name, affected: affected.length}
+```
+
+The script body is an async function, so top-level `await` and `return` work.
+It also receives these variables:
+
+- `context`: `{input, output, args, Blockbench, globals, project, waitForTextures}`
+- `input` and `output`: resolved absolute paths
+- `args`: values after `--`
+- `module` and `exports`: optional CommonJS-style export support
+
+Instead of using a script body, a file can export a function:
+
+```js
+module.exports = async ({args}) => {
+  Cube.all[0].name = args[0]
+  return {renamed: Cube.all[0].uuid}
+}
+```
+
+Run it with arguments using `-- old_name new_name`. For short actions,
+`--eval <javascript>` can be used instead of `--script`.
+
+Scripts are not sandboxed. They run with the desktop app's local permissions and
+must be trusted.
+
+## Process contract
+
+The last stdout line is a JSON result. Script `console` output is written to
+stderr so callers can parse stdout reliably.
+
+Successful result:
+
+```json
+{"ok":true,"input":"...","output":"...","phase":"complete","exitCode":0,"format":"free","elements":12,"durationMs":913,"result":{"removed":"saddle"}}
+```
+
+Failed result:
+
+```json
+{"ok":false,"input":"...","output":"...","phase":"script","exitCode":5,"error":{"name":"Error","message":"Saddle group not found"}}
+```
+
+Exit codes are `0` for success, `2` for invalid arguments, `3` for input/load
+errors, `4` for output/save errors, `5` for script errors, `6` for renderer or
+runtime errors, and `124` for a timeout.
+
+Every invocation is independent. It does not load installed plugins, contact the
+plugin API or updater, modify recent projects, start backups, or reuse a profile.
+This lets multiple processes edit different files concurrently without sharing
+`Project`, `Undo`, scene, or codec state.
diff --git a/README.md b/README.md
index f03d92c37..ab1eb35eb 100644
--- a/README.md
+++ b/README.md
@@ -39,6 +39,12 @@ Use this command or press Ctrl + Shift + B to launch Blockbench in Electron:
 To enable debugging in VS Code, switch to the **Run & Debug** tab, select the **"Debug Renderer"** configuration, and press the green arrow button to launch.
 Now you can set breakpoints and debug inside VSCode.
 
+### Run Headlessly
+
+Use the [headless CLI](HEADLESS_CLI.md) to open a model, run JavaScript against
+Blockbench's live renderer globals, save a `.bbmodel`, and exit without showing
+a window or starting a server.
+
 
 ### Run the web app
 Use this command to launch the web app locally:
diff --git a/electron/headless_cleanup.js b/electron/headless_cleanup.js
new file mode 100644
index 000000000..4fd9ad67c
--- /dev/null
+++ b/electron/headless_cleanup.js
@@ -0,0 +1,36 @@
+import {setTimeout as wait} from 'node:timers/promises'
+
+import {removeHeadlessCLIProfile} from './headless_cli.js'
+
+const profile_path = process.argv[2]
+const parent_pid = Number(process.argv[3])
+
+if (!profile_path || !Number.isInteger(parent_pid) || parent_pid <= 0) {
+	process.exit(2)
+}
+
+function isParentRunning() {
+	try {
+		process.kill(parent_pid, 0)
+		return true
+	} catch (error) {
+		return false
+	}
+}
+
+// Chromium releases profile database and cache handles only after its parent
+// exits. Bound both waits so a failed cleanup can never become a stray daemon.
+for (let attempt = 0; attempt < 300 && isParentRunning(); attempt++) {
+	await wait(100)
+}
+
+for (let attempt = 0; attempt < 50; attempt++) {
+	try {
+		removeHeadlessCLIProfile(profile_path)
+		process.exit(0)
+	} catch (error) {
+		await wait(100)
+	}
+}
+
+process.exit(1)
diff --git a/electron/headless_cli.js b/electron/headless_cli.js
new file mode 100644
index 000000000..03bf26176
--- /dev/null
+++ b/electron/headless_cli.js
@@ -0,0 +1,211 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+export const HEADLESS_CLI_PROFILE_PREFIX = 'blockbench-headless-'
+
+export const HeadlessExitCode = Object.freeze({
+	SUCCESS: 0,
+	USAGE: 2,
+	INPUT: 3,
+	OUTPUT: 4,
+	SCRIPT: 5,
+	RUNTIME: 6,
+	TIMEOUT: 124,
+})
+
+export const HEADLESS_CLI_USAGE = `Usage:
+  Blockbench --headless --input <model> --script <file.js> --output <result.bbmodel> [options] [-- <script args...>]
+  Blockbench --headless --input <model> --eval <javascript> --output <result.bbmodel> [options] [-- <script args...>]
+
+Options:
+  -i, --input <path>    Model to open using Blockbench's normal codecs
+  -s, --script <path>   JavaScript file to run against the live Blockbench globals
+  -e, --eval <code>     JavaScript source to run instead of a script file
+  -o, --output <path>   Destination Blockbench project (.bbmodel)
+      --force           Allow replacing an existing output file
+      --timeout <ms>    Whole-operation timeout (default: 60000)
+  -h, --help            Show this help
+
+The script runs in Blockbench's renderer after the input model is loaded. It can
+use live globals such as Project, Cube, Group, Mesh, Texture, Undo, Canvas, and
+Blockbench. Top-level await and return are supported. The variables context,
+input, output, args, module, and exports are also provided. A CommonJS export
+that is a function is called with context after the script body is evaluated.
+
+This executes trusted code with the same local access as the desktop app. Each
+invocation uses a new temporary Blockbench profile and exits after one action.`
+
+export class HeadlessCLIArgumentError extends Error {
+	constructor(message, exit_code = HeadlessExitCode.USAGE) {
+		super(message)
+		this.name = 'HeadlessCLIArgumentError'
+		this.exitCode = exit_code
+	}
+}
+
+function readOptionValue(argv, index, option) {
+	const value = argv[index + 1]
+	if (value === undefined || value === '--') {
+		throw new HeadlessCLIArgumentError(`Missing value after ${option}`)
+	}
+	return value
+}
+
+/**
+ * Parse arguments following --headless. Arguments before --headless belong to
+ * Electron and are deliberately ignored.
+ */
+export function parseHeadlessCLIArguments(argv, cwd = process.cwd()) {
+	const headless_index = argv.indexOf('--headless')
+	if (headless_index === -1) return null
+
+	const options = {
+		headless: true,
+		help: false,
+		input: '',
+		output: '',
+		script: '',
+		eval: '',
+		force: false,
+		timeout: 60_000,
+		args: [],
+	}
+
+	for (let index = headless_index + 1; index < argv.length; index++) {
+		const argument = argv[index]
+		if (argument === '--') {
+			options.args = argv.slice(index + 1)
+			break
+		}
+		switch (argument) {
+			case '-h':
+			case '--help':
+				options.help = true
+				break
+			case '-i':
+			case '--input':
+				options.input = readOptionValue(argv, index, argument)
+				index++
+				break
+			case '-o':
+			case '--output':
+				options.output = readOptionValue(argv, index, argument)
+				index++
+				break
+			case '-s':
+			case '--script':
+				options.script = readOptionValue(argv, index, argument)
+				index++
+				break
+			case '-e':
+			case '--eval':
+				options.eval = readOptionValue(argv, index, argument)
+				index++
+				break
+			case '--force':
+				options.force = true
+				break
+			case '--timeout': {
+				const value = readOptionValue(argv, index, argument)
+				options.timeout = Number(value)
+				index++
+				break
+			}
+			default:
+				throw new HeadlessCLIArgumentError(`Unknown headless option: ${argument}`)
+		}
+	}
+
+	if (options.help) return options
+	if (!options.input) throw new HeadlessCLIArgumentError('Missing required option: --input')
+	if (!options.output) throw new HeadlessCLIArgumentError('Missing required option: --output')
+	if (!options.script && !options.eval) {
+		throw new HeadlessCLIArgumentError('Specify exactly one of --script or --eval')
+	}
+	if (options.script && options.eval) {
+		throw new HeadlessCLIArgumentError('--script and --eval cannot be used together')
+	}
+	if (!Number.isInteger(options.timeout) || options.timeout < 1_000 || options.timeout > 3_600_000) {
+		throw new HeadlessCLIArgumentError('--timeout must be an integer from 1000 to 3600000 milliseconds')
+	}
+
+	options.input = path.resolve(cwd, options.input)
+	options.output = path.resolve(cwd, options.output)
+	if (options.script) options.script = path.resolve(cwd, options.script)
+	return options
+}
+
+export function validateHeadlessCLIPaths(options) {
+	let input_stat
+	try {
+		input_stat = fs.statSync(options.input)
+	} catch (error) {
+		throw new HeadlessCLIArgumentError(`Input file does not exist: ${options.input}`, HeadlessExitCode.INPUT)
+	}
+	if (!input_stat.isFile()) {
+		throw new HeadlessCLIArgumentError(`Input path is not a file: ${options.input}`, HeadlessExitCode.INPUT)
+	}
+
+	if (options.script) {
+		let script_stat
+		try {
+			script_stat = fs.statSync(options.script)
+		} catch (error) {
+			throw new HeadlessCLIArgumentError(`Script file does not exist: ${options.script}`, HeadlessExitCode.SCRIPT)
+		}
+		if (!script_stat.isFile()) {
+			throw new HeadlessCLIArgumentError(`Script path is not a file: ${options.script}`, HeadlessExitCode.SCRIPT)
+		}
+	}
+
+	if (path.extname(options.output).toLowerCase() !== '.bbmodel') {
+		throw new HeadlessCLIArgumentError('Output path must use the .bbmodel extension')
+	}
+	let output_directory_stat
+	const output_directory = path.dirname(options.output)
+	try {
+		output_directory_stat = fs.statSync(output_directory)
+	} catch (error) {
+		throw new HeadlessCLIArgumentError(`Output directory does not exist: ${output_directory}`, HeadlessExitCode.OUTPUT)
+	}
+	if (!output_directory_stat.isDirectory()) {
+		throw new HeadlessCLIArgumentError(`Output parent is not a directory: ${output_directory}`, HeadlessExitCode.OUTPUT)
+	}
+	if (!options.force && fs.existsSync(options.output)) {
+		throw new HeadlessCLIArgumentError(
+			`Output file already exists (use --force to replace it): ${options.output}`,
+			HeadlessExitCode.OUTPUT,
+		)
+	}
+	return options
+}
+
+export function createHeadlessCLIProfile() {
+	return fs.mkdtempSync(path.join(os.tmpdir(), HEADLESS_CLI_PROFILE_PREFIX))
+}
+
+/**
+ * Remove only a profile directory created directly under the OS temp folder.
+ * Returns false when the directory was already absent.
+ */
+export function removeHeadlessCLIProfile(profile_path) {
+	const resolved_profile = path.resolve(profile_path)
+	const resolved_temp = path.resolve(os.tmpdir())
+	const profile_name = path.basename(resolved_profile)
+	const random_suffix = profile_name.slice(HEADLESS_CLI_PROFILE_PREFIX.length)
+	if (
+		path.dirname(resolved_profile) !== resolved_temp ||
+		!profile_name.startsWith(HEADLESS_CLI_PROFILE_PREFIX) ||
+		!/^[A-Za-z0-9]{6}$/.test(random_suffix)
+	) {
+		throw new Error(`Refusing to remove unexpected headless profile path: ${profile_path}`)
+	}
+	if (!fs.existsSync(resolved_profile)) return false
+	const profile_stat = fs.lstatSync(resolved_profile)
+	if (!profile_stat.isDirectory() || profile_stat.isSymbolicLink()) {
+		throw new Error(`Refusing to remove non-directory headless profile path: ${profile_path}`)
+	}
+	fs.rmSync(resolved_profile, {recursive: true, force: false})
+	return true
+}
diff --git a/electron/main.js b/electron/main.js
index 133ef91e6..74cfeab75 100644
--- a/electron/main.js
+++ b/electron/main.js
@@ -4,6 +4,15 @@ import url from 'url'
 import { createRequire } from 'node:module'
 import { fileURLToPath } from 'node:url'
 import fs from 'node:fs'
+import {spawn} from 'node:child_process'
+import {
+	HEADLESS_CLI_USAGE,
+	HeadlessExitCode,
+	createHeadlessCLIProfile,
+	parseHeadlessCLIArguments,
+	removeHeadlessCLIProfile,
+	validateHeadlessCLIPaths,
+} from './headless_cli.js'
 
 const require = createRequire(import.meta.url)
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
@@ -15,10 +24,148 @@ remote.initialize();
 let all_wins = [];
 let orig_win;
 let load_project_data;
+let headless_cli_options;
+let headless_cli_profile;
+let headless_cli_window;
+let headless_cli_timeout;
+let headless_cli_finished = false;
+
+try {
+	headless_cli_options = parseHeadlessCLIArguments(process.argv);
+	if (headless_cli_options?.help) {
+		process.stdout.write(HEADLESS_CLI_USAGE + '\n');
+		process.exit(HeadlessExitCode.SUCCESS);
+	}
+	if (headless_cli_options) {
+		validateHeadlessCLIPaths(headless_cli_options);
+		headless_cli_profile = createHeadlessCLIProfile();
+		app.setPath('userData', headless_cli_profile);
+		app.setPath('sessionData', headless_cli_profile);
+	}
+} catch (error) {
+	const exit_code = Number.isInteger(error.exitCode) ? error.exitCode : HeadlessExitCode.USAGE;
+	process.stderr.write(`Blockbench headless: ${error.message}\n`);
+	if (exit_code === HeadlessExitCode.USAGE) {
+		process.stderr.write(`\n${HEADLESS_CLI_USAGE}\n`);
+	} else {
+		const phase = exit_code === HeadlessExitCode.INPUT
+			? 'input'
+			: (exit_code === HeadlessExitCode.OUTPUT ? 'output' : 'script');
+		process.stdout.write(JSON.stringify({
+			ok: false,
+			input: headless_cli_options?.input,
+			output: headless_cli_options?.output,
+			phase,
+			exitCode: exit_code,
+			error: {name: error.name, message: error.message},
+		}) + '\n');
+	}
+	process.exit(exit_code);
+}
+
+function cleanupHeadlessCLIProfile() {
+	if (!headless_cli_profile) return;
+	try {
+		removeHeadlessCLIProfile(headless_cli_profile);
+		headless_cli_profile = null;
+	} catch (error) {
+		// Chromium can briefly retain cache files while quitting. The process exit
+		// hook below makes one final synchronous attempt.
+	}
+}
+
+function scheduleHeadlessCLIProfileCleanup() {
+	if (!headless_cli_profile) return;
+	const profile_path = headless_cli_profile;
+	const cleanup_script = path.join(__dirname, 'headless_cleanup.js');
+	try {
+		const cleanup_process = spawn(
+			process.execPath,
+			[cleanup_script, profile_path, String(process.pid)],
+			{
+				detached: true,
+				stdio: 'ignore',
+				windowsHide: true,
+				env: {...process.env, ELECTRON_RUN_AS_NODE: '1'},
+			},
+		);
+		cleanup_process.unref();
+		headless_cli_profile = null;
+	} catch (error) {
+		// Keep the path for the in-process quit/exit cleanup fallback.
+	}
+}
+
+function finishHeadlessCLI(result) {
+	if (!headless_cli_options || headless_cli_finished) return;
+	headless_cli_finished = true;
+	clearTimeout(headless_cli_timeout);
+
+	const exit_code = Number.isInteger(result.exitCode)
+		? result.exitCode
+		: (result.ok ? HeadlessExitCode.SUCCESS : HeadlessExitCode.RUNTIME);
+	const payload = {
+		ok: !!result.ok,
+		input: headless_cli_options.input,
+		output: headless_cli_options.output,
+		...result,
+		exitCode: exit_code,
+	};
+	if (!payload.ok && payload.error?.message) {
+		process.stderr.write(`Blockbench headless: ${payload.error.message}\n`);
+	}
+	process.stdout.write(JSON.stringify(payload) + '\n');
+	process.exitCode = exit_code;
+
+	scheduleHeadlessCLIProfileCleanup();
+	if (headless_cli_window && !headless_cli_window.isDestroyed()) {
+		headless_cli_window.destroy();
+	}
+	app.exit(exit_code);
+}
+
+if (headless_cli_options) {
+	app.commandLine.appendSwitch('disable-background-networking');
+	app.commandLine.appendSwitch('disable-component-update');
+	app.commandLine.appendSwitch('disable-http-cache');
+	app.commandLine.appendSwitch('disable-renderer-backgrounding');
+	app.commandLine.appendSwitch('no-proxy-server');
+
+	ipcMain.on('headless-cli-log', (event, entry) => {
+		if (event.sender !== headless_cli_window?.webContents) return;
+		const level = entry?.level || 'log';
+		const message = typeof entry?.message === 'string' ? entry.message : String(entry?.message ?? '');
+		process.stderr.write(`[headless:${level}] ${message}\n`);
+	});
+	ipcMain.on('headless-cli-result', (event, result) => {
+		if (event.sender !== headless_cli_window?.webContents) return;
+		finishHeadlessCLI(result);
+	});
+	process.on('uncaughtException', error => {
+		finishHeadlessCLI({
+			ok: false,
+			phase: 'main',
+			exitCode: HeadlessExitCode.RUNTIME,
+			error: {name: error.name, message: error.message, stack: error.stack},
+		});
+	});
+	process.on('unhandledRejection', reason => {
+		const error = reason instanceof Error ? reason : new Error(String(reason));
+		finishHeadlessCLI({
+			ok: false,
+			phase: 'main',
+			exitCode: HeadlessExitCode.RUNTIME,
+			error: {name: error.name, message: error.message, stack: error.stack},
+		});
+	});
+	app.on('quit', cleanupHeadlessCLIProfile);
+	process.on('exit', cleanupHeadlessCLIProfile);
+}
 
 (() => {
 	// Allow advanced users to specify a custom userData directory.
 	// Useful for portable installations, and for setting up development environments.
+	if (headless_cli_options) return;
 	const index = process.argv.findIndex(arg => arg === '--userData');
 	if (index !== -1) {
 		if (!process.argv.at(index + 1)) {
@@ -56,7 +203,7 @@ if (LaunchSettings.get('hardware_acceleration') == false) {
 }
 
 function createWindow(second_instance, options = {}) {
-	if (app.requestSingleInstanceLock && !app.requestSingleInstanceLock()) {
+	if (!options.headless && app.requestSingleInstanceLock && !app.requestSingleInstanceLock()) {
 		app.quit()
 		return;
 	}
@@ -71,14 +218,22 @@ function createWindow(second_instance, options = {}) {
 		minHeight: 480,
 		width: 1080,
 		height: 720,
+		skipTaskbar: options.headless === true,
 		webPreferences: {
 			webgl: true,
 			webSecurity: true,
 			nodeIntegration: true,
 			contextIsolation: false,
-			enableRemoteModule: true
+			enableRemoteModule: true,
+			backgroundThrottling: options.headless !== true,
+			offscreen: options.headless === true,
+			additionalArguments: options.headless ? ['--blockbench-headless-renderer'] : [],
 		}
 	};
+	if (options.headless) {
+		win_options.frame = false;
+		win_options.paintWhenInitiallyHidden = true;
+	}
 	if (options.position) {
 		win_options.x = options.position[0] - 300;
 		win_options.y = Math.max(options.position[1] - 100, 0);
@@ -89,7 +244,7 @@ function createWindow(second_instance, options = {}) {
 
 	remote.enable(win.webContents)
 
-	if (process.platform === 'darwin') {
+	if (!options.headless && process.platform === 'darwin') {
 
 		let template = [
 			{
@@ -156,11 +311,11 @@ function createWindow(second_instance, options = {}) {
 
 		var osxMenu = Menu.buildFromTemplate(template);
 		Menu.setApplicationMenu(osxMenu)
-	} else {
+	} else if (!options.headless) {
 		win.setMenu(null);
 	}
 	
-	if (options.maximize !== false) win.maximize()
+	if (!options.headless && options.maximize !== false) win.maximize()
 
 	let index_path = path.join(__dirname, './../index.html')
 	let url_path = url.format({
@@ -168,12 +323,23 @@ function createWindow(second_instance, options = {}) {
 		protocol: 'file:',
 		slashes: true
 	});
-	win.loadURL(url_path).finally(() => {
-		win.show();
+	win.loadURL(url_path).then(() => {
+		if (!options.headless) win.show();
+	}, error => {
+		if (options.headless) {
+			finishHeadlessCLI({
+				ok: false,
+				phase: 'boot',
+				exitCode: HeadlessExitCode.RUNTIME,
+				error: {name: error.name, message: error.message, stack: error.stack},
+			});
+		} else {
+			win.show();
+		}
 	});
 	win.on('closed', () => {
-		win = null;
-		all_wins.splice(all_wins.indexOf(win), 1);
+		const index = all_wins.indexOf(win);
+		if (index !== -1) all_wins.splice(index, 1);
 	})
 	if (second_instance === true) {
 		win.webContents.second_instance = true;
@@ -270,22 +436,14 @@ ipcMain.on('open-in-default-app', async (event, path) => {
 app.on('ready', () => {
 
 	const dev_mode = process.execPath && process.execPath.match(/node_modules[\\\/]electron/);
-
-	if (dev_mode) {
-
-		// Timeout to avoid race condition of Blockbench opening before esbuild finishes. Needs proper solution long-term
-		setTimeout(() => {
-			createWindow()
-		}, 1000);
-
-	} else {
-
-		createWindow()
-		
-	}
-
 	let app_was_loaded = false;
-	ipcMain.on('app-loaded', () => {
+	ipcMain.on('app-loaded', event => {
+		if (headless_cli_options) {
+			if (event.sender !== headless_cli_window?.webContents || app_was_loaded) return;
+			app_was_loaded = true;
+			event.sender.send('headless-cli-run', headless_cli_options);
+			return;
+		}
 
 		if (load_project_data) {
 			all_wins[all_wins.length-1].send('load-tab', load_project_data);
@@ -333,6 +491,61 @@ app.on('ready', () => {
 			autoUpdater.checkForUpdates().catch(err => {})
 		}
 	})
+
+	if (headless_cli_options) {
+		headless_cli_window = createWindow(false, {headless: true, maximize: false});
+		headless_cli_window.webContents.on('console-message', event => {
+			if (event.level === 'error' || event.level === 'warning') {
+				process.stderr.write(`[renderer:${event.level}] ${event.message}\n`);
+			}
+		});
+		headless_cli_window.webContents.on('did-fail-load', (event, error_code, error_description, validated_url, is_main_frame) => {
+			if (!is_main_frame) return;
+			finishHeadlessCLI({
+				ok: false,
+				phase: 'boot',
+				exitCode: HeadlessExitCode.RUNTIME,
+				error: {
+					name: 'RendererLoadError',
+					message: `Renderer load failed: ${error_description} (${error_code})`,
+				},
+			});
+		});
+		headless_cli_window.webContents.on('render-process-gone', (event, details) => {
+			finishHeadlessCLI({
+				ok: false,
+				phase: 'renderer',
+				exitCode: HeadlessExitCode.RUNTIME,
+				error: {
+					name: 'RendererProcessError',
+					message: `Renderer process exited: ${details.reason} (${details.exitCode})`,
+				},
+			});
+		});
+		headless_cli_timeout = setTimeout(() => {
+			finishHeadlessCLI({
+				ok: false,
+				phase: 'timeout',
+				exitCode: HeadlessExitCode.TIMEOUT,
+				error: {
+					name: 'HeadlessCLITimeoutError',
+					message: `Headless action exceeded ${headless_cli_options.timeout}ms`,
+				},
+			});
+		}, headless_cli_options.timeout);
+
+	} else if (dev_mode) {
+
+		// Timeout to avoid race condition of Blockbench opening before esbuild finishes. Needs proper solution long-term
+		setTimeout(() => {
+			createWindow()
+		}, 1000);
+
+	} else {
+
+		createWindow()
+
+	}
 })
 
 app.on('window-all-closed', () => {
diff --git a/js/api.ts b/js/api.ts
index 490d44ae6..3527dc511 100644
--- a/js/api.ts
+++ b/js/api.ts
@@ -5,7 +5,7 @@ import { EventSystem } from "./util/event_system";
 import VersionUtil from './util/version_util';
 import { Filesystem } from "./file_system";
 import { MessageBoxOptions } from "./interface/dialog";
-import { currentwindow, electron, shell, SystemInfo } from "./native_apis";
+import { currentwindow, electron, process as nativeProcess, shell, SystemInfo } from "./native_apis";
 import { ToastNotification, ToastNotificationOptions } from "./interface/toast_notification";
 
 declare const appVersion: string;
@@ -19,6 +19,7 @@ export const LastVersion = localStorage.getItem('last_version') || localStorage.
 export const Blockbench = {
 	//...previous_data,
 	isWeb: !isApp,
+	isHeadless: isApp && nativeProcess.argv.includes('--blockbench-headless-renderer'),
 	isMobile: (window.innerWidth <= 960 || window.innerHeight <= 500) && 'ontouchend' in document,
 	isLandscape: window.innerWidth > window.innerHeight,
 	isTouch: 'ontouchend' in document,
@@ -321,8 +322,15 @@ export const Blockbench = {
 	removeDragHandler: Filesystem.removeDragHandler,
 };
 
+if (Blockbench.isHeadless) {
+	Blockbench.addFlag('headless');
+	Blockbench.addFlag('no_localstorage_saving');
+}
+
 (function() {
-	if (!LastVersion || LastVersion.replace(/.\d+$/, '') != appVersion.replace(/.\d+$/, '')) {
+	if (Blockbench.isHeadless) {
+		return;
+	} else if (!LastVersion || LastVersion.replace(/.\d+$/, '') != appVersion.replace(/.\d+$/, '')) {
 		Blockbench.addFlag('after_update');
 	} else if (LastVersion != appVersion) {
 		Blockbench.addFlag('after_patch_update');
diff --git a/js/boot_loader.js b/js/boot_loader.js
index fb1a78b6f..0859a2826 100644
--- a/js/boot_loader.js
+++ b/js/boot_loader.js
@@ -9,6 +9,7 @@ import { initializeDesktopApp, loadOpenWithBlockbenchFile } from "./desktop";
 import { AutoBackup } from "./auto_backup";
 import { initReferenceImages } from "./preview/reference_images";
 import { initCanvas } from "./preview/canvas";
+import { initializeHeadlessCLI } from "./headless_cli";
 
 Interface.page_wrapper = document.getElementById('page_wrapper');
 Interface.work_screen = document.getElementById('work_screen');
@@ -69,8 +70,10 @@ console.log('%cBlockbench ' + Blockbench.version + (isApp
 	: (' Web ('+capitalizeFirstLetter(Blockbench.browser) + (Blockbench.isPWA ? ', PWA)' : ')'))),
 	'border: 2px solid #3e90ff; padding: 4px 8px; font-size: 1.2em;'
 )
-Blockbench.startup_count = parseInt(localStorage.getItem('startups')||0) + 1;
-localStorage.setItem('startups', Blockbench.startup_count);
+Blockbench.startup_count = Blockbench.isHeadless
+	? 1
+	: parseInt(localStorage.getItem('startups')||0) + 1;
+if (!Blockbench.isHeadless) localStorage.setItem('startups', Blockbench.startup_count);
 
 document.getElementById('blackout').addEventListener('click', event => {
 	if (typeof open_interface.cancel == 'function' && open_interface.cancel_on_click_outside !== false) {
@@ -80,7 +83,7 @@ document.getElementById('blackout').addEventListener('click', event => {
 	}
 })
 
-if (isApp) {
+if (isApp && !Blockbench.isHeadless) {
 	updateRecentProjects()
 }
 
@@ -101,7 +104,7 @@ if (!Blockbench.isWeb || !Blockbench.isPWA) {
 	$.ajaxSetup({ cache: false });
 }
 
-if (Blockbench.startup_count == 1) {
+if (!Blockbench.isHeadless && Blockbench.startup_count == 1) {
 	try {
 		jQuery.ajax({
 			url: 'https://blckbn.ch/api/event/new_installation',
@@ -112,7 +115,7 @@ if (Blockbench.startup_count == 1) {
 		console.error(err);
 	}
 }
-if (Blockbench.startup_count == 3) {
+if (!Blockbench.isHeadless && Blockbench.startup_count == 3) {
 	try {
 		jQuery.ajax({
 			url: 'https://blckbn.ch/api/event/recurring_user',
@@ -133,7 +136,7 @@ Blockbench.on('before_closing', (event) => {
 updateProjectResolution()
 
 setupInterface()
-setupDragHandlers()
+if (!Blockbench.isHeadless) setupDragHandlers()
 
 onVueSetup.funcs.forEach((func) => {
 	if (typeof func === 'function') {
@@ -145,15 +148,15 @@ if (settings.streamer_mode.value) {
 	updateStreamerModeNotification();
 }
 
-AutoBackup.initialize();
+if (!Blockbench.isHeadless) AutoBackup.initialize();
 
 if (isApp) {
-	initializeDesktopApp();
+	if (!Blockbench.isHeadless) initializeDesktopApp();
 } else {
 	initializeWebApp();
 }
 
-localStorage.setItem('last_version', Blockbench.version);
+if (!Blockbench.isHeadless) localStorage.setItem('last_version', Blockbench.version);
 
 (function() {
 	// Promise.any workaround
@@ -161,17 +164,26 @@ localStorage.setItem('last_version', Blockbench.version);
 	function proceed() {
 		if (proceeded) return;
 
-		Settings.saveLocalStorages();
+		if (!Blockbench.isHeadless) Settings.saveLocalStorages();
 		if (isApp) {
-			loadOpenWithBlockbenchFile();
-			ipcRenderer.send('app-loaded');
+			if (Blockbench.isHeadless) {
+				initializeHeadlessCLI();
+			} else {
+				loadOpenWithBlockbenchFile();
+			}
+			// Defer IPC until main.ts has evaluated the final global exports.
+			setTimeout(() => ipcRenderer.send('app-loaded'), 0);
 		} else {
 			loadInfoFromURL();
 		}
 		proceeded = true;
 	}
-	loadInstalledPlugins().then(proceed);
-	setTimeout(proceed, 1200);
+	if (Blockbench.isHeadless) {
+		proceed();
+	} else {
+		loadInstalledPlugins().then(proceed);
+		setTimeout(proceed, 1200);
+	}
 })()
 
 setStartScreen(true);
diff --git a/js/headless_cli.ts b/js/headless_cli.ts
new file mode 100644
index 000000000..3049298a6
--- /dev/null
+++ b/js/headless_cli.ts
@@ -0,0 +1,244 @@
+import { Blockbench } from './api';
+import { Codecs } from './io/codec';
+import { loadModelFile } from './io/io';
+import { fs, ipcRenderer, PathModule } from './native_apis';
+
+interface HeadlessCLIOptions {
+	input: string
+	output: string
+	script: string
+	eval: string
+	force: boolean
+	timeout: number
+	args: string[]
+}
+
+const HeadlessExitCode = {
+	INPUT: 3,
+	OUTPUT: 4,
+	SCRIPT: 5,
+	RUNTIME: 6,
+} as const;
+
+class HeadlessCLIError extends Error {
+	exitCode: number
+
+	constructor(message: string, exit_code: number) {
+		super(message);
+		this.name = 'HeadlessCLIError';
+		this.exitCode = exit_code;
+	}
+}
+
+function serializeError(error: unknown) {
+	const normalized = error instanceof Error ? error : new Error(String(error));
+	return {
+		name: normalized.name,
+		message: normalized.message,
+		stack: normalized.stack,
+	};
+}
+
+function serializeValue(value: unknown): unknown {
+	if (value === undefined) return null;
+	try {
+		return JSON.parse(JSON.stringify(value));
+	} catch (error) {
+		return String(value);
+	}
+}
+
+function formatLogValue(value: unknown): string {
+	if (typeof value === 'string') return value;
+	if (value instanceof Error) return value.stack || value.message;
+	try {
+		return JSON.stringify(value);
+	} catch (error) {
+		return String(value);
+	}
+}
+
+function createScriptConsole() {
+	const script_console = {} as Record<string, (...values: unknown[]) => void>;
+	for (const level of ['debug', 'log', 'info', 'warn', 'error']) {
+		script_console[level] = (...values: unknown[]) => {
+			ipcRenderer.send('headless-cli-log', {
+				level,
+				message: values.map(formatLogValue).join(' '),
+			});
+		};
+	}
+	return script_console;
+}
+
+async function waitForTextures(): Promise<void> {
+	const pending = Texture.all.map(texture => {
+		const image = texture.img as HTMLImageElement;
+		if (!image || image.complete) return Promise.resolve();
+		return new Promise<void>(resolve => {
+			const finish = () => {
+				image.removeEventListener('load', finish);
+				image.removeEventListener('error', finish);
+				resolve();
+			};
+			image.addEventListener('load', finish, {once: true});
+			image.addEventListener('error', finish, {once: true});
+		});
+	});
+	await Promise.all(pending);
+	// Let Texture.onload finish its project and canvas updates.
+	await new Promise<void>(resolve => setTimeout(resolve, 0));
+}
+
+async function executeScript(options: HeadlessCLIOptions) {
+	let source = options.eval;
+	let source_name = 'blockbench-headless-eval.js';
+	if (options.script) {
+		try {
+			source = fs.readFileSync(options.script, 'utf8');
+			source_name = options.script.replace(/[\r\n]/g, '');
+		} catch (error) {
+			throw new HeadlessCLIError(`Unable to read script: ${options.script}`, HeadlessExitCode.SCRIPT);
+		}
+	}
+
+	const context = {
+		input: options.input,
+		output: options.output,
+		args: options.args.slice(),
+		Blockbench,
+		globals: window,
+		get project() {
+			return Project;
+		},
+		waitForTextures,
+	};
+	const module = {exports: {}} as {exports: any};
+	const exports = module.exports;
+	const script_console = createScriptConsole();
+	const AsyncFunction = Object.getPrototypeOf(async function() {}).constructor;
+	let result;
+	try {
+		const fn = new AsyncFunction(
+			'context',
+			'input',
+			'output',
+			'args',
+			'console',
+			'module',
+			'exports',
+			`"use strict";\n${source}\n//# sourceURL=${source_name}`,
+		);
+		result = await fn.call(
+			window,
+			context,
+			options.input,
+			options.output,
+			options.args.slice(),
+			script_console,
+			module,
+			exports,
+		);
+		const exported_function = typeof module.exports === 'function'
+			? module.exports
+			: (typeof module.exports?.default === 'function' ? module.exports.default : null);
+		if (exported_function) {
+			result = await exported_function.call(window, context);
+		} else if (result === undefined && module.exports !== exports) {
+			result = module.exports;
+		}
+	} catch (error) {
+		if (error instanceof HeadlessCLIError) throw error;
+		const normalized = error instanceof Error ? error : new Error(String(error));
+		const wrapped = new HeadlessCLIError(normalized.message, HeadlessExitCode.SCRIPT);
+		wrapped.name = normalized.name;
+		wrapped.stack = normalized.stack;
+		throw wrapped;
+	}
+	return result;
+}
+
+async function runHeadlessCLIAction(options: HeadlessCLIOptions) {
+	const started_at = performance.now();
+	let phase = 'input';
+	try {
+		let content: string;
+		try {
+			content = fs.readFileSync(options.input, 'utf8');
+		} catch (error) {
+			throw new HeadlessCLIError(`Unable to read input model: ${options.input}`, HeadlessExitCode.INPUT);
+		}
+
+		phase = 'load';
+		const input_codec = loadModelFile({
+			name: PathModule.basename(options.input),
+			path: options.input,
+			content,
+		}, {silent: true});
+		if (!input_codec || !(Project instanceof ModelProject)) {
+			throw new HeadlessCLIError(`Blockbench could not load input model: ${options.input}`, HeadlessExitCode.INPUT);
+		}
+		await waitForTextures();
+
+		phase = 'script';
+		const script_result = await executeScript(options);
+
+		phase = 'output';
+		if (!(Project instanceof ModelProject)) {
+			throw new HeadlessCLIError('The script closed the active project; there is nothing to save', HeadlessExitCode.OUTPUT);
+		}
+		if (!options.force && fs.existsSync(options.output)) {
+			throw new HeadlessCLIError(
+				`Output file already exists (use --force to replace it): ${options.output}`,
+				HeadlessExitCode.OUTPUT,
+			);
+		}
+		Project.save_path = options.output;
+		Project.name = PathModule.basename(options.output, PathModule.extname(options.output));
+		try {
+			const output_content = await Promise.resolve(Codecs.project.compile());
+			if (!options.force) {
+				// Atomically reserve the destination after compilation. This closes the
+				// preflight-check race when independent agents choose the same output.
+				const reservation = fs.openSync(options.output, 'wx');
+				fs.closeSync(reservation);
+			}
+			Codecs.project.write(output_content, options.output);
+		} catch (error) {
+			if (error instanceof HeadlessCLIError) throw error;
+			const message = error instanceof Error ? error.message : String(error);
+			throw new HeadlessCLIError(`Unable to save output model: ${message}`, HeadlessExitCode.OUTPUT);
+		}
+		if (!fs.existsSync(options.output) || !fs.statSync(options.output).isFile()) {
+			throw new HeadlessCLIError(`Blockbench did not create output model: ${options.output}`, HeadlessExitCode.OUTPUT);
+		}
+
+		ipcRenderer.send('headless-cli-result', {
+			ok: true,
+			phase: 'complete',
+			exitCode: 0,
+			format: Format.id,
+			elements: Outliner.elements.length,
+			durationMs: Math.round(performance.now() - started_at),
+			result: serializeValue(script_result),
+		});
+	} catch (error) {
+		ipcRenderer.send('headless-cli-result', {
+			ok: false,
+			phase,
+			exitCode: error instanceof HeadlessCLIError ? error.exitCode : HeadlessExitCode.RUNTIME,
+			error: serializeError(error),
+			durationMs: Math.round(performance.now() - started_at),
+		});
+	}
+}
+
+let initialized = false;
+
+export function initializeHeadlessCLI(): void {
+	if (!Blockbench.isHeadless || initialized) return;
+	initialized = true;
+	ipcRenderer.once('headless-cli-run', (event, options: HeadlessCLIOptions) => {
+		runHeadlessCLIAction(options);
+	});
+}
diff --git a/js/io/io.js b/js/io/io.js
index 89ab2e7cf..42a94944f 100644
--- a/js/io/io.js
+++ b/js/io/io.js
@@ -68,7 +68,7 @@ export function setupDragHandlers() {
 	)
 }
 
-export function loadModelFile(file, args) {
+export function loadModelFile(file, args = {}) {
 	
 	let existing_tab = isApp && ModelProject.all.find(project => (
 		project.save_path == file.path || project.export_path == file.path
@@ -87,7 +87,7 @@ export function loadModelFile(file, args) {
 				} else {
 					codec.load(content, file, args);
 				}
-				return true;
+				return codec;
 			}
 		}
 	}
@@ -95,20 +95,22 @@ export function loadModelFile(file, args) {
 	// Image
 	for (let id in Codecs) {
 		let success = loadIfCompatible(Codecs[id], 'image', file.content);
-		if (success) return;
+		if (success) return success;
 	}
 	// Text
 	for (let id in Codecs) {
 		let success = loadIfCompatible(Codecs[id], 'text', file.content);
-		if (success) return;
+		if (success) return success;
 	}
 	// JSON
-	let model = autoParseJSON(file.content, {file_path: file.path});
+	let model = autoParseJSON(file.content, args.silent ? false : {file_path: file.path});
+	if (model === undefined) return false;
 	for (let id in Codecs) {
 		let success = loadIfCompatible(Codecs[id], 'json', model);
-		if (success) return;
+		if (success) return success;
 	}
-	unsupportedFileFormatMessage(file.path);
+	if (!args.silent) unsupportedFileFormatMessage(file.path);
+	return false;
 }
 
 export async function loadImages(files, event) {
diff --git a/js/plugin_loader.ts b/js/plugin_loader.ts
index 427cd4595..60e0d5263 100644
--- a/js/plugin_loader.ts
+++ b/js/plugin_loader.ts
@@ -1024,7 +1024,7 @@ ExperimentalSettings.add(
 	'plugin_load_timeout',
 	{type: 'number', label: 'Plugin load timeout', min: 0.5, value: 10}
 );
-Plugins.loading_promise = new Promise((resolve, reject) => {
+Plugins.loading_promise = Blockbench.isHeadless ? Promise.resolve() : new Promise((resolve, reject) => {
 	const timeout_seconds = ExperimentalSettings.get('plugin_load_timeout') as number ?? 10;
 	$.ajax({
 		cache: false,
@@ -1069,12 +1069,14 @@ Plugins.loading_promise = new Promise((resolve, reject) => {
 	}, 3000);
 })
 
-$.getJSON('https://blckbn.ch/api/stats/plugins?weeks=2', data => {
-	Plugins.download_stats = data;
-	if (Plugins.json) {
-		Plugins.sort();
-	}
-})
+if (!Blockbench.isHeadless) {
+	$.getJSON('https://blckbn.ch/api/stats/plugins?weeks=2', data => {
+		Plugins.download_stats = data;
+		if (Plugins.json) {
+			Plugins.sort();
+		}
+	})
+}
 
 export async function loadInstalledPlugins() {
 	if (Plugins.loading_promise) {
diff --git a/package.json b/package.json
index 4afe92c6b..8f9a0373c 100644
--- a/package.json
+++ b/package.json
@@ -134,6 +134,10 @@
 		"dev": "concurrently --raw \"electron --remote-debugging-port=9223 .\" \"node ./build.js --target=electron --watch\" --kill-others --success=first",
 		"serve": "node ./build.js --target=web --serve",
 		"electron": "electron .",
+		"headless": "electron . --headless",
+		"test-headless-cli": "node --test tests/headless_cli.test.js",
+		"test-headless-cli-e2e": "npm run build-electron && node --test tests/headless_cli.e2e.test.js",
+		"test-headless-cli-concurrency": "node --test tests/headless_cli.concurrent.test.js",
 		"build-web": "node ./build.js --target=web",
 		"build-electron": "node ./build.js --target=electron",
 		"build-test-portable": "npm run build-electron && electron-builder --windows portable --publish=never",
diff --git a/tests/fixtures/headless_add_cube.js b/tests/fixtures/headless_add_cube.js
new file mode 100644
index 000000000..301c479b7
--- /dev/null
+++ b/tests/fixtures/headless_add_cube.js
@@ -0,0 +1,20 @@
+if (Blockbench.Cube !== Cube || Blockbench.Project !== Project) {
+	throw new Error('Live Blockbench globals are not connected')
+}
+
+Undo.initEdit({outliner: true, elements: [], selection: true})
+const cube = new Cube({
+	name: args[0] || 'headless_cube',
+	from: [0, 0, 0],
+	to: [2, 3, 4],
+}).init()
+Undo.finishEdit('Add headless test cube', {outliner: true, elements: [cube], selection: true})
+Canvas.updateAll()
+
+console.log('created', cube.name)
+return {
+	name: cube.name,
+	from: cube.from,
+	to: cube.to,
+	undoEntries: Undo.history.length,
+}
diff --git a/tests/fixtures/headless_empty.bbmodel b/tests/fixtures/headless_empty.bbmodel
new file mode 100644
index 000000000..54522e299
--- /dev/null
+++ b/tests/fixtures/headless_empty.bbmodel
@@ -0,0 +1,14 @@
+{
+	"meta": {
+		"format_version": "5.0",
+		"model_format": "free",
+		"box_uv": false
+	},
+	"name": "headless_empty",
+	"resolution": {
+		"width": 16,
+		"height": 16
+	},
+	"elements": [],
+	"outliner": []
+}
diff --git a/tests/headless_cli.concurrent.test.js b/tests/headless_cli.concurrent.test.js
new file mode 100644
index 000000000..c635c212b
--- /dev/null
+++ b/tests/headless_cli.concurrent.test.js
@@ -0,0 +1,85 @@
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import {spawn} from 'node:child_process'
+import test from 'node:test'
+import {setTimeout as wait} from 'node:timers/promises'
+
+import electron from 'electron'
+
+const repository = path.resolve(import.meta.dirname, '..')
+const concurrency = Number(process.env.BLOCKBENCH_HEADLESS_CONCURRENCY || 8)
+
+function listHeadlessProfiles() {
+	return new Set(fs.readdirSync(os.tmpdir()).filter(name => name.startsWith('blockbench-headless-')))
+}
+
+function runAction(index, output) {
+	return new Promise((resolve, reject) => {
+		const child = spawn(electron, [
+			'.',
+			'--headless',
+			'--input', path.join(repository, 'tests', 'fixtures', 'headless_empty.bbmodel'),
+			'--eval', `const cube = new Cube({name: "agent_${index}", from: [0, 0, 0], to: [1, 1, 1]}).init(); Canvas.updateAll(); return {uuid: cube.uuid}`,
+			'--output', output,
+			'--timeout', '60000',
+		], {
+			cwd: repository,
+			stdio: ['ignore', 'pipe', 'pipe'],
+			windowsHide: true,
+		})
+		let stdout = ''
+		let stderr = ''
+		child.stdout.setEncoding('utf8').on('data', chunk => stdout += chunk)
+		child.stderr.setEncoding('utf8').on('data', chunk => stderr += chunk)
+		child.on('error', reject)
+		child.on('exit', code => resolve({code, stdout, stderr}))
+	})
+}
+
+test(`${concurrency} independent headless actions can run concurrently`, async t => {
+	assert.ok(Number.isInteger(concurrency) && concurrency > 0 && concurrency <= 64)
+	const profiles_before = listHeadlessProfiles()
+	const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'blockbench-cli-concurrent-'))
+	t.after(() => fs.rmSync(directory, {recursive: true, force: false}))
+
+	const started_at = performance.now()
+	const actions = Array.from({length: concurrency}, (_, index) => {
+		const output = path.join(directory, `agent_${index}.bbmodel`)
+		return runAction(index, output).then(run => ({index, output, ...run}))
+	})
+	const runs = await Promise.all(actions)
+	const duration_ms = Math.round(performance.now() - started_at)
+
+	for (const run of runs) {
+		assert.equal(run.code, 0, `agent ${run.index}\nstdout:\n${run.stdout}\nstderr:\n${run.stderr}`)
+		const model = JSON.parse(fs.readFileSync(run.output, 'utf8'))
+		assert.equal(model.elements.length, 1)
+		assert.equal(model.elements[0].name, `agent_${run.index}`)
+	}
+	console.log(`${concurrency} headless actions completed in ${duration_ms}ms`)
+
+	for (let attempt = 0; attempt < 100; attempt++) {
+		const added = [...listHeadlessProfiles()].filter(name => !profiles_before.has(name))
+		if (!added.length) return
+		await wait(100)
+	}
+	const added = [...listHeadlessProfiles()].filter(name => !profiles_before.has(name))
+	assert.deepEqual(added, [], `Leaked temporary profiles: ${added.join(', ')}`)
+})
+
+test('concurrent actions cannot both claim the same output', async t => {
+	const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'blockbench-cli-collision-'))
+	t.after(() => fs.rmSync(directory, {recursive: true, force: false}))
+	const output = path.join(directory, 'shared.bbmodel')
+	const runs = await Promise.all([
+		runAction('first', output),
+		runAction('second', output),
+	])
+
+	assert.deepEqual(runs.map(run => run.code).sort((a, b) => a - b), [0, 4])
+	const model = JSON.parse(fs.readFileSync(output, 'utf8'))
+	assert.equal(model.elements.length, 1)
+	assert.ok(['agent_first', 'agent_second'].includes(model.elements[0].name))
+})
diff --git a/tests/headless_cli.e2e.test.js b/tests/headless_cli.e2e.test.js
new file mode 100644
index 000000000..c65713836
--- /dev/null
+++ b/tests/headless_cli.e2e.test.js
@@ -0,0 +1,140 @@
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import {spawnSync} from 'node:child_process'
+import test from 'node:test'
+import {setTimeout as wait} from 'node:timers/promises'
+
+import electron from 'electron'
+
+const repository = path.resolve(import.meta.dirname, '..')
+const executable = process.env.BLOCKBENCH_EXECUTABLE || electron
+const application_arguments = process.env.BLOCKBENCH_EXECUTABLE ? [] : ['.']
+
+function listHeadlessProfiles() {
+	return new Set(fs.readdirSync(os.tmpdir()).filter(name => name.startsWith('blockbench-headless-')))
+}
+
+async function assertNoNewProfiles(before) {
+	for (let attempt = 0; attempt < 50; attempt++) {
+		const added = [...listHeadlessProfiles()].filter(name => !before.has(name))
+		if (!added.length) return
+		await wait(100)
+	}
+	const added = [...listHeadlessProfiles()].filter(name => !before.has(name))
+	assert.deepEqual(added, [], `Leaked temporary profiles: ${added.join(', ')}`)
+}
+
+function parseResult(stdout) {
+	const lines = stdout.trim().split(/\r?\n/).reverse()
+	for (const line of lines) {
+		try {
+			const value = JSON.parse(line)
+			if (typeof value.ok === 'boolean' && Number.isInteger(value.exitCode)) return value
+		} catch (error) {}
+	}
+	throw new Error(`No headless result found in stdout:\n${stdout}`)
+}
+
+test('prints help without booting the renderer', () => {
+	const run = spawnSync(executable, [
+		...application_arguments,
+		'--headless',
+		'--help',
+	], {
+		cwd: repository,
+		encoding: 'utf8',
+		timeout: 10_000,
+	})
+
+	assert.equal(run.error, undefined, run.error?.stack)
+	assert.equal(run.status, 0, run.stderr)
+	assert.match(run.stdout.trimStart(), /^Usage:\r?\n  Blockbench --headless/)
+})
+
+test('reports preflight failures as structured results', t => {
+	const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'blockbench-cli-e2e-preflight-'))
+	t.after(() => fs.rmSync(directory, {recursive: true, force: false}))
+	const run = spawnSync(executable, [
+		...application_arguments,
+		'--headless',
+		'--input', path.join(directory, 'missing.bbmodel'),
+		'--eval', 'return true',
+		'--output', path.join(directory, 'output.bbmodel'),
+	], {
+		cwd: repository,
+		encoding: 'utf8',
+		timeout: 10_000,
+	})
+
+	assert.equal(run.error, undefined, run.error?.stack)
+	assert.equal(run.status, 3, run.stderr)
+	const result = parseResult(run.stdout)
+	assert.equal(result.ok, false)
+	assert.equal(result.phase, 'input')
+	assert.match(result.error.message, /does not exist/)
+})
+
+test('opens a bbmodel, edits live globals, and saves a new bbmodel', async t => {
+	const profiles_before = listHeadlessProfiles()
+	const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'blockbench-cli-e2e-'))
+	t.after(() => fs.rmSync(directory, {recursive: true, force: false}))
+	const output = path.join(directory, 'created.bbmodel')
+	const run = spawnSync(executable, [
+		...application_arguments,
+		'--headless',
+		'--input', path.join(repository, 'tests', 'fixtures', 'headless_empty.bbmodel'),
+		'--script', path.join(repository, 'tests', 'fixtures', 'headless_add_cube.js'),
+		'--output', output,
+		'--timeout', '30000',
+		'--', 'agent_cube',
+	], {
+		cwd: repository,
+		encoding: 'utf8',
+		timeout: 40_000,
+	})
+
+	assert.equal(run.error, undefined, run.error?.stack)
+	assert.equal(run.status, 0, `stdout:\n${run.stdout}\nstderr:\n${run.stderr}`)
+	const result = parseResult(run.stdout)
+	assert.equal(result.ok, true, `result:\n${JSON.stringify(result, null, 2)}\nstdout:\n${run.stdout}\nstderr:\n${run.stderr}`)
+	assert.equal(result.result.name, 'agent_cube')
+	assert.ok(result.result.undoEntries >= 1)
+	assert.equal(result.elements, 1)
+
+	const model = JSON.parse(fs.readFileSync(output, 'utf8'))
+	assert.equal(model.elements.length, 1)
+	assert.equal(model.elements[0].name, 'agent_cube')
+	assert.deepEqual(model.elements[0].from, [0, 0, 0])
+	assert.deepEqual(model.elements[0].to, [2, 3, 4])
+	await assertNoNewProfiles(profiles_before)
+})
+
+test('returns the script exit code and does not write output after a script failure', async t => {
+	const profiles_before = listHeadlessProfiles()
+	const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'blockbench-cli-e2e-error-'))
+	t.after(() => fs.rmSync(directory, {recursive: true, force: false}))
+	const output = path.join(directory, 'should_not_exist.bbmodel')
+	const run = spawnSync(executable, [
+		...application_arguments,
+		'--headless',
+		'--input', path.join(repository, 'tests', 'fixtures', 'headless_empty.bbmodel'),
+		'--eval', 'throw new Error("expected script failure")',
+		'--output', output,
+		'--timeout', '30000',
+	], {
+		cwd: repository,
+		encoding: 'utf8',
+		timeout: 40_000,
+	})
+
+	assert.equal(run.error, undefined, run.error?.stack)
+	assert.equal(run.status, 5, `stdout:\n${run.stdout}\nstderr:\n${run.stderr}`)
+	const result = parseResult(run.stdout)
+	assert.equal(result.ok, false)
+	assert.equal(result.phase, 'script')
+	assert.match(result.error.message, /expected script failure/)
+	assert.equal(fs.existsSync(output), false)
+	await assertNoNewProfiles(profiles_before)
+})
diff --git a/tests/headless_cli.test.js b/tests/headless_cli.test.js
new file mode 100644
index 000000000..c8697652d
--- /dev/null
+++ b/tests/headless_cli.test.js
@@ -0,0 +1,95 @@
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import test from 'node:test'
+
+import {
+	HeadlessCLIArgumentError,
+	HeadlessExitCode,
+	createHeadlessCLIProfile,
+	parseHeadlessCLIArguments,
+	removeHeadlessCLIProfile,
+	validateHeadlessCLIPaths,
+} from '../electron/headless_cli.js'
+
+test('returns null outside headless mode', () => {
+	assert.equal(parseHeadlessCLIArguments(['Blockbench', 'model.bbmodel']), null)
+})
+
+test('parses one stateless action and trailing script arguments', () => {
+	const cwd = path.join('C:', 'models')
+	const options = parseHeadlessCLIArguments([
+		'Blockbench',
+		'--headless',
+		'--input', 'creature.bbmodel',
+		'--script', 'remove_saddle.js',
+		'--output', 'creature_no_saddle.bbmodel',
+		'--force',
+		'--timeout', '90000',
+		'--', 'saddle', 'replacement_back',
+	], cwd)
+
+	assert.equal(options.input, path.resolve(cwd, 'creature.bbmodel'))
+	assert.equal(options.script, path.resolve(cwd, 'remove_saddle.js'))
+	assert.equal(options.output, path.resolve(cwd, 'creature_no_saddle.bbmodel'))
+	assert.equal(options.force, true)
+	assert.equal(options.timeout, 90_000)
+	assert.deepEqual(options.args, ['saddle', 'replacement_back'])
+})
+
+test('requires exactly one script source', () => {
+	assert.throws(() => parseHeadlessCLIArguments([
+		'Blockbench', '--headless',
+		'--input', 'in.bbmodel',
+		'--output', 'out.bbmodel',
+	]), HeadlessCLIArgumentError)
+
+	assert.throws(() => parseHeadlessCLIArguments([
+		'Blockbench', '--headless',
+		'--input', 'in.bbmodel',
+		'--output', 'out.bbmodel',
+		'--script', 'action.js',
+		'--eval', 'return 1',
+	]), /cannot be used together/)
+})
+
+test('validates input, script, output extension, and replacement policy', t => {
+	const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'blockbench-cli-test-'))
+	t.after(() => fs.rmSync(directory, {recursive: true, force: false}))
+	const input = path.join(directory, 'input.bbmodel')
+	const script = path.join(directory, 'action.js')
+	const output = path.join(directory, 'output.bbmodel')
+	fs.writeFileSync(input, '{}')
+	fs.writeFileSync(script, 'return true')
+
+	const options = parseHeadlessCLIArguments([
+		'Blockbench', '--headless',
+		'--input', input,
+		'--script', script,
+		'--output', output,
+	])
+	assert.equal(validateHeadlessCLIPaths(options), options)
+
+	fs.writeFileSync(output, '{}')
+	assert.throws(() => validateHeadlessCLIPaths(options), error => {
+		assert.match(error.message, /already exists/)
+		assert.equal(error.exitCode, HeadlessExitCode.OUTPUT)
+		return true
+	})
+	options.force = true
+	assert.equal(validateHeadlessCLIPaths(options), options)
+
+	options.output = path.join(directory, 'wrong.json')
+	assert.throws(() => validateHeadlessCLIPaths(options), /\.bbmodel extension/)
+})
+
+test('ephemeral profiles are unique and cleanup rejects unrelated paths', () => {
+	const first = createHeadlessCLIProfile()
+	const second = createHeadlessCLIProfile()
+	assert.notEqual(first, second)
+	assert.equal(removeHeadlessCLIProfile(first), true)
+	assert.equal(removeHeadlessCLIProfile(second), true)
+	assert.equal(removeHeadlessCLIProfile(second), false)
+	assert.throws(() => removeHeadlessCLIProfile(os.tmpdir()), /Refusing to remove/)
+})