ArkStore CLI

Publish signed Android APKs to ArkStore from a terminal or GitHub Actions.

npx arkstore-cli setup

Run that command from the Android app's GitHub repository. The guided setup:

1. Detects Expo, Gradle, and the GitHub repository.
2. Collects the store name, description, developer, and category.
3. Creates the ArkStore app through the active gh login.
4. Generates arkstore.json and the keyless GitHub Actions workflow.
5. Registers the repository's GitHub OIDC trust without creating a deployment token.

If a signed APK already exists, submit it during the same setup:

npx arkstore-cli setup ./app-release.apk \
  --version-name 1.0.0 \
  --version-code 1

The version flags are only needed when Android SDK apkanalyzer is unavailable. A clean first release is submitted for manual review so ArkStore can pin its package and signer. needs_review is a successful submission, not a reason to upload the APK again.

The CLI exchanges the active gh account for a short-lived ArkStore publisher token. GitHub credentials are never written to the project or printed. Run gh auth login first if GitHub CLI is not already signed in.

Expo projects need one additional CI secret after setup:

gh secret set EXPO_TOKEN --repo OWNER/REPOSITORY

Create that token at https://expo.dev/settings/access-tokens. The generated workflow checks for it before installing dependencies or starting an Android build.

Non-interactive setup

Create an app and its keyless CI files from the Android repository:

npx arkstore-cli app create \
  --name "LinkPay" \
  --slug linkpay \
  --summary "Send money to Nigerian banks, pay bills, and buy airtime in seconds." \
  --description "LinkPay lets people send money, pay bills, and buy airtime from one naira balance." \
  --developer-name "LinkPay" \
  --category finance \
  --init-ci

--init-ci creates the workflow and registers GitHub OIDC trust through the active gh login. No ARKSTORE_TOKEN secret or temporary deployment token is required.

Build and publish a signed APK at any time:

npx arkstore-cli publish ./app-release.apk

To add commit-driven delivery, run this inside the Android repository:

npx arkstore-cli ci init \
  --app YOUR_APP_ID

npx arkstore-cli ci trust
npx arkstore-cli doctor

ci init detects native Gradle and Expo projects. Expo projects default to expo-local, which compiles on the GitHub runner instead of consuming an EAS cloud build. Use --provider expo-persistent to route builds to an Ark-owned runner with persistent disk, or --provider gradle|expo-local|expo-persistent|expo-eas|custom to override detection; expo-eas remains an explicit cloud fallback. Expo projects must have an EAS profile that produces an APK. The default profile name is ark-store and can be changed with --eas-profile. Custom builds require --build and --artifact.

Local Expo builds target arm64-v8a by default, which avoids compiling three unnecessary emulator and legacy-device architectures on every release. Use --architectures all (or a comma-separated subset) when the app must support those devices. Generated workflows persist the Gradle dependency/build cache and give native compilation a larger memory ceiling; documentation-only and test-only commits do not trigger a release.

The persistent provider targets [self-hosted, linux, x64, ark-android] by default. Change the custom label with --runner-label. The runner must expose ARK_BUILD_CACHE_ROOT; Ark's builder image and deployment guide are in infra/builder in the ArkStore repository.

ci trust binds the app to the exact GitHub repository, branch, and generated workflow through the active GitHub CLI login. The workflow requests a GitHub OIDC identity and exchanges it for a 15-minute, app-scoped ArkStore credential. Expo workflows still require an EXPO_TOKEN secret to read the Expo project configuration and existing signing credentials. With expo-local, compilation and artifact creation happen on the GitHub runner.

Generated workflows authorize their GitHub OIDC identity before installing build tooling or compiling the app. An untrusted repository therefore fails immediately instead of spending build time. ci init also adds .arkstore/ to .gitignore for generated local artifacts.

ark doctor checks the provider, config, Git remote, keyless workflow, registered trust, OIDC runtime, and ArkStore API health. Use --offline to skip the API health check.

The CLI uses Android SDK apkanalyzer to read the APK version. When it is unavailable, provide --version-name and --version-code, or the ARKSTORE_VERSION_NAME and ARKSTORE_VERSION_CODE environment variables.

ark publish gives a request up to four attempts when the API is unreachable or answers 408, 429, 500, 502, 503, or 504, waiting 5s, 20s, then 40s so the 65s of waiting outlasts a 30-60s cold start on a sleeping deployment. Every other answer, including a rejected duplicate version, fails on the first attempt. A duplicate rejection that arrives after a retry says so: the earlier attempt may have been accepted, so check the app's releases before rebuilding. Set ARKSTORE_RETRY_DELAYS_MS to a comma-separated list of whole milliseconds to change the backoff; anything else is ignored with a warning. ark doctor never retries, so it still reports an unreachable API immediately.