tgcloud — Telegram serverless bots

Scaffolds a module with `tgcloud add <target>` (tgcloud/ layout). handlers/<type> is one flat update handler (message, edited_message, callback_query, inline_query, chosen_inline_result, shipping_query, pre_checkout_query, poll, poll_answer, my_chat_member, chat_member, chat_join_request, message_reaction, channel_post, …). endpoints/<name> is a Mini App function (POST /api/<name>; identifier, not starting with a digit). lib/<path> is shared code and may be nested. Existing files are never overwritten.

Scaffolds a serverless bot with `npm create @tgcloud/bot <name>` inside parent_dir. Needs Node.js 18+ and the npm registry. Does not overwrite existing files.

Runs `npm run build` when package.json has a build script, then `tgcloud push`. Use this after front-end edits: a plain push uploads static.source as it sits on disk and never runs the bundler, so it would publish a stale dist. Does not migrate the database and never passes --force. skip_build=true pushes without building. If there is no build script, only push runs.

Line-by-line diff of the local project against the deployed snapshot (tgcloud diff). Offline.

Updates the local snapshot of what is deployed without touching working files (tgcloud fetch). Use it before resolving a revision conflict.

Scaffolds tgcloud into an existing directory (tgcloud init, offline): tgcloud/schema.js, handlers/, endpoints/, lib/, tgcloud.jsonc, AGENTS.md, docs/tgcloud-sdk.md. In a front-end project it detects the bundler, sets static.source, and adds an npm run deploy script (build, then push) without overwriting files you already have.

Runs `tgcloud login` with a CLI access token (app<id>:<secret> from @BotFather → your bot → Serverless → CLI Access → Access token). This is NOT the Bot API token (123456:AA…). The CLI wants a TTY, so the token is written to stdin with TGCLOUD_ASSUME_TTY=1 and masked in every tool result. NEVER show the token to the user after this call. In CI, set TGCLOUD_TOKEN and skip login.

Applies schema.js changes to the database (tgcloud migrate). push never does this. dry_run defaults to true (--dry-run): preview only. Applying (dry_run: false) requires confirm: true. apply "safe" passes --safe (auto-apply safe changes, skip warnings and manual steps). apply "yes" or omitting apply passes --yes (safe changes plus every warning, including .deprecated drops that delete data; manual type changes are still skipped). local: true diffs against the local schema.js instead of the deployed one (--local) and can be combined with either mode. Show the user the preview before applying. Warn when the preview contains a drop.

Makes the local project match the cloud: updates the snapshot and working files (tgcloud pull). Does not write the Mini App build folder.

Uploads changed modules in one atomic batch (tgcloud push). Without files, mirrors the whole local module set (deletions included) and, when tgcloud.jsonc names static.source, uploads that build folder exactly as it is on disk. push never runs the bundler — after front-end edits call deploy, or the previous build goes live. A targeted push never deletes other modules and leaves static files untouched unless the target is the build folder. push does not migrate the database; it only prints pending schema changes. Adding or removing a handler can leave the webhook out of sync — follow with webhook_sync. force=true skips the revision check and requires confirm: true.

DESTRUCTIVE: discards local module edits and restores the working tree from the last known cloud snapshot (tgcloud reset). Does not touch the Mini App build folder. Requires confirm: true.

Runs a handler or an endpoint on the platform using local files, without publishing them (tgcloud run). args is the payload (a Message for handlers/message, or the endpoint input) as a JSON5 object. ctx is the second argument (--ctx): the raw update for a handler, or initData for an endpoint, for example { initData: { user: { id: 1, first_name: "Ann" } } }. Returns the value, captured console logs, and elapsed time.

Shows local changes against the deployed snapshot (tgcloud status). Offline. Also reports stray .js files inside tgcloud/ that will not deploy, Mini App static diffs, and a webhook that is out of sync with the deployed handlers.

One-time move of schema.js, handlers/, and lib/ from the project root into tgcloud/ (tgcloud upgrade). Required before other commands on projects created before CLI 0.2.0. Keeps the bot link; nothing needs to be redeployed. dry_run defaults to true and only prints the planned moves. Applying (dry_run: false) requires confirm: true.

Shows the platform-managed webhook (tgcloud webhook): URL, allowed_updates, pending update count, the last delivery error, and whether it is in sync with the deployed handlers. First step when a bot is silent. Deploying or removing a handler can leave it out of sync.

Points the webhook at the platform and rebuilds allowed_updates from deployed handlers (tgcloud webhook sync). Call it after adding or removing a handler. drop_pending=true discards updates Telegram already queued — destructive, requires confirm: true.