aego/engine/res/docs/cli.ru.md

---
id: cli
title: Команда aego
---

# Команда aego

Каждая команда принимает папку проекта первым аргументом; если его нет, она ищет `project.aego` вверх от текущей папки. Команды выводят диагностику с файлом, строкой и кодом и при любой ошибке завершаются с ненулевым кодом, поэтому в CI они работают без изменений.

## aego new

Создаёт проект из шаблона или примера движка и проверяет его.

| Флаг | Значение |
|---|---|
| `--template empty\|2d\|2.5d\|3d` | начальное содержимое, по умолчанию `2d` |
| `--module name` | путь модуля скриптов, по умолчанию имя папки |
| `--example name` | скопировать пример движка вместо шаблона |
| `--native` | добавить нативный модуль на Go в `native/` |
| `--engine dir` | дерево исходников движка; нужно для нативных проектов и примеров |

## aego edit

Открывает проект в редакторе. Без проекта открывает лаунчер. Нативные проекты работают под присмотром процесса, который пересобирает и перезапускает редактор, когда меняется код на Go.

| Флаг | Значение |
|---|---|
| `--profile name` | профиль настроек игрока для игры в редакторе |
| `--debug` | подробный журнал и отладочный вывод GPU |
| `--cpuprofile file` | записать профиль процессора |
| `--hidden`, `--headless`, `--frames n` | для тестов: скрытое окно, без окна, остановиться через n кадров |

## aego run

Импортирует ассеты и запускает главную сцену. Ассеты и скрипты перезагружаются при сохранении; нативный код пересобирается, и игра перезапускается со своим состоянием.

| Флаг | Значение |
|---|---|
| `--scene file` | запустить эту сцену вместо главной |
| `--profile name` | профиль настроек игрока |
| `--trace file` | при выходе записать трассировку Chrome последних кадров |
| `--headless`, `--frames n` | запустить без окна, остановиться через n кадров |
| `--debug` | подробный журнал и отладочный вывод GPU |

## aego check

Разбирает каждый документ, проверяет файлы `.meta`, разделы проекта и ассеты и проверяет типы в каждом пакете скриптов. Код выхода 1 при проблемах, 2 — когда нативный код не собирается.

Проверка открывает индекс ассетов только для чтения, если не задан `--ensure-meta`; скрипт вне `scripts/` считается ошибкой импорта.

| Флаг | Значение |
|---|---|
| `--explain` | вывести статью справочника для каждого найденного кода диагностики |
| `--ensure-meta` | записать недостающие файлы `.meta`, а не сообщать о них |
| `--manifest file` | проверять по этому манифесту привязок, а не собирать новый |

## aego test

Запускает тесты скриптов `*_test.aes` без окна, а с `--determinism` запускает игру дважды и сравнивает хеши состояния.

| Флаг | Значение |
|---|---|
| `-run name` | только тесты, в имени которых есть эта строка |
| `-v` | перечислить и пройденные тесты; с `--determinism` — службы, которые входят в хеш |
| `-budget n` | бюджет инструкций на тест |
| `-seed n` | зерно `aego/rand`, а с `--determinism` — зерно обоих запусков |
| `--determinism` | сравнить два запуска вместо запуска тестов |
| `--frames n`, `--every n`, `--scene file` | длина запусков, интервал между контрольными точками, сцена для запуска |

## aego export

Собирает игру для распространения, которой не нужны ни Go, ни исходники проекта.

| Флаг | Значение |
|---|---|
| `--target host\|linux\|windows\|darwin` | целевая платформа, по умолчанию `host` |
| `--release`, `--development` | профиль сборки |
| `--out dir` | папка вывода |
| `--check` | только выполнить проверки перед экспортом |
| `--json` | вывести отчёт о сборке в JSON |
| `--cc compiler` | компилятор C для другой платформы |
| `--release-json` | ещё упаковать экспорт в один архив и записать подписанный `release.json`, по которому обновляются копии |
| `--channel stable\|nightly` | канал этого релиза |
| `--base-url url` | откуда скачивается архив, по умолчанию `update.url/<канал>` |
| `--key-file file` | закрытый ключ, которым подписывается `release.json`, из `aego release keygen` |

Игра обновляет себя, если в `project.aego` есть `update { url="https://…" publicKey="…" }`; выложите архив, `release.json` и `release.json.sig` в `<url>/<канал>/`. См. [aego/update](ref:aego/update).

## aego build

Собирает нативный исполняемый файл проекта с модулем `native/` и выводит путь к нему.

## aego bootstrap

Перегенерирует `.aego/generated` для нативного модуля без сборки.

## aego import

Заново импортирует все ассеты; `--force` не использует кэш артефактов.

## aego icons

`aego icons check` сверяет используемые иконки с исходниками иконок и завершается ошибкой, если иконки нет или она не используется; `aego icons list [--json] [--out file]` выводит манифест.

## aego dump

`aego dump script <package|Type> [--func name]` дизассемблирует скомпилированный пакет скриптов с его строками исходника.

## aego version

`aego version` выводит версию движка и коммит, из которого собрана программа, например `aego 0.11.0-dev (6151233e0586, 2026-10-25T13:17:32Z)`. У сборки из рабочей копии с незакоммиченными изменениями к коммиту добавляется `-dirty`.

## aego update

`aego update [status|check|apply|restore] [--channel stable|nightly]` управляет обновлениями установленной копии: `status` показывает версию, режим и способ установки, `check` ищет новую версию, `apply` скачивает её и ставит для следующего запуска, `restore` возвращает версию до последнего обновления. См. [Обновления](ref:install).

## aego release

`aego release keygen [--out base]` создаёт пару ключей Ed25519 для подписи релизов: `<base>.key` — закрытый ключ, доступный только вам, его не коммитят; `<base>.pub` — открытый ключ для `project.aego` или сборки. Без `--out` пара попадает в `keys/release` в папке настроек пользователя. `aego release manifest --version v --channel c --base-url url [--notes file] [--min v] [--key-file file] [--out dir] <files>…` пишет `release.json` для файлов и подписывает его в `release.json.sig`.

## aego mcp

Отдаёт проект по MCP через stdio для таких инструментов, как Claude Code; см. [Работа с ИИ-агентами](ref:agents).

| Флаг | Значение |
|---|---|
| `--watch` | отправлять обновления ресурсов, когда меняются файлы проекта |
| `--interval d` | как часто опрашивает `--watch`, по умолчанию 500ms |
| `--project dir` | папка проекта |

## Правка из командной строки

Эти команды читают и меняют сцены, префабы, ассеты данных и ссылки без редактора. Они используют те же операции, что и редактор, и любое изменение можно отменить, применив обратное ему.

- Пути задаются относительно корня проекта. Узел — это путь от корня (`Player/Sprite`) или `#<id>`. Значение записывается в синтаксисе сцены.
- Каждая команда принимает `--json` (стабильный машиночитаемый отчёт), `--quiet`, `--strict` (предупреждения тоже приводят к ошибке) и `--project dir`.
- Команды, которые пишут, принимают `--dry-run`: он сообщает об изменениях и ничего не трогает.
- Код выхода — 0 при успехе, 1 при ошибке и 2, когда в результате есть проблемы уровня ошибки.
- Пока проект открыт в редакторе, команды, создающие ассеты, отказываются работать. Правки существующих файлов редактор подхватывает.

<!-- agent:begin -->
| Команда | Значение |
|---|---|
| `aego anim add-event <file> <time> <name> [--payload v] [--mode v] [--dry-run]` | добавить событие; имя должно быть объявлено в **Настройках проекта → Анимация** |
| `aego anim expand-frames <file> <target> [--dry-run]` | превратить блок frames в дорожки спрайтов со ступенчатыми ключами, чтобы править кадры по одному |
| `aego anim get <file>` | длина, повтор, дорожки с ключами, блоки frames и события клипа |
| `aego anim move-event <file> <index> <time> [--dry-run]` | перенести событие на другое время |
| `aego anim move-key <file> <target> <prop> <time> <to> [--dry-run]` | перенести ключ на другое время |
| `aego anim remove-event <file> <index> [--dry-run]` | удалить событие |
| `aego anim remove-key <file> <target> <prop> <time> [--dry-run]` | удалить ключ; вместе с последним ключом удаляется его дорожка |
| `aego anim remove-track <file> <target> <prop> [--dry-run]` | удалить дорожку со всеми ключами |
| `aego anim set <file> <attr> [<value>] [--dry-run]` | задать длину, повтор или fps клипа; без значения повтор или fps сбрасываются |
| `aego anim set-key <file> <target> <prop> <time> <value> [--kind v] [--interp v] [--tangent v] [--dry-run]` | задать ключ; для новой дорожки нужен --kind |
| `aego asset delete <asset> [--force] [--dry-run]` | удалить ассет; если на него есть ссылки, отказывается без --force |
| `aego asset import-variant [--variant v] [--path v] [--replace] [--dry-run]` | импортировать просмотренный вариант изображения как исходный PNG проекта |
| `aego asset list [--kind v]` | ассеты с их id и видами |
| `aego asset move <asset> <to> [--dry-run]` | перенести ассет вместе с его .meta; id и все ссылки сохраняются |
| `aego asset paint <path> [--ops v] [--width v] [--height v] [--source v] [--palette v] [--replace] [--dry-run]` | нарисовать или изменить исходный PNG за одну операцию с предпросмотром |
| `aego asset pixels <path> [--grid v] [--palette v] [--scale v] [--flipbook] [--replace] [--dry-run]` | нарисовать спрайт текстом: каждый символ grid — пиксель цвета из palette; строки вида idle: начинают кадры одного размера, из которых получается атлас со спрайтом на кадр и зацикленный клип-флипбук. Отвечает картинкой-превью |
| `aego asset rename <asset> <name> [--dry-run]` | переименовать ассет в его папке |
| `aego asset svg <path> [--svg v] [--width v] [--height v] [--replace] [--dry-run]` | нарисовать текстуру из SVG: path, rect, circle, ellipse, line, polyline, polygon, fill, stroke, прозрачность и transform; без фильтров, градиентов и текста. Для тайлов, интерфейса и иконок предметов. Отвечает картинкой-превью |
| `aego ctrl add-param <file> <name> <kind> [--default v] [--dry-run]` | добавить параметр |
| `aego ctrl add-state <file> <name> [--clip v] [--speed v] [--loop v] [--pos v] [--dry-run]` | добавить состояние |
| `aego ctrl add-transition <file> <from> <to> [--duration v] [--exit v] [--interrupt] [--cond v] [--dry-run]` | добавить переход; from может быть any |
| `aego ctrl entry <file> <name> [--dry-run]` | задать состояние, с которого начинает аниматор |
| `aego ctrl get <file>` | параметры, состояния и переходы контроллера |
| `aego ctrl remove-param <file> <name> [--dry-run]` | удалить параметр; условия с ним становятся проблемами |
| `aego ctrl remove-state <file> <name> [--dry-run]` | удалить состояние и переходы в него и из него |
| `aego ctrl remove-transition <file> <index> [--dry-run]` | удалить переход |
| `aego ctrl set-state <file> <name> <attr> [<value>] [--dry-run]` | задать clip, speed, loop, events или pos состояния |
| `aego ctrl set-transition <file> <index> <attr> [<value>] [--dry-run]` | задать to, duration, exitTime или interrupt перехода |
| `aego data add-row <file> <id> [--dry-run]` | добавить строку со значениями по умолчанию |
| `aego data base <file> [<asset>] [--dry-run]` | задать или сбросить базовый ассет ассета данных |
| `aego data export <file> <csv> [--dry-run]` | записать строки таблицы в файл csv |
| `aego data get <file> [--row v]` | поля, заданные в ассете данных или строке таблицы; пропущенные поля берутся из базы или из значения типа по умолчанию |
| `aego data import <file> <csv> [--dry-run]` | заменить строки таблицы файлом csv |
| `aego data remove-row <file> <id> [--dry-run]` | удалить строку |
| `aego data rename-row <file> <id> <name> [--dry-run]` | изменить id строки |
| `aego data reset <file> <path> [--row v] [--dry-run]` | удалить поле, чтобы оно бралось из базы или значения по умолчанию |
| `aego data rows <file>` | id строк таблицы |
| `aego data set <file> <path> <value> [--row v] [--dry-run]` | задать поле |
| `aego material apply <file> [--tx v] [--expected v] [--dry-run]` | атомарно применяет транзакцию материала через общие с Inspector mutations и сериализацию |
| `aego material assign <file> <node> <material> [--dry-run]` | назначает совместимый материал SpriteRenderer или Mesh2D через Mutation Service сцены |
| `aego material create <file> <shader> [--dry-run]` | создаёт материал, наследующий значения по умолчанию из шейдера |
| `aego material get <file>` | читает явные и унаследованные параметры, неизвестные данные, варианты и ревизию текущего документа |
| `aego material reset <file> <param> [--expected v] [--dry-run]` | удаляет явное значение параметра и наследует default шейдера |
| `aego material set <file> <param> <value> [--expected v] [--dry-run]` | устанавливает типизированный явный параметр одной семантической операцией |
| `aego material validate <file>` | проверяет значения материала и ссылки на шейдер и текстуры без изменения исходника |
| `aego material variants <file> [--keywords v] [--expected v] [--dry-run]` | выбирает разрешённую комбинацию keywords через запятую; пустая строка отключает все keywords |
| `aego postfx get <file> <node>` | Прочитать стек эффектов текущей камеры и постоянные ID экземпляров в открытой сцене. |
| `aego postfx set <file> <node> <instance> <field> <value> [--dry-run]` | Изменить параметр эффекта или переключить его по постоянному ID одной операцией редактирования сцены. |
| `aego prefab apply <file> <node> [--level v] [--owner v] [--field v] [--nearest] [--dry-run]` | записать переопределения экземпляра в файл префаба |
| `aego prefab create <file> <node> <out> [--dry-run]` | превратить узел в файл префаба и связать узел с ним |
| `aego prefab instantiate <file> <prefab> [--parent v] [--name v] [--index v] [--dry-run]` | добавить экземпляр префаба |
| `aego prefab overrides <file> <node>` | перечислить переопределения экземпляра, к которому относится узел |
| `aego prefab revert <file> <node> [--level v] [--owner v] [--field v] [--dry-run]` | отбросить переопределения экземпляра |
| `aego prefab unpack <file> <node> [--deep] [--dry-run]` | превратить экземпляр в обычные узлы |
| `aego project get [<section>]` | разделы модулей в project.aego (physics, …) с их текущими значениями |
| `aego project input-action <name> [--type v] [--bind v] [--context v] [--active] [--dry-run]` | добавить или изменить действие ввода в карте действий проекта |
| `aego project main-scene <file> [--dry-run]` | назначить главную сцену проекта по стабильной ссылке |
| `aego project set <section> <field> [<value>] [--reset] [--dry-run]` | задать поле раздела модуля в project.aego, например physics gravity [0, -15] |
| `aego project validate` | отсутствующие ассеты и узлы, ошибки импорта, префабы и сцены, которые не загружаются |
| `aego refs find <asset>` | файлы и поля, которые ссылаются на ассет |
| `aego refs fix <from> [<to>] [--dry-run]` | перенаправить все ссылки с одного ассета на другой (без второго — сбросить их); оригиналы попадают в .aego/recovery |
| `aego refs missing` | ссылки на несуществующие ассеты и узлы |
| `aego scene add-comp <file> <node> <comp> [--preset v] [--no-required] [--dry-run]` | добавить компонент со значениями по умолчанию и компонентами, которые ему нужны, или повесить скрипт по имени его типа |
| `aego scene add-node <file> <name> [--parent v] [--space v] [--index v] [--dry-run]` | добавить пустой узел |
| `aego scene apply <file> [--tx v] [--tx-file v] [--dry-run]` | применить транзакцию (tx version=1 { op … }) за один шаг |
| `aego scene get <file> <node> [<path>]` | узел с его трансформацией и всеми сохранёнными полями или одно поле |
| `aego scene move <file> <node> <parent> [--index v] [--keep-world] [--dry-run]` | перенести узел под другого родителя |
| `aego scene new <file> [--dry-run]` | создать пустую сцену |
| `aego scene remove-comp <file> <node> <comp> [--dry-run]` | удалить компонент |
| `aego scene remove-node <file> <node> [--dry-run]` | удалить узел вместе с детьми |
| `aego scene rename <file> <node> <name> [--dry-run]` | переименовать узел |
| `aego scene reset <file> <node> <path> [--dry-run]` | сбросить поле на значение по умолчанию, часть трансформации — на единичную |
| `aego scene run [<file>] [--frames v] [--seed v] [--watch v] [--input v] [--assert v] [--camera v] [--shot v] [--scale v]` | запустить сцену без окна и вывести журнал, хеш состояния и где побывали отслеживаемые узлы; `--input` нажимает действия, `--assert` проверяет значения, `--shot` снимает кадры |
| `aego scene set <file> <node> <path> <value> [--dry-run]` | задать поле |
| `aego scene tree <file> [--node v]` | дерево узлов с ID, компонентами, скриптами и связями с префабами; `--node` — только поддерево узла |
| `aego scene validate <file>` | проблемы загрузки и ссылки на узлы, которых нет в сцене |
| `aego schema list [--kind v]` | типы компонентов и данных |
| `aego schema show <type> [--lang v]` | поля типа: вид, диапазон, единица, значение по умолчанию, флаги и описание |
| `aego script create <file> [--text v] [--dry-run]` | создать файл скрипта; если файл уже есть, команда отказывает, и существующий скрипт меняют через script.edit |
| `aego script edit <file> [--old v] [--new v] [--dry-run]` | заменить текст в скрипте; old должен встречаться ровно один раз, поэтому цитируйте достаточно строк вокруг правки |
| `aego script read <file> [--from v] [--to v]` | текст скрипта в том виде, в каком он в редакторе, с несохранёнными правками; `--from` и `--to` читают часть длинного скрипта |
| `aego script write <file> [--text v] [--dry-run]` | заменить весь текст скрипта; для небольшой правки надёжнее script.edit |
| `aego shader create <file> [--dry-run]` | создаёт переносимый шейдер спрайта через зарегистрированный asset importer |
| `aego shader schema <shader>` | читает объявленные параметры, типизированные defaults, domain и варианты; проверяет текущий исходник и несохранённые includes |
| `aego shader validate <shader>` | проверяет текущий исходник общим importer; разделяет schema/reference validation и линковку на GPU |
| `aego texture apply <file> [--tx v] [--expected v] [--dry-run]` | атомарная типизированная транзакция метаданных текстуры; те же проверки и правила Undo, что в Inspector |
| `aego texture channel <file> <channel> <asset> [--frame v] [--expected v] [--dry-run]` | назначить исходник или кадр normal/height/emission по стабильному AssetID; неразрешённые ID сохраняются с диагностикой |
| `aego texture channel-reset <file> <channel> [--frame v] [--expected v] [--dry-run]` | снять явную привязку канала, не удаляя исходные ассеты |
| `aego texture get <file>` | прочитать текущие метаданные с несохранёнными правками, стабильные кадры, размеры, роли и ссылки каналов |
| `aego texture reset <file> <setting> [--expected v] [--dry-run]` | удалить явную настройку импорта и наследовать значение по умолчанию импортёра |
| `aego texture schema` | зарегистрированные роли/параметры импорта и контракт каналов кадров исходника |
| `aego texture set <file> <setting> <value> [--expected v] [--dry-run]` | установить настройку импорта через общий сервис семантических мутаций |
| `aego texture validate <file>` | проверить метаданные и подготовить приватный кандидат импорта, не меняя кэш или GPU-ресурсы |
<!-- agent:end -->

## aego docs

| Команда | Значение |
|---|---|
| `aego docs export [--out file]` | записать реестр документации в JSON |
| `aego docs check [--strict]` | битые ссылки, пропущенные группы и порядки, привязки без описаний, модули Script API и руководства по скриптам без запускаемого примера |
| `aego docs build [--out dir] [--playground=false] [--repo url]` | собрать статический сайт с песочницей |
| `aego docs serve [--addr host:port]` | собрать, раздать на localhost и пересобирать при изменениях |

`--project dir` документирует собственные скрипты проекта, `--engine dir` указывает на дерево исходников движка.