ctrader-cli

概要

cTrader CLI は cTrader プラットフォーム用のヘッドレスクライアントです。デスクトップ UI を使わずに、アカウントとシンボル、市場データ、注文とポジション、履歴、価格アラート、そして cBot の全ライフサイクルを操作できます。

呼び出しパイプラインは 2 種類あります。適切な方を選ぶことが、最も重要なポイントです。バッチ動詞は、スクリプト向けのコンパクトで機械可読なペイロードを返します。シェル経由動詞は、より広範なコマンドを利用でき、より豊かなペイロードを返す対話型コマンドシェルを通じて実行されます。同じ動詞をどちらのパイプラインでも実行できますが、どちらのパイプラインで実行されるかによって、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 として利用できます。動詞、フラグ、環境変数は同一です。このスキル全体で使用するコマンド形式は Windows の実行ファイル名を使っています。macOS または Linux では .exe を省略すれば、ほかはそのまま使えます（OS ごとの認証情報の設定については 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 を指定すると、処理が確実に終了します。標準入力をリダイレクトすると、プロセスがプロンプトを待つことはありません。要求された処理を完了してストリームの終端に達すると、終了します。
• 1> と 2> で別々に出力をキャプチャし、呼び出しごとに一意のファイル名を使うことで、ペイロードとコマンドエコーを分離できます。共有マシン上でセッションを同時に実行すると、固定名のファイルが上書きされる可能性があります。
• $? を直接読み取ってください。パイプでは最後の段階の終了ステータスが報告されるため、head や grep にパイプすると CLI 自身の終了コードが失われます。

呼び出しごとのプロセス起動には、およそ 1.5～2 秒かかると見込んでください。読み取り専用の結果が複数必要な場合は、標準入力経由で 1 つのプロセスにまとめると、起動コストを分散できます。

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

この方法なら、2 つのコマンドを個別に呼び出した場合の 5.1～5.8 秒に対し、4.1～4.4 秒で実行できます。空行と # で始まる行は無視されるため、パイプで渡すスクリプトにコメントを含められます。パイプで渡したセッションはシェルセッションである点に注意してください。出力はバッチ形式ではなく、シェル経由の形式（camelCase、ラップされたオブジェクト）になります。

Windows では、bash が引用符で囲まれていない引数内のバックスラッシュを処理するため、Windows パスは必ずダブルクォートで囲んでください。例：--report-json="C:\reports\run.json"。

ルーティング：バッチ動詞とシェル経由の動詞

バッチコードパスが用意されている動詞は、periods、accounts、symbols、metadata、run、backtest の6つです。これは、--help でBATCHモード用として明示されている6つです。create と build は --help のBATCH MODEの参照セクションに記載されていますが、どの形式で呼び出してもコマンドシェル経由で実行されます。まずバナーが表示され、続いてcamelCaseのJSONペイロードが出力され、さらに -q を指定しない場合は対話型メニューに移行します。そのため、これらは -q を付けて呼び出してください。それ以外のすべての動詞は、コマンドシェル経由でのみ実行できます。

-q／--quick はルーティングフラグであり、静音フラグではありません。6つのバッチ動詞のいずれかに付けると、呼び出し全体がシェルパイプラインに切り替わります。これにより、ペイロードの大文字・小文字の形式が変わり、コマンド名のキーでラップされ、バナーとタイムスタンプヘッダーが先頭に追加され、受け付けるフラグも変わる場合があります。

動詞の分類	呼び出し方	ペイロード
バッチデータ（accounts、symbols、metadata）	-q なし	PascalCaseのJSON、バナーなし
バッチストリーミング（run、backtest）	-q なし	backtest：プレーンテキストの進行状況ログに続いて、最終的な簡潔なPascalCaseのJSONサマリー。run：停止するまでアルゴリズムの出力をストリーミング
スキャフォールディング（create、build）	-q あり	バナーとタイムスタンプヘッダーの後にcamelCaseのJSON
シェル経由（account、account-stats、symbol、sessions、price、prices、candles、orders、positions、order、position、exposure、orders-history、deals、alerts、alert、indicators、indicator）	-q あり	バナーの後に、コマンド名のキーでラップされたcamelCaseのJSON
periods	そのまま、フラグなし	プレーンテキスト、認証情報不要

初回呼び出しの前に把握しておくべき具体的な点：

• accounts -e は --account を受け付けませんが、symbols -e では必要です。この2つのバッチ動詞の仕様は意図的に異なります。
• バッチの symbols は各エントリに Id、Name、Description を返します。同じ動詞でも -q を付けると name、description、category、assetClass を返します。これはバッチのスキーマを拡張するのではなく、数値の Id を分類フィールドに置き換えます。そのため、シンボルIDが必要な場合はバッチの symbols を使用してください。
• periods はフラグを一切受け付けません。-e を渡すと Error: Parameter e is not allowed が返されます。
• シェル経由の動詞は、起動時に引数を明示的なフラグとして指定します。symbol --symbol=EURUSD は動作しますが、位置引数として EURUSD をそのまま渡しても動作しません。
• シェル経由の読み取りでは -q の指定を推奨しますが、必須ではありません。-q を付けると、ペイロードの後に表示されるコマンドメニューが省略されるため、解析時にstdoutを最小限に抑えられます。付けなくても、stdinをリダイレクトすれば呼び出しは正常に終了し、メニューが1回表示された後、終了コード0で Bye. が出力されます。
• 認識されない動詞はシェルメニューにルーティングされ、stdinが閉じられていれば終了コード0で終了します。そのため、「終了コード0」だけを、意図した動詞が実際に実行された証拠とみなさないでください。

ctrader-cli.exe --commands を実行すると、シェルコマンドの完全なリファレンスが表示されます。認証情報もネットワークも不要で、各動詞の正確な引数形式を確認する手軽な方法です。

認証情報

対話操作なしで使える認証情報の形式は2種類あります。シークレットがプロセス引数に一切含まれないため、最初の形式をおすすめします。

# 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 で別途選択します。パスワードファイルの1行目がパスワードです。フラグ名は --pwd-file で、短縮形はありません。--password は対話操作用であり、スクリプトからの呼び出しには含めないでください。

CTID や PWD-FILE の値を読み取ったり、出力したりしないでください。存在と長さだけを確認してください。また、PWD-FILE にはハイフンが含まれるため、$PWD-FILE では値が展開されないことに注意してください。

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

シェルのバナーは、標準出力に Connecting as <id>... として cTrader ID を出力します。出力を引用してレポートなど共有するものに含める際は、必ず伏せてください。

出力の読み取り

固定の行数やバイトオフセットではなく、構造に基づいてペイロードを見つけてください。タイムスタンプのヘッダー行、または最初に現れる対応の取れた { か [ を探します。一時的な接続再試行の行がペイロードより前に出力されても、ペイロードが正常に届くことがあります。

バッチのペイロードはバイト位置0から始まります。バナーもヘッダーもなく、フラットな PascalCase の JSON です。シェル経由のペイロードには、文言が一定しない数行のバナーが付き、その後にコマンドを反映した [yyyy-MM-dd HH:mm:ss <local numeric offset>] 形式のヘッダー行が続きます。さらに、{"orders": [...]} のように、コマンド名をキーとして camelCase の JSON がラップされます。このヘッダーの時刻は、マシン固有のタイムゾーンオフセットを伴うローカル時刻です。JSON 本文内のタイムスタンプとは異なり、こちらは末尾に Z が付く UTC です。

したがって、表記の大文字・小文字は動詞ではなくパイプラインによって決まります。accounts は Id と Balance を返しますが、orders は id と volumeLots を返します。特に注意が必要なのは backtest です。標準出力の簡潔なサマリーは PascalCase（Equity、NetProfit）ですが、--report-json で書き込まれるファイルは camelCase（main、equity、tradeStatistics）です。build にレポート用のフラグはありません。標準出力のペイロードは camelCase（projectPath、success、errors）です。

バッチ経由の呼び出しでは、成功時も失敗時も、CLI 自身によるコマンドラインのエコーが標準エラー出力に含まれます。そのため、標準エラー出力があるだけではエラーを意味しません。シェル経由の呼び出しでは、通常、標準エラー出力は空です。この違いがあるため、標準エラー出力はどちらのパイプラインを通ったかを判断する手掛かりとして扱い、成否の判定には決して使わないでください。

periods、--help、--commands、--version、確認メッセージや拒否メッセージ、Order #N not found. のような見つからない場合のメッセージは、JSON ではなくプレーンテキストを出力します。タイムスタンプヘッダーの規則が適用されるのは、シェル経由の JSON コマンドだけです。

Windows では改行コードは CRLF です。数値はプレーンな JSON 数値で、CLI 独自の書式設定によりすでに丸められており、ロケール依存の区切り文字は使われません。例外は、取引数が0のバックテストサマリーです。この場合、AverageTrade と ProfitFactor は単独の - トークンとして出力されるため、厳密な JSON パーサーでは拒否されます。

終了コードと失敗の検出

コード	意味
0	成功
1	使用方法が無効、認識されないフラグ、必須パラメーターの欠落、または検証エラー
81	cTrader ID またはパスワードが無効
82	アカウントが見つかりません
124	外部の timeout によってプロセスが終了しました

メッセージのテキストが主な検出シグナルで、終了コードは分岐のキーです。この表にないゼロ以外のコードは、ほかのエラー条件を示すために存在しますが、公開されていません。そのため、番号の意味を推測せず、メッセージを確認してください。ラッパーシェルは直接実行した場合と異なるコードを返すことがあるため、両者が食い違う場合はメッセージを優先してください。

終了コードだけで失敗を推測しないでください。build は、コンパイルが成功した場合も失敗した場合も 0 で終了します。判定の基準となるのは JSON 本文の success ブール値で、診断情報は errors: [{file, line, column, code, text}] に含まれます。backtest は要約の出力後も実行を続けるため、完了のシグナルは最終的な JSON 要約、または --report-json ファイルの出現です。これらの成果物が存在する場合、124 でも実行は完了しており、失敗ではありません。

数値フラグに数値以外の値を指定すると 1 で終了しますが、メッセージの形式はフラグとパイプラインによって異なります。バッチ経由でルーティングされる symbols で candles --count=abc を指定すると、Error: Option --count has invalid number: abc というエラー行が stdout にそのまま出力されます。一方、--account=abc を指定すると、バッチ経由でルーティングされる symbols では System.FormatException のトレースが表示され、orders のようなシェル経由でルーティングされる動詞では、Error: の接頭辞なしで Invalid account number: 'abc'. Expected a numeric login id. が stderr に出力されます。この種のエラーすべてに共通するストリームや接頭辞はないため、実行前に数値フラグの値を検証してください。

変更を伴うコマンド

状態を変更する動詞は、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 はシェル経由の読み取りでも通常使われるフラグであるため、慣れから付けてしまいやすい点に注意してください。変更を伴うコマンドに -q を付けるのは、ユーザーがその特定の操作を明示的に許可した後、かつ accounts の "Live": false を確認して対象アカウントがデモ口座であることを確かめた後に限ります。動作を確かめるために、変更を伴うコマンドを実行してはいけません。

フラグ形式の起動行では、適用される確認形式は -q です。--yes と -y は Refused: confirmation required を返し、終了コード 1 で終了します。末尾に単独で指定する yes はシェルプロンプトの構文です。これをフラグ形式の行に混在させると、終了コード 1 で ConsoleInvalidUsageException の使用法トレースを出力してプロセスが終了します。同様に、キーワード all はシェルプロンプトで使います。--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 を返します。

変更時のストップロスとテイクプロフィットには、値の指定方法が3通りあります。 値を指定すると置き換え、0 を指定すると削除し、フラグを省略すると現在の値が維持されます。価格は絶対値で指定してください。参照価格に対して不適切な側の価格は送信前に拒否され、終了コード 1 で2行のメッセージ（Warning: に続いて Error:）が表示されます。この場合、サーバーの状態は変更されません。

正確なフラグ名 --order=<id>、--position=<id>、--alert=<id> を使用してください。応答キーはコマンドごとに異なります。order place-limit は status: "placed" とともに orderId を返します（保留中の注文も同じ形式です。即時に約定する成行注文では status: "opened" とともに positionId が返されることを想定してください）。alert create は status: "created" とともに id を返し、alert delete は status: "deleted" とともに alertId を返します。呼び出したコマンドが返すキーを確認してください。

変更を行うたびに、orders、positions、または orders-history で対象のエンティティを再読み込みし、適用された状態を確認してから成功を報告してください。

セッションの事前確認

最初の認証済み呼び出しの前に、references/setup.md にある4段階の事前確認を実行してください。実行ファイルにアクセスできること、CTID と PWD-FILE の有無および長さのみを確認すること、パスワードファイルの妥当性を確認すること、そして accounts -e による単一の実行可否プローブを行うことです。結果は、JSON アカウント配列を伴う終了コード 0（準備完了）、終了コード 81（認証情報が拒否された）、終了コード 1 とパラメーター不足のメッセージ（迅速かつ明確な失敗であり、ハングはしません）の3通りです。このリファレンスには、設定の修正が必要なユーザーに伝える正確な文面も記載されています。

リファレンスファイル

• 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 - 失敗の一覧、メッセージ形式、復旧操作。