ctrader-cli

概览

cTrader CLI 是 cTrader 平台的无头客户端：无需桌面界面，即可管理账户和交易品种、市场数据、订单和持仓、历史记录、价格提醒，以及完整的 cBot 生命周期。

它提供两种调用管道，选择正确的管道是最值得掌握的要点。批处理动词会返回简洁的机器可读载荷，便于编写脚本。通过 Shell 路由的动词通过交互式命令 Shell 运行，可访问范围大得多的命令集，并返回更丰富的载荷。同一个动词可以通过任一管道执行，而所使用的管道会决定 JSON 的大小写格式、载荷包装方式，以及接受哪些标志。以下内容旨在帮助你有意识地选择管道，而非偶然选中。

CLI 可在所有平台上原生运行。在 Windows 上，使用 winget install Spotware.cTrader.CLI 安装为 ctrader-cli.exe；在 macOS 和 Linux 上，从 Spotware Homebrew tap 安装（先运行 brew tap spotware/tap https://github.com/spotware/homebrew-tap，再运行 brew install spotware/tap/ctrader-cli），安装为 ctrader-cli——这是同一个 CLI，动词、标志和环境变量均完全相同。本技能中的命令格式均使用 Windows 可执行文件名称；在 macOS 或 Linux 上，只需去掉 .exe 后缀，其余内容保持不变（references/setup.md 介绍了各操作系统上的凭据设置）。

此处描述的行为与构建版本 5.9.0.38 相符；使用较新版本时，请重新确认重要细节。

调用规范

每次调用都使用此模板，只调整超时时间：

timeout 30 ctrader-cli.exe <verb> [flags] -e </dev/null 1>out.txt 2>err.txt; echo "EXIT:$?"

每个元素都有其作用：

• timeout 限制每次调用的时长。数据命令使用 30 秒，build、backtest 和 run 使用 240 秒。
• </dev/null 可确保进程终止。将 stdin 重定向后，进程不会等待提示，而是完成所请求的工作，到达流末尾并退出。
• 分别捕获 1> 和 2> 的输出，并为每次调用使用唯一文件名，避免载荷与命令回显混在一起。在共享机器上运行并发会话时，固定文件名可能会被覆盖。
• 直接读取 $?。管道会报告最后一个阶段的退出状态，因此将输出传入 head 或 grep 会丢弃 CLI 自身的状态码。

每次调用的进程启动时间约为 1.5 到 2 秒。需要获取多个只读结果时，可通过管道 stdin 将它们合并到一个进程中，从而分摊启动开销：

printf 'accounts\nsymbols\nq\n' | timeout 60 ctrader-cli.exe -e --account=<n>

这样运行两个命令需要 4.1 到 4.4 秒，而分开调用则需要 5.1 到 5.8 秒。空行和以 # 开头的行会被忽略，因此管道脚本可以包含注释。请注意，通过管道运行的会话属于 Shell 会话：其输出采用通过 Shell 路由的格式（camelCase、包装对象），而非批处理格式。

在 Windows 上，bash 会处理未加引号参数中的反斜杠，因此 Windows 路径始终要加双引号：--report-json="C:\reports\run.json"。

路由：批处理动词和经命令 shell 路由的动词

有 6 个动词有真正的批处理代码路径：periods、accounts、symbols、metadata、run、backtest——这 6 个就是 --help 本身列出的 BATCH 模式动词。create 和 build 虽然出现在 --help 的 BATCH MODE 参考部分，但无论以何种调用形式执行，它们都会经由命令 shell 运行——先显示横幅，再输出 camelCase JSON 载荷；若不使用 -q，还会继续进入交互菜单——因此请使用 -q 调用它们。其他所有动词都只能通过命令 shell 调用。

-q / --quick 是路由标志，不是静默标志。给这 6 个批处理动词之一添加该标志，会让整个调用转入 shell 管道，从而改变载荷的大小写格式、将载荷包装在以命令名为键的对象中、在载荷前添加横幅和时间戳标题，并且可能改变可接受的标志。

动词类别	调用方式	载荷
批处理数据（accounts、symbols、metadata）	不使用 -q	PascalCase JSON，无横幅
批处理流式任务（run、backtest）	不使用 -q	backtest：纯文本进度日志，随后输出紧凑的 PascalCase JSON 最终摘要；run：持续输出算法的内容，直到停止
脚手架（create、build）	使用 -q	横幅和时间戳标题之后的 camelCase JSON
经 shell 路由的动词（account、account-stats、symbol、sessions、price、prices、candles、orders、positions、order、position、exposure、orders-history、deals、alerts、alert、indicators、indicator）	使用 -q	横幅之后、以命令名为键包装的 camelCase 载荷
periods	直接调用，不带任何标志	纯文本，无需凭据

首次调用前需要了解的具体事项：

• accounts -e 不接受 --account；symbols -e 则要求提供该参数。这两个批处理动词有意采用了不同的设计。
• 批处理 symbols 会为每个条目返回 Id、Name、Description。同一动词加上 -q 时，则返回 name、description、category、assetClass——它会用分类字段替换数字 Id，而不是扩展批处理架构，因此需要符号 ID 时请使用批处理 symbols。
• periods 不接受任何标志；传入 -e 会返回 Error: Parameter e is not allowed。
• 经 shell 路由的动词需要在启动时通过显式标志传入参数。symbol --symbol=EURUSD 可以运行；直接传入位置参数 EURUSD 则不行。
• 对于经 shell 路由的读取操作，建议使用 -q，但并非强制要求：它会跳过命令菜单，避免菜单在载荷之后输出，从而让 stdout 保持精简，便于解析。不使用该标志时，只要 stdin 被重定向，调用仍会正常结束，并在退出码为 0 时打印一次菜单，然后显示 Bye.。
• 无法识别的动词会路由到 shell 菜单，并在 stdin 关闭时以退出码 0 结束，因此绝不能仅凭“退出码为 0”就认定预期的动词确实已运行。

ctrader-cli.exe --commands 会输出完整的 shell 命令参考，无需凭据或网络；这是确认动词确切参数形式的零成本方式。

凭据

有两种凭据格式可用于非交互式调用。优先使用第一种，它能让机密完全避开进程参数。

# Environment-variable credentials: CTID and PWD-FILE are set in the environment.
timeout 30 ctrader-cli.exe accounts -e </dev/null

# Explicit credentials.
timeout 30 ctrader-cli.exe accounts --ctid="<id>" --pwd-file="<path>" </dev/null

-e 的映射规则很严格：只有当环境变量名称与长选项名称完全一致（保留连字符、不区分大小写），且命令行中指定了 -e 时，才会读取该环境变量。因此会读取 CTID、PWD-FILE 和 ACCOUNT；account 也可以；不会读取带下划线的 PWD_FILE，而 ACCOUNT_ID 会导致 Error: Option account does not exist。显式指定的标志始终优先于匹配的环境变量。--environment-variables 是 -e 的长格式。

在所有路径中，--ctid 都用于标识用户（cTrader ID，即电子邮件地址）；交易账户则通过 --account 单独选择。密码文件的第一行是密码。标志名称是 --pwd-file；它没有短别名。--password 用于交互式操作，不应出现在脚本调用中。

切勿读取或打印 CTID 或 PWD-FILE 的值。只检查是否存在及其长度，并记住 PWD-FILE 中包含连字符，因此 $PWD-FILE 不会对它进行插值：

val="$(printenv 'PWD-FILE')"; echo "PWD-FILE length: ${#val}"

Shell 横幅会在标准输出中以 Connecting as <id>... 的形式打印 cTrader ID。将捕获的输出引用到报告或任何共享内容中时，请对其进行脱敏。

读取输出

应通过结构定位有效负载，切勿依赖固定的行数或字节偏移。扫描时间戳标题行，或第一个配对完整的 { 或 [；即使临时的连接重试行出现在有效负载之前，有效负载仍可能成功到达。

批处理有效负载从字节零开始：没有横幅、没有标题，JSON 使用扁平的 PascalCase。通过 Shell 路由的有效负载带有数行横幅，措辞会有所变化；随后是 [yyyy-MM-dd HH:mm:ss <local numeric offset>] 格式的标题行，其中回显了命令；接着是以命令名称为键包装的 camelCase JSON，例如 {"orders": [...]}。该标题中的时间是本地墙上时间，使用机器自身的时区偏移；这与 JSON 正文中的时间戳不同：正文中的时间戳为 UTC，并带有 Z 后缀。

因此，大小写取决于处理流程，而非命令动词。accounts 返回 Id 和 Balance；orders 返回 id 和 volumeLots。特别值得一提的是 backtest：其精简的标准输出摘要使用 PascalCase（Equity、NetProfit），而它为 --report-json 写入的文件使用 camelCase（main、equity、tradeStatistics）。build 不接受报告标志；其标准输出有效负载使用 camelCase（projectPath、success、errors）。

通过批处理路由调用时，无论成功还是失败，标准错误都会包含 CLI 自身回显的命令行，因此标准错误出现本身并不表示有错误。通过 Shell 路由的调用通常不会产生标准错误。因此，应将标准错误视为判断到达了哪条处理流程的线索，绝不能将其作为成功或失败的信号。

periods、--help、--commands、--version、确认和拒绝消息，以及诸如 Order #N not found. 这样的未找到消息，输出的是纯文本，而非 JSON。时间戳标题规则仅适用于通过 Shell 路由的 JSON 命令。

Windows 上的换行符为 CRLF。数字是普通 JSON 数字，已由 CLI 自身格式化并舍入，不受区域设置影响，不会使用分隔符；唯一例外是零交易回测摘要，它会将 AverageTrade 和 ProfitFactor 显示为单独的 - 标记，严格的 JSON 解析器会拒绝该标记。

退出代码和失败检测

代码	含义
0	成功
1	用法无效、标志无法识别、缺少必需参数或验证错误
81	cTrader ID 或密码无效
82	找不到账户
124	外部 timeout 结束了进程

消息文本是主要检测信号，退出代码是分支依据。此表之外还存在用于其他错误情况的非零代码，但这些代码未公开记录，因此请查看消息，不要根据数字推断含义。包装器 shell 报告的代码可能与直接调用不同；如果两者不一致，请优先参考消息。

切勿仅凭退出代码判断失败。build 在编译成功和失败时都会以 0 退出：JSON 正文中的 success 布尔值才是权威信号，诊断信息位于 errors: [{file, line, column, code, text}] 中。backtest 打印摘要后仍会继续运行，因此完成信号是最终的 JSON 摘要，或 --report-json 文件出现；如果这些产物已存在，那么 124 表示运行已完成，而非失败。

数值标志的值若不是数字，退出代码为 1，但消息的形式取决于标志和执行流程：candles --count=abc 会在 stdout 上返回一行格式清晰的 Error: Option --count has invalid number: abc；批处理路由的 symbols 中，--account=abc 会显示 System.FormatException 跟踪信息；而 shell 路由的动词（例如 orders）中，--account=abc 会在 stderr 上打印 Invalid account number: 'abc'. Expected a numeric login id.，且不带 Error: 前缀。此类错误没有统一的输出流或前缀，因此调用前请先验证数值标志的值。

修改状态的命令

会改变状态的动词包括 order place-market、order place-limit、order place-stop、order place-stop-limit、order modify、order cancel、position close、position close-partial、position modify、alert create、alert delete 和 stop。

授权门槛。 对于会修改状态的动词，-q 就是确认：它会自动回答确认提示并执行命令。由于 -q 也是通过 shell 路由读取操作时的常用标志，很容易因习惯而误用。只有在用户明确授权了这项具体操作，并且你已通过检查 accounts 返回 "Live": false 确认目标账户是模拟账户后，才能为修改状态的命令添加 -q。切勿通过运行会修改状态的命令来了解其行为。

对于使用标志的启动方式，适用的确认形式是 -q。--yes 和 -y 会返回 Refused: confirmation required 并以退出码 1 结束。末尾单独的 yes 是 shell 提示符语法；将它混入使用标志的命令行，会导致进程以退出码 1 结束，并输出 ConsoleInvalidUsageException 用法跟踪信息。all 关键字同样属于 shell 提示符；--help 文档说明了另一个启动标志 --all——依赖它之前请先核实。

默认情况下，交易量以单位表示。 对 EURUSD 而言，不指定 --volume-type 时使用 --volume=1000、使用 --volume=1000 --volume-type=units，以及使用 --volume=0.01 --volume-type=lots，最终存储的订单完全相同：volume: 1000, volumeLots: 0.01。请先通过 symbol --symbol=<name> 查看该交易品种自身的限制；该命令会返回 lotSize、minVolume、maxVolume、volumeStep、digits 和 pipSize。

修改时，止损和止盈有三种状态。 指定数值会替换当前值，0 会移除当前值，省略标志则保留当前值。请提供绝对价格。若价格位于参考价的错误一侧，系统会在提交前拒绝请求，并以退出码 1 输出两行消息：先是 Warning:，然后是 Error:；服务器状态不会改变。

请使用准确的标志名称 --order=<id>、--position=<id> 和 --alert=<id>。不同命令的响应键各不相同：order place-limit 返回 orderId，状态为 status: "placed"（挂单也采用此结构；市价单立即成交时则会返回 positionId，状态为 status: "opened"）；alert create 返回 id，状态为 status: "created"；alert delete 返回 alertId，状态为 status: "deleted"。请读取所调用命令实际返回的键。

每次修改后，都应使用 orders、positions 或 orders-history 重新读取受影响的实体，并确认状态已应用，然后再报告成功。

会话预检

首次进行经过身份验证的调用之前，请按照 references/setup.md 运行四步预检：检查可执行文件是否可访问；仅检查 CTID 和 PWD-FILE 是否存在及其长度；检查密码文件是否正常；以及使用 accounts -e 执行一次通过或失败探测。可能有三种结果：退出码 0 并返回 JSON 账户数组（就绪）；退出码 81（凭据遭拒）；以及退出码 1 并返回缺少参数的消息（快速、明确地失败，不会卡住）。该参考文件还提供了向配置需要修正的用户说明情况时应使用的准确措辞。

参考文件

• references/setup.md - 预检流程，以及针对各类失败情况向用户提供的设置说明。
• references/routing-and-output.md - 完整的路由矩阵、负载结构和解析示例。
• references/commands.md - 只读功能各动词的标志和负载结构。
• references/trading-write.md - 受保护的修改流程、交易量和保护机制语义，以及响应结构。
• references/algo-lifecycle.md - cBot 和指标的创建、构建、元数据、回测和运行。
• references/errors-and-exit-codes.md - 故障表、消息结构和恢复操作。