DOCSEARCHbyAlgolia
Submit Docs

QuantConnect Lean CLI

repository·master·Indexed 43 days ago

https://github.com/quantconnect/lean-cli

A cross-platform command-line tool that bridges local development with the QuantConnect LEAN engine. It enables developers to manage projects, run backtests and research environments via Docker, synchronize code with the QuantConnect cloud, and manage live trading deployments.

Tokens
36.5K
Snippets
139
Records
178
Agent score
51%

What's inside Lean CLI

  1. Use command shortcuts in Lean CLI

    master

    The Lean CLI allows you to use unambiguous prefixes to save typing. For example, lean clo back is equivalent to lean cloud backtest.

    Warning: While shortcuts are useful for interactive terminal use, you should always use the full command names in scripts to prevent breakage if new commands are added that share the same prefix.

  2. Access Docker containers via SSH for Rider debugging

    master
    When debugging QuantConnect Lean using JetBrains Rider, the system utilizes SSH keys located in the lean/ssh/ directory to provide access to the Docker container over SSH. These keys are sourced from phusion/baseimage-docker and are required for the remote debugging connection to function correctly.

  3. Install the Lean CLI

    master

    The Lean CLI can be installed or updated using pip. Note that many CLI commands require Docker to be installed on your system to run the LEAN engine or research environments.

    Linux Users: You may need to install tkinter manually.

    After installation, initialize your workspace by running lean init in an empty directory. This downloads the necessary configuration files and sample data. It is recommended to run all subsequent lean commands from this initialized directory.

    pip install --upgrade lean

# For Linux users (Python 3)
sudo apt-get install python3-tk

# Initialize the workspace
lean init

  5. Cloud-focused workflow (Local Dev, Cloud Execution)

    master

    Use this workflow if you want to write code locally but leverage QuantConnect's cloud infrastructure for running backtests and optimizations.

    1. Sync from Cloud: Run lean cloud pull to download files changed remotely.
    2. Backtest in Cloud: Run lean cloud backtest "Project Name" --open --push.
      • --open: Opens results in your browser automatically.
      • --push: Uploads your local code changes to the cloud before the backtest starts.
    3. Create Projects: Use lean create-project "Project Name" followed by lean cloud push --project "Project Name" to scaffold and upload a new project.
    4. Sync to Cloud: Use lean cloud push to upload all local changes to the cloud.
    # Pull remote changes
lean cloud pull

# Backtest in cloud, push code, and open results in browser
lean cloud backtest "MyProject" --open --push

# Create and push a new project
lean create-project "MyNewProject"
lean cloud push --project "MyNewProject"

# Push all local changes to cloud
lean cloud push

  6. Generate random market data with `lean data generate`

    master

    Use lean data generate to create realistic market data using a Brownian motion model. This is useful for testing algorithms without needing real historical data.

    Supported Security Types and Resolutions

    Security typeGenerated tick typesSupported resolutions
    EquityTradeTick, Second, Minute, Hour, Daily
    ForexQuoteTick, Second, Minute, Hour, Daily
    CFDQuoteTick, Second, Minute, Hour, Daily
    FutureTrade and QuoteTick, Second, Minute, Hour, Daily
    CryptoTrade and QuoteTick, Second, Minute, Hour, Daily
    OptionTrade and QuoteMinute

    Data Densities

    • Dense: At least one data point per resolution step.
    • Sparse: At least one data point per 5 resolution steps.
    • VerySparse: At least one data point per 50 resolution steps.

    Usage Examples

    Generate minute data for 100 equity symbols since 2015-01-01:

    lean data generate --start=20150101 --symbol-count=100

    Generate daily data for 100 crypto symbols since 2015-01-01:

    lean data generate --start=20150101 --symbol-count=100 --security-type=Crypto --resolution=Daily

  7. Run `lean backtest` in non-interactive mode

    master

    By default, lean backtest launches an interactive wizard to configure your brokerage and live data provider. To bypass this and run in non-interactive mode (useful for CI/CD or automation), provide the --environment, --brokerage, or --data-provider-live flags.

    • Use --environment to specify the name of a live environment defined in your Lean configuration.
    • If you provide both --brokerage and --data-provider-live, you must also include any options specific to those providers. The CLI will attempt to fall back to values in your Lean configuration if a specific option is missing. If a required option is missing from both the command and the Lean config, the command will abort.
    lean backtest --environment <env_name> --brokerage <brokerage_name> --data-provider-live <provider_name>

  8. Locally-focused workflow (Local Dev, Local Execution)

    master

    Use this workflow to run everything on your own machine using Docker. This is ideal for privacy, offline work, or using your own local datasets.

    1. Create Project: Run lean create-project "Project Name" to scaffold a new strategy.
    2. Research: Run lean research "Project Name" to launch a Jupyter Lab session for data analysis and strategy prototyping.
    3. Backtest Locally: Run lean backtest "Project Name". This executes your strategy inside a Docker container that mirrors the QuantConnect environment, using your local data.
    # Create a new local project
lean create-project "MyLocalStrategy"

# Start a Jupyter Lab research session
lean research "MyLocalStrategy"

# Run a local backtest in Docker
lean backtest "MyLocalStrategy"

  9. Configure the LEAN engine image

    master

    The CLI uses the official LEAN engine image by default. You can change this in two ways:

    1. Per command: Use the --image flag during a command execution.
    2. Globally: Set a default engine image for all commands using the lean config set command.
    lean config set engine-image <image>

  10. Set up Lean CLI for development

    master

    To develop the Lean CLI locally, clone the repository and use an environment with Python 3.7+. Install the dependencies in editable mode so that code changes are immediately reflected when running the lean command.

    If you add new dependencies, update setup.py for production dependencies or requirements.txt for development dependencies, then re-run the installation command.

    # Install dependencies and the CLI in editable mode
pip install -r requirements.txt

  11. Build and install Lean CLI from source

    master

    To create distribution packages and install them manually, use setup.py to build the source distribution and wheel, then install the resulting wheel file.

    After installing a new version, you can update the command references in the documentation by running the provided script.

    # Build the distribution packages
python setup.py sdist bdist_wheel

# Install the generated wheel (adjust filename if version differs)
pip install --force-reinstall dist/lean-dev-py3-none-any.whl

# Update README command references
python scripts/readme.py

  12. Configure historical data providers for backtests

    master

    You can control where your backtest retrieves historical data using the --data-provider-historical flag. This updates your local Lean configuration.

    • Local: The default provider, using data already present on your machine.
    • QuantConnect: Retrieves data directly from the QuantConnect API. This is also triggered by using the --download-data flag.

    If using the QuantConnect provider, you can limit spending by setting --data-purchase-limit <INT> to specify the maximum amount of QCC to be used for data downloads.

    # Use QuantConnect as the historical data provider and limit spending to 10 QCC
lean backtest ./MyProject --data-provider-historical QuantConnect --data-purchase-limit 10

# Alternative way to use QuantConnect provider
lean backtest ./MyProject --download-data