> ## Documentation index
> Fetch the complete documentation index at: https://tgcloud.docs7.io/llms.txt
> Ask it with GET https://tgcloud.docs7.io/ask?q=<keywords or question>. Short keywords rank best.
> Use these to discover all available pages before exploring further.

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

> Все 16 инструментов tgcloud-mcp

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

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

<CardGroup cols={2}>
  <Card title="Жизненный цикл" icon="hammer" href="#lifecycle">
    create, init, login, add, upgrade
  </Card>
  <Card title="Синхронизация" icon="refresh" href="#sync">
    status, diff, push, deploy, pull, fetch, reset
  </Card>
  <Card title="Данные" icon="database" href="#data">
    прогон handler или endpoint, migrate
  </Card>
  <Card title="Вебхук" icon="link" href="#webhook">
    статус и sync, в том числе молчащий бот
  </Card>
</CardGroup>

## Жизненный цикл {#lifecycle}

| Инструмент | Команда 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` |

## Синхронизация {#sync}

| Инструмент | Команда 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` |

## Данные {#data}

| Инструмент | Команда 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` |

## Вебхук {#webhook}

| Инструмент | Команда 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`