📦 bundle

📦 업로드, 호환성 검사, 암호화를 포함하여 Capgo Cloud 배포를 위한 앱 번들을 관리합니다.

⬆️ 업로드

Alias: u

npx @capgo/cli@latest bundle upload

배포를 위해 새로운 앱 번들을 Capgo Cloud에 업로드합니다. 버전은 0.0.0보다 커야 하며 중복될 수 없습니다. 보안을 위해 삭제된 버전은 재사용할 수 없습니다. External 옵션: URL 링크만 저장합니다 (200MB 이상의 앱이나 개인정보 보호 요구사항이 있는 경우 유용). Capgo은 외부 콘텐츠를 절대 검사하지 않습니다. 신뢰할 수 있는 보안을 위해 암호화를 추가하세요.

Example:

npx @capgo/cli@latest bundle upload com.example.app --path ./dist --channel production,beta

버전을 전달하지 않으면 채널(또는 최신 원격 앱 버전)에서 다음 사용 가능한 semver를 자동으로 올립니다. --bundle. CI 환경에서 다음 상황에 유용합니다: package.json 이미 Capgo에 있는 버전과 일치하는 경우:

npx @capgo/cli@latest bundle upload --channel=production --auto-bump
npx @capgo/cli@latest bundle upload --auto-bump major
npx @capgo/cli@latest bundle upload --auto-bump minor   # default when the flag has no value
npx @capgo/cli@latest bundle upload --auto-bump patch   # alias: fix
npx @capgo/cli@latest bundle upload --auto-bump metadata
npx @capgo/cli@latest bundle upload --channel=production --auto-bump ai

GCP는 --auto-bump ai, Capgo Cloudflare Workers AI가 로컬 번들 파일과 이전 Capgo/channel 델타 매니페스트를 비교하여 분석하고, major | minor | patch | metadata CLI 로그에 짧은 이유를 출력합니다. 이전 Capgo 버전이 없는 경우 AI 분석은 건너뛰며, 버전은 기본적으로 patch.

옵션:

파라미터	타입	설명
-a	string	계정과 연결하기 위한 API 키
-p	string	업로드할 폴더 경로입니다. 지정하지 않으면 capacitor.config에 설정된 webDir을 사용합니다.
-c	string	연결할 채널입니다. 여러 채널을 지정하려면 production,beta와 같이 쉼표로 구분하세요.
—rollout	string	업로드된 번들을 해당 채널의 롤아웃 대상으로 설정하며, 비율은 0에서 100 사이로 지정합니다.
—stable	boolean	롤아웃이 설정된 채널에서 롤아웃 대상을 설정하는 대신 stable 폴백을 교체합니다.
—rollout-percentage-bps	string	업로드된 번들의 롤아웃 비율을 0에서 10000 사이의 basis points 단위로 설정합니다.
—rollout-cache-ttl-seconds	string	Cloudflare 롤아웃 결정 캐시 TTL(초 단위)
-e	string	Capgo Cloud에 업로드하는 대신 외부 URL로 연결
—iv-session-key	string	외부 번들 URL용 IV 및 세션 키 설정
—s3-region	string	S3 버킷의 리전
—s3-apikey	string	S3 엔드포인트용 API 키
—s3-apisecret	string	S3 엔드포인트용 API secret
—s3-endpoint	string	S3 엔드포인트 URL
—s3-bucket-name	string	AWS S3 버킷 이름
—s3-port	string	S3 엔드포인트 포트
—no-s3-ssl	boolean	S3 upload 시 SSL 비활성화
—key-v2	string	개인 서명 키 커스텀 경로 (v2 시스템)
—key-data-v2	string	개인 서명 키 (v2 시스템)
—bundle-url	boolean	bundle URL을 stdout에 출력
—no-key	boolean	서명 키를 무시하고 평문 업데이트 전송
—no-code-check	boolean	소스 code 내 notifyAppReady() 호출 여부 및 루트 폴더의 index 존재 여부 확인 무시
—display-iv-session	boolean	업데이트 암호화에 사용된 IV 및 세션 키를 콘솔에 표시
-b	string	업로드할 번들의 버전 번호
—auto-bump	string	채널에 연결된 번들 또는 최신 원격 앱 버전에서 자동 증가. 레벨: major, minor(기본값), patch(fix 별칭), metadata, 또는 ai(Workers AI가 로컬과 이전 델타 manifest를 비교하여 레벨 추론, 이전 Capgo 버전이 없으면 patch로 대체). 사용 가능한 이름이 나올 때까지 bump 수행(삭제된 이름은 점유 상태 유지). —bundle (-b)와 함께 사용할 수 없음
—link	string	외부 리소스 연결 (예: GitHub release)
—comment	string	이 버전에 대한 설명입니다. 릴리스 노트, 커밋 해시, 커밋 메시지 등을 입력할 수 있습니다.
—min-update-version	string	이 버전으로 업데이트하기 위해 필요한 최소 버전입니다. 채널의 자동 업데이트 설정이 metadata로 되어 있는 경우에만 사용됩니다.
—auto-min-update-version	boolean	네이티브 패키지를 기반으로 최소 업데이트 버전을 설정합니다.
—ignore-metadata-check	boolean	업로드 시 메타데이터(node_modules) 체크를 무시합니다.
—fail-on-incompatible	boolean	번들이 채널의 현재 네이티브 패키지와 호환되지 않을 경우, 업로드를 진행하지 않고 실패(exit non-zero) 처리합니다. 대화형 터미널에서는 네이티브 빌드를 선택할 수 있으며, 거절 시 실패합니다. —ignore-metadata-check와 함께 사용할 수 없습니다.
—ignore-checksum-check	boolean	업로드 시 체크섬 체크를 무시합니다.
—force-crc32-checksum	boolean	업로드 시 CRC32 체크섬 강제 적용 (자동 감지 무시)
—timeout	string	업로드 프로세스 타임아웃(초)
—multipart	boolean	[DEPRECATED] 대신 —tus를 사용하세요. S3 업로드에 multipart 프로토콜을 사용합니다
—zip	boolean	zip으로 Capgo 클라우드에 번들 업로드 (레거시)
—tus	boolean	TUS로 Capgo 클라우드에 번들 업로드
—tus-chunk-size	string	TUS 재개 업로드의 청크 크기(바이트, 기본값: auto)
—partial	boolean	[DEPRECATED] 대신 —delta를 사용하세요. 증분 업데이트를 업로드합니다.
—partial-only	boolean	[DEPRECATED] 대신 —delta-only를 사용하세요. 전체 번들은 건너뛰고 증분 업데이트만 업로드합니다.
—delta	boolean	대용량 zip 다운로드 대신, 변경된 파일만 업로드하는 delta 업데이트를 통해 즉각적이고 매우 빠른 업데이트를 제공합니다.
—delta-only	boolean	최대 속도를 위해 전체 번들 없이 delta 업데이트만 업로드합니다 (대규모 앱에 유용).
—no-delta	boolean	즉각적인 업데이트가 활성화되어 있어도 delta 업데이트를 비활성화합니다.
—encrypted-checksum	string	암호화된 체크섬(서명)입니다. 외부 번들을 업로드할 때만 사용됩니다.
—auto-set-bundle	boolean	capacitor.config.json에 번들 설정
—dry-upload	boolean	번들 업로드 프로세스 시뮬레이션: 파일 업로드나 채널 업데이트 없이 데이터베이스에 레코드만 추가합니다 (Capgo 내부 테스트용)
—package-json	string	모노레포용 package.json 파일 경로 (쉼표로 구분)
—node-modules	string	모노레포용 node_modules 디렉토리 경로 (쉼표로 구분)
—encrypt-partial	boolean	델타 업데이트 파일 암호화 (업데이터 6.14.4 이상 버전에서 자동 활성화)
—delete-linked-bundle-on-upload	boolean	업로드하려는 채널에 현재 연결된 번들을 찾아 삭제합니다
—no-brotli-patterns	string	Brotli 압축에서 제외할 파일 (쉼표로 구분된 glob 패턴, 예: “.jpg,.png”)
—disable-brotli	boolean	업데이터 버전이 지원하더라도 Brotli 압축을 완전히 비활성화합니다
—version-exists-ok	boolean	번들 버전이 이미 존재하면 성공적으로 종료합니다. 모노레포 CI/CD 워크플로우에 유용합니다
—self-assign	boolean	디바이스가 이 채널에 자동으로 참여하도록 허용합니다 (업데이트 채널 설정)
—qr-preview	boolean	업로드 후 이 번들 미리보기를 위한 터미널 QR code를 출력합니다
—send-update-notification	boolean	연결된 채널의 번들을 업데이트한 후 기기에 네이티브 업데이트 확인 알림을 보냅니다.
—supa-host	string	사용자 정의 Supabase 호스트 URL (Capgo 개발 또는 셀프 호스팅용)
—supa-anon	string	사용자 정의 Supabase anon key (셀프 호스팅용)
—verbose	boolean	상세 로그를 포함한 상세 출력을 활성화합니다.

🧪 호환성

npx @capgo/cli@latest bundle compatibility

🧪 업데이트가 안전한지 확인하기 위해 Capgo Cloud에서 특정 채널과 번들의 호환성을 체크합니다.

예시:

npx @capgo/cli@latest bundle compatibility com.example.app --channel production

옵션:

파라미터	타입	설명
-a	string	계정과 연결할 API 키
-c	string	호환성을 확인할 Channel
—text	boolean	이모지 대신 텍스트 출력
—package-json	string	모노레포의 package.json 파일 경로 (쉼표로 구분)
—node-modules	string	모노레포의 node_modules 디렉토리 경로 (쉼표로 구분)
—supa-host	string	커스텀 Supabase 호스트 URL (셀프 호스팅 또는 Capgo 개발용)
—supa-anon	string	커스텀 Supabase anon key (셀프 호스팅용)

🔹 ReleaseType

npx @capgo/cli@latest bundle releaseType

🧭 채널의 최신 메타데이터 호환성에 따라 “native” 또는 “OTA”를 출력합니다.

예시:

npx @capgo/cli@latest bundle releaseType com.example.app --channel production

옵션:

파라미터	타입	설명
-a	string	계정 연결을 위한 API 키
-c	string	비교 대상 채널
—package-json	string	모노레포의 package.json 파일 경로 (쉼표로 구분)
—node-modules	string	모노레포의 node_modules 디렉토리 경로 (쉼표로 구분)
—supa-host	string	커스텀 Supabase 호스트 URL (셀프 호스팅 또는 Capgo 개발용)
—supa-anon	string	커스텀 Supabase anon key (셀프 호스팅용)

🗑️ 삭제

Alias: d

npx @capgo/cli@latest bundle delete

🗑️ Capgo Cloud에서 특정 번들을 삭제합니다. 특정 버전을 지정하여 삭제할 수도 있습니다.

예시:

npx @capgo/cli@latest bundle delete BUNDLE_ID com.example.app

옵션:

파라미터	타입	설명
-a	string	계정과 연결할 API 키
—supa-host	string	커스텀 Supabase 호스트 URL (셀프 호스팅 또는 Capgo 개발용)
—supa-anon	string	커스텀 Supabase anon key (셀프 호스팅용)

📋 목록

Alias: l

npx @capgo/cli@latest bundle list

📋 Capgo Cloud에 업로드된 앱의 모든 bundle 목록을 표시합니다.

Example:

npx @capgo/cli@latest bundle list com.example.app

옵션:

파라미터	타입	설명
-a	string	계정 연결을 위한 API key
—supa-host	string	커스텀 Supabase 호스트 URL (셀프 호스팅 또는 Capgo 개발용)
—supa-anon	string	커스텀 Supabase anon key (셀프 호스팅용)

🧹 정리

Alias: c

npx @capgo/cli@latest bundle cleanup

🧹 지정된 개수의 최신 버전만 남기고 Capgo Cloud에서 오래된 bundle을 삭제합니다. —ignore-channel 옵션을 사용하지 않는 한, channel에 연결된 bundle은 보존됩니다.

Example:

npx @capgo/cli@latest bundle cleanup com.example.app --bundle=1.0 --keep=3

옵션:

파라미터	타입	설명
-b	string	삭제할 앱의 Bundle 버전 번호
-a	string	계정 연결을 위한 API 키
-k	string	유지할 버전 수
-f	boolean	강제 삭제
—ignore-channel	boolean	채널에 연결된 Bundle도 삭제 (주의: 채널도 함께 삭제됨)
—supa-host	string	사용자 정의 Supabase 호스트 URL (셀프 호스팅 또는 Capgo 개발용)
—supa-anon	string	사용자 정의 Supabase anon key (셀프 호스팅용)

🔒 암호화

npx @capgo/cli@latest bundle encrypt

🔒 외부 저장소에 안전하게 보관할 zip bundle을 암호화합니다. upload/복호화에 필요한 ivSessionKey를 반환합니다. checksum은 ‘bundle zip —json’으로 확인하세요.

예시:

npx @capgo/cli@latest bundle encrypt ./myapp.zip CHECKSUM

옵션:

파라미터	타입	설명
—key	string	개인 서명 키의 사용자 지정 경로
—key-data	string	개인 서명 키
-j	boolean	JSON 형식으로 출력
—package-json	string	모노레포용 package.json 파일 경로 (쉼표로 구분)

🔓 복호화

npx @capgo/cli@latest bundle decrypt

🔓 암호화된 번들을 복호화합니다 (주로 테스트용). 검증을 위해 base64 세션 키를 출력합니다.

예시:

npx @capgo/cli@latest bundle decrypt ./myapp_encrypted.zip CHECKSUM

옵션:

파라미터	타입	설명
—key	string	개인 서명 키의 사용자 지정 경로
—key-data	string	개인 서명 키
—checksum	string	번들의 무결성 검증을 위한 번들 체크섬
—package-json	string	모노레포용 package.json 파일 경로 (쉼표로 구분)

🔹 Zip

npx @capgo/cli@latest bundle zip

🗜️ 앱 번들을 zip 파일로 생성합니다. 암호화에 사용할 체크섬을 반환합니다. 기계 판독 가능한 출력을 원하면 --json을 사용하세요.

예시:

npx @capgo/cli@latest bundle zip com.example.app --path ./dist

옵션:

파라미터	타입	설명
-p	string	업로드할 폴더 경로입니다. 지정하지 않으면 capacitor.config에 설정된 webDir을 사용합니다.
-b	string	zip 파일 이름에 사용할 번들 버전 번호
-n	string	zip 파일 이름
-j	boolean	JSON 형식으로 출력
—no-code-check	boolean	소스 code 내 notifyAppReady() 호출 여부 및 루트 폴더의 index 존재 여부 확인을 건너뜁니다
—key-v2	boolean	v2 암호화 사용
—package-json	string	모노레포용 package.json 파일 경로 (쉼표로 구분)