CLI Commands

Detailed reference for every command available in the tma CLI.

tma login

Authenticate with TMA.sh using the device code flow.

tma login

The CLI opens your browser and displays a one-time code. Enter the code in the browser to authorize the session. Once confirmed, credentials are stored locally and used for all subsequent commands.

Credentials are saved to ~/.tma/credentials.json. They persist across sessions until you run tma logout or they expire.

tma logout

Clear stored authentication credentials.

tma logout

Removes the local credentials file. You will need to run tma login again before using any authenticated commands.

tma init [project-name]

Create a new TMA.sh project with interactive scaffolding.

tma init my-app

If project-name is omitted, the CLI prompts you for one.

The scaffolding wizard walks through the following:

1. Template selection — choose from Vite (React, Vue, or Svelte) or Plain HTML.
2. API routes — optionally include a server/api/index.ts file for edge API routes powered by Hono.
3. Bot handlers — optionally include a bot/index.ts file for Telegram bot command handlers.
4. Dependency installation — runs bun install automatically after scaffolding.

The command creates the project directory, writes all template files, and generates .tma/project.json to link the directory to your TMA.sh project.

my-app/
  .tma/
    project.json
  src/
    ...
  server/          # only if API routes selected
    api/
      index.ts
  bot/             # only if bot handlers selected
    index.ts
  index.html
  package.json

tma link

Link the current directory to an existing TMA.sh project.

tma link

Use this when you have an existing codebase that you want to deploy to TMA.sh, or when cloning a repo that does not yet have a .tma/project.json file.

The CLI fetches your projects and prompts you to select one. After selection, it writes .tma/project.json to the current directory.

tma dev

Start the local development environment.

tma dev

This command starts everything you need for local development:

• Vite dev server on port 5173 with hot module replacement.
• API routes (if server/api/index.ts exists): starts an esbuild watcher and Miniflare on port 8787.
• Bot handlers (if bot/index.ts exists): starts Miniflare on port 8788 for bot webhook processing.

Vite proxies /api/* and /bot/* requests to the respective Miniflare instances so your frontend, API, and bot handlers share the same origin during development.

tma deploy

Trigger a manual deployment to production.

tma deploy

Triggers a server-side deployment by calling the TMA.sh API, then polls for completion. The CLI does not build locally or upload assets — all building happens on the server.

This command is for manual deployments. If you have auto-deploy enabled (the default), pushing to your main branch on GitHub triggers a deployment automatically without needing to run this command.

The CLI streams build status to your terminal and prints the live URL when the deployment is complete:

Deployment triggered...
Building (Vite detected)...
Deployment live at https://my-app.tma.sh

Options

Flag	Description
--preview	Trigger a preview deployment instead of production

tma env

Manage environment variables and secrets for your project.

# List all environment variables
tma env list

# Set a variable (use = between key and value)
tma env set API_KEY=sk-abc123

# Remove a variable
tma env remove API_KEY

# Pull env vars to a local .env.local file (values are redacted)
tma env pull

All environment variables are set for the production environment. Environment scoping for preview and development is managed through the dashboard.

tma env pull

Writes a .env.local file to the current directory containing the secret key names from your project. Values are redacted by the API — this is useful for seeing which variables are configured without exposing actual secrets.

Security

All environment variables are encrypted at rest. They are injected at build time and available as process.env.* in API routes. Sensitive values (tokens, keys) are masked in build logs.

tma logs

View build logs for recent deployments.

# View logs for the latest deployment
tma logs

# View logs for a specific deployment
tma logs --deployment dpl_abc123

# Stream logs in real time
tma logs --follow

Options

Flag	Description
--deployment <id>	View logs for a specific deployment
--follow	Stream logs in real time

Displays the build output, including framework detection, build commands, asset upload progress, and any errors. Useful for debugging failed deployments.

tma bot

Manage Telegram bots registered with your TMA.sh project.

# List all registered bots (default when no subcommand is given)
tma bot
tma bot list

# Register a new bot
tma bot register

# Remove a registered bot
tma bot remove

# Check bot status
tma bot status

Subcommands

Subcommand	Description
list	List all registered bots for the project (default)
register	Register a Telegram bot with TMA.sh. Prompts for the bot token and environment selection (production or staging).
remove	Remove a registered bot from the project
status	Check the status of registered bots

Running tma bot with no subcommand is equivalent to tma bot list.