CLI Reference

The plotknot compiler is a command-line tool with three subcommands.

Usage

plotknot <command> [options]

Commands

compile

Compile a .plotknot file to engine output.

plotknot compile <file> [options]

Example:

plotknot compile stories/main.plotknot --output build/
# compiled: stories/main.plotknot -> build/main.lua

The compiler runs the full pipeline: lex → parse → validate → generate. If validation finds errors, compilation fails with exit code 1.

validate

Check a .plotknot file for errors without generating output.

plotknot validate <file>

Example:

plotknot validate stories/main.plotknot
# valid: stories/main.plotknot

Or with warnings:

# valid with warnings: stories/main.plotknot

watch

Watch a file and recompile on changes.

plotknot watch <file> [options]

Example:

plotknot watch stories/main.plotknot --output build/
# watching: stories/main.plotknot (press Ctrl+C to stop)
# change detected, recompiling...
# compiled: stories/main.plotknot -> build/main.lua

Polls every 500ms for file modification time changes.

Options

Option	Description	Default
--target <name>	Target engine	defold
--output <dir>	Output directory	. (current dir)
--lang <code>	Target language for localization	(all)
--version, -v	Print version	—
--help, -h	Print help	—

Exit codes

Code	Meaning
0	Success
1	Validation errors or compile failure
2	Usage error (bad arguments, missing file)

Error output format

Errors and warnings are printed to stderr in a compiler-standard format:

file.plotknot:12:5: error: goto target 'missing_section' does not match any section
file.plotknot:8:1: warning: variable 'gold' used before being set

Format: file:line:col: severity: message

Targets

defold (default)

Produces a Lua table file (.lua) containing the story data. The output is a pure data file — no executable code, just tables that the runtime loads.

plotknot compile story.plotknot --target defold --output assets/

Building from source

# Development build
nim c src/plotknot.nim

# Release build (optimized)
nim c -d:release src/plotknot.nim

# Run tests
nimble test

Examples

Compile all stories in a directory:

for f in stories/*.plotknot; do
  plotknot compile "$f" --output build/
done

Validate in CI:

plotknot validate stories/main.plotknot || exit 1

Watch during development:

plotknot watch stories/main.plotknot --output /path/to/game/assets/