CI와 헤드리스 서버에서 Sume CLI 실행하기

CI나 헤드리스 서버에서 Sume CLI를 실행하려면 버전을 고정한 릴리스 바이너리를 설치하고, CI 시크릿 저장소의 API 키를 SUME_API_KEY나 sume auth setup --api-key로 넘기고, SUME_CONFIG_DIR로 CI 작업 전용 디렉터리를 지정하고, 사전 점검으로 sume doctor --agent --json을 실행하고, 모든 결과를 --json으로 읽으세요.

이 단계는 CLI 문서의 설정, 인증, 설치와 업데이트, 보안 페이지를 바탕으로 하며, 2026-09-26에 확인했습니다. CLI는 여전히 동작하지만, 문서에 따르면 현재 주 경로는 아닙니다. 로컬 셸과 스크립트를 위한 것이지 기본 연동 경로가 아닙니다. 대화형 설치와 로그인은 CLI 튜토리얼에서 다룹니다.

CI에서 Sume CLI 버전은 어떻게 고정하나요?

호스팅 인스톨러는 최신 sumelabs/cli GitHub Release를 확인하므로, 이를 실행하는 파이프라인은 빌드 사이에 새 버전을 받게 될 수 있습니다. 버전을 고정해 설치하려면 설치와 업데이트에 있는 직접 내려받기 대체 경로를 쓰고, 그 다운로드 URL의 latest를 특정 릴리스 태그로 바꾸세요. 각 GitHub Release에는 checksums.txt가 첨부됩니다.

• 릴리스 에셋은 sume-darwin-arm64, sume-darwin-x64, sume-linux-arm64, sume-linux-x64, sume-windows-x64.exe입니다.
• 설치는 sume version으로 확인하세요. sume update --check는 로컬 파일을 바꾸지 않고 더 새로운 릴리스가 있는지 알려 주므로, 아무것도 업그레이드하지 않고 버전 드리프트를 감지할 수 있습니다.

CLI는 브라우저 없이 어떻게 인증하나요?

API 키를 쓰세요. 설치 문서는 CI와 통제된 서버 환경을 위해 수동 API 키 설정을 그대로 지원합니다. API Keys 대시보드에서 발급한 키를 CI 시크릿 저장소에 저장하고 CI 작업에 SUME_API_KEY로 노출하거나, 설정 단계에서 sume auth setup --api-key "$SUME_API_KEY"를 실행하세요.

sume login은 기기 승인 페이지에서 요청이 승인될 때까지 기다리므로 무인 작업에는 맞지 않습니다. sume login --no-browser는 브라우저를 여는 대신 승인 URL만 출력하므로, 로그인해 있는 원격 머신에서 유용합니다. 이 대화형 플로는 CLI 튜토리얼에서 다룹니다.

CI 작업의 설정은 어떻게 격리하나요?

CLI는 기본적으로 로컬 설정을 ~/.sume-com/config.json에 저장합니다. SUME_CONFIG_DIR 값을 해당 CI 작업이 소유한 디렉터리로 설정해, 병렬 작업이나 공유 러너가 설정 파일 하나를 함께 쓰지 않게 하세요. SUME_API_KEY, 설정 파일, 원본 프로바이더 페이로드는 절대 출력하거나 커밋하지 마세요.

# SUME_API_KEY is injected by the CI secret store
export SUME_CONFIG_DIR="$(mktemp -d)"
export SUME_API_BASE_URL="https://api.sume.com/v1"

sume version
sume doctor --agent --json
sume account get --json

CI 작업은 크레딧을 쓰기 전에 무엇을 확인해야 하나요?

문제 해결 페이지에 나온 읽기 전용 점검부터 시작하세요. sume version, sume auth status, sume doctor --agent --json, sume account get --json입니다. doctor는 API를 호출하지 않고 로컬 준비 상태를 확인하고, account get은 설정된 키의 계정 컨텍스트를 읽습니다.

쓰기 명령어에는 확인 플래그가 필요하므로 파이프라인이 직접 넘겨야 합니다. Job 취소처럼 유료가 아닌 쓰기에는 --confirm-submit을, 크레딧을 예약하거나 쓸 수 있는 Avatar와 Avatar Video 실행에는 --confirm-paid를 넘기세요. 문서가 에이전트에게 주는 조언은 파이프라인에도 들어맞습니다. 테스트할 때는 범위가 제한된 Job 하나를 먼저 제출하고, 유료 명령어를 재시도하지 말고 기존 Job을 복구하세요.

파이프라인에서 CLI 출력은 어떻게 읽나요?

기계가 읽을 수 있는 안정적인 출력이 필요하면 --json을 붙이고, 로그에 민감한 URL이나 계정 메타데이터가 담길 수 있다면 --agent도 붙이세요. --agent는 지원되는 곳에서 URL 형태의 필드와 계정·워크스페이스 필드를 가립니다.

• sume tools list --json과 sume tools schema <name> --json은 런타임에 정확한 스키마를 확인하므로, CI 작업이 유료 단계 전에 페이로드를 검증할 수 있습니다.
• CI 단계가 재시작되거나 로컬 대기가 타임아웃되면, 유료 생성을 다시 제출하지 말고 sume jobs status와 sume jobs result로 ID를 지정해 Job을 복구하세요. sume jobs download <job_id> --output-dir ./out은 완료된 미디어 산출물을 로컬 디렉터리에 씁니다.
• 결과에는 자사 미디어 URL이 포함될 수 있으며, 이 URL은 공개돼 있지만 여전히 사용자 데이터입니다. CI 작업이 결과를 보고할 때는 원본 페이로드를 그대로 쏟아내지 말고 미디어 개수와 파일 형식을 요약하고 쿼리 문자열을 가리세요.

파이프라인에서 CLI로 할 수 없는 일은 무엇인가요?

sume image, sume video, sume music 서브커맨드는 없습니다. CLI 문서는 이런 Job을 HTTP로 Image 1.0, Video 1.0, Music 1.0에 보내라고 안내하지만, Image 1.0과 Video 1.0은 곧 은퇴하고 Music 1.0은 점진적으로 은퇴합니다. 새 연동은 마이그레이션 가이드처럼 sume/auto로 POST /v1/images나 POST /v1/videos를 쓰거나, 음악에는 POST /v1/music-router/generate를 쓰며, 이런 Job도 여전히 sume jobs로 복구할 수 있습니다.

스케줄에도 CLI 명령어가 없습니다. CI에서 스케줄 실행을 시작하려면 POST /v1/actions/{action_id}/runs를 HTTP로 호출하세요. 전체 명령어 목록은 Sume CLI 명령어 레퍼런스를 참고하세요.