Command-line interface

The Narratyr CLI runs without opening the editor. Use it to check projects and export game data in continuous integration (CI). It can also update older projects to the current format.

Run from a terminal

The desktop application includes the CLI. It uses the bundled runtime, so you don't need a separate Node.js installation.

Windows

The installer adds Narratyr's installation directory to your user PATH. Open a new terminal after installing, then run:

narratyr-cli --help

If the command isn't found, run narratyr-cli.cmd from the Narratyr installation directory. In PowerShell, use & before a quoted executable path.

macOS

Run the launcher inside the application bundle:

/Applications/Narratyr.app/Contents/Resources/narratyr-cli --help

To use the shorter command in the current terminal, add its directory to PATH:

export PATH="/Applications/Narratyr.app/Contents/Resources:$PATH"
narratyr-cli --help

Adjust the path if you installed Narratyr somewhere else. Add the export PATH line to your shell's startup file to keep it for future sessions.

Linux

The Debian package puts narratyr-cli on PATH:

narratyr-cli --help

AppImage and Snap packages include the launcher but don't add it to PATH automatically. The examples below assume narratyr-cli is available in your shell.

Help and project paths

Use --help on any command to see its options:

narratyr-cli export --help

Command	Purpose	Writes
validate	Report project issues	Prints results only
normalize	Migrate a project to the current document format	The source project, unless you pass --check
export	Install engine support, export data, or both	The target engine project
install-license	Install a signed license file	The selected user-data directory

Project commands accept the project formats listed below.

Extension	Format
.ntproj	Split project file
.ntprojc	Combined project file

For a split project, pass the .ntproj file, with its sibling .ntproj.data folder beside it. Paths are relative to the terminal's current working directory. Quote paths that contain spaces.

The CLI reads saved project data. Save changes in the editor before running it. It doesn't recover interrupted saves. Open an affected project in the editor to recover it first.

Validate a project

validate runs the same project checks as the editor:

narratyr-cli validate --project "Story.ntproj"

Option	Meaning
-p, --project <path>	Required. Project to check.
-f, --format <format>	text (default) or json.
-s, --min-severity <severity>	error (default) or warning. Sets the severity that fails the command.

By default, the command groups issues by editor view and includes issue codes, messages, target IDs, and error and warning counts. All issues appear in the output regardless of --min-severity. That option only controls the exit code.

To fail a build on warnings and errors:

narratyr-cli validate --project "Story.ntproj" --min-severity warning

For structured output:

narratyr-cli validate --project "Story.ntproj" --format json

The JSON result contains issues, errorCount, and warningCount. Each issue includes code, severity, message, and navTarget, which identifies its location in the editor. A failure to load or process the project returns { "ok": false, "error": "..." } instead. Validation reports issues without applying fixes.

Normalize a project

normalize applies the document migrations used when opening a project in the editor, then saves the result back to the same path:

narratyr-cli normalize --project "Story.ntproj"

Option	Meaning
-p, --project <path>	Required. Project to migrate.
--check	Report whether the project needs migration without writing.
-f, --format <format>	text (default) or json.

Check pending changes before writing, or use this as a CI check:

narratyr-cli normalize --project "Story.ntproj" --check --format json

Successful JSON output contains ok, upToDate, changed, and written. changed lists the top-level document sections affected, such as version or graphs. With --check, written is always false, and the command exits with 1 if the project needs changes. Without --check, a successful migration exits with 0. A project that's already current isn't rewritten.

Normalization keeps the project's existing split or combined format. For split projects, only changed project files are rewritten. Commit or back up the source project before migrating so you can review the changes. Run validate afterward to check for content issues.

Export to an engine

export runs the engine export workflow from the terminal. Supply an engine, operation, source project, and root directory of the engine project:

narratyr-cli export --engine unreal --operation both --project "Story.ntproj" --out "../MyUnrealGame"
narratyr-cli export --engine godot --operation both --project "Story.ntproj" --out "../MyGodotGame"
narratyr-cli export --engine unity --operation both --project "Story.ntproj" --out "../MyUnityGame"

Choose the root directory containing the engine project.

Operation	Result
install	Write the engine runtime support and any generated code for the project.
data	Write game data and copy referenced assets.
both	Run installation followed by data export.

Run both for initial setup. Run installation again when runtime support or generated types change. Exporting writes files for the engine to import. Follow the integration guide for Unreal Engine, Godot, or Unity for the remaining setup steps.

Option	Meaning
-e, --engine <engine>	unreal, godot, or unity. Required unless supplied in the configuration file.
-o, --operation <operation>	install, data, or both. Required unless supplied in the configuration file.
-p, --project <path>	Source project. Required unless supplied in the configuration file.
--out <path>	Root directory of the engine project. Required unless supplied in the configuration file.
--source-locale <code>	Source locale for Godot and Unity translations. Default: en.
--no-cleanup	Keep obsolete exported source files during Unreal data export.
--config <path>	Read export settings from a JSON file.
--user-data-dir <path>	Read the license from a different user-data directory.
--json	Write a JSON result to standard output.
--quiet	Suppress success output. Report warnings on standard error.

Unreal data export removes obsolete Narratyr source files and copied assets under Content/NarratyrData by default. It doesn't delete engine-generated .uasset files. Use --no-cleanup to keep those source files. This option has no effect on Godot or Unity.

Export configuration

Save repeated settings in a JSON file such as narratyr-export.json:

{
  "engine": "unity",
  "operation": "both",
  "project": "Story.ntproj",
  "out": "../MyUnityGame",
  "sourceLocale": "en",
  "cleanup": true
}

Run it with:

narratyr-cli export --config "narratyr-export.json"

The supported configuration fields are engine, operation, project, out, sourceLocale, and cleanup. Command-line values override matching configuration fields. --no-cleanup overrides cleanup. Relative paths in the configuration resolve from the terminal's working directory. Supply --user-data-dir, --json, and --quiet as flags.

To export only data using the same configuration:

narratyr-cli export --config "narratyr-export.json" --operation data --json

Export results

Successful JSON output contains ok: true, fileCount, assetCount, warnings, deletedCount, and deletedPaths. The exporter skips identical asset copies, so assetCount counts assets copied during this run. Warnings can accompany a successful exit, including asset-copy failures. Check the warnings array when deciding whether a build can continue.

Failures return ok: false and error. A license node-limit failure also includes code: "license_node_limit_exceeded", nodeCount, and limit.

Install a license

Without a valid Pro license, export uses the free tier's limit of 500 graph nodes across the project. This applies to all export operations, including install. validate and normalize don't require a Pro license.

Install a signed license file before exporting larger projects:

narratyr-cli install-license --file "license.rpgedlicense"

Option	Meaning
-f, --file <path>	Required. Signed license file to install.
--user-data-dir <path>	Install into a different user-data directory.
--json	Write a JSON result to standard output.
--quiet	Suppress success output. Errors still appear.

By default, installation and export use the same license directory as the desktop app:

Platform	Default directory
Windows	%APPDATA%\Narratyr
macOS	~/Library/Application Support/Narratyr
Linux	$XDG_CONFIG_HOME/Narratyr, or ~/.config/Narratyr when unset

For a build job, provide the signed file through your secrets storage and choose a dedicated directory. Pass the same --user-data-dir to both commands. License installation creates the directory if needed.

Successful JSON output includes ok, edition, licenseId, and expiresAt, plus customer details when present. expiresAt is null for a perpetual license. Failures include ok: false and error.

Automate builds

Use the same Narratyr version locally and in CI so validation, migrations, and exports agree. The following Bash example stops at the first failed command. It assumes the launcher is on PATH and the job's secrets storage supplied the signed license file:

set -e
narratyr-cli normalize --project "Story.ntproj" --check
narratyr-cli validate --project "Story.ntproj" --min-severity warning
narratyr-cli install-license --file "$NARRATYR_LICENSE_FILE" --user-data-dir "./ci-user-data" --quiet
narratyr-cli export --config "narratyr-export.json" --user-data-dir "./ci-user-data" --json > export-result.json

Skip the license installation step for projects within the free-tier limit. Keep license files and the license directory out of version control and public build artifacts.

Exit codes and output

Command	Exit 0	Exit 1
validate	Project passes the chosen severity threshold	Matching issues, or a command failure
normalize --check	Project is current	Migration needed, or a command failure
normalize	Already current, or migrated and saved	A command failure
export	Export completed, possibly with warnings	Export or license failure
install-license	License installed	File, validation, or installation failure

Use --format json for validate and normalize, and --json for export and install-license. JSON takes precedence over --quiet. Command argument errors, such as an unknown flag or an invalid option value, can still produce plain text on standard error and exit with 1. Check the exit code and any JSON output.