cTrader CLI¶

You can think of ctrader-cli as a console version of cTrader Desktop with its functionality focused on running and managing cBots and related features. Here is a non-exhaustive list of what you can do while working with ctrader-cli.

• Launch and stop algorithms without having to access cTrader Desktop itself.
• Access account and symbol data.

Our usual one-minute summary of this feature can be found below.

cTrader CLI Commands¶

Similarly to any other command line tool, ctrader-cli is operated via the user issuing certain pre-defined commands to the command line interface. For example, typing the following command will display the list of all chart periods on which trading algos can run.

ctrader-cli.exe periods

Commands can have named options and unnamed arguments.

• Options are typically preceded by -- (followed by the full option name) or - (followed by the shortened option name).
• The values of arguments are typed ‘as is’ without any additional names or notations.

For an example of a command that has one argument, see below.

ctrader-cli.exe metadata C://Users/{username}/Documents/cAlgo/Sources/Robots/mycoolcbot.algo

This command will output essential metadata about the algorithm for which you have specified the file path after the metadata command. This information will contain the algorithm name, its type, the parameters that it has, as well as its last build time.

For an example of a command that has two named options, see below.

ctrader-cli.exe accounts --ctid=test@email.com --pwd-file=C:/password/password.pwd

The command should output data about all accounts linked to the specified cTID.

For the full list of commands and their supported arguments, consult the below table. All non-required options for a given command are denoted in square brackets.

The table below explains each option and argument.

How to Launch cTrader CLI¶

ctrader-cli is installed by default with regular cTrader Desktop. You can access it in three different ways.

Via cTrader

To run a cBot instance via ctrader-cli, right-click on it in the cTrader Desktop interface (e.g., in the ‘Trade’ app). You should see the following menu.

Click on ‘Start External Process’, and ctrader-cli will launch. On launch, the service will run your chosen instance on the chart to which it was originally attached.

Via a Command Line

You can access ctrader-cli by opening any suitable command line interface (e.g., by typing ‘cmd’ in the Windows search bar).

In the interface, navigate to the folder containing the ctrader-cli.exe file. Usually, this path looks as follows on Windows machines.

C:\Users\{username}\AppData\cTrader\{installationId}

After navigating to the correct folder, you can simply type any valid command in the command line interface to execute it.

Via the PATH Variable

Last but not least, you can add ctrader-cli to your PATH environment variable (on Windows machines). After doing so, you will be able to use the ctrader-cli command in any suitable command line interface while inside any folder.

Perform the following actions.

1. Type ‘env’ into the Windows search bar and select ‘Edit the system environment variables’.

2. In the newly appeared window, click on ‘Environment Variables’.

3. In the ‘User variables for {username}’ section, select ‘Path’, and click on ‘Edit’.

4. Press the ‘New’ button and paste the full path to the ctrader-cli.exe file into the text field that has just appeared.

Afterward, open any suitable command line interface. You can now execute ctrader-cli commands from any folder.

Common Use Cases¶

Here is a list of the common commands you can execute to perform common operations.

Getting all symbols

ctrader-cli.exe symbols --ctid=test@email.com --pwd-file=C:/password/password.pwd

Getting algo metadata

ctrader-cli.exe metadata C:/RSI_cBot.algo

Here is an example of an output you should get when executing the metadata command - as you can see, this output shows all important information including the names of any cBot parameters (you can use these names with the --CustomParameter1 option), their types, and default values.

{
  "Name": "RSI_cBot",
  "Type": "cBot",
  "AccessRights": "None",
  "BuildTime": "2023-05-11T16:42:56.7421508+03:00",
  "Parameters": [
    {
    "PropertyName": "Quantity",
    "FriendlyName": "Quantity (Lots)",
    "GroupName": "Volume",
    "Type": "Double",
    "DefaultValue": 1.0,
    "MinValue": 0.01
    },
    {
    "PropertyName": "Source",
    "FriendlyName": "Source",
    "GroupName": "RSI",
    "Type": "DataSeries",
    "DefaultValue": {
        "OwnerId": "00000000-0000-0000-0000-000000000000",
        "FriendlyName": "Close",
        "IsStandard": true
    }
    },
    {
    "PropertyName": "Periods",
    "FriendlyName": "Periods",
    "GroupName": "RSI",
    "Type": "Integer",
    "DefaultValue": 14
    }
  ]
}

Running a cBot with default parameters

ctrader-cli.exe run C:\mycoolbot.algo -c=test@email.com --pwd-file=C:\password\password.pwd --account=1209201 --symbol=EURUSD --period=h1

Running a cBot with custom parameters

ctrader-cli.exe run C:\mycoolbot.algo -c=test@email.com --pwd-file=C:\password\password.pwd --account=1209201 --symbol=EURUSD --period=h1 --ConsolidationPeriods=3 --Periods=15

Running a cBot with parameters from a saved preset

ctrader-cli.exe run C:\mycoolbot.algo C:\coolbotsettings.cbotset -c=test@email.com --pwd-file=C:\password\password.pwd --account=1209201 --symbol=EURUSD --period=h1 

The Algo API in cTrader CLI¶

The following table summarises how certain Algo API members behave in ctrader-cli. Note that these behaviors differ from regular cTrader.

Summary¶

cTrader CLI is an essential feature for anyone who wants to expand the scope of their algorithm trading activities as it allows for managing cBots using any custom interface that can interact with command line instructions. We recommend experimenting with integrating ctrader-cli with various APIs and third-party services - you may just create an unbeatable ‘companion’ app for any cTrader algorithm.