aego/engine/res/docs/cli.md

id, title, group, order

id	title	group	order
cli	The aego command	ref-cli	1

The aego command

Every command takes the project directory as its first argument and looks for project.aego upwards from the current directory when it is left out. Commands print diagnostics with file, line and code and exit with a non-zero status on any error, so they run unchanged in CI.

aego new

Creates a project from a template or an engine example and checks it.

Flag	Meaning
--template empty|2d|2.5d|3d	starting contents, 2d by default
--module name	module path of the scripts, the directory name by default
--example name	copy an engine example instead of a template
--native	add a native Go module under native/
--engine dir	engine source tree, needed for native projects and examples

aego edit

Opens the project in the editor. Without a project it opens the launcher. Native projects run under a supervisor that rebuilds and restarts the editor when Go code changes.

Flag	Meaning
--profile name	player settings profile used by Play
--debug	verbose logging and GPU debug output
--cpuprofile file	write a CPU profile
--hidden, --headless, --frames n	for tests: hidden window, no window, stop after n frames

aego run

Imports assets and runs the main scene. Assets and scripts reload on save; native code is rebuilt and the game restarts with its state.

Flag	Meaning
--scene file	run this scene instead of the main scene
--profile name	player settings profile
--trace file	write a Chrome trace of the last frames on exit
--headless, --frames n	run without a window, stop after n frames
--debug	verbose logging and GPU debug output

aego check

Parses every document, audits .meta sidecars, checks project sections and assets and type-checks every script package. Exit 1 on problems, 2 when native code does not build.

Flag	Meaning
--explain	print the reference entry of every reported diagnostic code
--ensure-meta	write missing .meta files instead of reporting them
--manifest file	check against this bindings manifest instead of building one

aego test

Runs *_test.aes script tests headless, or with --determinism runs the game twice and compares state hashes.

Flag	Meaning
-run name	only tests whose name contains this
-v	list passing tests too; with --determinism, the services the hash covers
-budget n	instruction budget per test
-seed n	seed of aego/rand, and of both runs with --determinism
--determinism	compare two runs instead of running tests
--frames n, --every n, --scene file	length of the runs, checkpoint spacing, scene to run

aego export

Builds a distributable game that runs without Go and without the project sources.

Flag	Meaning
--target host|linux|windows|darwin	target platform, host by default
--release, --development	build profile
--out dir	output directory
--check	run the pre-export checks only
--json	print the build report as JSON
--cc compiler	C compiler for a cross target

aego build

Builds the native binary of a project with a native/ module and prints its path.

aego bootstrap

Regenerates .aego/generated for the native module without building it.

aego import

Reimports every asset; --force ignores the artifact cache.

aego icons

aego icons check compares icon use with the icon sources and fails on missing or unused icons; aego icons list [--json] [--out file] prints the manifest.

aego dump

aego dump script <package|Type> [--func name] disassembles a compiled script package with its source lines.

aego mcp

Serves the project to an AI agent over MCP on stdio; see Working with AI agents.

Flag	Meaning
--watch	send resource updates when project files change
--interval d	how often --watch polls, 500ms by default
--project dir	project directory

Editing from the command line

These commands read and change scenes, prefabs, data assets and references without the editor, through the same operations the editor uses, and every change can be undone by applying its inverse. Paths are relative to the project root; a node is a path from the root (Player/Sprite) or #<id>; a value is written in scene syntax. Every command takes --json (a stable machine-readable report), --quiet, --strict (warnings fail too) and --project dir; commands that write take --dry-run, which reports the changes and touches nothing. The exit status is 0 on success, 1 on an error and 2 when the result has error-level problems. While the editor has the project open, commands that create assets refuse to run; edits of existing files are picked up by the editor.

Command	Meaning
aego asset delete <asset> [--force] [--dry-run]	delete an asset; refuses while it is referenced unless --force
aego asset list [--kind v]	assets with their ids and kinds
aego asset move <asset> <to> [--dry-run]	move an asset with its .meta; the id and every reference stay
aego asset rename <asset> <name> [--dry-run]	rename an asset in its folder
aego data add-row <file> <id> [--dry-run]	add a row with defaults
aego data base <file> [<asset>] [--dry-run]	set or clear the base asset of a data asset
aego data export <file> <csv> [--dry-run]	write the rows of a table to a csv file
aego data get <file> [--row v]	fields set in a data asset or a table row; omitted fields use the base or the type default
aego data import <file> <csv> [--dry-run]	replace the rows of a table with a csv file
aego data remove-row <file> <id> [--dry-run]	remove a row
aego data rename-row <file> <id> <name> [--dry-run]	change a row id
aego data reset <file> <path> [--row v] [--dry-run]	remove a field so it falls back to the base or the default
aego data rows <file>	row ids of a table
aego data set <file> <path> <value> [--row v] [--dry-run]	set a field
aego prefab apply <file> <node> [--level v] [--owner v] [--field v] [--nearest] [--dry-run]	write instance overrides into the prefab file
aego prefab create <file> <node> <out> [--dry-run]	turn a node into a prefab file and link the node to it
aego prefab instantiate <file> <prefab> [--parent v] [--name v] [--index v] [--dry-run]	add an instance of a prefab
aego prefab overrides <file> <node>	list the overrides of the instance a node belongs to
aego prefab revert <file> <node> [--level v] [--owner v] [--field v] [--dry-run]	drop instance overrides
aego prefab unpack <file> <node> [--deep] [--dry-run]	turn an instance into plain nodes
aego project validate	missing assets and nodes, import errors, prefabs and scenes that do not load
aego refs find <asset>	files and fields that reference an asset
aego refs fix <from> [<to>] [--dry-run]	point every reference to one asset at another (none clears them); originals go to .aego/recovery
aego refs missing	references to assets and nodes that do not exist
aego scene add-comp <file> <node> <comp> [--dry-run]	add a component with its defaults
aego scene add-node <file> <name> [--parent v] [--space v] [--index v] [--dry-run]	add an empty node
aego scene apply <file> [--tx v] [--tx-file v] [--dry-run]	apply a transaction (tx version=1 { op … }) in one step
aego scene get <file> <node> [<path>]	a node with its transform and every saved field, or one field
aego scene move <file> <node> <parent> [--index v] [--keep-world] [--dry-run]	move a node under another parent
aego scene new <file> [--dry-run]	create an empty scene
aego scene remove-comp <file> <node> <comp> [--dry-run]	remove a component
aego scene remove-node <file> <node> [--dry-run]	remove a node with its children
aego scene rename <file> <node> <name> [--dry-run]	rename a node
aego scene reset <file> <node> <path> [--dry-run]	reset a field to its default, a transform part to identity
aego scene run [<file>] [--frames v] [--seed v]	run a scene headless and report the log and the state hash
aego scene set <file> <node> <path> <value> [--dry-run]	set a field
aego scene tree <file>	node tree with IDs, components, scripts and prefab links
aego scene validate <file>	load problems and references to nodes the scene does not have
aego schema list [--kind v]	component and data types
aego schema show <type>	fields of a type: kind, range, unit, default, flags and docs

aego docs

Command	Meaning
aego docs export [--out file]	write the documentation registry as JSON
aego docs check [--strict]	broken links, missing groups and orders, undocumented bindings, Script API modules and script guides without a runnable example
aego docs build [--out dir] [--playground=false] [--repo url]	generate the static site with the playground
aego docs serve [--addr host:port]	build, serve on localhost and rebuild on changes

--project dir documents a project's own scripts, --engine dir points at the engine source tree.