rorkai/App-Store-Connect-CLI

App Store Connect API를 위한 빠르고 가볍고 스크립트 작성이 가능한 CLI입니다. 터미널, IDE 또는 CI/CD 파이프라인에서 iOS, macOS, tvOS 및 visionOS 출시 워크플로 (workflows)를 자동화하세요.

• asc skills
• 후원자 (Sponsors)
• 빠른 시작 (Quick Start)
• 문제 해결 (Troubleshooting)
• 개인정보 보호 및 텔레메트리 (Privacy and telemetry)
• 지원 (Support)
• 앱 목록 (Wall of Apps)
• 일반적인 워크플로 (Common Workflows)
• 명령어 및 참조 (Commands and Reference)
• 문서 (Documentation)
• 기여하기 (Contributing)
• 라이선스 (License)

빌드, TestFlight, 메타데이터 동기화 (metadata sync), 제출 (submissions) 및 서명 (signing)을 포함한 워크플로 (workflows)를 자동화하기 위한 에이전트 기술 (Agent Skills):

모든 프로젝트에서 사용할 수 있도록 전역적으로 설치하세요:

asc install-skills

직접 설치:

npx skills add rorkai/app-store-connect-cli-skills --global --agent codex

인증 (authentication)을 설정하기 전에 바이너리 (binary)가 작동하는지 확인하려면:

asc version
asc --help

# Homebrew (권장)
brew install asc
# 설치 스크립트 (macOS/Linux)
...

# Windows (WinGet, 패키지 승인 후)
winget install asc
# 스크립팅 시 정확한 대체 방법
...

WinGet 패키지는 GitHub Discussion #1552에서 추적됩니다. winget search asc에 나타나기 전까지 Windows 사용자는 GitHub releases 페이지에서 서명된 릴리스 바이너리 (release binaries)를 직접 다운로드할 수 있습니다.

소스 빌드 및 기여자 설정을 보려면 CONTRIBUTING.md를 참조하세요.

asc auth login \
--name "MyApp" \
--key-id "ABC123" \
...

API 키는 다음에서 생성하세요: https://appstoreconnect.apple.com/access/integrations/api

CI, 헤드리스 셸 (headless shell), 또는 키체인 (keychain) 접근이 불가능한 머신에서 실행하는 경우, 대신 설정 기반 인증 (config-backed auth)을 사용하세요:

asc auth login \
--bypass-keychain \
--name "MyCIKey" \
...

asc auth status --validate
asc auth doctor

asc apps list --output table
asc apps list --output json --pretty

asc는 stdout이 연결된 위치에 따라 기본 --output을 선택합니다:

• 대화형 터미널 (Interactive terminal, TTY):
  table

• 비대화형 출력 (Non-interactive output, 파이프/파일/CI):
  json

여전히 전역 기본 설정을 설정할 수 있습니다:

export ASC_DEFAULT_OUTPUT=markdown

그리고 명시적인 플래그 (flags)가 항상 우선합니다:

asc apps list --output json

asc는 가시적인 라이프사이클 라벨 (lifecycle labels)을 사용하여, CI 또는 스크립트에서 명령어를 사용하기 전에 지원 기대치를 판단할 수 있도록 합니다:

• 라벨 없음: 일반적인 사용을 위한 안정적인 공개 CLI 계약 (stable public CLI contract)

• [experimental]: 유용하지만 여전히 발전 중임; 더 날카로운 모서리(sharper edges)와 빠른 반복 (iteration)을 예상하십시오.

• DEPRECATED: 또는 지원 중단 경고 (deprecation warnings): 마이그레이션 기간 동안 호환성 경로는 유지되지만, 장기적인 거처는 아님

• 먼저 Homebrew를 새로고침하십시오:
  brew update && brew upgrade asc

• 실행 중인 바이너리 (binary)를 확인하십시오:
  which asc

• 설치된 버전을 확인하십시오:
  asc version

• 만약 Homebrew가 최신 GitHub 릴리스보다 뒤처져 있다면, 다음의 설치 스크립트를 사용하십시오:
  https://asccli.sh/install

• 먼저 WinGet 소스를 새로고침하십시오:
  winget source update

• 사용 가능해지면 짧은 설치 명령을 선호하십시오:
  winget install asc

• 만약 짧은 이름이 모호해질 경우, 패키지 식별자 (package identifier)를 사용하십시오:
  winget install --id Rorkai.ASC --exact

• 설치된 명령어가 정상적으로 해결되는지 확인하십시오:
  Get-Command asc

그리고 asc version

• 활성 프로필 (active profile)을 검증하십시오:
  asc auth status --validate

• 인증 상태 점검 (auth health check)을 실행하십시오:
  asc auth doctor

• 만약 키체인 (keychain) 접근이 차단된다면, 다음을 사용하여 재시도하십시오:
  ASC_BYPASS_KEYCHAIN=1

또는 asc auth login --bypass-keychain을 다시 실행하십시오.

• ./.asc/config.json에 저장소 로컬 자격 증명 (repo-local credentials)을 두고 싶을 때는 다음을 사용하십시오:
  asc auth login --local --bypass-keychain ...

asc는 대화형 터미널에서는 기본값으로 table을 사용하며, 파이프 (pipes), 파일, 그리고 CI에서는 json을 사용합니다. 스크립팅을 하거나 재현 단계 (repro steps)를 공유할 때는 명시적인 포맷을 사용하십시오:
--output json
, --output table
, 또는 --output markdown

• 터미널이나 버그 리포트에서 읽기 쉬운 출력을 원할 경우 JSON과 함께 --pretty를 사용하십시오.
• ASC_DEFAULT_OUTPUT으로 개인 기본값을 설정할 수 있지만, --output이 항상 우선한다는 점을 기억하십시오.

asc

기본적으로 가명화된 명령 수준의 사용량 텔레메트리 (telemetry)를 전송하여, 유지 관리자가 어떤 명령이 사용되는지, 그리고 신뢰성 작업이 어디에 필요한지를 이해할 수 있도록 돕습니다. 로컬 이벤트에는 무작위 설치 ID가 포함되어 시간이 지나도 하나의 설치에서 발생한 이벤트들을 그룹화할 수 있게 합니다. 이는 Apple 계정이나 기기 식별자로부터 유도되지 않습니다.

텔레메트리 (telemetry)에는 CLI 버전, 운영 체제 및 아키텍처, 등록된 명령 경로, 실행 시간 및 종료 결과, 런타임 컨텍스트 (runtime context), 호출 소스, 그리고 무작위 이벤트 및 세션 ID가 포함됩니다. 여기에는 원시 인자 (raw arguments) 또는 플래그 값, 자격 증명 (credentials), 개인 키, Apple 계정, 팀 또는 발행자 ID (issuer IDs), 앱 또는 번들 ID (bundle IDs), API 응답, 사용자 이름, 호스트 이름, 리포지토리 이름 또는 파일 경로가 포함되지 않습니다.

언제든지 텔레메트리 (telemetry)를 검토하거나 변경할 수 있습니다:

asc telemetry status
asc telemetry disable
asc telemetry reset-id

ASC_TELEMETRY_DISABLED=1 및 DO_NOT_TRACK=1 또한 텔레메트리 (telemetry)를 비활성화합니다. 정확한 이벤트 페이로드 (event payload), 런타임 처리, 수집기 엔드포인트 (collector endpoint) 및 모든 제어 사항은 텔레메트리 (telemetry) 참조 문서를 확인하십시오.

• 설치 도움말, 인증 설정, 워크플로 조언 및 "어떻게 ... 하나요?" 질문은 GitHub Discussions를 사용하십시오.
• 재현 가능한 버그 및 구체적인 기능 요청은 GitHub Issues를 사용하십시오.
• 지원 정책 및 버그 보고 체크리스트는 SUPPORT.md를 참조하십시오.
• 인증 또는 API 버그를 보고하기 전에 ASC_BYPASS_KEYCHAIN=1로 다시 시도해 보십시오.

; 안전한 경우, ASC_DEBUG=api asc ... 또는 asc --api-debug ...의 편집된(redacted) 출력 내용을 포함해 주세요.

본인의 앱을 추가하고 싶으신가요?
asc apps wall submit --app "1234567890" --confirm

이 명령은 인증된 gh 세션을 사용하여 리포지토리를 포크 (fork)하고 docs/wall-of-apps.json을 업데이트하는 풀 리퀘스트 (pull request)를 생성합니다.
앱 ID로부터 공개 App Store 이름, URL 및 아이콘을 자동으로 찾아냅니다. 아직 공개 App Store에 등록되지 않은 수동 항목의 경우 --name과 함께 --link를 사용하십시오.
무언가를 생성하기 전에 포크 (fork), 브랜치 (branch) 및 PR 계획을 미리 보려면 asc apps wall submit --dry-run을 사용하십시오.

asc testflight feedback list --app "123456789" --paginate
asc testflight crashes list --app "123456789" --sort -createdDate --limit 10
asc testflight crashes log --submission-id "SUBMISSION_ID"

asc builds upload --app "123456789" --ipa "/path/to/MyApp.ipa"
asc builds list --app "123456789" --output table
asc testflight groups list --app "123456789" --output table

macOS TestFlight 배포의 경우, 먼저 내보낸 .pkg 파일을 업로드한 다음,
처리된 빌드를 베타 그룹에 추가하십시오:

asc builds upload --app "123456789" --pkg "./build/MyMacApp.pkg" --version "1.2.3" --build-number "42" --wait --output json
asc builds add-groups --app "123456789" --build-number "42" --version "1.2.3" --platform MAC_OS --group "Internal Testers"

--app은 App Store Connect 앱 ID입니다. 만약 --archive-path와 같은 로컬 Xcode 빌드 플래그를 사용한다면, 반드시 --workspace 또는 --project 중 하나와 + --scheme을 함께 전달해야 합니다. 그렇지 않다면 미리 내보낸 .ipa 또는 .pkg 업로드를 사용하십시오. 외부 TestFlight 그룹에 배포하여 베타 앱 검토 제출이 필요한 경우, asc builds add-groups에 --submit --confirm을 추가하십시오.

# 선택 사항: 제출 전 스테이징 계획 미리 보기
asc release stage --app "123456789" --version "1.2.3" --build "BUILD_ID" --copy-metadata-from "1.2.2" --dry-run
# 표준 업로드 + 첨부 + 제출 명령어
...

낮은 수준의 제출 수명 주기 명령어 (디버깅 또는 부분 워크플로우용):

# 표준 준비 상태 확인
asc validate --app "123456789" --version "1.2.3"
asc submit status --version-id "VERSION_ID"
...

asc review status --app "123456789"
asc review doctor --app "123456789"

asc localizations list --app "123456789" --type app-info
asc metadata init --dir "./metadata" --version "1.2.3" --locale "en-US"
asc metadata apply --app "123456789" --version "1.2.3" --dir "./metadata" --dry-run
...

sync 또는 apply 전에 asc metadata keywords audit를 사용하십시오.

여러 로케일(locales)에 걸친 라이브 키워드 메타데이터(keyword metadata)를 ASO(App Store Optimization) 관점에서 검토하고 싶을 때 사용합니다. 이 명령은 중복된 구절, 로케일 간 반복되는 용어, 현지화된 앱 이름 또는 부제목과의 중복, 바이트 예산(byte-budget) 사용량, 그리고 --blocked-term 플래그나 텍스트 파일을 통해 지정된 선택적 차단 용어(blocked terms)를 보고합니다.

asc screenshots plan --app "123456789" --version "1.2.3" --review-output-dir "./screenshots/review"
asc screenshots apply --app "123456789" --version "1.2.3" --review-output-dir "./screenshots/review" --confirm
asc screenshots list --version-localization "VERSION_LOCALIZATION_ID"
...

단일 로케일에 대한 스크린샷 업로드:

asc apps list
asc versions list --app "APP_ID"
asc localizations list --version "VERSION_ID" --output json --locale "en-US" | jsonpp
...

VERSION_LOCALIZATION_ID는 attributes.locale의 로케일 코드가 아니라, data[].id에서 가져온 App Store 버전 현지화 리소스 ID(version localization resource ID)입니다.

asc certificates list
asc profiles list
asc bundle-ids list

asc workflow validate
asc workflow run --dry-run testflight_beta VERSION:1.2.3

asc builds next-build-number, asc xcode inject, asc xcode archive, asc xcode export --timeout 10m, 그리고 asc publish testflight --group ... --wait를 사용하는 복사 가능한 .asc/deployment.json, .asc/workflow.json, ExportOptions.plist 파일은 docs/WORKFLOWS.md를 참조하십시오. 베타 앱 심사 제출(beta app review submission)이 필요한 외부 TestFlight 그룹에 배포할 때는 --submit --confirm을 추가하십시오.

asc workflow validate
asc xcode inject --manifest .asc/deployment.json --set version=1.2.3 --set build_number=42 --dry-run --output json
asc workflow run --dry-run testflight_beta VERSION:1.2.3
...

# 풀 리퀘스트(pull request)로부터 트리거
asc xcode-cloud run --workflow-id "WORKFLOW_ID" --pull-request-id "PR_ID"
# 클린 빌드(clean build)를 사용하여 기존 빌드 실행에서 재실행
...

Apple Ads는 App Store Connect와는 별도의 OAuth 인증 정보(credentials)를 사용합니다:

asc ads auth login --name "Marketing" --client-id "SEARCHADS_CLIENT_ID" --team-id "SEARCHADS_TEAM_ID" --key-id "KEY_ID" --private-key ./ads-key.pem --org "123456"
asc ads auth discover --output json
asc ads campaigns --org "123456" --limit 100 --output json
...

자격 증명(credential) 보안, 조직 조사(org inspection), 읽기 전용 스모크 테스트(smoke tests), 리포팅(reporting), 원시 API(raw API) 사용 및 보호된 변이(guarded mutations)를 다루는 운영 플레이북은 guides/apple-ads-playbooks.mdx를 참조하세요.

리텐션 메시징(Retention Messaging)은 App Store Connect API 자격 증명과는 별개인 전용 인앱 결제(In-App Purchase) API 키를 사용합니다:

asc storekit auth login --name Production --key-id "KEY_ID" --issuer-id "ISSUER_ID" --private-key ./SubscriptionKey.p8 --bundle-id com.example.app
asc storekit auth doctor --environment sandbox --network
asc storekit retention-messaging messages list --environment sandbox --output json
...

엔드포인트 맵(endpoint map), 메시지 및 이미지 요구 사항, 환경 변수(environment variables), 그리고 전체 샌드박스(sandbox) 검증 시퀀스를 확인하려면 docs/architecture/storekit-retention-messaging.md를 참조하세요.

내장된 도움말을 신뢰할 수 있는 정보원(source of truth)으로 사용하세요:

asc --help
asc <command> --help
asc <command> <subcommand> --help

참조 계층 구조:

asc --help
: 권위 있는 명령어 및 플래그(flag) 노출

docs/COMMANDS.md
: 생성된 최상위 분류 체계(taxonomy) 맵

asc docs show workflows
: 큐레이션된 워크플로 레시피(workflow recipes)

asc docs show reference
: asc init에서 사용되는 저장소 로컬 빠른 참조(quick reference) 템플릿

전체 명령어 제품군(command families), 플래그, 그리고 탐색 패턴에 대해서는 다음을 참조하세요:

• docs/CI_CD.md - CI/CD 통합 가이드 (GitHub Actions, GitLab, Bitrise, CircleCI)
• docs/COMMANDS.md - 명령어 제품군 (Command families) 및 참조 탐색
• docs/WORKFLOWS.md - 로컬 Xcode에서 TestFlight로의 과정을 포함한 재사용 가능한 워크플로 (Workflow) 패턴
• guides/apple-ads-playbooks.mdx - Apple Ads 운영자 플레이북 (Playbooks)
• docs/architecture/storekit-retention-messaging.md - 리텐션 메시징 (Retention Messaging) 설정 및 샌드박스 (Sandbox) 검증
• docs/API_NOTES.md - API의 특이사항 및 동작 방식
• docs/CONTRIBUTING.md - CLI 개발 및 테스트 관련 노트
• docs/TESTING.md - 테스트 패턴 및 컨벤션 (Conventions)
• docs/openapi/README.md - 오프라인 OpenAPI 스냅샷 + 업데이트 흐름
• CONTRIBUTING.md - 기여 가이드

로컬 스크린샷 프레이밍 (Framing)은 결정론적인 디바이스 프레임 렌더링을 위해 Koubou (0.18.1 버전 고정)를 사용합니다.
GitHub: https://github.com/bitomule/koubou

스크린샷 캡처 및 상호작용을 위한 시뮬레이터 (Simulator) UI 자동화에는 AXe CLI를 사용합니다. GitHub: https://github.com/cameroncooke/AXe

기여를 환영합니다. 자세한 내용은 CONTRIBUTING.md를 참조하세요.

MIT License - 자세한 내용은 LICENSE를 참조하세요.