Инструменты#

Каждый инструмент принимает project_dir — абсолютный путь к проекту tgcloud (create_project вместо этого принимает parent_dir и name).

create, init, login, add, upgrade

status, diff, push, deploy, pull, fetch, reset

прогон handler или endpoint, migrate

статус и sync, в том числе молчащий бот

Жизненный цикл #

Инструмент	Команда CLI	Описание
`create_project`	`npm create @tgcloud/bot`	Скаффолд нового проекта (`parent_dir`, `name`)
`init_project`	`tgcloud init`	Скаффолд в существующем каталоге, в том числе с обнаруженным Mini App
`login_bot`	`tgcloud login`	Привязка бота по CLI access token (`app<id>:<secret>`), токен через stdin, маскируется
`add_module`	`tgcloud add`	Новый модуль: `handlers/<type>`, `endpoints/<name>`, `lib/<path>`
`upgrade`	`tgcloud upgrade`	Перенос layout до 0.2.0 в `tgcloud/`. По умолчанию `dry_run: true`; применение требует `confirm: true`

Инструмент	Команда CLI	Описание
`status`	`tgcloud status`	Локальные изменения vs снапшот (офлайн), включая статику и рассинхрон вебхука
`diff`	`tgcloud diff`	Построчный diff (офлайн)
`push`	`tgcloud push`	Атомарный деплой. Не собирает фронтенд и не мигрирует БД. `force: true` требует `confirm: true`
`deploy`	`npm run build` + `tgcloud push`	Сборка, если в `package.json` есть script `build`, затем push. `skip_build: true` — только push
`pull`	`tgcloud pull`	Облако → снапшот и рабочие файлы. Папку сборки Mini App не пишет
`fetch`	`tgcloud fetch`	Облако → только снапшот
`reset`	`tgcloud reset`	Откатить локальные правки модулей; требует `confirm: true`

Инструмент	Команда CLI	Описание
`run_handler`	`tgcloud run`	Прогон handler или endpoint без деплоя. `args` и `ctx` — JSON5. `args` — первый аргумент (payload: `Message` для handler, вход для endpoint); `ctx` — второй (`ctx.update` — сырое Update для handler, включая `update_id`; `initData` для endpoint)
`migrate`	`tgcloud migrate`	`dry_run: true` (по умолчанию) — предпросмотр. Применение: `dry_run: false` и `confirm: true`. `apply: "safe"` — это `--safe`; `apply: "yes"` (по умолчанию при применении) — `--yes`. `local: true` — `--local`

Инструмент	Команда CLI	Описание
`webhook_status`	`tgcloud webhook`	URL, allowed_updates, очередь, ошибки доставки, синхронен ли вебхук
`webhook_sync`	`tgcloud webhook sync`	Перепривязка вебхука. `drop_pending: true` требует `confirm: true`

Новый или удалённый handler может оставить вебхук рассинхронизированным. push это не гарантирует. После такого деплоя вызывайте webhook_sync.

Бот молчит: webhook_status → status / diff → push → webhook_sync
Логи деплоя: команды для их скачивания нет; смотрите последнюю ошибку доставки в webhook_status, затем воспроизводите через run_handler (его console.* — локальный вывод, а не развёрнутого бота)
Конфликт ревизий на push: fetch → diff → push (или force с confirm)
Схема: правка schema.js → push → migrate (dry-run) → migrate с confirm. Если удалений нет, apply: "safe"
Фронтенд Mini App: deploy, не голый push