运行 cTrader CLI 命令¶

本文介绍 cTrader CLI 命令的结构、身份验证方式, 以及如何查看账户数据、价格和历史记录。

命令结构 ¶

所有 cTrader CLI 命令都遵循相同的结构:

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

• 选项以特定前缀开头。 -- 表示长格式, - 表示短格式 (--symbol 与 -s 等效)。
• 选项与其值之间使用空格或等号分隔。 --symbol EURUSD 和 --symbol=EURUSD 两种写法都有效。
• 参数是没有前缀、按位置指定的值。 .algo 文件路径就是一个参数。
• 包含空格的值必须用单引号或双引号括起来, 例如 '/opt/my cbots/trend cbot.algo'。在同一命令中, 请统一使用一种引号样式。

身份验证 ¶

cTrader CLI 支持两种身份验证方式。两种方式都使用你在设置时准备的凭据文件。

accounts、symbols、metadata、run 和 backtest 这几个命令同时支持两种方式。它们会根据你提供的选项进入批处理或交互式模式:

• 批处理模式 – 从 --pwd-file (或 --broker) 读取凭据, 无需交互即可执行。
• 交互式模式 – 使用 --password 和 -q (或任何命令专用选项), 以交互式调用方式执行。

时间周期标识符 ¶

许多命令可以接受 --period 的值。运行 ctrader-cli periods 可列出所有受支持的标识符。标识符涵盖分钟、小时、天、周和月, 以及 tick、Renko、区间柱和 Heikin Ashi 的不同变体。解析标识符时不区分大小写。

交易量单位 ¶

--volume 可以接受以基础货币单位或手数表示的交易量。使用 --volume-type=units (默认) 或 --volume-type=lots 来选择交易量的计算单位。对于大多数外汇交易品种, 100,000 个单位等于 1 标准手。

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

日期和时间 ¶

cTrader CLI 中的所有日期和时间均采用 UTC。 CLI 不会使用你设备的本地时区或经纪商服务器时间。

UTC 在命令输出和日期输入中的使用规则如下:

• 输出: JSON 输出中的所有时间戳均采用 UTC, 使用带 Z 的 ISO 8601 格式, 例如 2026-10-08T14:05:00.000Z。
• 交互式命令 (candles、deals、orders-history 和使用 -q 运行的 backtest): --from 和 --to 只能接受日期, 格式为 yyyy-MM-dd、dd/MM/yyyy、dd-MM-yyyy 或 yyyy/MM/dd。该日期表示 UTC 时区中的一个日历日。
  • 对于 deals 和 orders-history, --to 包含指定日期的整天, 直至 UTC 23:59:59。
  • 对于 candles, --to 表示指定日期的开始时刻 (UTC 00:00)。如果要包含整天的数据, 请将 --to 设置为次日。
  • 如果不提供 --from / --to, 交互式 backtest 默认覆盖最近 7 天。
• 批处理命令 (backtest 等): 日期使用 dd/MM/yyyy 格式, 也可附加采用 24 小时制的 dd/MM/yyyy HH:mm 时间, 例如 31/12/2026 18:00, 同样以 UTC 为准。

唯一的例外是正在运行的 cBot (run、backtest)。其时间遵循 cBot 内设置的 TimeZone, 与 cTrader Algo 中的行为一致。

读取账户和市场数据 ¶

ctrader-cli periods 不需要账户或登录凭据, 很适合用于首次测试。

ctrader-cli periods

列出与你的 cTrader ID 关联的交易账户:

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

获取账户号码后, 列出该账户可用的交易品种:

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

通过脚本查看某交易品种的当前价格并获取历史 K 线数据:

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

历史记录限制 ¶

deals 和 orders-history 的历史数据查询存在以下限制:

• CLI 会加载 --from / --to 指定的完整时间范围, 不限制时间跨度。
• 但一次调用仅返回该范围内最近的 200 笔成交 (deals) 或最近的 500 笔订单 (orders-history)。
• 不提供 --from / --to 时, 两个命令都只返回最近 30 天的数据。

• --count 用于设置返回的记录数量:

  • deals 默认返回 50 条, 最多返回 200 条。
  • orders-history 默认返回 100 条, 最多返回 500 条。

指定 --from 或 --to 后, --count 会被忽略, 单次调用最多返回允许的最大记录数。

如果时间范围内的记录数超过单次调用的返回上限, 请将其拆分为更短的时间范围, 分别执行命令。

要判断结果是否被截断, 请检查命令输出:

• orders-history: 输出中包含 available 和 returned 字段。如果 available 大于 returned, 说明该范围内还有其他订单。
• deals: 如果 count 恰好为 200, 则该范围内可能还有其他成交记录。

交互式 Shell 中的批量操作 ¶

在交互式 Shell 中, 部分命令支持在末尾添加 all 和 yes, 以批量执行操作并跳过确认提示。

以交互方式运行命令 ¶

不指定任何命令, 直接运行 ctrader-cli 即可打开交互式 Shell。按提示使用 cTID 和密码登录后, 便可以连续输入多个命令, 无需反复提供凭据。当你需要连续运行多个命令时, 这种方式很方便。

要仅运行一个命令并立即退出, 请添加 -q。这适用于脚本, 因为命令执行完毕后进程应立即结束。

以下两个选项可以帮助你了解 CLI 支持哪些功能。

如果你的 cTrader ID 关联了多家经纪商的账户, 且这些账户的号码相同, 请添加 --broker=<broker-name> 以消除歧义。

常见错误 ¶