Run cTrader CLI commands¶

This article explains how cTrader CLI commands are structured, how authentication works and how to read account data, prices and history.

Command shape¶

Every cTrader CLI command follows the same shape:

ctrader-cli <command> [arguments] [options]

• Options start with a prefix. -- is the long form, - is the short form (--symbol and -s are equivalent).
• Option values separate with a space or an equals sign. Both --symbol EURUSD and --symbol=EURUSD are valid.
• Arguments are positional values without a prefix. The path to an .algo file is an argument.
• Values that contain spaces must be wrapped in single or double quotes, such as '/opt/my cbots/trend cbot.algo'. Apply one quoting style consistently within a command.

Authentication¶

cTrader CLI has two authentication conventions. Both draw on the credentials file you prepare during setup.

The homonym commands accounts, symbols, metadata, run and backtest route to batch or interactive based on the flags you supply:

• Batch route – reads credentials from --pwd-file (or --broker) and runs non-interactively.
• Interactive route – takes --password and -q (or any command-specific flag) and runs as an interactive call.

Period tokens¶

Many commands accept a --period value. Run ctrader-cli periods to list every accepted token. Tokens cover minutes, hours, days, weeks and months, plus tick, Renko, range bars and Heikin Ashi variants. Parsing is case-insensitive.

Volume units¶

--volume accepts either base-currency units or lots. Use --volume-type=units (default) or --volume-type=lots to switch the interpretation. For most forex symbols, 100,000 units equal one standard lot.

ctrader-cli symbol --ctid=letstrade --pwd-file=C:/test/password.pwd --account=1234567 -q --symbol=XAUUSD

Dates and times¶

All dates and times in cTrader CLI are in UTC. The CLI never uses your machine's local time zone or the broker's server time.

UTC applies to command output and date input as follows:

• Output: every time in the JSON output is UTC in ISO 8601 with Z, for example 2026-10-08T14:05:00.000Z.
• Interactive commands (candles, deals, orders-history, and backtest run with -q): --from and --to take a date only, in yyyy-MM-dd, dd/MM/yyyy, dd-MM-yyyy or yyyy/MM/dd format. The date is a calendar day in UTC.
  • For deals and orders-history, --to includes the whole day, up to 23:59:59 UTC.
  • For candles, --to is the start of that day (00:00 UTC). To include a day, set --to to the next day.
  • Without --from / --to, the interactive backtest covers the last 7 days.
• Batch commands (backtest and others): dates use dd/MM/yyyy, optionally with a 24-hour time as dd/MM/yyyy HH:mm, for example 31/12/2026 18:00, also in UTC.

The one exception is a running cBot (run, backtest). Its time follows the TimeZone set in the cBot, as in cTrader Algo.

Read account and market data¶

ctrader-cli periods needs no account or credentials and is a good first test.

ctrader-cli periods

List the trading accounts linked to your cTrader ID:

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

Once you have the account number, list the symbols available on that account:

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

Read the current price for one symbol and pull historical candles in a script:

ctrader-cli price --ctid=letstrade --password=secret --account=1234567 -q --symbol=EURUSD
ctrader-cli candles --ctid=letstrade --password=secret --account=1234567 -q --symbol=EURUSD --period=h1 --count=200 > eurUSD_h1.json

History limits¶

deals and orders-history have the following history limits:

• The CLI loads the full --from / --to range with no length limit.
• One call returns only the latest 200 deals (deals) or the latest 500 orders (orders-history) in the range.
• Without --from / --to, both commands return only the last 30 days.

• --count sets the number of records to return:

  • 50 by default and up to 200 for deals.
  • 100 by default and up to 500 for orders-history.

--count is ignored when --from or --to is given; the call then returns up to the maximum.

If a range holds more records than one call returns, split it into shorter ranges and run the command for each.

To see whether the result was cut, check its output:

• orders-history: the output has available and returned. If available is bigger than returned, there are more orders in the range.
• deals: if count is exactly 200, there may be more trades in the range.

Bulk actions in the interactive shell¶

Inside the interactive shell, several commands accept a trailing all and a trailing yes to act in bulk and skip the confirmation prompt.

Run commands interactively¶

Run ctrader-cli without a command to open the interactive shell. Sign in with your cTID and password when prompted, then enter commands one after another without repeating your credentials. This is convenient when you want to run several commands in a row.

To run a single command and exit immediately, add -q. This is useful in scripts, where the process should finish as soon as the command completes.

Two flags help discover what the CLI supports.

If your cTrader ID has accounts with more than one broker that share the same account number, add --broker=<broker-name> to remove the ambiguity.

Common errors¶