tt-ide-cli

v0.1.34

Published

14 days ago

Command line interface for micro app development

0High
0Medium
0Low

tma-cli

tma 是抖音小程序官方提供的命令行工具

安装

运行环境要求 Node.js >= 18.17.0；下载功能使用原生 fetch，通过 Undici 保留 HTTP / HTTPS 代理支持。

建议在全局安装 tma

npm install -g tt-ide-cli

使用

设置小程序 token

设置小程序的 token, 用于替代登录态

命令行使用

Usage: tma set-app-config <appid> --token <token>

Example: tma set-app-config ttxxxxxxx --token 123123123

代码调用

const tma = require('tt-ide-cli');
tma.setAppConfig({
  appId: 'ttxxxxxx',
  config: {
    token: '123123123',
  },
});

设置全局配置

主要用于配置工具的全局代理

命令行使用

Usage: tma set-config [options]

Set tt-ide-cli config

Options:
  --proxy <proxy> Set global proxy（配置全局代理）
  --default       Use default（恢复为默认配置）

代码调用

const tma = require('tt-ide-cli');
await tma.setConfig({
    proxy: 'http://127.0.0.1:8899';
});

创建新项目

在当前目录下，以给定的项目名字创建一个空白的小程序项目

命令行使用

Usage: tma create [options] <project-name>

Create a new project with given name in current folder

Options:
  -f, --force  Overwrite target directory if it exists
  --template <template>    rich | empty (default: empty)
  --type <type>', 'js | ts (default: js)
  --targetDir <targetDir>  Target directory

代码调用

const tma = require('tt-ide-cli');
await tma.create({
  projectName: 'projectName',
  force: false, // 是否覆盖目标文件夹
  template: 'rich', // 'rich' ｜ 'empty'
  // rich 为小程序能力展示 DEMO
  // empty 为小程序空项目
  targetDir: '/path/to/targetDir',
  type: 'js', // 'js' | 'ts'
  // js 为 js 小程序
  // ts 为 ts 小程序
});

下载代码片段

从分享链接下载 ZIP 并解压为本地项目，不需要安装或启动桌面 IDE。

tma download-minicode "https://developer.open-douyin.com/ide/minicode/<codeID>" --targetDir ./demo
tma download-minicode "bytedanceide://minicode/<codeID>" --targetDir ./demo --json

链接（或代码片段 ID）和 --targetDir 必填。targetDir 与 create 一致，表示最终项目目录，不是父目录；与 IDE 导入界面一致，允许不存在、空目录或仅含 .DS_Store 的目录，拒绝已有项目，不覆盖同名文件。已有空目录在导入失败时会保留；交付中途失败可能留下部分已复制文件。
支持新旧代码片段链接，以及查询参数、fragment 和末尾斜杠。链接只用于提取 ID，不作为任意 URL 下载器。
新版片段先请求 shared，有 CLI 登录 Cookie 时携带，没有 Cookie 时也会尝试；失败再使用备用接口，需要登录时由用户执行 tma login，App token 不能替代此接口的登录态。旧版 CDN 下载不要求本地 Cookie。
保留 IDE 的旧 CDN / BOE 和新版备用接口兜底，内部环境可能受网络权限限制。复用 tma set-config 的代理、BOE / PPE 配置；不会把登录 Cookie 转发给备用接口、CDN 或跨域重定向。
shared 请求失败后，若第一次备用 CDN 返回 JSON，再尝试一次备用接口；其余失败不循环重试。shared 和 CDN 下载不额外设置总时限、连接、响应头或正文空闲超时，备用元数据接口保留 60 秒超时；需要中止等待时可终止命令。
直连及代理请求均保留 TLS 证书校验，不照搬 IDE 代理下跳过校验的行为。使用内部 CA 或抓包代理时，应通过 NODE_EXTRA_CA_CERTS 配置经确认可信的 CA 文件；证书不可信时请求会失败，不自动绕过校验。
不修改 AppID、不安装依赖、不执行项目脚本、不预览或打开 IDE。校验 ZIP 文件长度与 CRC、保留文件修改时间，拒绝危险 ZIP 路径和符号链接，排除根部 .vscode。
--json 成功时 stdout 只输出结果 JSON，错误写 stderr，失败退出码为非零。shared 的 error/message 业务说明会保留，不按固定过期文案白名单过滤；明确的凭证、URL 和终端控制字符会被过滤，消息长度有上限。不会打印原始响应或请求错误对象，即使设置了 DEBUG_TT_REQUEST=1。

代码调用

import { downloadMinicode, DownloadMinicodeResult } from 'tt-ide-cli';

const result: DownloadMinicodeResult = await downloadMinicode({
  url: 'https://developer.open-douyin.com/ide/minicode/<codeID>',
  targetDir: './demo',
});
// { codeID: '...', targetDir: '/absolute/path/to/demo' }

下载文件先在系统临时目录中校验和解压，再保存到目标目录，结束后清理临时文件。内容仍是不可信代码，后续执行或预览前应检查项目。

维护者发布前需确认备用接口的对外使用及鉴权契约，并检查 npm 包中不包含真实片段、凭证或临时文件。客户端含 BOE 地址不代表服务端权限已经验证。

打开已有项目

在小程序开发者工具中打开给定目录的项目，如果给定的目录不存在，则仅打开开发者工具

命令行使用

Usage: tma open <project-path> --mode lite

Open target project by path

Options:
  --mode  <mode>         IDE mode(eg. full, lite)

代码调用

const tma = require('tt-ide-cli');
await tma.open({
  project: {
    path: 'projectPath',
    mode: 'lite',
  },
});

通过 email 登录

命令行使用

Usage: tma login-e [email] [password]

Login to the developer platform by E-mail

Options:
  -p, --proxy <proxy>  Login with proxy
  -h, --help           Output usage information

代码调用

const tma = require('tt-ide-cli');
await tma.loginByEmail({
  email: 'email',
  password: 'password',
});

通过手机号登录

通过调用tma.sendVerificationCodeToPhone({ phoneNumber: 'phoneNumber' })可以发送验证码

代码调用

const tma = require('tt-ide-cli');
await tma.loginByPhone({
  phoneNumber: 'phoneNumber',
  code: 'code',
});

登出（清除本地 session）

命令行使用

Usage: tma logout

Logout and clear the session.

代码使用

const tma = require('tt-ide-cli');
await tma.logout();

本地项目体积

查看本地项目的文件体积

命令行使用

Usage: tma project-size [--json] entry

Output current project package size information.

Options:
  --json Output as JSON string

代码调用

const tma = require('tt-ide-cli');
const result = await tma.getProjectSize(projectPath);

预览小程序

将项目上传后，扫码二维码来预览小程序（如果要设置 miniapp-query, miniapp-scene 等启动参数需要同时设置 miniapp-path 参数，否则将不会生效）。

命令行使用

Usage: tma preview [options] [entry]

Preview project by remote

Options:
  --disable-cache                     Preview project without local cache
  -s, --small                         Use small QR Code, it may fail in some environments
  -c, --copy                          Copy remote url to clipboard
  -p, --proxy <proxy>                 Preview with proxy
  --application-type <applicationType> Preview application type. microapp
  --miniapp-path <path>               Miniapp path
  --miniapp-query <query>             Miniapp query
  --miniapp-scene <scene>             Miniapp scene
  --miniapp-launch-from <launchFrom>  Miniapp launchFrom
  --miniapp-location <location>       Miniapp location
  --qrcode-output <qrcodeOutputPath>  Qrcode output path

常规小程序预览示例：

tma preview ./project

代码调用

const tma = require('tt-ide-cli');
// previewResult 返回值
interface ProjectQRCode {
  expireTime: number; // 二维码过期时间
  shortUrl: string; // 二维码短链
  originSchema: string; // 二维码 schema
  qrcodeSVG?: string; // 二维码 SVG
  qrcodeFilePath?: string; // 二维码存储路径
  useCache: boolean; // 是否命中并使用缓存
}
const previewResult: ProjectQRCode = await tma.preview({
  project: {
    path: 'projectPath', // 项目地址
  },
  applicationType: 'microapp', // 默认值为 microapp
  page: {
    path: '', // 小程序打开页面
    query: '', // 小程序打开 query
    scene: '', // 小程序打开场景值
    launchFrom: '', // 小程序打开场景（未知可填空字符串）
    location: '', // 小程序打开位置（未知可填空字符串）
  },
  qrcode: {
    format: 'imageSVG', // imageSVG | imageFile | null | terminal
    // imageSVG 用于产出二维码 SVG
    // imageFile 用于将二维码存储到某个路径
    // terminal 用于将二维码在控制台输出
    // null 则不产出二维码
    output: '', // 只在 imageFile 生效，填写图片输出绝对路径
    options: {
      small: false, // 使用小二维码，主要用于 terminal
    },
  },
  cache: true, // 是否使用缓存
  copyToClipboard: true, // 是否将产出的二维码链接复制到剪切板
});

上传项目

把项目上传到开发者平台进行发布

命令行使用

app-changelog 为必填参数，其余为可选参数，其中 app-version 的默认值为前序版本号末位加一。

Usage: tma upload [options] [entry]

Upload project to the developer platform

Options:
  -v, --app-version <appVersion>          App version (eg: [major].[minor].[patch])
  -c, --app-changelog <appChangelog>      Changelog for this version
  -p, --proxy <proxy>                     Update request proxy
  -cp, --copy                             Copy remote url to clipboard
  --qrcode-output <qrcodeOutputPath>      Qrcode output path
  --channel <channel>                     Test Channel

代码调用

const tma = require('tt-ide-cli');
// uploadResult 返回值
interface ProjectQRCode {
  expireTime: number; // 二维码过期时间
  shortUrl: string; // 二维码短链
  originSchema: string; // 二维码 schema
  qrcodeSVG?: string; // 二维码 SVG
  qrcodeFilePath?: string; // 二维码存储路径
  useCache: boolean; // 是否命中并使用缓存
}
const uploadResult: ProjectQRCode = await tma.upload({
  project: {
    path: 'projectPath', // 项目地址
  },
  qrcode: {
    format: 'imageSVG', // imageSVG | imageFile | null | terminal
    // imageSVG 用于产出二维码 SVG
    // imageFile 用于将二维码存储到某个路径
    // terminal 用于将二维码在控制台输出
    // null 则不产出二维码
    output: '', // 只在 imageFile 生效，填写图片输出绝对路径
    options: {
      small: false, // 使用小二维码，主要用于 terminal
    },
  },
  copyToClipboard: true, // 是否将产出的二维码链接复制到剪切板
  changeLog: 'changelog', // 本次更新日志
  version: '1.0.0', // 本次更新版本，可选参数，默认值为前序版本号末位加一
  needUploadSourcemap: true, // 是否上传后生成 sourcemap，推荐使用 true，否则开发者后台解析错误时将不能展示原始代码
  channel: '1', // 可选项，测试通道，不传该参数时为默认通道
});

小程序 host

查询小程序支持的 host 。

命令行使用

Usage: tma hosts [appid]

Get Audit Host List

tma hosts tt07e3715e98c9xxxx

代码调用

const tma = require('tt-ide-cli');
await tma.getAuditHostsList({ appid: '' });

小程序提审

小程序首次提审，需要通过 defaultSsUrl 属性给定一个截图路径；
推荐首次提审时，到开发者平台上传合规截图；
后续提审会复用前一次提审的截图；
现在支持的 host 参数已有
- douyin
- toutiao
- douyin_lite
- tt_lite
- 更多 host 可以通过 tma hosts [appid] 的命令查询

命令行使用

Usage: tma audit [options] [appid]

Audit project in the developer platform

Options:
  --host <hosts>            Host Apps(eg: douyin,toutiao,tt_lite)
  --auto-publish <boolean>  Auto Publish After Audit
  --channel <channel>       Test channel

# 使用示范
tma audit --host douyin,toutiao,tt_lite tt07e3715e98c9xxxx

代码调用

const tma = require('tt-ide-cli');
// 提审
await tma.audit({
  appid: '',
  host: [], // douyin,toutiao,tt_lite
  autoPublish: true, // 是否审核通过后自动发布
  defaultSsUrl: '/tmp/picture/default.png',
});

获取小程序信息

命令行使用

Usage: tma get-meta [options] [appid]

Get appid meta

代码调用

const tma = require('tt-ide-cli');
// metaResult 返回值
interface MiniappMetaInfo {
  version: String; // 线上小程序版本号
}
const metaResult: MiniappMetaInfo = await tma.getMeta({
  appid: 'appid',
});

构建 NPM

对应开发者工具构建 NPM 功能

命令行使用

Usage: tma build-npm [options]

Build npm

Options:
  --project-path  Project path

代码调用

const tma = require('tt-ide-cli');
await tma.buildNpm({
  project: {
    path: 'projectPath',
  },
});

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

tma-cli

安装

使用

设置小程序 token

命令行使用

代码调用

设置全局配置

命令行使用

代码调用

创建新项目

命令行使用

代码调用

下载代码片段

代码调用

打开已有项目

命令行使用

代码调用

登录

命令行使用

通过 email 登录

命令行使用

代码调用

通过手机号登录

代码调用

登出（清除本地 session）

命令行使用

代码使用

本地项目体积

命令行使用

代码调用

预览小程序

命令行使用

代码调用

上传项目

命令行使用

代码调用

小程序 host

命令行使用

代码调用

小程序提审

命令行使用

代码调用

获取小程序信息

命令行使用

代码调用

构建 NPM

命令行使用

代码调用