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 without launching or relying on cTrader Windows 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 and newer versions and works only with modern .NET 6 algos.

Launching and Using cTrader CLI¶

As cTrader CLI is bundled with a standard cTrader Windows installation, it can be launched using different methods.

Via cTrader¶

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'.

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 consumption. cTrader CLI does not require cTrader Windows to be open.

Via the 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:

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

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:

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 followed by any valid <command> and execute it. For example, you can run ctrader-cli periods to see available periods.

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. 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.

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

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

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.

Common Use Cases¶

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

Get all symbols

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

Response:

[
  {
    "Id": 1,
    "Name": "EURUSD",
    "Description": "Euro vs US Dollar"
  },

    .
    .
    .

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

Get algo metadata

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

Response:

{
  "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

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

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

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

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

Understanding 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:

ctrader-cli periods

Some commands have options or arguments that follow these rules:

-- is written before a full version of an option (e.g., --ctid, --symbol) while - is written before a shortened version (e.g., -c, -s).
The value of options can be specified using a space (e.g., --ctid letstrade, --symbol EURUSD) or using the equals to sign (e.g., --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 with --ctid and --pwd-file as its options outputs data on all accounts linked to letstrade:

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

Command with arguments

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

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".

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 (e.g., --pwd-file=C:\test\password.pwd, --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 e.g. [--broker] in the table below. When you use such options in your code, you have to type them in without the square brackets e.g. --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`], [`<params.cbotset>`], [`--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 (e.g., `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 (e.g., `C:/test/special-parameters.cbotset`). In `run` and `backest` 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 (e.g., `--ctid=letstrade`, `--ctid=letstrade@email.com`).
`--pwd-file`	Path to a PWD or TXT file containing the password for the specified cTID (e.g., `--pwd-file=C:/test/password.pwd`).
`--account` or `-a`	Trading account number (e.g. `--account=1234567`).
`--broker`	Name of a specific broker (e.g., `--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 (e.g., `--symbol=EURUSD`).
`--period`	Period for the symbol chart (e.g., `--period=h1`). In `run` and `backtest` commands, this parameter is mandatory.
`--environment-variables` or `-e`	If specified, it allows the values for other options (e.g., `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` (e.g., `--SpecialPeriods=20`).
`--balance`	Starting capital for `backtest` (e.g., `--balance=10000`).
`--commission`	Commission per million for `backtest` (e.g., `--commission=30`).
`--spread`	Spread in pips for `backtest` (e.g., `--spread=1`).
`--data-mode`	Ticks, such as `m1`, `m1-csv`, `open`, etc, for `backtest` (e.g., `--data-mode=m1`).
`--data-file`	Path to CSV file containing data for `backtest` (e.g., `--data-file=C:/test/data.csv`).
`--start`	Start time in UTC in the `DD/MM/YYY [hh:mm]` format for `backtest` (e.g., `--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` (e.g., `--end=31/08/2024` or `--end='31/08/2024 20:56'` ).
`--report`	Path to HTML file where `backtest` report is saved (e.g., `--report=C:/test/report.html`).
`--report-json`	Path to JSON file where `backtest` report is saved (e.g., `--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:

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:

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.

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

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\{cBotNamet}\{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.

EventsLogParametersReport

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

[

 {

  "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.

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.

{

 "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.

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 and or alter its parameters to prevent margin calls.
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.

The cAlgo API in cTrader CLI¶

Some cAlgo 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.

cTrader users are always encouraged to integrate cTrader CLI with useful APIs and third-party services that suit their needs. To learn more about the cTrader Algo API, see our documentation and API Reference or post a question on our forum.