Skip to content

cTrader CLI

You can think of ctrader-cli as a console version of cTrader Windows 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 Windows itself.
  • Access account and symbol data.

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

cTrader CLI in One Minute!

  • Working with algorithms no longer requires launching the cTrader Windows application, saving on RAM and CPU consumption.
  • cTrader CLI gives more control over cBot instances. You can write custom scripts that start and stop CLI processes programmatically!
  • Using a language of your choice, you can create custom tools for cBot management that use cTrader CLI to programmatically manage trading algos!
  • You can also integrate cTrader CLI with generative AI tools to use natural language to issue commands to your algorithms.
  • Using ctrader-cli you can run cBots under different trading accounts without many cTrader Windows applications opened.
  • Command line skills are not required. You can start a cBot in an external process from cTrader Windows without typing anything in a command line.

Warning

cTrader CLI supports only modern .NET 6 algos.
cTrader CLI is available in cTrader 4.8 and newer versions.

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.

Command Definition Supported Options and Arguments
-h | --help Show the list of available commands and their arguments. None
periods Show all available chart periods. None
accounts Show accounts linked to a cTID. --ctid | -c, --pwd-file, [--broker], [--environment-variables | -e]
symbols Show all available symbols. --ctid | -c, --pwd-file, --account | -a, [--broker], [--environment-variables | -e]
metadata Show metadata about a specific algorithm - either a cBot or an indicator. <cbot.algo>
run Run a specific cBot on a certain symbol with a given period. <cbot.algo>, [<params.cbotset>], --ctid | -c, --pwd-file, --account | -a, [--broker], [--environment-variables | -e], --symbol, --period, [--full-access], [<params.cbotset>], [--CustomParameter1], …, [--CustomParameterX]

The table below explains each option and argument.

Option or Argument Definition
--version | -v The current version of cTrader CLI (can be shown via ctrader-cli.exe --version).
--ctid | -c The nickname or an email assigned to a cTID.
--pwd-file The path to a file containing the password for the specified cTID.
--account | -a The number of a specific account.
--broker The name of a specific broker (should be specified only if a cTID has several accounts with the same numbers registered under different brokers).
--symbol | -s The symbol on which an algorithm is supposed to operate.
--environment-variables | -e If specified, the values for any other option (e.g., -c) can be taken from the environment variables rather than having to be typed explicitly.
<cbot.algo> The path to the .algo file you intend to run/receive metadata about. In run and metadata commands, this parameter has to be specified first.
--full-access If specified, runs the algorithms without any access rights limitations.
<params.cbotset> The path to the .cbotset file containing the parameter values for the algorithm you intend to run. In the run command, this parameter has to be specified immediately after <cbot.algo>.
--CustomParameter1 The value of any custom parameter the name of which matches CustomParameter1.

Creating PWD Files

To create a .pwd file containing your password, you can simply add a new text file with a .pwd extension. Afterward, open it and type/paste your password making sure to avoid unnecessary whitespaces.

How to Launch cTrader CLI

ctrader-cli is installed by default with regular cTrader Windows. 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 Windows interface (e.g., in the ‘Trade’ app). You should see the following menu.

Image title

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.

Reducing Resource Consumption

After you start a cBot instance in an external process using ctrader-cli you can freely close cTrader Windows to save on CPU and RAM consumption - this will not affect the behaviour of the instance.

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.

Command Syntax

If you have added cTrader CLI to your PATH variable, you will have to specify ctrader-cli before every command rather than ctrader-cli.exe.

Tip

Using a programming language of your choice, you can create scripts that will start and stop CLI processes under custom conditions.

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.

Algo API Member cTrader CLI Behaviour
MessageBox Returns MessageBoxResult.None.
Window All methods are ignored, no window(s) is/are shown.
Notifications.PlaySound Fully ignored.
Chart.TakeChartshot Returns null.

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.