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 powered by Hono.
• Bot handlers — optionally set up bot command and message handlers.
• Dependency installation — automatically runs bun install when scaffolding completes.

After init finishes, your project is ready to develop:

cd my-app
tma dev

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.

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": "proj_abc123",
  "orgId": "org_xyz789",
  "projectName": "my-app"
}

This file identifies the project when running CLI commands. Commit it to your repository so that deployments work from CI and other machines.

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.