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를 실행하면 허용되는 모든 식별자를 나열할 수 있습니다. 식별자는 분, 시간, 일, 주, 월뿐 아니라 틱, 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는 해당 날짜의 23:59:59 UTC까지 하루 전체를 포함합니다.
  • candles에서 --to는 해당 날짜의 시작 시각(00:00 UTC)을 의미합니다. 특정 날짜 전체를 포함하려면 --to를 다음 날로 설정하세요.
  • --from / --to를 지정하지 않으면 대화형 backtest는 최근 7일을 대상으로 합니다.
• 일괄 처리 명령어(backtest 등): 날짜 형식은 dd/MM/yyyy이며, 필요하면 dd/MM/yyyy HH:mm 형식으로 24시간제 시간을 추가할 수 있습니다. 예: 31/12/2026 18:00. 모두 UTC 기준입니다.

유일한 예외는 실행 중인 cBot(run, backtest)입니다. 해당 cBot의 시간은 cTrader Algo와 마찬가지로 cBot에 설정된 TimeZone을 따릅니다.

계정 및 시장 데이터 조회 ¶

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

스크립트에서 심벌의 현재 가격을 조회하고 과거 캔들 데이터를 가져오세요:

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이면 해당 기간에 체결 내역이 더 있을 수 있습니다.

대화형 셸의 일괄 작업 ¶

대화형 셸에서는 일부 명령어 끝에 all과 yes를 추가하면 확인 메시지 없이 일괄 작업을 수행할 수 있습니다.

대화형으로 명령어 실행 ¶

대화형 셸을 열려면 명령어 없이 ctrader-cli를 실행하세요. 메시지가 나타나면 cTID와 비밀번호로 로그인한 후, 인증 정보를 다시 입력하지 않고 명령어를 연속으로 입력하세요. 여러 명령어를 연달아 실행할 때 편리합니다.

명령어 하나만 실행하고 즉시 종료하려면 -q를 추가하세요. 명령어가 완료되자마자 프로세스를 종료해야 하는 스크립트에 유용합니다.

CLI에서 지원하는 기능을 확인하는 데 도움이 되는 옵션이 두 가지 있습니다.

cTrader ID에 연결된 서로 다른 브로커의 계정이 동일한 계정 번호를 사용하는 경우, --broker=<broker-name>을 추가해 계정을 명확히 지정하세요.

일반적인 오류 ¶