Skip to main content
Version: v3

CLI Guide

The Cloud Engine CLI (tds) is a tool for you to deploy your Cloud Engine projects and manage your applications.

Install the CLI​

macOS​

You can install the CLI with Homebrew:

brew update && brew install lean-cli
Having trouble using Homebrew?

If you’re having a poor connection to Homebrew’s service, you can set up environment variables like http_proxy to make your connection faster. You can also use a mirror for Homebrew (like TUNA).

If you prefer not to use Homebrew, you can download the binary file named tds-macos-arm64 (for Apple Silicon) or tds-macos-x64 (for Intel) from GitHub releases, rename the file to tds, and move the file to a directory listed within $PATH. Make sure to make the file executable by running chmod a+x /path/to/tds.

Windows​

You can download the 32-bit or 64-bit msi file from GitHub releases and run the file to install the CLI. After you install the CLI, you’ll be able to use it by running tds in Command Prompt or PowerShell.

You can also download the exe file, rename it to tds.exe, and add its path to the PATH environment variable (instructions). You will then be able to run tds under any directory using Command Prompt or PowerShell. Besides adding the file’s path to PATH, you can also choose to move the file to a directory already listed within PATH, like C:\Windows\System32.

Linux​

For Debian-based distributions, you can download the deb file from GitHub releases.

For other distributions, you can download the pre-compiled binary file (like tds-linux-x64) from GitHub releases, rename the file to tds, and move the file to a directory listed within $PATH. Make sure to make the file executable by running chmod a+x /path/to/tds.

Upgrade to the Latest Version​

If you have already installed the CLI, you can upgrade it to the latest version by reinstalling the CLI with the latest file.

Usage​

After installing the CLI, you can run tds help on the terminal to view the help information:

View the output of tds help
NAME:
   tds - Command line tool to manage and deploy Cloud Engine apps

USAGE:
   tds [global options] command [command options] [arguments...]

VERSION:
   1.0.0

COMMANDS:
     login    Log in to TapTap Developer Services
     switch   Change the associated Cloud Engine app
     info     Show information about the associated user and app
     up       Start a development instance locally with debug console
     new      Create a new Cloud Engine project from official examples
     deploy   Deploy the project to Cloud Engine
     publish  Publish the version of staging to production
     db       Access to to Database instances
     file     Manage files ('_File' class in Data Storage)
     logs     Show Cloud Engine logs
     debug    Start the debug console without running the project
     env      Print custom environment variables on Cloud Engine (secret variables not included)
     cql      Enter CQL interactive shell (warn: CQL is deprecated)
     help     Show usages of all subcommands

GLOBAL OPTIONS:
   --version, -v  print the version

To view the version of the CLI, use the --version option:

$ tds --version
tds version 1.0.0

The following subcommands are available in the CLI:

CommandPurpose
loginLog in to an account
switchChange the application and group linked to the project
infoView the application and group linked to the project
upRun and debug the project locally
newCreate a new project from a template
deployDeploy the project to Cloud Engine
publishPublish the version in the staging environment to the production environment
dbConnect to LeanCache or LeanDB
fileUpload files to the Data Storage service (uploaded files can be found on Developer Center > Your game > Game Services > Cloud Services > Data Storage > Files)
logsView Cloud Engine logs
debugOpen the Cloud Function Debug Console without running the project
envView or edit the environment variables of the current project

You can learn more about each subcommand by running tds <command> --help. For example:

View the output of tds deploy --help
NAME:
   tds deploy - Deploy the project to Cloud Engine

USAGE:
   tds deploy [command options] (--prod | --staging) [--no-cache --build-logs --overwrite-functions]

OPTIONS:
   --prod                              Deploy to production environment
   --staging                           Deploy to staging environment
   --build-logs                        Print build logs
   -g                                  Deploy from git repo
   --war                               Deploy .war file for Java project. The first .war file in target/ is used by default
   --no-cache                          Disable buliding cache
   --overwrite-functions               Overwrite cloud functions with the same name in other groups
   --leanignore value                  Rule file for ignored files in deployment (default: ".leanignore")
   --message value, -m value           Comment for this version, only applicable when deploying from local files
   --keep-deploy-file
   --revision value, -r value          Git revision or branch. Only applicable when deploying from Git (default: "master")
   --options --options build-root=app  Send additional deploy options to server, in urlencode format(like --options build-root=app)
   --direct                            Upload project's tarball to remote directly

Log In​

The first thing you may want to do after installing the CLI is to log in to your account.

Please go to the Developer Center, click “Create Game”, and then follow the instructions to enter your game’s information. After this, go to your game’s Game Services > Cloud Services > Cloud Engine > Turn on now > Deploy projects > Deploy using CLI and follow the instructions to log in to your account.

To switch to a different account, run tds login again.

Initialize a Project​

After logging in, you can initialize a project with tds new. This will also link the project to an existing application.

If you haven’t created an app on the dashboard, please do it first. Once you have your app created, create a new project by running tds new:

$ tds new my-engine-app
[?] Please select an app template:
 1) Node.js - Express
 2) Node.js - Koa
 3) Python - Flask
 4) Python - Django
 5) Java - Servlet
 6) Java - Spring Boot
 7) PHP - Slim
 8) .NET Core
 9) Go - Echo
 10) React Web App (via create-react-app)
 11) Vue Web App (via @vue/cli)
 => 1
[?] Please select an app:
 1) my-engine-app
 => 1
[INFO] Downloading templates 7.71 KiB / 7.71 KiB [==================] 100.00% 0s
[INFO] Creating project...
[INFO] Created Node.js - Express project in `my-engine-app`
[INFO] Lean how to use Express at https://expressjs.com

tds new will create a directory with the name you provided. We can now run cd my-engine-app and install the dependencies:

npm install

Most of the functions provided by the CLI require the project to be linked to an application. You can use tds switch to link a project to an application:

tds switch

If your application contains multiple groups, you’ll need to pick a group as well.

To link the project to a different application, run tds switch again.

You can also run tds switch <another app’s ID> to quickly switch to a different application.

You can view the application linked to the current project with tds info.

Run and Debug Locally​

Run the following command under the root directory of your project to run and debug the project locally:

tds up

Besides starting your project, the CLI will also start a Cloud Function Debug Console.

To change the port for starting the project, run tds up --port <new port>.

The CLI won’t take care of auto-restart or hot-reload for your project, though some of our demo projects (like the Node.js demo project) come with the auto-restart feature.

Besides starting your project with the CLI, you can also start them natively using commands like node server.js or python wsgi.py. This helps if you want to integrate the development process of your Cloud Engine project into your own development process or the IDE you’re using. If you created your project with the CLI, the project would depend on certain environment variables. You will need to configure these environment variables on your own.

You can run tds env to get the environment variables mentioned above. Once you’ve configured them on the terminal, you won’t have to start your project with the CLI anymore. If your shell is compatible with sh, you can also run eval $(tds env) to have all the environment variables configured automatically.

When starting your project, you can add custom options to the startup command by adding -- after tds up. All the options added after -- will be passed to the actual startup command. For example, if you want to enable the inspector by adding --inspect when starting a Node.js project, you can run tds up -- --inspect.

You can also start your project with any startup command by using the --cmd flag, like tds up --cmd=my-custom-command.

If you ever need to start your project with an IDE or debug the Cloud Functions of a project located on a virtual machine or a remote computer, you can run the Cloud Function Debug Console without running the project itself:

$ tds debug --remote=http://remote-url-or-ip-address:remote-port --app-id=xxxxxx

For more information about Cloud Engine, see Cloud Engine Overview.

Deploy​

Starting from v1.0, tds deploy requires that you provide an argument specifying the environment you would like to deploy your project to. If you don’t provide the argument, the CLI will ask for the environment interactively:

CommandBehavior under trial modeBehavior under standard mode
tds deploy --prodDeploy to the production environmentDeploy to the production environment
tds deploy --stagingNot supportedDeploy to the staging environment
tds publishNot supportedPublish the version in the staging environment to the production environment

Deploy From Local Project​

Once you’ve finished developing and testing your project, you can deploy it to Cloud Engine:

tds deploy --prod

This command will deploy the project to the production environment and override the previous version deployed from a local project, Git, or the online editor.

You will see the progress during the deployment:

$ tds deploy --prod
[INFO] lean (v1.0.0) running on darwin/arm64
[INFO] Current app: my-engine-app (xxxxxxxxxxxxxxxxxxxxxxxx), group: web, region: cn-n1
[INFO] Deploying new verison to production
[INFO] Node.js runtime detected
[INFO] Uploading file 6.40 KiB / 6.40 KiB [=========================] 100.00% 0s
[REMOTE] 开始构建 20220328-114036
[REMOTE] 正在下载应用代码 ...
[REMOTE] 正在解压缩应用代码 ...
[REMOTE] 运行环境: nodejs
[REMOTE] 正在下载和安装依赖项 ...
[REMOTE] 存储镜像到仓库（0B）...
[REMOTE] 镜像构建完成：20220328-114036
[REMOTE] 开始部署 20181207-115634 到 web1
[REMOTE] 正在创建新实例 ...
[REMOTE] 正在启动新实例 ...
[REMOTE] [Python] 使用 Python 3.7.1, Python SDK 2.1.8
[REMOTE] 实例启动成功：{"version": "2.1.8", "runtime": "cpython-3.7.1"}
[REMOTE] 云函数和 Hook 信息已更新
[REMOTE] 部署完成：1 个实例部署成功

The default message for the deployment is “Built from lean-cli”, which will be displayed on Developer Center > Your game > Game Services > Cloud Services > Cloud Engine > Manage deployment > Your group > Logs. You can customize the message with -m:

tds deploy --prod -m 'fix #42'

After deploying, you’ll need to bind a Cloud Engine domain for your application, then you’ll be able to test your project with curl or visit your site via a browser.

Ignore files with .leanignore

If your project contains certain files that need to be skipped when your deploy your project (like temporary files or those used by source code management tools), you can add them to .leanignore.

.leanignore shares a similar format with .gitignore (the syntax for .leanignore is actually a subset of that for .gitignore), with every single line as a file or directory to be ignored. If your project does not contain a .leanignore, the CLI will automatically create one according to the language used for the project. Make sure to check if the content in the file meets the requirements of your project.

Staging Environment​

If you’ve upgraded your application to the standard mode, a staging environment will be included in your application. The staging environment shares almost the same environment with the production environment and they both have access to the same data from the Data Storage services. You can bind a separate domain to the staging environment for testing purposes. While developing your project, you can deploy the changes to the staging environment first, and only publish the changes to the production environment if everything goes well in the staging environment.

To deploy to the staging environment:

tds deploy --staging

To publish the version in the staging environment to the production environment:

$ tds publish
[INFO] Current CLI tool version:  0.21.0
[INFO] Retrieving app info ...
[INFO] Deploying AwesomeApp(xxxxxx) to region: cn group: web production
[REMOTE] 开始部署 20181207-115634 到 web1
[REMOTE] 正在创建新实例 ...
[REMOTE] 正在启动新实例 ...
[REMOTE] 实例启动成功：{"version": "2.1.8", "runtime": "cpython-3.7.1"}
[REMOTE] 正在更新云函数信息 ...
[REMOTE] 部署完成：1 个实例部署成功
tds publish guarantees that the exact same version in the staging environment (including dependencies and the build output) will be deployed to the production environment.

Deploy From Git Repository​

If your project is hosted on a Git platform (like GitHub) and you have already configured the Git repository and deploy key on the dashboard, you can run the following command to have your project deployed with the source code in the repository:

tds deploy --prod -g
  • -g means to deploy from the Git repository. Make sure it is already set up on the dashboard.
  • The command will use the latest commit on the master branch by default. You can specify the commit or branch by adding -r <revision>.
  • See Cloud Engine Platform Features § Deploying With Git for instructions on how to set up Git repository and deploy key.

View Logs​

You can view the latest logs of your application with logs:

$ tds logs
      2019-11-20 17:17:12  Deploying 20191120-171431 to web1
      2019-11-20 17:17:12  Creating new instance ...
      2019-11-20 17:17:22  Starting new instance ...
web1  2019-11-20 17:17:22
web1  2019-11-20 17:17:22  > [email protected] start /home/leanengine/app
web1  2019-11-20 17:17:22  > node server.js
web1  2019-11-20 17:17:22
web1  2019-11-20 17:17:23  Node app is running on port: 3000
      2019-11-20 17:17:23  Instance started: {"runtime":"nodejs-v12.13.1","version":"3.4.0"}
      2019-11-20 17:17:23  Cloud functions and hooks metadata updated
      2019-11-20 17:17:23  Deploy finished: 1 instances deployed

The command will return 30 entries by default, with the latest ones on the bottom.

You can use the -f option to have logs fetched continuously (similar to using tail -f):

tds logs -f

Newer logs will be automatically printed to the bottom of the screen.

Advanced usage of tds logs

You can specify the number of entries returned by the CLI using the -l option. For example, to return the latest 100 entries:

tds logs -l 100

If you want to fetch the logs generated within a certain period of time, you can provide a --from and --to parameter:

tds logs --from=2017-07-01 --to=2017-07-07

Use --from without --to if you want to fetch the logs from a certain day to the current time:

tds logs --from=2017-07-01

If you prefer viewing logs with a different tool on your computer, you can export the logs into a file in the format of JSON:

tds logs --from=2017-07-01 --to=2017-07-07 --format=json > leanengine.logs

Both --from and --to use the local time zone (the time zone of the machine in which you run tds).

Connect to LeanDB​

You can open an interactive shell connected to LeanDB using tds db shell, a command provided by the CLI:

$ tds db shell mysqldb
Welcome to the MySQL monitor.
Your MySQL connection id is 3450564
Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
mysql> use test
Database changed
mysql> insert into users set name = 'leancloud';
Query OK, 1 row affected (0.04 sec)
mysql> select * from users;
+------+-----------+
| id   | name      |
+------+-----------+
|    1 | zhenzhen  |
|    2 | leancloud |
+------+-----------+
2 rows in set (0.06 sec)

With tds db proxy, you can export LeanDB to a local port and have local programs or GUI clients connect to the database:

$ tds db proxy myredis
[INFO] Now, you can connect myredis via [redis-cli -h 127.0.0.1 -a hsdt9wIAuKcTZmpg -p 5678]

As long as you keep the terminal open, you’ll be able to access LeanDB from the port 5678. You can use a GUI client to browse and interact with LeanDB. While running your project with tds up, you can also have your program connected to LeanDB using this feature. You can set the environment variable (from the output of tds db proxy):

export REDIS_URL_myredis=redis://default:[email protected]:5678
note

You should only use tds db for developing and debugging locally. Don’t use it for the production environment, as the connection might be interrupted occasionally.

Troubleshooting​

What should I do if the deployment failed?​

There could be different reasons that could cause a deployment to fail. Please read the error message to find the specific reason. If you’re not using the latest version of the CLI, you can try to upgrade the CLI to the latest version and try again.

I’m seeing Error: listen EADDRINUSE :::3000 when starting my project locally.​

listen EADDRINUSE :::3000 means the default port used by your program, 3000, is already occupied by a different program. You can find and kill the program using the port 3000 by following the instructions below:

You can also change the default port used by the CLI:

tds -p 3002

How to upload files with the CLI?​

$ tds file upload public/index.html
Uploads /Users/dennis/programming/avos/new_app/public/index.html successfully at: http://ac-7104en0u.qiniudn.com/f9e13e69-10a2-1742-5e5a-8e71de75b9fc.html

You will get a URL for each file successfully uploaded. That’s the message shown after successfully at: in the example above.

To upload all the files under images:

tds file upload images/

How to deploy the same project to multiple applications?​

You can switch to a different application with tds switch and deploy the project with tds deploy --prod. tds switch can be used non-interactively with arguments provided:

tds switch --region <REGION> --group <GROUP_NAME> <APP_ID>
tds deploy --prod

In the command above, <REGION> is the region of the application. --prod means to deploy to the production environment. To deploy to the staging environment, use tds deploy --staging. With the two commands mentioned above, you can write CI scripts to quickly deploy your project to multiple applications.

Can I extend the features provided by the CLI?​

If you have certain operations that need to be performed frequently (like checking the total number of records in _User), you can define your own commands.

Simply create an executable file with its name starting with lean- (like lean-usercount) and put it into a directory included in PATH or .leancloud/bin under the project directory. After this, you will be able to run the file with tds usercount. Compared to running lean-usercount, this method gives the program in the file the ability to access the environment variables related to each application.

For example, you can put the file below into a directory included in PATH (like /usr/local/bin):

#! /bin/env python

import sys

import leancloud

app_id = os.environ['LEANCLOUD_APP_ID']
master_key = os.environ['LEANCLOUD_APP_MASTER_KEY']

leancloud.init(app_id, master_key=master_key)
print(leancloud.User.query.count())

Grant the file the permission to be executed by running $ chmod +x /usr/local/bin/lean-usercount, and then run tds usercount under the project directory. Now you will see the total number of records in _User.

What has been changed in the 1.0 version of the CLI?​

In March 2022, we launched the 1.0 version of the CLI. Below are the breaking changes:

  • When using tds deploy, you have to specify the environment you want to deploy your project to (--prod or --staging). The older version of the CLI will deploy your project to the production environment if you’re using the trial mode and to the staging environment if you’re using the standard mode.
  • tds up won’t fetch the server-side environment variables by default. You can add the `--fetch-env` option to have those environment variables fetched.
  • Deleted tds cache. We recommend that you use the most advanced tds db for accessing LeanCache and LeanDB.

I’ve installed the older version of the CLI with npm. How do I upgrade to the latest version?​

If you’ve installed the older version of the CLI with npm, please uninstall the CLI with npm uninstall -g avoscloud-code leancloud-cli to avoid any conflicts. You can also follow Homebrew’s instructions to run brew link --overwrite lean-cli to override the previous lean command.