Skip to content

cTrader CLI

cTrader CLI enables traders to manage account and algo-trading operations directly from a console or terminal without launching or relying on the regular cTrader application. With cTrader CLI, users simply type commands into a text-based terminal to access and run cTrader algorithms.

cTrader CLI in one minute!

  • Run cBots in Windows and Linux without launching or relying on cTrader Desktop app and save on RAM and CPU resources.
  • Exercise more robust control over cBot instances and run cBots under different accounts without opening several cTrader application windows.
  • Create custom programs that use cTrader CLI to start, stop and manage trading algorithms in your preferred programming language.
  • Integrate cTrader CLI with generative AI tools and use natural language to issue commands to algorithms.

Warning

cTrader CLI is available in cTrader 4.8 or newer versions and works only with modern .NET 6 algos.

Launch and usage methods

Via cTrader Windows

Note

Command line or programming skills are not required to use cTrader CLI. You can prepare and apply your preferred parameters for a cBot in cTrader Windows and then instruct cTrader Windows to start your cBot in a cTrader CLI external process.

To run a cBot in cTrader CLI, right-click a local instance of that cBot in cTrader Windows and then select Start in external process.

Image title

cTrader CLI launches automatically and starts running the instance independently of the cTrader Windows application.

After you start a cBot instance in a cTrader CLI external process, you can close cTrader Windows to save on CPU and RAM resources, as cTrader CLI does not require cTrader Windows to stay open.

Via Windows command line

You can launch cTrader CLI from any command-line program in Windows, such as Command Prompt or Windows PowerShell.

First, navigate to the folder containing ctrader-cli and copy the path. The cTrader CLI executable file is usually located in the same directory as your cTrader Windows application:

1
C:\Users\{username}\AppData\Local\Spotware\cTrader\{installationId}

Image title

Second, open Command Prompt or Windows PowerShell, type cd, add a space and then paste the path you copied earlier. Your code should look like this:

1
cd C:\Users\{username}\AppData\Local\Spotware\cTrader\{installationId}

Run the code, and your command line program will enter the directory containing the ctrader-cli executable.

Finally, you can type in ctrader-cli.exe followed by any valid <command> and execute it. For example, you can run ctrader-cli.exe periods to see available periods.

Image title

Add path variable

Info

After you add cTrader CLI to your PATH environment variable, you will no longer have to navigate to the directory containing ctrader-cli before running commands in your Windows machine. Instead, you will be able to run commands in any location or folder by simply typing ctrader-cli followed by the <command>.

First, locate the folder containing ctrader-cli as you did before and copy the path. 

1
C:\Users\{username}\AppData\Local\Spotware\cTrader\{installationId}

Search for Environment variables in the Windows Start menu. Click Edit the system environment variables.

Image title

In the System properties window, click Environment variables. Double-click Path under the User variables for {username}. In the Edit environment variable window, click the New button and then paste the path you copied earlier into the field.

Click OK until all dialogues are dismissed.

Via Linux Docker image

cTrader CLI is available as a Linux Docker image, allowing you to run cBots on cheap Linux VPS instances, high-performance servers and reliable cloud platforms. This image can also be used on Windows through Docker Desktop (WSL) as a Docker container.

Note

If you are new to Docker, you are advised to study its documentation and familiarise yourself with the necessary concepts.

cTrader CLI Docker image is published under Spotware Github packages and new releases are provided with every major cTrader Windows update.

To use cTrader CLI Docker image, ensure that Docker is installed on your machine, then pull the latest available cTrader CLI Docker image:

1
docker pull ghcr.io/spotware/ctrader-console:latest

After pulling the image, you need to create and run a container. Since Docker containers run in a virtualised sandbox that is isolated from your operating system, you must explicitly allow the container to access your cBot algorithm file and cTID password file. This can be achieved using Docker’s mount feature, which lets a container access a directory or file from the host system.

The command below creates a container based on the pulled image and runs a cBot:

1
docker run -d -it --name ctrader.console.run.mybot --mount type=bind,src=/cAlgo/Robots,dst=/mnt/Robots -e CTID='mycid' -e PWD-FILE='/mnt/Robots/ctrader-cli.pwd' -e ACCOUNT='9102302' -e SYMBOL='EURUSD' -e PERIOD='H1' ghcr.io/spotware/ctrader-console:latest run "/mnt/Robots/My bot.algo" --environment-variables

1
2
3
4
5
6
7
8
9
docker run -d -it \
  --name ctrader.console.run.mybot \
  --mount type=bind,src=/cAlgo/Robots,dst=/mnt/Robots \
  -e CTID='mycid' \
  -e PWD-FILE='/mnt/Robots/ctrader-cli.pwd' \
  -e ACCOUNT='9102302' \
  -e SYMBOL='EURUSD' \
  -e PERIOD='H1' \
  ghcr.io/spotware/ctrader-console:latest run "/mnt/Robots/My bot.algo" --environment-variables

The remaining parameters in the command are explained below:

Parameter Description
--name ctrader.console.run.mybot Specifies the name of the container.
--mount type=bind,src=/cAlgo/Robots,dst=/mnt/Robots Mounts the host directory /cAlgo/Robots to the container directory /mnt/Robots.
-e CTID='mycid' Sets your cTID username as an environment variable.
-e PWD-FILE='/mnt/Robots/ctrader-cli.pwd' Defines the path to your cTID password file, relative to the mount point.
-e ACCOUNT='9102302' Sets your trading account number as an environment variable.
-e SYMBOL='EURUSD' Sets the symbol name as an environment variable.
-e PERIOD='H1' Sets the period as an environment variable.
"/mnt/Robots/My bot.algo" Specifies the path to your cBot algorithm file, relative to the mount point.
--environment-variables Informs cTrader CLI that environment variables are being used to pass configuration settings.

You can also create a ready-to-run Docker image based on the cTrader CLI image, copy your algorithm file into it and then configure all environment variables and other settings directly within the image.

Note

All cTrader CLI features are available when using the Docker image, including backtesting and other commands described in this article.

Common use cases

This is a list of popular operations traders employ cTrader CLI for:

  • Get all symbols

    1
    ctrader-cli symbols --ctid=letstrade@email.com --pwd-file=C:/test/password.pwd --account=1234567

    Response:

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
    [
  {
    "Id": 1,
    "Name": "EURUSD",
    "Description": "Euro vs US Dollar"
  },

    .
    .
    .

  {
    "Id": 21497,
    "Name": "HONG KONG 50",
    "Description": "HONG KONG 50"
  }
]

  • Get algo metadata

    1
    ctrader-cli metadata C:/test/RSI_cBot.algo

    Response:

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
    {
  "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
    }
  ]
}

  • Backtest a cBot

    1
    ctrader-cli run C:\test\mycbot.algo -c=letstrade@email.com --pwd-file=C:\test\password.pwd --account=1234567 --symbol=EURUSD --period=h1

  • Run a cBot with default parameters

    1
    ctrader-cli run C:\test\mycbot.algo -c=letstrade --pwd-file=C:\test\password.pwd --account=1234567 --symbol=EURUSD --period=h1

  • Run a cBot with custom parameters

    1
    ctrader-cli run C:\mycbot.algo -c=letstrade@email.com --pwd-file=C:\test\password.pwd --account=1234567 --symbol=EURUSD --period=h1 --ConsolidationPeriods=3 --Periods=15

  • Run a cBot with parameters saved in a file

    1
    ctrader-cli run C:\mycbot.algo C:\test\mysettings.cbotset -c=letstrade --pwd-file=C:\test\password.pwd --account=1234567 --symbol=EURUSD --period=h1

Breakdown of commands

cTrader CLI operates the same way as any command line tool. Users type in ctrader-cli along with predefined commands and run them. For example, the periods command is used this way to list all the chart periods on which algorithms can run:

1
ctrader-cli periods

Some commands have options or arguments that follow these rules:

  • -- is written before a full version of an option (such as, --ctid, --symbol) while - is written before a shortened version (such as, -c, -s).

  • The value of options can be specified using a space (such as, --ctid letstrade, --symbol EURUSD) or using the equals sign (such as, --ctid=letstrade, --symbol=EURUSD).

  • Unlike options, arguments are typed as is. Consider the path to an algorithm. It is an argument that is simply typed: C:/test/mycbot.algo

Example

  • Command with options

    This accounts command, which takes --ctid and --pwd-file as its options, outputs data on all accounts linked to letstrade:

    1
    ctrader-cli accounts --ctid=letstrade --pwd-file=C:/test/password.pwd

  • Command with arguments

    This metadata command, which takes the path to an algo as its only argument, outputs essential metadata about the algo: 

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

Any path or value containing a space must be specified using single or double quotes as demonstrated below:

  • Arguments such as 'C:/test for cbot/my cbot.algo' or "C:/test for cbot/my cbot.algo"
  • Options such as --pwd-file='C:\test for cbot\password.pwd' or --pwd-file="C:\test for cbot\password.pwd" , --start='01/01/2024 12:34' or --start="01/01/2024 12:34" and others.

Note

If you choose a style for doing something, avoid using a different style later within your code. For example, when you have already used single quotes (') for a path or value containing spaces, you have to use single quotes for other paths or values containing spaces in your code.

Creating PWD or TXT files

Passwords for cTrader ID are not specified directly. Instead, they are saved in PWD or TXT files and then the --pwd-file option is used to specify the path to the files (such as, --pwd-file=C:\test\password.pwdor --pwd-file=C:\test\password.txt).

Open an empty document in a text editor such as Notepad, paste or type in your password (without any whitespaces), then save the file with the .pwd or .txt extension.

All CLI commands

Note

Non-mandatory options for a given command are denoted in square brackets, for example, [--broker] in the table below. When you use such options in your code, you have to type them in without the square brackets, for example, --broker.

Command Function Supported options and arguments
--help or -h List available commands and their arguments. —
periods List available chart periods. —
accounts List accounts linked to a cTID. --ctid or -c, --pwd-file, [--broker], [--environment-variables or -e]
symbols List available symbols. --ctid or -c, --pwd-file, --account or -a, [--broker], [--environment-variables or -e]
metadata Show metadata about a cBot or indicator. <cbot.algo>
run Run a cBot on a specific symbol with a given period. <cbot.algo>, [<params.cbotset>], --ctid or -c, --pwd-file, --account or -a, [--broker], [--environment-variables or -e], --symbol, --period, [--full-access], [--CustomParameter1], …, [--CustomParameterN]
backtest Backtest a cBot using historical data for specified period, symbol and other parameters. <cbot.algo>, [<params.cbotset>], --start=<start-time>, --end=<end-time>, --data-mode=<data-mode>, [--data-file=<path>], [--balance=<balance>], [--commission=<commission>], [--spread=<pips>], [--report=<path>], [--report-json=<path>], --ctid=<ctid>, --pwd-file=<path>, --account=<id>, --symbol=<name>, --period=<period>, [--CustomParameter1=<value>], [--environment-variables]

Explanations

Argument Explanation
<cbot.algo> Path to the relevant .algo file (for example, C:/test/mycbot.algo). In run, metadata and backtest commands, this parameter must be specified first.
<params.cbotset> Path to the .cbotset file containing parameter values for the cBot (for example, C:/test/special-parameters.cbotset). In run and backtest commands, this parameter must be specified immediately after <cbot.algo>.
Option Explanation
--version or -v Version of cTrader CLI.
--ctid or -c cTID username or email (for example, --ctid=letstrade, --ctid=letstrade@email.com).
--pwd-file Path to a PWD or TXT file containing the password for the specified cTID (for example, --pwd-file=C:/test/password.pwd).
--account or -a Trading account number (for example, --account=1234567).
--broker Name of a specific broker (for example, --broker=spotware). This option is used to eliminate ambiguity in cases where the specified cTID has several trading accounts with different brokers that share the same number.
--symbol or -s Symbol the algorithm trades or operates on (for example, --symbol=EURUSD).
--period Period for the symbol chart (for example, --period=h1). In run and backtest commands, this parameter is mandatory.
--environment-variables or -e If specified, it allows the values for other options (for example, ctid) to be taken from the environment variables instead of having them typed in explicitly.
--full-access If specified, the algorithm runs without any access rights limitations.
--CustomParameter1 The value of any custom parameter whose name matches CustomParameter1 (for example, --SpecialPeriods=20).
--balance Starting capital for backtest (for example, --balance=10000).
--commission Commission per million for backtest (for example, --commission=30).
--spread Spread in pips for backtest (for example, --spread=1).
--data-mode Ticks, such as m1, m1-csv, open, etc., for backtest (for example, --data-mode=m1).
--data-file Path to CSV file containing data for backtest (for example, --data-file=C:/test/data.csv).
--start Start time in UTC in the DD/MM/YYYY [hh:mm] format for backtest (for example, --start=01/01/2024 or --start='01/01/2024 12:34' ).
--end End time in UTC in the DD/MM/YYY [hh:mm] format for backtest (for example, --end=31/08/2024 or --end='31/08/2024 20:56' ).
--report Path to HTML file where backtest report is saved (for example, --report=C:/test/report.html).
--report-json Path to JSON file where backtest report is saved (for example, --report-json=C:/test/report.json).
--exit-on-stop If specified, the CLI process terminates when the cBot stops.

Backtesting in cTrader CLI

Backtesting allows traders to use historical data to assess the performance and reliability of a cBot, discover its strengths or weaknesses and experiment with parameters. By simulating trades on past market conditions, backtesting helps to determine how an algorithm may perform before real funds are committed in live markets.

Note

While backtesting does not guarantee that an algorithm will be successful, it provides statistical backing that reduces the risk of unanticipated failures in live trading environments.

Commands

The backtest command with all possible options:

1
ctrader-cli backtest <cbot.algo> [<params.cbotset>] --start=<start-time> --end=<end-time> --data-mode=<data-mode> [--data-file=<path>] [--balance=<balance>] [--commission=<commission>] [--spread=<pips>] [--report=<path>] --ctid=<ctid> --pwd-file=<path> --account=<id> --symbol=<name> --period=<period> [--CustomParameter1=<value>] [--environment-variables]

A sample backtest command:

1
ctrader-cli backtest 'C:\test\sample martingale.algo' C:\test\special-parameters.cbotset --start='01/01/2024 12:34' --end='31/08/2024 20:56' --balance=10000 --commission=30 --data-mode=m1 --spread=1 --ctid=letstrade --pwd-file=C:\test\password.pwd --account=4791386

Reports

After the backtest command is executed, cTrader CLI first displays information about the backtesting parameters.

Image title

When the backtesting operation finishes, cTrader CLI displays a summary of the results.

Image title

Additionally, cTrader CLI saves the backtesting results and useful details in a Backtesting folder. Every backtesting operation gets its own unique InstanceID and Backtesting folder.

Path to a specific cBot backtesting instance: …\data\{cBotName}\{BacktestingInstanceID}\Backtesting

The data folder in the path above is usually in the same directory as the cBot algo file that was specified during backtesting.

Image title

The events JSON file contains details for every important trade event. 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
[

 {

  "serial": 0,

  "orderId": null,

  "positionId": 1,

  "event": "Create Position",

  "time": 1704146700000,

  "volume": 100000,

  "quantity": 1,

  "type": "Sell",

  "entryPrice": 1.10426,

  "tp": 1.10026,

  "sl": 1.10826,

  "closePrice": null,

  "grossProfit": 0,

  "pips": 0,

  "balance": null,

  "equity": 10000

 },
 .
 .
 .
 {

  "serial": 284,

  "orderId": null,

  "positionId": 143,

  "event": "Create Position",

  "time": 1725023280000,

  "volume": 200000,

  "quantity": 2,

  "type": "Buy",

  "entryPrice": 1.10559,

  "tp": 1.10959,

  "sl": 1.10159,

  "closePrice": null,

  "grossProfit": 0,

  "pips": 0,

  "balance": null,

  "equity": 32340.43

 }

]

The log TXT (text) file provides information on the cBot start, stop, trade actions and outcomes. 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
Info | CBot instance [sample martingale, EURUSD, h1] started.

01/01/2024 22:05:00.000 | Trade | Executing Market Order to Sell 100000 EURUSD (SL: 40, TP: 40)

01/01/2024 22:05:00.000 | Trade | → Executing Market Order to Sell 100000 EURUSD (SL: 40, TP: 40) SUCCEEDED, Position PID1

02/01/2024 10:12:00.000 | Info | Closed

02/01/2024 10:12:00.000 | Trade | Executing Market Order to Buy 100000 EURUSD (SL: 40, TP: 40)

02/01/2024 10:12:00.000 | Trade | → Executing Market Order to Buy 100000 EURUSD (SL: 40, TP: 40) SUCCEEDED, Position PID2

02/01/2024 12:22:00.000 | Info | Closed

02/01/2024 12:22:00.000 | Trade | Executing Market Order to Buy 200000 EURUSD (SL: 40, TP: 40)

02/01/2024 12:22:00.000 | Trade | → Executing Market Order to Buy 200000 EURUSD (SL: 40, TP: 40) SUCCEEDED, Position PID3
.

.

.

30/08/2024 13:08:00.000 | Info | Closed

30/08/2024 13:08:00.000 | Trade | Executing Market Order to Buy 200000 EURUSD (SL: 40, TP: 40)

30/08/2024 13:08:00.000 | Trade | → Executing Market Order to Buy 200000 EURUSD (SL: 40, TP: 40) SUCCEEDED, Position PID143

Info | CBot instance [sample martingale, EURUSD, h1] stopped.

The parameters CBOTSET file contains the parameters and values used in the backtesting operation. 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
{

 "Chart": {

  "Symbol": "EURUSD",

  "Period": "h1"

 },

 "Parameters": {

  "InitialQuantity": "1",

  "StopLoss": "40",

  "TakeProfit": "40"

 }

}

The report HTML file is a GUI report that provides an overview of the backtesting operation, trade statistics, order history and many important details. It can be viewed in any web browser.

Image title

Troubleshooting errors

Error message Solution
Unhandled exception or invalid usage Check your code thoroughly. Correct mistakes in syntax or remove unknown commands, options or arguments.
cTrader CLI does not support .NET 4 cBots Recompile your cBot for .NET 6 in the latest cTrader Windows application and use the new cBot file.
Connection cannot be established Check and fix the internet connection on your computer.
Invalid cTrader ID credentials Check the specified cTrader ID email, username or password thoroughly.
Account cannot be found Use the accounts command to list all trading accounts linked to your cTrader ID and then specify the correct number.
Unknown symbol name Use the symbols command to list available symbols and then specify the correct symbol.
Unknown period Use the periods command to list available periods and then specify the correct period.
Stop out (backtesting only) Improve your cBot code, alter its parameters to prevent margin calls or do both.
No historical data for the specified period (backtesting only) Provide the path to a file containing historical data for the specified period or specify another period.
Additional AccessRights are required. Use --full-access to grant the cBot elevated rights.
Invalid CBOTSET file format Consider generating your CBOTSET file using the latest version of cTrader Windows to ensure validity.
Ambiguous account number Use --broker to explicitly specify the broker associated with the account to avoid ambiguity.
Not supported cBot Build your cBot using .NET 6 in the latest cTrader Windows, export the cBot and then use the exported file.
Invalid settings (backtesting only) Check all the parameters specified for backtesting thoroughly and correct mistakes.

cTrader Algo API in cTrader CLI

Some cTrader Algo API members behave differently in cTrader CLI. The table below lists the members and describes the change in their behaviour.

cAlgo API member Behaviour in cTrader CLI
MessageBox Returns MessageBoxResult.None.
Window All methods are ignored. No window is shown.
Notifications.PlaySound Completely ignored.
Chart.TakeChartshot Returns null.

Summary

cTrader CLI is an essential feature for traders looking to expand the scope of their algo-trading activities because it empowers them to run and manage cBots efficiently with straightforward command-line instructions. Users are always encouraged to integrate cTrader CLI with useful APIs and third-party services that suit their needs.

Image title