portfolio-hub/docs/technical/management-cli-operations.md

Management CLI Operations

• Related REQ: N/A

목표

portfoliohub CLI를 운영 자동화와 수동 점검 모두에 안전하게 사용할 수 있도록 명령 책임과 사용 규칙을 정의한다.

명령 그룹

그룹	주요 명령	목적
DB 운영	init-db, migrate-db, health-check	스키마 적용 및 연결 상태 점검
사용자 관리	user list/get/create/update/delete	운영 계정 라이프사이클
포트폴리오 조회	portfolio list, portfolio status	상태 확인
포트폴리오 변경	portfolio create/update/buy/sell/invest/transfer/reset/delete	거래/자금/상태 변경

인터페이스 명세

전역 옵션:

• --format [table|json] (기본값: table)

공통 명령:

• portfoliohub init-db [--maintenance-db postgres]
• portfoliohub migrate-db
• portfoliohub health-check

포트폴리오 하위 명령:

• portfoliohub portfolio list [--broker ...] [--status ...]
• portfoliohub portfolio status <portfolio_id> [--recent 5]
• portfoliohub portfolio create <portfolio_id> --symbol ... [--name ...] [options] [--force]
• portfoliohub portfolio update <portfolio_id> [options] [--force]
• portfoliohub portfolio buy <portfolio_id> --quantity ... --price ... [options] [--force]
• portfoliohub portfolio sell <portfolio_id> --quantity ... --price ... [options] [--force]
• portfoliohub portfolio invest <portfolio_id> --type <deposit|profit|withdraw> --amount ... [options] [--force]
• portfoliohub portfolio transfer <portfolio_id> --direction <to-buffer|from-buffer> --amount ... [options] [--force]
• portfoliohub portfolio reset <portfolio_id> [--infer-symbol ...] [--force]
• portfoliohub portfolio delete <portfolio_id> [--keep-ledger] [--force]

포트폴리오 댓글 하위 명령:

• portfoliohub portfolio comment add <portfolio_id> --content <text>
• portfoliohub portfolio comment list <portfolio_id>
• portfoliohub portfolio comment update <portfolio_id> <comment_id> --content <text> [--force]
• portfoliohub portfolio comment delete <portfolio_id> <comment_id> [--force]

전략셋 하위 명령:

• portfoliohub strategy list
• portfoliohub strategy create --name ... --config ...
• portfoliohub strategy update <strategy_set_id> [--name ...] [--config ...]
• portfoliohub strategy delete <strategy_set_id> [--force]

실행 원칙

• 쓰기 명령은 기본적으로 확인 프롬프트를 띄운다.
• 자동화 스크립트에서는 --force를 사용해 비대화식 실행을 보장한다.
• DB 타깃 실행 시 PORTFOLIOHUB_DB_ENABLED=true와 TIMESCALEDB_*를 명시한다.

예시 시나리오

1. 신규 환경 준비
   • portfoliohub init-db
   • portfoliohub health-check
2. 일상 운영
   • portfoliohub portfolio list
   • portfoliohub portfolio status <portfolio_id>
3. 배포 후 검증
   • portfoliohub user list
   • 주요 API smoke test와 결과 비교

오류/종료코드 가이드

• 0: 정상 종료
• 1: 입력/검증/런타임 오류
• 재시도 가능 오류(예: 일시적 DB 연결 실패)는 메시지에 원인을 명확히 표기한다.

확인 동작:

• 변경 명령은 기본적으로 확인 프롬프트를 요청한다.
• --force를 지정하면 확인 프롬프트를 생략한다.

Open Implementation Points

• JSON 출력 모드(--json)를 도입해 자동화 친화성을 높일지 결정한다.
• 대량 작업(batch) 명령 추가 시 실패 항목 보고 포맷을 표준화한다.