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.

Check opens the asset index read-only unless --ensure-meta is given; a script outside scripts/ is reported as an import error.

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
--release-json	also pack the export into one archive and write the signed release.json its copies update from
--channel stable|nightly	channel of that release
--base-url url	where the archive is downloaded from, update.url/<channel> by default
--key-file file	private key that signs release.json, from aego release keygen

A game updates itself when project.aego has update { url="https://…" publicKey="…" }; upload the archive, release.json and release.json.sig to <url>/<channel>/. See aego/update.

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 version

aego version prints the engine version and the commit the binary was built from, such as aego 0.11.0-dev (6151233e0586, 2026-10-25T13:17:32Z). A build from a checkout with uncommitted changes adds -dirty to the commit.

aego update

aego update [status|check|apply|restore] [--channel stable|nightly] manages updates of an installed copy: status shows the version, the mode and how Aego was installed, check looks for a newer version, apply downloads and installs it for the next start, restore goes back to the version before the last update. See Updates.

aego release

aego release keygen [--out base] makes the Ed25519 pair that signs releases: <base>.key is the private key, readable only by you and never committed; <base>.pub is the public key for project.aego or the build. Without --out the pair goes to keys/release in the user config folder. aego release manifest --version v --channel c --base-url url [--notes file] [--min v] [--key-file file] [--out dir] <files>… writes release.json for the files and signs it into release.json.sig.

aego mcp

Serves the project over MCP on stdio, for tools such as Claude Code; 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. They use the same operations as the editor, 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. The editor picks up edits of existing files.

Command	Meaning
aego anim add-event <file> <time> <name> [--payload v] [--mode v] [--dry-run]	add an event; the name must be declared in Project Settings → Animation
aego anim expand-frames <file> <target> [--dry-run]	turn a frames block into sprite tracks with step keys, so its frames can be edited one by one
aego anim get <file>	length, loop, tracks with their keys, frames blocks and events of a clip
aego anim move-event <file> <index> <time> [--dry-run]	move an event to another time
aego anim move-key <file> <target> <prop> <time> <to> [--dry-run]	move a key to another time
aego anim remove-event <file> <index> [--dry-run]	remove an event
aego anim remove-key <file> <target> <prop> <time> [--dry-run]	remove a key; the last key removes its track
aego anim remove-track <file> <target> <prop> [--dry-run]	remove a track with all its keys
aego anim set <file> <attr> [<value>] [--dry-run]	set length, loop or fps of a clip; no value clears loop or fps
aego anim set-key <file> <target> <prop> <time> <value> [--kind v] [--interp v] [--tangent v] [--dry-run]	set a key; a new track needs --kind
aego asset delete <asset> [--force] [--dry-run]	delete an asset; refuses while it is referenced unless --force
aego asset import-variant [--variant v] [--path v] [--replace] [--dry-run]	Import an inspected generated PNG variant from this editor conversation as a stable project source asset
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 paint <path> [--ops v] [--width v] [--height v] [--source v] [--palette v] [--replace] [--dry-run]	Edit a source PNG, create a transparent canvas, or paint on a copy of another source PNG. A single reversible batch; returns image pixels. Coordinates are top-left source pixels.
aego asset pixels <path> [--grid v] [--palette v] [--scale v] [--flipbook] [--replace] [--dry-run]	draw a sprite as text: each character of grid is a pixel colored by palette; lines like idle: start frames of one size, which become an atlas with one sprite per frame and a looping flipbook clip. Answers with a preview image
aego asset rename <asset> <name> [--dry-run]	rename an asset in its folder
aego asset svg <path> [--svg v] [--width v] [--height v] [--replace] [--dry-run]	draw a texture from SVG: path, rect, circle, ellipse, line, polyline, polygon, fill, stroke, opacity and transform; no filters, gradients or text. For tiles, UI and item icons. Answers with a preview image
aego ctrl add-param <file> <name> <kind> [--default v] [--dry-run]	add a parameter
aego ctrl add-state <file> <name> [--clip v] [--speed v] [--loop v] [--pos v] [--dry-run]	add a state
aego ctrl add-transition <file> <from> <to> [--duration v] [--exit v] [--interrupt] [--cond v] [--dry-run]	add a transition; from may be any
aego ctrl entry <file> <name> [--dry-run]	set the state the animator starts in
aego ctrl get <file>	parameters, states and transitions of a controller
aego ctrl remove-param <file> <name> [--dry-run]	remove a parameter; conditions on it become problems
aego ctrl remove-state <file> <name> [--dry-run]	remove a state and the transitions into and out of it
aego ctrl remove-transition <file> <index> [--dry-run]	remove a transition
aego ctrl set-state <file> <name> <attr> [<value>] [--dry-run]	set clip, speed, loop, events or pos of a state
aego ctrl set-transition <file> <index> <attr> [<value>] [--dry-run]	set to, duration, exitTime or interrupt of a transition
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 material apply <file> [--tx v] [--expected v] [--dry-run]	apply a material transaction atomically, using the same mutations and serialization as Inspector
aego material assign <file> <node> <material> [--dry-run]	assign a compatible material to SpriteRenderer or Mesh2D through the scene mutation service
aego material create <file> <shader> [--dry-run]	create a material inheriting defaults from a shader
aego material get <file>	read explicit/inherited parameters, unknown data, variants and source revision from the current document
aego material reset <file> <param> [--expected v] [--dry-run]	remove an explicit parameter and inherit the shader default
aego material set <file> <param> <value> [--expected v] [--dry-run]	set a typed explicit parameter as one semantic mutation
aego material validate <file>	validate material values, shader and texture references without changing the source
aego material variants <file> [--keywords v] [--expected v] [--dry-run]	select an allowed combination of comma-separated keywords; an empty string selects no keywords
aego postfx get <file> <node>	read the authored camera stack including stable instance IDs from the live scene
aego postfx set <file> <node> <instance> <field> <value> [--dry-run]	set an effect switch or typed numeric parameter by persistent instance ID in one scene edit
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 get [<section>]	module sections of project.aego (physics, …) with their current values
aego project input-action <name> [--type v] [--bind v] [--context v] [--active] [--dry-run]	Create/update one action and add it to a context. Binding strings use the project input syntax. Only an empty initial stack is initialized.
aego project main-scene <file> [--dry-run]	Set an imported scene as the startup scene by project-relative path.
aego project set <section> <field> [<value>] [--reset] [--dry-run]	set a field of a module section in project.aego, for example physics gravity [0, -15]
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> [--preset v] [--no-required] [--dry-run]	add a component with its defaults and the components it requires, or attach a script by its type name
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] [--watch v] [--input v] [--assert v] [--camera v] [--shot v] [--scale v]	run a scene headless and report the log, the state hash and where the watched nodes went
aego scene set <file> <node> <path> <value> [--dry-run]	set a field
aego scene tree <file> [--node v]	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> [--lang v]	fields of a type: kind, range, unit, default, flags and docs
aego script create <file> [--text v] [--dry-run]	create a script file; it fails when the file exists, so change an existing script with script.edit
aego script edit <file> [--old v] [--new v] [--dry-run]	replace text in a script; old must match exactly once, so quote enough lines around the change
aego script read <file> [--from v] [--to v]	text of a script, as the editor has it, with unsaved changes; from and to read a part of a long one
aego script write <file> [--text v] [--dry-run]	replace the whole text of a script; for a small change script.edit is safer
aego shader create <file> [--dry-run]	create a portable sprite shader through the registered asset importer
aego shader schema <shader>	declared parameters, typed defaults, domain and allowed variants; checks current source and unsaved includes
aego shader validate <shader>	validate current source with the registered importer; reports schema/reference validation independently from GPU linking
aego texture apply <file> [--tx v] [--expected v] [--dry-run]	atomic typed texture metadata transaction; same validation and Undo rules as Inspector
aego texture channel <file> <channel> <asset> [--frame v] [--expected v] [--dry-run]	assign a normal/height/emission source or frame by stable AssetID; unresolved IDs are retained with diagnostics
aego texture channel-reset <file> <channel> [--frame v] [--expected v] [--dry-run]	remove the explicit channel mapping without deleting source assets
aego texture get <file>	read current dirty metadata, stable frames, source size, roles and channel references
aego texture reset <file> <setting> [--expected v] [--dry-run]	remove an explicit import setting and inherit the importer default
aego texture schema	registered import roles/settings and source-frame channel contract
aego texture set <file> <setting> <value> [--expected v] [--dry-run]	set an import setting using the shared semantic mutation service
aego texture validate <file>	check source metadata and prepare a private import candidate without changing cache or GPU resources

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.