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.

Pattern	Required options	Typical commands
Batch	`--ctid` and `--pwd-file`	`periods`, `accounts`, `symbols`, `metadata`, `run`, `backtest`
Interactive	`--ctid`, `--password` and `-q`	`account`, `orders`, `price`, `candles`, `positions`, `exposure`, `alerts`, indicator commands

Note

The two conventions are not interchangeable. Batch commands reject --password; interactive commands reject --pwd-file.

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.

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

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.

Command	Trailing `all` and `yes` form
`order cancel`	`order cancel all yes`
`position close`	`position close all yes`
`stop`	`stop all yes`
`alert delete`	`alert delete all yes`

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.

Flag	Purpose
`--help`	List global options and the launch forms.
`--commands`	List every interactive command with its positional forms, no authentication needed.

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¶

Symptom	Likely cause	Next step
`ctrader-cli: command not found`	The CLI is not on your `PATH`.	Reopen the terminal or follow the manual install steps in the setup guide.
`Parameter password is not allowed`	You supplied `--password` to a batch command.	Switch to `--pwd-file`; the full rule is in the setup guide.
`Parameter pwd-file is not allowed`	You supplied `--pwd-file` to an interactive command.	Add `-q` and use `--password`.
`Account cannot be found`	The account number is ambiguous across brokers.	Add `--broker=<broker-name>`.
`Unknown symbol name`	The symbol name is wrong or unsupported.	Run `symbols` and use the exact name from the output.
`Unknown period`	The period token is wrong.	Run `periods` to list every accepted token.

Note

For every option, default value and complete description, see the CLI references.