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 (Hono scaffolded by default, but any fetch-compatible framework works).
3. Bot handlers — optionally include a bot/index.ts file for Telegram bot command handlers.
4. Dependency installation — runs bun install when Bun is available, otherwise falls back to npm install.

The command creates the project directory, writes all template files, and creates a local .tma/project.json containing only projectName.

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

After scaffolding, run tma link from inside the project directory to write the full linked-project config (projectId, orgId, projectName) required by authenticated commands.

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. You can also choose + Create new project in the prompt. It then writes .tma/project.json with projectId, orgId, and projectName.

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.

tma deploy requires:

• A linked project config from tma link (.tma/project.json with projectId and orgId)
• A repository connected to that project in the dashboard (the build runs from GitHub)

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...
Deployment status: building
Deployment live at https://my-app.tma.sh

Options

Flag	Description
--preview	Trigger a preview deployment for the currently selected staging PR (set in dashboard)

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. During deployments they are provided to build commands and worker bindings. In API routes, access them from worker bindings (env / c.env), not process.env. Avoid logging secret values from your own code.

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 11111111-2222-3333-4444-555555555555

# 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 build output, status transitions, and 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, preview, or development).
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.