cBot operations¶

This article covers the cBot lifecycle in cTrader CLI. Use it to run a cBot from a terminal, list and stop running instances, host a cBot on a VPS or cloud server with Docker and backtest a cBot against historical data.

Prerequisites¶

cTrader CLI is installed.
Your cTrader ID, a credentials file and your account number are ready.
The cBot is exported as an .algo file built for .NET 8.

Read cBot metadata¶

Before you run a cBot, list the parameters it accepts with metadata. The output names each cBot property and its type.

ctrader-cli metadata <path-to-algo-file>

Use the parameter names from the metadata output when you supply parameters through the command line or through a .cbotset file.

Run a cBot¶

Start a cBot with run. The path to the .algo file is the first argument. --account, --symbol and --period are required.

ctrader-cli run <path-to-algo-file> --account=<account-id> --symbol=<symbol> --period=<period>

Three ways to pass parameters.

Source	When to use	Example
Default	The cBot has parameters that already work.	`ctrader-cli run /opt/mycbot.algo --account=1234567 --symbol=EURUSD --period=h1`
On the command line	Override one or two values without creating a file.	`ctrader-cli run /opt/mycbot.algo --account=1234567 --symbol=EURUSD --period=h1 --Periods=15 --ConsolidationPeriods=3`
`.cbotset` file	Reuse a set of values across runs; export the file from the cTrader desktop application.	`ctrader-cli run /opt/mycbot.algo /opt/mysettings.cbotset --account=1234567 --symbol=EURUSD --period=h1`

Two optional flags matter for unattended runs.

Option	Purpose
`--full-access`	Run the cBot without access-right restrictions, when the cBot needs to read or write local files or reach the network.
`--exit-on-stop`	Exit the cTrader CLI process when the cBot stops itself; useful in scripts and containers.

Run a cBot on a VPS or cloud server¶

A terminal-only tool runs comfortably on a small Linux instance, so a cBot can run continuously at a lower cost than on a desktop machine. The cTrader CLI Docker image is the most portable way to do this.

Pull the latest image:

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

Run a cBot in a container. The --mount option maps a host folder into the container; the -e options pass configuration through environment variables:

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

Part	Meaning
`--name ctrader.console.run.mybot`	Names the container.
`--mount type=bind,src=...,dst=...`	Maps a host folder into the container at `/mnt/Robots`.
`-e CTID='mycid'`	Sets the cTrader ID as an environment variable.
`-e PWD-FILE='/mnt/Robots/ctrader-cli.pwd'`	Sets the path to the password file inside the container.
`-e ACCOUNT='9102302'`	Sets the trading account number.
`-e SYMBOL='EURUSD'`	Sets the symbol.
`-e PERIOD='H1'`	Sets the period.
`"<path>"`	Path to the cBot file inside the container.
`--environment-variables`	Tells cTrader CLI to read configuration from environment variables.

Note

All cTrader CLI features are available in the Docker image, including backtesting and optimisation.

Launch from the cTrader desktop application¶

You do not need command-line skills to benefit from cTrader CLI.

In the cTrader desktop application, prepare a cBot with your preferred parameters.
Right-click a local cBot instance and select Start in external process. cTrader CLI launches automatically and runs the instance independently.
Close the desktop application to save CPU and RAM. The cBot keeps running in the cTrader CLI process.

List and stop cBots¶

List the cBot instances currently running on the account:

ctrader-cli cbots --ctid=letstrade --password=secret --account=1234567 -q

Stop a running instance with its identifier, which run reports in the output:

ctrader-cli stop --ctid=letstrade --password=secret --account=1234567 -q --instance=<instance-id>

To stop every running cBot at once, drop into the interactive shell and run stop all yes. The cTrader CLI process exits when the last instance stops.

Backtest a cBot¶

Run a cBot against historical data with backtest. The path to the .algo file is the first argument, an optional .cbotset file can follow it, and the test needs a symbol, a period and a date range:

ctrader-cli backtest <path-to-algo-file> [<path-to-cbotset-file>] --account=<account-id> --symbol=<symbol> --period=<period> --start=<start-date> --end=<end-date> --data-mode=<data-mode>

Testing-context options¶

The testing-context flags follow the backtest entry in the CLI references. The only required inputs are --start, --end and --data-mode. The optional flags cover starting balance, commission, spread, data sources and report outputs.

Data modes¶

Value	Description
`open`	Uses the open prices of the base period; fast, with lower accuracy within each bar.
`m1`	Uses one-minute data downloaded from the server.
`m1-csv`	Uses one-minute data supplied through `--data-file`.
`tick-csv`	Uses tick data supplied through `--data-file`.
`ticks`	Uses tick data downloaded from the server; the most accurate mode and the slowest; required for tick, range and Renko periods.

Tip

Set --data-dir to a folder that persists between runs, so cTrader CLI reuses the downloaded price data instead of downloading it again for each backtest. In Docker, map this folder to a host directory to keep the data after the container stops.

Worked example¶

Run a backtest on a sample cBot with a single .cbotset parameters file:

ctrader-cli backtest "C:/test/sample martingale.algo" C:/test/special-parameters.cbotset \
  --ctid=letstrade --pwd-file=C:/test/password.pwd --account=1234567 --symbol=EURUSD --period=h1 \
  --start="01/01/2025 12:34" --end="31/01/2025 20:56" \
  --balance=10000 --commission=30 --commission-type=UsdPerMillionUsdVolume --spread=1 --data-mode=m1

Backtest output¶

cTrader CLI streams progress to the terminal, then prints a summary when finished. The full result is in a Backtesting folder next to the .algo file, one instance per run:

…/data/{cBotName}/{BacktestingInstanceID}/Backtesting

File	Contents
Events (JSON)	Every significant trade event, such as opening and closing positions.
Log (TXT)	cBot start, stop, trade actions and outcomes.
Parameters (`.cbotset`)	The parameters and values used in the backtest.
Report (HTML)	A visual report of trade statistics and order history, which opens in a web browser.

--report and --report-json save reports to a specific path in addition to the folder above.

Algo API behaviour in cTrader CLI¶

A few cTrader Algo API members behave differently when a cBot runs in cTrader CLI, because there is no graphical interface.

API member	Behaviour in cTrader CLI
`MessageBox`	Returns `MessageBoxResult.None`.
`Window`	All methods are ignored and no window is shown.
`Notifications.PlaySound`	Ignored.
`Chart.TakeChartshot`	Returns `null`.