Key Concepts

Before you start installing the Lean CLI, check the requirements of deploying with your brokerage to ensure you have a compatible machine and review the integration documentation for your brokerage so you are aware of what functionality is available through the integration.

The Lean CLI is distributed as a Python package, so it requires pip to be installed. See Installing pip to learn how to install pip on your operating system. Note that the Python distribution from the Microsoft Store is not supported, we recommend using the Anaconda distribution instead.

The commands which run the LEAN engine locally also depend on Docker being installed and running. See Install Docker to learn how to install Docker on your operating system.

To use the CLI, you must be a member in an organization on a paid tier.

Run pip install lean in a terminal to install the latest version of the CLI.

After installing the CLI, open a terminal in an empty directory and run lean login to log in to your QuantConnect account and then run lean init to create your first organization workspace. The lean init command downloads the latest configuration file and sample data from the QuantConnect/Lean repository. We recommend running all Lean CLI commands in your organization workspace directory.

$ lean init
Downloading latest sample data from the Lean repository...
The following objects have been created:
- lean.json contains the configuration used when running the LEAN engine locally
- data/ contains the data that is used when running the LEAN engine locally
...

If you are running Docker on Windows using the legacy Hyper-V backend instead of the new WSL 2 backend, you need to enable file sharing for your temporary directories and for your organization workspace. To do so, open your Docker settings, go to Resources > File Sharing and add C: / Users / <username> / AppData / Local / Temp and your organization workspace path to the list. Click Apply & Restart after making the required changes.

The CLI contains a lot of commands to make working on LEAN algorithms easier and more productive. Below we list some of the most common tasks, see the pages in the sidebar and the API reference for a complete overview of the supported features.

Authenticate With the Cloud

Before using the CLI to perform tasks in the cloud it is required to log in with your QuantConnect API credentials. Run lean login to open an interactive wizard which asks you for your user Id and API token. Request these credentials and we'll email them to you.

$ lean login
Your user Id and API token are needed to make authenticated requests to the QuantConnect API
You can request these credentials on https://www.quantconnect.com/account
Both will be saved in /home/<username>/.lean/credentials
User id: <user id>
API token: <api token>
Successfully logged in

Pull Projects From the Cloud

Run lean cloud pull to pull your QuantConnect projects to your local drive. This command pulls all your cloud projects to your local drive while preserving your QuantConnect directory structure. If you have a lot of projects and only want to work locally on a few of them you can run this command with the --project "<projectName>" option, which makes the command pull a single project instead.

$ lean cloud pull
[1/3] Pulling 'Creative Red Mule'
Successfully pulled 'Creative Red Mule/main.py'
[2/3] Pulling 'Determined Yellow-Green Duck'
Successfully pulled 'Determined Yellow-Green Duck/main.py'
Successfully pulled 'Determined Yellow-Green Duck/research.ipynb'
[3/3] Pulling 'Halloween Strategy'
Successfully pulled 'Halloween Strategy/benchmark.py'
Successfully pulled 'Halloween Strategy/main.py'
Successfully pulled 'Halloween Strategy/research.ipynb'

Source Data

Run lean data generate --start 20180101 --symbol-count 100 to generate realistic fake market data to test with. You can also choose to download data from QuantConnect Datasets or convert your own data into LEAN-compatible data.

$ lean data generate --start 20180101 --symbol-count 100
Begin data generation of 100 randomly generated Equity assets...
...

Run a Local Backtest

Run lean backtest "<projectName>" to run a local backtest for the specified project. This command runs a backtest in a Docker container containing the same packages as the ones used on QuantConnect.com, but with your own data.

$ lean backtest "Project Name"
20210308 23:58:35.354 TRACE:: Engine.Main(): LEAN ALGORITHMIC TRADING ENGINE v2.5.0.0 Mode: DEBUG (64bit)
20210308 23:58:35.360 TRACE:: Engine.Main(): Started 11:58 PM
...

Push Local Changes to the Cloud

Run lean cloud push to push local changes to the QuantConnect. This command pushes all your local projects to the cloud and creates new cloud projects when necessary. If you only want to push a single project you can run this command with the --project "<projectName>" option.

$ lean cloud push
[1/3] Pushing 'Creative Red Mule'
Successfully updated cloud file 'Creative Red Mule/main.py'
[2/3] Pushing 'Determined Yellow-Green Duck'
[3/3] Pushing 'Halloween Strategy'

Run a Cloud Backtest

Run lean cloud backtest "<projectName>" to run a cloud backtest for the specified project. By default, a summary of the results and a link to the full results are shown in the terminal. Running this command with the --open flag automatically opens the full results in the browser once the backtest is finished. Additionally, you can run this command with the --push flag to push all local changes to the project to the cloud before running the backtest.

$ lean cloud backtest "Project Name"
Started compiling project 'Project Name'
Detected parameters (2):
- main.py:19 :: 1 Order Event parameter detected near "SetHoldings(self.spy, 1)".
- main.py:21 :: 1 Order Event parameter detected near "SetHoldings(self.spy, 0)".
Build Request Successful for Project ID: 4882833, with CompileID: eaf9b677c91cfadd0a9032eb95918beb-c3b92b55d26a6d610e9b792ce561a687, Lean Version: 2.5.0.0.11058
Successfully compiled project 'Project Name'
Started backtest named 'Swimming Orange Lemur' for project 'Project Name'
...

LEAN is the open-source algorithmic trading engine. LEAN CLI is the way we recommend you run LEAN on your local machine. The LEAN CLI can do almost everything that LEAN can do. There are just some programs in the ToolBox that the LEAN CLI can't currently run. The lean data generate is a wrapper for the random data generator in the ToolBox. However, if you need any of the other programs in the ToolBox, you'll have to run LEAN manually and move the downloaded/parsed data to the CLI's data directory.