cTrader CLI

cTrader CLI 使交易者能够直接从控制台或终端管理账户和算法交易操作，无需启动或依赖常规 cTrader 应用程序。使用 cTrader CLI，用户只需在基于文本的终端中输入命令即可访问和运行 cTrader 算法。

cTrader CLI 一分钟入门！

在 Windows 和 Linux 上运行 cBot，无需启动或依赖 cTrader Windows 应用程序，节省 RAM 和 CPU 资源。
对 cBot 实例进行更强大的控制，无需打开多个 cTrader 应用程序窗口即可在不同账户下运行 cBot。
创建使用 cTrader CLI 启动、停止和管理交易算法的自定义程序，使用您喜欢的编程语言。
将 cTrader CLI 与生成式 AI 工具集成，使用自然语言向算法发出命令。

警告

cTrader CLI 在 cTrader 4.8 或更新版本中可用，仅适用于现代 .NET 6 算法。

启动和使用方法

通过 cTrader Windows

注意

使用 cTrader CLI 不需要命令行或编程技能。您可以在 cTrader Windows 中准备并应用 cBot 的首选参数，然后指示 cTrader Windows 在 cTrader CLI 外部进程中启动您的 cBot。

要在 cTrader CLI 中运行 cBot，请在 cTrader Windows 中右键单击该 cBot 的本地实例，然后选择在外部进程中启动。

cTrader CLI 会自动启动，并开始独立于 cTrader Windows 应用程序运行实例。

在 cTrader CLI 外部进程中启动 cBot 实例后，您可以关闭 cTrader Windows 以节省 CPU 和 RAM 资源，因为 cTrader CLI 不需要 cTrader Windows 保持打开状态。

通过 Windows 命令行

您可以从 Windows 中的任何命令行程序（如命令提示符或 Windows PowerShell）启动 cTrader CLI。

首先，导航到包含 ctrader-cli 的文件夹并复制路径。 cTrader CLI 可执行文件通常位于与 cTrader Windows 应用程序相同的目录中：

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

其次，打开命令提示符或 Windows PowerShell，输入 cd，添加一个空格，然后粘贴您之前复制的路径。您的代码应该如下所示：

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

运行代码，您的命令行程序将进入包含 ctrader-cli 可执行文件的目录。

最后，您可以输入 ctrader-cli.exe，后跟任何有效的 <command>，然后执行它。例如，您可以运行 ctrader-cli.exe periods 来查看可用的周期。

添加路径变量

信息

将 cTrader CLI 添加到 PATH 环境变量后，您将不再需要在 Windows 机器上运行命令之前导航到包含 ctrader-cli 的目录。相反，您可以在任何位置或文件夹中运行命令，只需输入 ctrader-cli，后跟 <command>。

首先，像之前一样找到包含 ctrader-cli 的文件夹并复制路径。

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

在 Windows 开始菜单中搜索环境变量。点击编辑系统环境变量。

在系统属性窗口中，点击环境变量。双击{用户名}的用户变量下的Path。在编辑环境变量窗口中，点击新建按钮，然后将您之前复制的路径粘贴到字段中。

点击确定，直到所有对话框关闭。

通过 Linux Docker 镜像

cTrader CLI 作为 Linux Docker 镜像 提供，允许您在廉价的 Linux VPS 实例、高性能服务器和可靠的云平台上运行 cBot。这个镜像也可以通过 Docker Desktop (WSL) 在 Windows 上作为 Docker 容器使用。

注意

如果您是 Docker 新手，建议您学习其文档并熟悉必要的概念。

cTrader CLI Docker 镜像发布在 Spotware Github 包 下，每次 cTrader Windows 主要更新时都会提供新的 发布版本。

要使用 cTrader CLI Docker 镜像，请确保您的机器上已安装 Docker，然后拉取最新可用的 cTrader CLI Docker 镜像：

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

拉取镜像后，您需要创建并运行一个容器。由于 Docker 容器在与您的操作系统隔离的虚拟沙盒中运行，您必须明确允许容器访问您的 cBot 算法文件和 cTID 密码文件。这可以通过 Docker 的挂载功能实现，该功能允许容器访问主机系统中的目录或文件。

以下命令基于拉取的镜像创建一个容器并运行一个 cBot：

单行多行

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

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

命令中的其余参数解释如下：

参数	描述
`--name ctrader.console.run.mybot`	指定容器的名称。
`--mount type=bind,src=/cAlgo/Robots,dst=/mnt/Robots`	将主机目录 `/cAlgo/Robots` 挂载到容器目录 `/mnt/Robots`。
`-e CTID='mycid'`	将您的 cTID 用户名设置为环境变量。
`-e PWD-FILE='/mnt/Robots/ctrader-cli.pwd'`	定义 cTID 密码文件的路径，相对于挂载点。
`-e ACCOUNT='9102302'`	将您的交易账户号码设置为环境变量。
`-e SYMBOL='EURUSD'`	将交易品种名称设置为环境变量。
`-e PERIOD='H1'`	将周期设置为环境变量。
`"/mnt/Robots/My bot.algo"`	指定 cBot 算法文件的路径，相对于挂载点。
`--environment-variables`	通知 cTrader CLI 正在使用环境变量传递配置设置。

您还可以基于 cTrader CLI 镜像创建一个随时可运行的 Docker 镜像，将算法文件复制到其中，然后直接在镜像内配置所有环境变量和其他设置。

注意

使用 Docker 镜像时，所有 cTrader CLI 功能都可用，包括本文描述的回测和其他命令。

常见用例

这是交易者使用 cTrader CLI 进行的常见操作列表：

获取所有交易品种

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

响应：

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

    .
    .
    .

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

获取算法元数据

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

响应：

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

回测 cBot

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

使用默认参数运行 cBot

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

使用自定义参数运行 cBot

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

使用保存在文件中的参数运行 cBot

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

命令详解

cTrader CLI 的操作方式与任何命令行工具相同。用户输入 ctrader-cli 以及预定义的命令并运行它们。例如，periods 命令用于列出算法可以运行的所有图表周期，使用方式如下：

1	`ctrader-cli periods`

一些命令有选项或参数，遵循以下规则：

-- 写在选项的完整版本之前（例如，--ctid、--symbol），而 - 写在缩写版本之前（例如，-c、-s）。
选项的值可以使用空格指定（例如，--ctid letstrade、--symbol EURUSD）或使用等号（例如，--ctid=letstrade、--symbol=EURUSD）。
与选项不同，参数直接输入。考虑算法的路径。它是一个直接输入的参数：C:/test/mycbot.algo

示例

带选项的命令

这个 accounts 命令，以 --ctid 和 --pwd-file 作为选项，输出与 letstrade 关联的所有账户数据：
1
ctrader-cli accounts --ctid=letstrade --pwd-file=C:/test/password.pwd
带参数的命令

这个 metadata 命令，以算法路径作为其唯一参数，输出有关算法的基本元数据：
1
ctrader-cli metadata C:/Users/{username}/Documents/cAlgo/Sources/Robots/mycoolcbot.algo

任何包含空格的路径或值必须使用单引号或双引号指定，如下所示：

参数如 'C:/test for cbot/my cbot.algo' 或 "C:/test for cbot/my cbot.algo"
选项如 --pwd-file='C:\test for cbot\password.pwd' 或 --pwd-file="C:\test for cbot\password.pwd" 、 --start='01/01/2024 12:34' 或 --start="01/01/2024 12:34" 等。

注意

如果你选择了一种做事方式，请避免在代码中稍后使用不同的方式。例如，当你已经使用单引号（'）来表示包含空格的路径或值时，你必须在代码中对其他包含空格的路径或值使用单引号。

创建 PWD 或 TXT 文件

cTrader ID 的密码不直接指定。相反，它们保存在 PWD 或 TXT 文件中，然后使用 --pwd-file 选项指定文件路径（例如，--pwd-file=C:\test\password.pwd 或 --pwd-file=C:\test\password.txt）。

在记事本等文本编辑器中打开一个空白文档，粘贴或输入你的密码（不含任何空白字符），然后以 .pwd 或 .txt 扩展名保存文件。

所有 CLI 命令

注意

给定命令的非必需选项用方括号表示，例如下表中的 [--broker]。在代码中使用这些选项时，你必须输入它们时不带方括号，例如 --broker。

命令	功能	支持的选项和参数
`--help` 或 `-h`	列出可用命令及其参数。	—
`periods`	列出可用的图表周期。	—
`accounts`	列出与 cTID 关联的账户。	`--ctid` 或 `-c`、`--pwd-file`、[`--broker`]、[`--environment-variables` 或 `-e`]
`symbols`	列出可用的交易品种。	`--ctid` 或 `-c`、`--pwd-file`、`--account` 或 `-a`、[`--broker`]、[`--environment-variables` 或 `-e`]
`metadata`	显示 cBot 或指标的元数据。	`<cbot.algo>`
`run`	在特定交易品种和给定周期上运行 cBot。	`<cbot.algo>`、[`<params.cbotset>`]、`--ctid` 或 `-c`、`--pwd-file`、`--account` 或 `-a`、[`--broker`]、[`--environment-variables` 或 `-e`]、`--symbol`、`--period`、[`--full-access`]、[`--CustomParameter1`]、…、[`--CustomParameterN`]
`backtest`	使用指定时期、交易品种和其他参数的历史数据对 cBot 进行回测。	`<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`]

解释

参数	解释
`<cbot.algo>`	相关 `.algo` 文件的路径（例如，`C:/test/mycbot.algo`）。在 `run`、`metadata` 和 `backtest` 命令中，此参数必须首先指定。
`<params.cbotset>`	包含 cBot 参数值的 `.cbotset` 文件的路径（例如，`C:/test/special-parameters.cbotset`）。在 `run` 和 `backtest` 命令中，此参数必须紧跟在 `<cbot.algo>` 之后指定。

选项	解释
`--version` 或 `-v`	cTrader CLI 的版本。
`--ctid` 或 `-c`	cTID 用户名或电子邮件（例如，`--ctid=letstrade`、`--ctid=letstrade@email.com`）。
`--pwd-file`	包含指定 cTID 密码的 PWD 或 TXT 文件的路径（例如，`--pwd-file=C:/test/password.pwd`）。
`--account` 或 `-a`	交易账户号码（例如，`--account=1234567`）。
`--broker`	特定经纪商的名称（例如，`--broker=spotware`）。此选项用于消除歧义，适用于指定的 cTID 在不同经纪商处有多个共享相同号码的交易账户的情况。
`--symbol` 或 `-s`	算法交易或操作的交易品种（例如，`--symbol=EURUSD`）。
`--period`	交易品种图表的周期（例如，`--period=h1`）。在 `run` 和 `backtest` 命令中，此参数是必需的。
`--environment-variables` 或 `-e`	如果指定，它允许其他选项的值（例如，`ctid`）从环境变量中获取，而不是显式输入。
`--full-access`	如果指定，算法将在没有任何访问权限限制的情况下运行。
`--CustomParameter1`	名称与 `CustomParameter1` 匹配的任何自定义参数的值（例如，`--SpecialPeriods=20`）。
`--balance`	`backtest` 的初始资金（例如，`--balance=10000`）。
`--commission`	`backtest` 的每百万佣金（例如，`--commission=30`）。
`--spread`	`backtest` 的点差（以点为单位）（例如，`--spread=1`）。
`--data-mode`	`backtest` 的报价，如 `m1`、`m1-csv`、`open` 等（例如，`--data-mode=m1`）。
`--data-file`	包含 `backtest` 数据的 CSV 文件路径（例如，`--data-file=C:/test/data.csv`）。
`--start`	`backtest` 的 UTC 开始时间，格式为 `DD/MM/YYYY [hh:mm]`（例如，`--start=01/01/2024` 或 `--start='01/01/2024 12:34'`）。
`--end`	`backtest` 的 UTC 结束时间，格式为 `DD/MM/YYY [hh:mm]`（例如，`--end=31/08/2024` 或 `--end='31/08/2024 20:56'`）。
`--report`	保存 `backtest` 报告的 HTML 文件路径（例如，`--report=C:/test/report.html`）。
`--report-json`	保存 `backtest` 报告的 JSON 文件路径（例如，`--report-json=C:/test/report.json`）。
`--exit-on-stop`	如果指定，当 cBot 停止时，CLI 进程将终止。

在 cTrader CLI 中进行回测

回测允许交易者使用历史数据来评估 cBot 的性能和可靠性，发现其优势或劣势，并尝试不同的参数。通过模拟过去市场条件下的交易，回测有助于在实际资金投入实时市场之前确定算法的表现。

注意

虽然回测不能保证算法一定会成功，但它提供了统计支持，可以降低在实时交易环境中出现意外失败的风险。

命令

带有所有可能选项的回测命令：

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]

回测命令示例：

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 

报告

执行 backtest 命令后，cTrader CLI 首先显示有关回测参数的信息。

回测操作完成后，cTrader CLI 显示结果摘要。

此外，cTrader CLI 将回测结果和有用的详细信息保存在 Backtesting 文件夹中。每次回测操作都会获得唯一的 InstanceID 和 Backtesting 文件夹。

特定 cBot 回测实例的路径： …\data\{cBotName}\{BacktestingInstanceID}\Backtesting

上述路径中的数据文件夹通常与回测期间指定的 cBot 算法文件位于同一目录中。

事件日志参数报告

events JSON 文件包含每个重要交易事件的详细信息。

[

 {

  "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

 }

]

log TXT（文本）文件提供有关 cBot 启动、停止、交易操作和结果的信息。

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.

parameters CBOTSET 文件包含回测操作中使用的参数和值。

{

 "Chart": {

  "Symbol": "EURUSD",

  "Period": "h1"

 },

 "Parameters": {

  "InitialQuantity": "1",

  "StopLoss": "40",

  "TakeProfit": "40"

 }

}

report HTML 文件是一个 GUI 报告，提供回测操作概览、交易统计、订单历史和许多重要细节。可以在任何网络浏览器中查看。

故障排除

错误消息	解决方案
未处理的异常或无效使用	仔细检查您的代码。纠正语法错误或删除未知的命令、选项或参数。
cTrader CLI 不支持 .NET 4 cBots	在最新的 cTrader Windows 应用程序中为 .NET 6 重新编译您的 cBot，并使用新的 cBot 文件。
无法建立连接	检查并修复您计算机上的互联网连接。
无效的 cTrader ID 凭证	仔细检查指定的 cTrader ID 电子邮件、用户名或密码。
找不到账户	使用 `accounts` 命令列出与您的 cTrader ID 关联的所有交易账户，然后指定正确的编号。
未知的交易品种名称	使用 `symbols` 命令列出可用的交易品种，然后指定正确的交易品种。
未知的时间周期	使用 `periods` 命令列出可用的时间周期，然后指定正确的时间周期。
强平（仅限回测）	改进您的 cBot 代码，更改其参数以防止追加保证金通知，或同时进行这两项操作。
指定时间周期没有历史数据（仅限回测）	提供包含指定时间周期历史数据的文件路径，或指定另一个时间周期。
需要额外的 `AccessRights`。	使用 `--full-access` 授予 cBot 提升的权限。
无效的 CBOTSET 文件格式	考虑使用最新版本的 cTrader Windows 生成 CBOTSET 文件以确保有效性。
账户号码不明确	使用 `--broker` 明确指定与账户关联的经纪商，以避免歧义。
不支持的 cBot	使用最新的 cTrader Windows 中的 .NET 6 构建您的 cBot，导出 cBot，然后使用导出的文件。
无效的设置（仅限回测）	仔细检查为回测指定的所有参数并纠正错误。

cTrader CLI 中的 cTrader Algo API

某些 cTrader Algo API 成员在 cTrader CLI 中的行为有所不同。下表列出了这些成员并描述了它们行为的变化。

cAlgo API 成员	在 cTrader CLI 中的行为
`MessageBox`	返回 `MessageBoxResult.None`。
`Window`	所有方法都被忽略。不显示窗口。
`Notifications.PlaySound`	完全被忽略。
`Chart.TakeChartshot`	返回 `null`。

摘要

cTrader CLI 是希望扩大算法交易活动范围的交易者的重要功能，因为它使他们能够通过简单的命令行指令高效地运行和管理 cBots。我们始终鼓励用户将 cTrader CLI 与适合其需求的有用 API 和第三方服务集成。