메인 콘텐츠로 건너뛰기

CLI 빠른 시작

SprintX CLI 설치부터 sx auth, 프로젝트 선택, 첫 event와 artifact 기록, 그리고 sx status / sx brief 확인까지 한 번에 정리한 가이드

이 문서는 SprintX 최소 연결 가이드입니다.

한 줄로 요약하면, CLI를 설치하고 sx auth로 계정을 연결한 뒤 sx project use로 프로젝트를 고르고, sx event 1건과 sx artifact add 1건을 남긴 다음 sx status, sx brief로 상태를 바로 확인하는 흐름입니다.

CLI 설치

CLI 패키지 이름은 @sprint-x/cli이며, 설치 후 sx 바이너리를 사용합니다.

npm install -g @sprint-x/cli
sx --help

런타임이 이미 설치를 대신 관리한다면 바로 sx auth부터 진행하면 됩니다.

1. sx auth로 CLI 연결

sx auth는 로컬 CLI 설치를 현재 로그인된 SprintX 계정에 연결합니다.

sx auth

동작 순서:

  1. CLI가 SprintX 승인 URL을 요청합니다.
  2. interactive 모드에서는 브라우저를 자동으로 엽니다.
  3. 승인이 끝나면 이후 명령에 쓸 로컬 세션을 저장합니다.

중요한 경계:

  • sx auth는 SprintX 계정 세션용입니다.
  • Anthropic, OpenAI 같은 provider key는 /settings에서 별도로 관리합니다.

2. sx project use로 현재 프로젝트 선택

handoff entry card에서 project UUID를 이미 알고 있다면 바로 선택하면 됩니다.

sx project use 11111111-1111-4111-8111-111111111111

성공 시 출력에는 보통 아래 값이 포함됩니다.

  • project_id
  • receipt_id

프로젝트 UUID를 아직 모를 때만 sx project list를 먼저 실행하세요. 이 명령은 접근 가능한 프로젝트 ID와 이름을 출력하고, 현재 선택된 프로젝트는 *로 표시합니다.

sx project list
# * 11111111-1111-4111-8111-111111111111	현재 프로젝트
#   22222222-2222-4222-8222-222222222222	공유 프로젝트

한 번 프로젝트 문맥을 고르면 이후 event, artifact, status, brief 명령에서 재사용할 수 있습니다.

이 명령이 특히 유용한 경우:

  • CLI 안에서 대상 프로젝트 UUID를 바로 찾아야 할 때
  • 하나의 런타임이 주로 하나의 프로젝트에서 일할 때
  • 매번 --project를 넘기지 않고 기본 문맥을 저장하고 싶을 때

3. sx event로 첫 실행 신호 보내기

sx event는 프로젝트 문맥에 연결된 실행 이벤트를 SprintX로 전송합니다.

sx event \
  --type runtime.started \
  --summary "Initial OpenClaw handoff started" \
  --metadata '{"source":"openclaw","taskId":"task_123"}'

주요 옵션:

  • --type 필수 event type
  • --summary 사람이 읽기 쉬운 짧은 설명
  • --metadata JSON payload
  • --project 일회성 project override
  • --runtime-instance-id audit에 남길 runtime 식별자

알아둘 점:

  • idempotency key는 CLI가 자동 생성합니다.
  • 저장된 프로젝트 선택 정보가 없거나 어긋나면 CLI가 프로젝트를 다시 맞춘 뒤 재시도합니다.

4. sx artifact add로 첫 artifact receipt 남기기

sx artifact add는 SprintX에 artifact reference를 기록합니다.

sx artifact add \
  --title "build-log" \
  --reference-uri "file:///tmp/build.log" \
  --content-type "text/plain" \
  --summary "First build output" \
  --metadata '{"kind":"log"}'

주요 옵션:

  • --title 필수 artifact 제목
  • --reference-uri 필수 reference URI
  • --content-type 필수 content type
  • --summary 짧은 설명
  • --metadata JSON payload
  • --project 일회성 project override

기존 upload도 alias로 계속 동작합니다.

sx artifact upload --title "build-log" --reference-uri "file:///tmp/build.log" --content-type "text/plain"

5. sx status, sx brief로 SprintX가 읽는 상태 확인

event와 artifact가 accepted 되면 곧바로 확인 명령을 실행하세요.

sx status
sx brief

정상 연결이라면 보통 아래가 보여야 합니다.

  • sx status는 project name, task totals, active sprint, active runs, member count를 출력합니다
  • sx brief는 project name, open task count, active run count, recent tasks를 출력합니다
  • sx project use가 이미 성공했다면 project id를 다시 넘기지 않아도 됩니다

즉, 이 두 명령은 "OpenClaw가 붙었다"를 터미널에서 가장 싸게 다시 확인하는 방법입니다.

Headless / CI 사용법

브라우저를 직접 열면 안 되는 환경에서는 headless 모드를 사용합니다.

sx --headless auth

headless 모드에서는:

  • 승인 URL을 stdout으로 출력하고
  • 색상과 spinner를 끄며
  • 올바른 SprintX 세션이 있는 브라우저에서 URL을 직접 열 수 있습니다

다음 조건 중 하나면 CLI는 headless 환경도 자동 감지합니다.

  • stdout이 TTY가 아님
  • CI가 truthy
  • GITHUB_ACTIONS가 truthy
  • OPENCLAW_SESSION이 truthy

완전 비대화형 환경에서는 access token을 직접 주입해 browser auth를 건너뛸 수 있습니다.

export SX_ACCESS_TOKEN="<access-token>"
export SX_PROJECT_ID="proj_123"

sx event --type runtime.started --summary "CI handoff started"
sx artifact add --title "ci-log" --reference-uri "https://example.com/logs/1" --content-type "text/plain"

환경 변수

현재 CLI에서 문서화된 환경 변수는 아래와 같습니다.

변수역할
SX_API_URLSprintX API base URL override. 기본값: https://www.sprintx.co.kr
SX_ACCESS_TOKENdirect access token override. 값이 있으면 sx auth가 browser auth를 건너뜁니다
SX_PROJECT_IDsx event, sx artifact add용 기본 프로젝트
SX_LANG언어 override. ko를 주면 한국어 CLI copy를 강제합니다
CIheadless 자동 감지에 사용
GITHUB_ACTIONSheadless 자동 감지에 사용
OPENCLAW_SESSIONheadless 자동 감지에 사용

최소 연결 체크리스트

  • CLI 설치 완료, sx 명령 사용 가능
  • sx auth 완료
  • sx project use <projectId> 완료
  • 첫 sx event accepted
  • 첫 sx artifact add accepted
  • sx status, sx brief가 기대한 프로젝트 문맥을 그대로 읽어줌

다음 문서