Skip to main content

CLI Guide

The Cloud Engine CLI (lean) 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 lean-macos-arm64 (for Apple Silicon) or lean-macos-x64 (for Intel) from GitHub releases, rename the file to lean, and move the file to a directory listed within $PATH. Make sure to make the file executable by running chmod a+x /path/to/lean.

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 lean in Command Prompt or PowerShell.

You can also download the exe file, rename it to lean.exe, and add its path to the PATH environment variable (instructions). You will then be able to run lean 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 lean-linux-x64) from GitHub releases, rename the file to lean, and move the file to a directory listed within $PATH. Make sure to make the file executable by running chmod a+x /path/to/lean.

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 lean help on the terminal to view the help information:

View the output of lean help
NAME:
   lean - Command line tool to manage and deploy LeanEngine apps

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

VERSION:
   1.0.0

COMMANDS:
     login    Log in to LeanCloud
     switch   Change the associated LeanEngine app
     info     Show information about the associated user and app
     up       Start a development instance locally with debug console
     new      Create a new LeanEngine project from official examples
     deploy   Deploy the project to LeanEngine
     publish  Publish the version of staging to production
     db       Access to to LeanDB instances
     file     Manage files ('_File' class in Data Storage)
     logs     Show LeanEngine logs
     debug    Start the debug console without running the project
     env      Print custom environment variables on LeanEngine (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:

$ lean --version
lean 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 Dashboard > 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 lean <command> --help. For example:

View the output of lean deploy --help
NAME:
   lean deploy - Deploy the project to LeanEngine

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.

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

Initialize a Project​

After logging in, you can initialize a project with lean 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 lean new:

$ lean 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

lean 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 lean switch to link a project to an application:

lean 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 lean switch again.

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

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

Run and Debug Locally​

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

lean up

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

To change the port for starting the project, run lean 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 lean 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 $(lean 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 lean 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 lean up -- --inspect.

You can also start your project with any startup command by using the --cmd flag, like lean 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:

$ lean 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, lean 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
lean deploy --prodDeploy to the production environmentDeploy to the production environment
lean deploy --stagingNot supportedDeploy to the staging environment
lean 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:

lean 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:

$ lean 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 Dashboard > LeanEngine > Manage deployment > Your group > Logs. You can customize the message with -m:

lean 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:

lean deploy --staging

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

$ lean 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 个实例部署成功
lean 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:

lean 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:

$ lean 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  > node-js-getting-started@1.0.0 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):

lean logs -f

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

Advanced usage of lean logs

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

lean 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:

lean 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:

lean 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:

lean 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 lean).

Connect to LeanDB​

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

$ lean 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 lean db proxy, you can export LeanDB to a local port and have local programs or GUI clients connect to the database:

$ lean 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 lean up, you can also have your program connected to LeanDB using this feature. You can set the environment variable (from the output of lean db proxy):

export REDIS_URL_myredis=redis://default:hsdt9wIAuKcTZmpg@127.0.0.1:5678
note

You should only use lean 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:

lean -p 3002

How to upload files with the CLI?​

$ lean 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:

lean file upload images/

How to deploy the same project to multiple applications?​

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

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

In the command above, <REGION> is the region of the application, which can be set to cn-n1 (China North), cn-e1 (China East), or us-w1 (International). --prod means to deploy to the production environment. To deploy to the staging environment, use lean 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 lean 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 lean 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 lean 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.
  • lean 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 lean cache. We recommend that you use the most advanced lean 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.