PyQQQ CLI 사용하기

pyqqq-cli는 PyQQQ 플랫폼에서 배포된 전략을 제어하기 위한 명령줄 도구입니다. 전략 배포, 로그 조회, 크론잡 설정 등 플랫폼의 주요 기능을 터미널에서 바로 사용할 수 있습니다.

PyPI 페이지에서 자세한 정보를 확인할 수 있습니다.

설치 및 설정

Python 3.11 이상이 필요합니다. pip로 설치합니다.

$ pip install pyqqq-cli

설치 후 PyQQQ에서 발급받은 API Key를 ~/.qred 파일에 저장합니다.

$ echo "YOUR_API_KEY" > ~/.qred

설치와 인증이 완료되면 아래 명령으로 확인합니다.

$ qqq version

Tip

qqq 명령어 --help를 사용하면 각 명령어의 도움말을 볼 수 있습니다.

전략 배포

간단한 전략 파일을 작성하고 배포하는 기본 흐름을 살펴봅니다.

# sample.py
import asyncio
import datetime as dtm

async def run():
    while True:
        print(dtm.datetime.now().strftime('%Y-%m-%d %H:%M:%S'), "Hello World!")
        await asyncio.sleep(1)

배포

$ qqq deploy sample.py

배포 이름은 기본적으로 파일명(확장자 제외)이 사용됩니다. --name 옵션으로 변경할 수 있습니다.

$ qqq deploy sample.py --name my-strategy

목록 확인

$ qqq list

DEPLOYMENT ID

STATUS

TYPE

SCHEDULE

CREATED AT

xpzn74qvwpo0wide4jfm64yfxfj9-sample

Running

Strategy

2025-01-13 13:54:34

xpzn74qvwpo0wide4jfm64yfxfj9-cron

Scheduled

Cronjob

0 9 * * 1-5

2025-01-14 09:00:00

  • STATUS: Running / Scheduled / Paused / Initializing / Error / CrashLoopBackOff

  • TYPE: Strategy / Cronjob / Backtest

  • SCHEDULE: 크론잡인 경우 cron 표현식이 표시됩니다.

로그 조회

$ qqq logs xpzn74qvwpo0wide4jfm64yfxfj9-sample -f   # 실시간 스트리밍
$ qqq logs xpzn74qvwpo0wide4jfm64yfxfj9-sample -n 100  # 최근 100줄

일시 정지 / 재개

$ qqq pause  xpzn74qvwpo0wide4jfm64yfxfj9-sample
$ qqq resume xpzn74qvwpo0wide4jfm64yfxfj9-sample

환경 변수 확인 및 업데이트

$ qqq env xpzn74qvwpo0wide4jfm64yfxfj9-sample           # 환경 변수 조회
$ qqq env xpzn74qvwpo0wide4jfm64yfxfj9-sample --pretty  # JSON 형태 출력
$ qqq update xpzn74qvwpo0wide4jfm64yfxfj9-sample        # 환경 변수 반영 후 재시작

삭제

$ qqq delete xpzn74qvwpo0wide4jfm64yfxfj9-sample

Warning

삭제된 전략은 복구할 수 없습니다.

크론잡 배포

전략을 주기적으로 자동 실행하는 크론잡으로 배포합니다. --schedule에 cron 표현식을 지정하며, 최소 실행 간격은 5분입니다.

$ qqq cronjob sample.py --schedule "0 9 * * 1-5"           # 평일 오전 9시 실행
$ qqq cronjob sample.py --name my-job --schedule "*/30 * * * *"  # 30분마다 실행

로그는 일반 전략과 동일하게 qqq logs로 조회합니다.

백테스트 배포

전략을 1회성 백테스트 작업으로 배포합니다. 전략 파일에 run_batch() 함수가 정의되어 있어야 하며, 이름은 24자 이하로 설정해야 합니다.

$ qqq backtest sample.py
$ qqq backtest sample.py --name my-backtest
$ qqq backtest sample.py --env-file .env.backtest

옵션

설명

--name, -n

백테스트 이름 지정 (지정 시 이름 입력 프롬프트 생략)

--skip, -s

이름 입력 프롬프트 생략

--env-file, -e

백테스트에 사용할 환경 변수 파일 경로

전략 공개 레지스트리

공개 레지스트리를 통해 전략을 다른 사용자와 공유하거나 다운로드할 수 있습니다.

검색 및 다운로드

$ qqq search momentum                        # 키워드 검색
$ qqq search --email user@example.com        # 특정 사용자의 전략 검색
$ qqq pull user@example.com/my-strategy      # 현재 디렉토리로 다운로드

공개 등록

$ qqq publish sample.py
$ qqq publish sample.py --name my-strategy
$ qqq deploy sample.py --publish             # 배포와 공개 등록 동시 진행
$ qqq list --published                       # 공개된 내 전략 목록 확인

로컬 실행 및 린트

클라우드 배포 없이 로컬 환경에서 전략을 바로 실행하거나 문법을 검사합니다.

$ qqq run sample.py            # 현재 Python 환경에서 실행 (requirements.txt 자동 설치)
$ qqq lint sample.py           # 문법 오류 검사
$ qqq lint sample.py --skip-test

OPENAI_KEY 환경 변수가 설정된 경우 lint 실행 시 AI를 활용한 추가 분석도 수행됩니다.