> ## 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.

# Tools

> All 16 tgcloud-mcp tools

# Tools

Every tool takes `project_dir` — an absolute path to a tgcloud project
(`create_project` takes `parent_dir` and `name` instead).

<CardGroup cols={2}>
  <Card title="Lifecycle" icon="hammer" href="#lifecycle">
    create, init, login, add, upgrade
  </Card>
  <Card title="Sync" icon="refresh" href="#sync">
    status, diff, push, deploy, pull, fetch, reset
  </Card>
  <Card title="Data" icon="database" href="#data">
    run a handler or endpoint, migrate
  </Card>
  <Card title="Webhook" icon="link" href="#webhook">
    status and sync, including a silent bot
  </Card>
</CardGroup>

## Lifecycle {#lifecycle}

| Tool | CLI command | Description |
|---|---|---|
| `create_project` | `npm create @tgcloud/bot` | Scaffold a new project (`parent_dir`, `name`) |
| `init_project` | `tgcloud init` | Scaffold into an existing directory, including a detected Mini App |
| `login_bot` | `tgcloud login` | Link a bot via CLI access token (`app<id>:<secret>`); token via stdin, masked |
| `add_module` | `tgcloud add` | New module: `handlers/<type>`, `endpoints/<name>`, `lib/<path>` |
| `upgrade` | `tgcloud upgrade` | Move a pre-0.2.0 layout into `tgcloud/`. `dry_run: true` by default; applying needs `confirm: true` |

## Sync {#sync}

| Tool | CLI command | Description |
|---|---|---|
| `status` | `tgcloud status` | Local changes vs snapshot (offline), including static diffs and webhook drift |
| `diff` | `tgcloud diff` | Line-by-line diff (offline) |
| `push` | `tgcloud push` | Atomic deploy. Does not build the front-end and does not migrate. `force: true` requires `confirm: true` |
| `deploy` | `npm run build` + `tgcloud push` | Build when `package.json` has a build script, then push. `skip_build: true` pushes only |
| `pull` | `tgcloud pull` | Cloud → snapshot and working files. Does not write the Mini App build folder |
| `fetch` | `tgcloud fetch` | Cloud → snapshot only |
| `reset` | `tgcloud reset` | Discard local module edits; requires `confirm: true` |

## Data {#data}

| Tool | CLI command | Description |
|---|---|---|
| `run_handler` | `tgcloud run` | Run a handler or endpoint without deploying. `args` and `ctx` are JSON5. `args` is the first argument (the payload: a `Message` for a handler, the input for an endpoint); `ctx` is the second (`ctx.update` is the raw Update for a handler, including `update_id`; `initData` for an endpoint) |
| `migrate` | `tgcloud migrate` | `dry_run: true` (default) previews. Applying needs `dry_run: false` and `confirm: true`. `apply: "safe"` is `--safe`; `apply: "yes"` (default when applying) is `--yes`. `local: true` is `--local` |

## Webhook {#webhook}

| Tool | CLI command | Description |
|---|---|---|
| `webhook_status` | `tgcloud webhook` | URL, allowed_updates, pending updates, delivery errors, in sync or not |
| `webhook_sync` | `tgcloud webhook sync` | Re-point the webhook. `drop_pending: true` requires `confirm: true` |

Adding or removing a handler can leave the webhook out of sync. `push` does not guarantee a refresh. Call `webhook_sync` after that kind of deploy.

## Recipes

- **Silent bot**: `webhook_status` → `status` / `diff` → `push` → `webhook_sync`
- **Deployed logs**: no command downloads them; read `webhook_status`'s last delivery error, then reproduce with `run_handler` (its `console.*` is local output, not the deployed bot's)
- **Revision conflict on push**: `fetch` → `diff` → `push` (or `force` with `confirm`)
- **Schema change**: edit `schema.js` → `push` → `migrate` (dry-run) → `migrate` with `confirm`. Prefer `apply: "safe"` when nothing is dropped
- **Mini App front-end**: `deploy`, not a bare `push`