📦 bundle

📦 Capgo Cloud에서 배포할 앱 bundle을 관리합니다. 업로드, 호환성 검사, 암호화를 포함합니다.

⬆️ 업로드

별칭: u

npx @capgo/cli@latest bundle upload

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

예시:

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

사용하면 --auto-bump ai, Capgo Cloudflare Workers AI가 로컬 bundle 파일과 이전 Capgo/채널 delta manifest를 비교하여 추론합니다 major | minor | patch | metadata, 그리고 CLI 로그에 짧은 이유를 출력합니다. 이전 Capgo 버전이 없으면 AI가 건너뛰고 bump가 기본값으로 설정됩니다 patch는.

옵션:

파라미터	유형	설명
-a	string	계정에 연결할 API 키
-p	string	업로드할 폴더 경로입니다. 지정하지 않으면 capacitor.config에 설정된 webDir을 사용합니다.
-c	string	연결할 Channel. 여러 Channel은 쉼표로 구분하여 지정합니다. 예: production,beta
—rollout	string	업로드된 bundle을 0~100 사이의 백분율로 이 Channel의 rollout 대상으로 설정합니다
—stable	boolean	rollout이 구성된 Channel에서 rollout 대상 대신 stable fallback을 대체합니다
—rollout-percentage-bps	string	업로드된 bundle의 rollout 백분율을 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 업로드 시 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	업로드할 bundle의 버전 번호
—auto-bump	string	채널에 연결된 bundle을 기준으로 자동 증분하며, 없으면 최신 원격 앱 버전을 기준으로 합니다. 레벨: major, minor(기본값), patch(별칭: fix), metadata 또는 ai(Workers AI가 로컬과 이전 delta manifest를 비교해 레벨을 추론하며, 이전 Capgo 버전이 없으면 patch로 폴백합니다). 사용 가능한 이름이 나올 때까지 증분합니다(삭제된 이름은 계속 점유됩니다). —bundle(-b)과 함께 사용할 수 없습니다
—link	string	외부 리소스 링크 (예: GitHub 릴리스)
—comment	string	이 버전에 대한 코멘트. 릴리스 노트, 커밋 해시, 커밋 메시지 등이 될 수 있습니다.
—min-update-version	string	이 버전으로 업데이트하는 데 필요한 최소 버전. 채널의 disable auto update가 metadata로 설정된 경우에만 사용됩니다.
—auto-min-update-version	boolean	네이티브 패키지를 기반으로 최소 업데이트 버전을 설정합니다.
—ignore-metadata-check	boolean	업로드 시 메타데이터(node_modules) 검사를 무시합니다.
—fail-on-incompatible	boolean	번들이 채널의 현재 네이티브 패키지와 호환되지 않을 경우 업로드 대신 업로드를 실패시킵니다(비영 종료). 인터랙티브 터미널에서는 네이티브 빌드를 선택할 수 있으며, 거절하면 실패합니다. —ignore-metadata-check와 함께 사용할 수 없습니다.
—ignore-checksum-check	boolean	업로드 시 체크섬 검사를 무시합니다
—force-crc32-checksum	boolean	업로드에 CRC32 체크섬을 강제 적용합니다 (자동 감지 오버라이드)
—timeout	string	업로드 프로세스의 타임아웃(초)
—multipart	boolean	[비추천] 대신 —tus를 사용하세요. S3 업로드에 multipart 프로토콜을 사용합니다
—zip	boolean	zip을 사용하여 번들을 Capgo 클라우드에 업로드합니다 (레거시)
—tus	boolean	TUS를 사용하여 번들을 Capgo 클라우드에 업로드합니다
—tus-chunk-size	string	TUS 재개 가능 업로드의 바이트 단위 chunk size (기본값: 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에 bundle 설정
—dry-upload	boolean	bundle 업로드 프로세스를 Dry upload로 실행: 파일을 업로드하거나 채널을 업데이트하지 않고 데이터베이스에 row만 추가합니다 (Capgo 내부 테스트용)
—package-json	string	모노레포의 package.json 파일 경로 (쉼표로 구분)
—node-modules	string	모노레포의 node_modules 디렉토리 경로 (쉼표로 구분)
—encrypt-partial	boolean	Delta 업데이트 파일 암호화 (updater > 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	디바이스가 이 채널에 자동으로 참여하도록 허용합니다 (updates 채널 설정)
—qr-preview	boolean	업로드 후 이 번들 미리보기를 위한 터미널 QR code를 출력합니다
—send-update-notification	boolean	링크된 채널 bundle 업데이트 후 기기에 네이티브 업데이트 확인 알림을 보냅니다
—supa-host	string	커스텀 Supabase 호스트 URL (셀프 호스팅 또는 Capgo 개발용)
—supa-anon	string	커스텀 Supabase anon key (셀프 호스팅용)
—verbose	boolean	상세 로그가 포함된 verbose 출력을 활성화합니다

🧪 호환성

npx @capgo/cli@latest bundle compatibility

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

예시:

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

옵션:

파라미터	유형	설명
-a	string	계정에 연결할 API 키
-c	string	호환성을 확인할 채널
—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	비교할 Channel
—package-json	string	모노레포의 package.json 파일 경로 (쉼표로 구분)
—node-modules	string	모노레포의 node_modules 디렉토리 경로 (쉼표로 구분)
—supa-host	string	커스텀 Supabase 호스트 URL (셀프 호스팅 또는 Capgo 개발용)
—supa-anon	string	커스텀 Supabase anon key (셀프 호스팅용)

🗑️ 삭제

별칭: d

npx @capgo/cli@latest bundle delete

🗑️ Capgo Cloud에서 특정 버전을 대상으로 지정하여 특정 bundle을 삭제합니다.

예시:

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 (셀프 호스팅용)

📋 목록

별칭: l

npx @capgo/cli@latest bundle list

📋 Capgo Cloud에서 앱에 업로드된 모든 bundle을 나열합니다.

예시:

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

옵션:

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

🧹 정리

별칭: c

npx @capgo/cli@latest bundle cleanup

지정된 최근 버전 수를 유지하면서 Capgo Cloud의 오래된 bundle을 삭제합니다. 채널에 연결된 bundle은 —ignore-channel을 사용하지 않는 한 보존됩니다.

예시:

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	채널에 연결되어 있더라도 번들을 삭제합니다 (경고: 채널도 함께 삭제됨)
—supa-host	string	커스텀 Supabase 호스트 URL (셀프 호스팅 또는 Capgo 개발용)
—supa-anon	string	커스텀 Supabase anon key (셀프 호스팅용)

🔒 암호화

npx @capgo/cli@latest bundle encrypt

안전한 외부 저장을 위해 zip 번들을 암호화합니다. 업로드/복호화를 위한 ivSessionKey를 반환합니다. 체크섬은 ‘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

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

예시:

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

옵션:

파라미터	유형	설명
—key	string	개인 서명 키의 사용자 지정 경로
—key-data	string	개인 서명 키
—checksum	string	Bundle의 무결성을 검증하기 위한 checksum
—package-json	string	모노레포의 package.json 파일 경로 (쉼표로 구분)

🔹 압축

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 파일 이름에 사용할 Bundle 버전 번호입니다.
-n	string	zip 파일 이름
-j	boolean	JSON으로 출력
—no-code-check	boolean	소스 code에서 notifyAppReady() 호출 여부와 루트 폴더의 index 존재 여부 검사를 무시합니다
—key-v2	boolean	v2 암호화 사용
—package-json	string	모노레포의 package.json 파일 경로 (쉼표로 구분)