kevingong2013/apkgo/apkgo

apkgo

Ship an Android app through the hosted apkgo cloud service. Two ways in:

• CLI (`apkgo-cloud`) — recommended for agents and interactive use. Install once, log in through the browser, then run one command to get a shareable download link or distribute to stores. No store credentials held locally.
• Open API (`X-API-Key`, curl) — for CI/CD runners where you don't want to install a binary. See Open API — CI/CD fallback at the end.

Hosted at `https://apkgo.baici.tech`. Store credentials are encrypted server-side; multiple apps and team members per organization; async distribution with optional webhook callbacks; dashboard-visible audit log.

When to use

Use this skill when the user wants to:

• Get a public 内测 (beta) download link for an APK they can send to testers → preview
• Distribute/publish/release an APK to Android app stores (Huawei, Xiaomi, OPPO, vivo, Honor, Meizu, Tencent, Google Play, Samsung, Pgyer, fir.im), an .ipa to the App Store, or a HarmonyOS 鸿蒙 .app pack to AppGallery → release
• Prepare listing materials or create the app entry in each store before its first release (「准备上架资料」「创建 App 提审」) → use the apkgo-app-listing skill instead
• Automate distribution in CI/CD without shipping store secrets → Open API

Install & log in (CLI)

If apkgo-cloud isn't installed yet, install it with the one-line installer (prebuilt binary, no Go toolchain needed), then log in through the browser:

curl -fsSL https://apkgo.baici.tech/install.sh | sh   # installs the `apkgo-cloud` binary onto PATH
apkgo-cloud login      # opens the browser; user clicks 同意授权
apkgo-cloud whoami     # confirm the connected organization

Windows (PowerShell): iwr https://apkgo.baici.tech/install.ps1 -UseBasicParsing | iex — installs to %LOCALAPPDATA%\apkgo-cloud and adds it to your user PATH (open a new terminal afterwards). Full agent setup doc: https://apkgo.baici.tech/doc/cli-setup.md.

Keep the skills local and fresh: apkgo-cloud skill install drops the apkgo skills into your skills directory — pass --dir to choose it (default .claude/skills; for Trae IDE pass --dir .trae/skills, or ~/.trae/skills for user-level; otherwise your own agent's skills dir). apkgo-cloud skill update --dir <dir> refreshes them when a new version ships.

Login is browser-only. The CLI starts a local callback, opens the approve page, and receives the credential automatically — it's written to ~/.apkgo-cloud/config.json (0600). Never ask the user for an API key or password. If the browser doesn't open, hand the user the URL the CLI printed.

Get a 内测 download link — preview

The fastest thing you can do for a freshly-built app. No store credentials required — works on day one.

apkgo-cloud preview ./app-release.apk --notes "首个内测版本"
apkgo-cloud preview ./app-release.apk --password 8888   # 加下载密码

The CLI parses the APK locally (package, version), uploads it directly to object storage, and prints a public link like https://apkgo.baici.tech/d/AbC123.... Send it to anyone — they get a download page and install the APK. Re-running preview for the same package refreshes the same link (one link per app), so testers keep a stable URL across builds.

--password gates the download page — visitors must enter it before downloading (share the password alongside the link). Omitting --password on a later preview leaves an existing link's password unchanged. Expiry and download-count limits are also supported on the link, settable in the dashboard.

Distribute to app stores — release

Push the APK to the app's bound stores and wait for each result.

apkgo-cloud release ./app-release.apk                     # all bound stores
apkgo-cloud release ./app-release.apk --stores huawei,oppo  # only these
apkgo-cloud release ./app-release.apk --no-wait            # create job, don't wait

• Prerequisite: the org has at least one store account (商店账号) added in the dashboard. Any store with exactly one account publishes automatically — there is no separate "bind" step. Only when a store has several accounts must the user pick one under 应用 → 发布商店 (the app page); a store can also be switched off there. If no store resolves, release fails with a message saying which account is missing. Use preview until stores are set up.
• Without --no-wait, the CLI polls until every store finishes and prints a ✓/✗ per-store summary; it exits non-zero if any store failed (usable in CI). When some stores succeeded and others failed it reports 部分成功 (partial success): the successful stores are already in review — retry only the failed ones (dashboard 发布记录 → 重试失败的商店, or POST /openapi/v1/uploads/{jobId}/retry), don't re-release to every store.
• The worker re-parses the binary after download; its metadata wins. A package mismatch fails the job before any store upload.

Before the first release — hand off

release only works for apps that already exist in each store. When the app has never been listed — the user says 「帮我上架」 for a new app, or needs icons, screenshots, copy, a privacy policy or to submit the store entry for review — switch to the `apkgo-app-listing` skill (https://apkgo.baici.tech/skill-app-listing.md):

Come back here once the store entries are approved — every later version ships with release.

Steps that must be the user's own action — stop and wait, never do these for them or try to bypass: 人脸核身 (face verification), 短信/图形验证码, 对公打款 (corporate bank verification), payment. When you hit one, tell the user exactly what to do and continue only after they confirm.

Supported stores

huawei, xiaomi, oppo, vivo, honor, meizu, tencent, googleplay, samsung, pgyer, fir, appstore (iOS .ipa), harmony (HarmonyOS 鸿蒙 .app)

HarmonyOS notes: harmony reuses the huawei AGC Service Account (add a「鸿蒙」store account with the same JSON); it only accepts the signed `.app` App Pack from DevEco Studio (Build → Build APP(s)), not a bare .hap. The app must exist in AppGallery Connect as a HarmonyOS app (same bundleName) with category / privacy policy / content rating filled in; the platform picks the HarmonyOS app automatically from the file extension. preview (内测分发) is Android APK only.

CLI command reference

APKGO_CLOUD_BASE overrides the service URL (default https://apkgo.baici.tech).

Open API — CI/CD fallback

For runners where installing the CLI isn't practical. Everything the CLI does maps to the same REST surface at base path `/openapi/v1`, authenticated only by the X-API-Key header — the organization is bound to the key itself, so orgId never appears in a URL. Mint a key in the dashboard's API 密钥 page.

curl -H "X-API-Key: apkgo_your_key" https://apkgo.baici.tech/openapi/v1/uploads

JWT bearer tokens are not accepted on /openapi/v1. All responses are enveloped: {"data": ...} on success, {"error": "..."} on failure — remember the .data prefix in jq.

Dashboard-minted keys track the subscription: API keys are a 专业版及以上 feature, so once the subscription lapses they return 403 with 「当前套餐（免费版）不支持 API 密钥」. Renewing restores the same key — no need to mint a new one. Keys issued by apkgo-cloud login for the CLI are exempt and work on every plan.

Upload the binary (shared by link + distribute)

APK bytes never transit the apkgo cloud server. Get the binary into storage one of two ways, both ending at a JSON create call.

Option A — three-step direct upload (local APK):

KEY="apkgo_your_key"; BASE="https://apkgo.baici.tech/openapi/v1"; APK="app-release.apk"
 
T=$(curl -s -X POST -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d "{\"file_name\":\"$APK\"}" $BASE/uploads/tickets)
OBJ=$(echo "$T" | jq -r .data.object_key)
 
curl -sf -F "token=$(echo "$T" | jq -r .data.token)" \
  -F "key=$OBJ" -F "file=@$APK" "$(echo "$T" | jq -r .data.upload_url)"

Option B — server-side fetch from a URL (APK already on your CDN): skip the ticket; pass file_url in the create call instead of object_key. Public http(s) only, 1GB cap, contacted exactly once at create time; file_url and object_key are mutually exclusive.

Create a 内测 download link (preview)

curl -s -X POST -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d "{\"object_key\":\"$OBJ\",\"package_name\":\"com.example.app\",\"version_name\":\"1.0.0\"}" \
  $BASE/dist
# → {"data":{"slug":"...","url":"https://apkgo.baici.tech/d/...","package_name":"..."}}

No store credentials needed. One link per app; a later create for the same package refreshes it.

Create a store-distribution job (release)

curl -s -X POST -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d "{\"object_key\":\"$OBJ\",\"package_name\":\"com.example.app\"}" \
  $BASE/uploads
# → 202 Accepted, job id at .data.id

Create-job fields (POST /uploads, JSON):

The legacy multipart upload (-F "apk=@..." straight to /uploads) has been removed and returns 400.

Poll job status

curl -sH "X-API-Key: $KEY" $BASE/uploads/{jobId}

Status flow: pending → processing → completed | failed. Once finished, .data.outcome is success | partial | failed with .data.stores_succeeded / .data.stores_failed: a job where some stores succeeded and some failed has status: failed but outcome: partial (部分成功) — describe it as partial, not as a failure. Per-store outcomes in .data.results[] (store_name, success, error, duration_ms) as each store finishes; .data.progress carries live per-store byte progress.

Webhook callbacks (alternative to polling)

Pro plan (专业版) and above. Configure one org-level Webhook URL + optional HMAC secret at the bottom of the dashboard's API 密钥 page. Saving first POSTs a signed webhook.test event to the URL — it's saved only if the endpoint answers HTTP 200 (any other status or a connection error is shown inline). The URL must be http(s) and publicly reachable; loopback / private / link-local addresses (127.0.0.1, 10.x, 192.168.x, …) are rejected.