Installation

The tma CLI is the primary tool for creating, developing, and deploying Telegram Mini Apps on TMA.sh.

Install the CLI

Install the CLI globally with Bun:

bun add -g @tma.sh/cli

Verify the installation:

tma --version

Log in to your account

1. Run the login command:

   tma login

   This opens your browser and starts an OAuth device code flow. Authorize the CLI to connect it to your TMA.sh account.

2. Once authorized, credentials are stored locally. You only need to do this once per machine.

Create a new project

Use tma init to scaffold a new project from a template:

tma init my-app

The interactive prompt walks you through:

• Template selection — pick a framework (Vite React, Vite Vue, Vite Svelte, or Plain HTML).
• API routes — optionally scaffold a server/api/index.ts file for edge API routes (Hono scaffolded by default, but any fetch-compatible framework works).
• Bot handlers — optionally set up bot command and message handlers.
• Dependency installation — automatically runs bun install (or npm install when Bun is unavailable).

After init finishes, your project is ready to develop:

cd my-app
tma dev

tma init only scaffolds local files. To use authenticated project commands like tma deploy, tma env, tma logs, or tma bot, run tma link next to write the full project ID/org ID config.

Link an existing project

If you already have a frontend project and want to deploy it to TMA.sh, run tma link from the project root:

cd my-existing-app
tma link

This prompts you to select an org and project, then writes the .tma/project.json config file to connect your local directory to your TMA.sh account.

If you select + Create new project in the prompt, tma link creates the project first, then writes the same full config.

Project configuration

After tma init or tma link, a .tma/project.json file is created in your project root.

tma init creates a partial config with only the project name:

{
  "projectName": "my-app"
}

tma link creates the full config with all fields:

{
  "projectId": "11111111-2222-4333-8444-555555555555",
  "orgId": "66666666-7777-4888-8999-000000000000",
  "projectName": "my-app"
}

This file identifies the project when running CLI commands. Commit .tma/project.json, but ignore local dev artifacts under .tma/:

.tma/*
!.tma/project.json

Set up your Telegram bot

Every TMA.sh project is connected to a Telegram bot. If you do not have one yet, create it now.

1. Open Telegram and start a conversation with @BotFather.

2. Send /newbot and follow the prompts to choose a name and username.

3. Copy the bot token that BotFather gives you. You will need it when connecting your project.

4. Run tma bot register and paste the token when prompted:

   tma bot register

   TMA.sh configures the bot’s Web App URL automatically on each deployment.

Next steps

Your CLI is installed, your account is connected, and your project is ready. Head to Your First Deploy to ship your first Telegram Mini App.