---
name: douyin-ide-cli
description: 当用户想要管理抖音小程序项目时使用此技能。这包括登录开发者平台、预览小程序、上传代码等操作。只要用户的意图涉及抖音小程序的开发流程、命令行工具(tt-ide-cli/tma)的使用，或者提到“抖音小程序”、“预览”、“上传”等关键词，都应触发此技能。
---

# 抖音小程序命令行工具 (tt-ide-cli)

本技能提供如何使用 `tt-ide-cli` (也称为 `tma`) 来管理抖音小程序项目的说明。该 CLI 允许你在不使用图形化 IDE 的情况下进行登录、预览、上传等操作。

## 先决条件

- **运行环境**: 这些命令必须在用户的本地终端中运行（即沙箱外部），以确保能够正确访问本地文件系统、网络代理设置以及用户的登录状态。请勿在隔离的沙箱环境中执行这些命令。
- 必须安装 `tt-ide-cli` 包。如果没有安装，建议通过 `npm install -g tt-ide-cli` 进行安装。
- 一个有效的抖音小程序项目目录。

## 核心命令

### 1. 登录 (Login)

执行大多数操作前必须先登录。

**邮箱登录:**

```bash
tma login-e [email] [password]
```

**多种方式登录:**

```bash
tma login
```

选项:

- `-m, --mobile`: 手机号登录 (需要交互式输入验证码)
- `-e, --email`: 邮箱登录

### 2. Token 设置 (Token Setup)

如果在 CI/CD 环境中运行，或者不想通过手机/邮箱登录，可以为指定的 appid 设置 token。

```bash
tma set-app-config <appid> --token <token>
```

### 3. 预览小程序 (Preview)

生成二维码以便在设备上预览小程序。

```bash
tma preview [options] <entry>
```

**注意**: `<entry>` (小程序项目目录地址) 是**必填**的。如果当前处于项目根目录，请使用 `./`。

选项:

- `--qrcode-output <qrcodeOutputPath>`: 可选，将二维码保存为文件到指定路径下

**示例:**

```bash
tma preview --qrcode-output ./preview.png ./
```

### 4. 上传项目 (Upload)

将项目上传到开发者平台以供审核或发布。

```bash
tma upload [options] <entry>
```

**注意**: `<entry>` (小程序项目目录地址) 是**必填**的。如果当前处于项目根目录，请使用 `./`。

选项:

- `-c, --app-changelog <appChangelog>`: **必填**。此版本的更新日志/描述。
- `-v, --app-version <appVersion>`: **选填**。版本号 (例如 1.0.0)。如果不传，则会自动使用版本自增逻辑。

**示例:**

```bash
tma upload -c "修复支付流程中的 bug" ./
```

## 使用指南

1.  **处理登录状态**: 用户可能在之前已经登录过。可以直接尝试执行预览或上传等操作。如果命令返回未登录相关的错误，再引导用户使用 `tma login-e` 或 `tma login` 进行登录，或者通过 `set-app-config` 设置 Token。
2.  **更新日志是必填项**: 对于 `tma upload`，如果用户未提供这些信息，请询问用户或生成合理的默认值。
3.  **路径上下文**: 大多数命令假设你处于项目根目录下。如果用户在其他地方，请先追加项目路径或 `cd` 进入项目目录。
4.  **探索更多功能**: `tt-ide-cli` 还有很多其他命令，上面列出的命令也有更多高级参数。你可以随时运行 `tma --help` 或 `tma [command] --help` 来获取完整的命令和参数列表。

## 常见问题

- **上传错误**: 确保版本号是唯一的且大于上一个版本。
- **权限不足 (Permission Denied)**:
  如果登录时遇到没有权限修改文件的错误，可以在调用命令时指定 `TMA_CLI_HOME` 环境变量，将登录态信息存储到一个临时目录（或其他有权限的目录）。

  **注意**: 在执行预览 (`preview`)、上传 (`upload`) 等后续操作时，也必须指定同一个 `TMA_CLI_HOME`，否则 CLI 无法读取登录态信息。

  示例:

  ```bash
  # 登录到临时目录
  export TMA_CLI_HOME=/tmp/tma_home
  tma login-e user@example.com password

  # 使用该目录进行预览
  tma preview
  ```