# app-ship **Repository Path**: flu-cli/app-ship ## Basic Information - **Project Name**: app-ship - **Description**: 一站式多平台 App 上传工具。支持全平台安装包(安卓/iOS/鸿蒙)一键分发至各大应用商店,提供透明开源、官方 API 调用、多并发上传及环境变量配置支持。 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 2 - **Forks**: 2 - **Created**: 2026-03-24 - **Last Updated**: 2026-10-28 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # App Ship Multi-platform app release and distribution engine — CLI & npm library for test distribution and store delivery of APK / IPA / AAB / HAP artifacts. **中文**: [简体中文](https://gitee.com/flu-cli/app-ship/blob/main/README.md) | English [![npm version](https://img.shields.io/npm/v/@huoye/app-ship.svg)](https://www.npmjs.com/package/@huoye/app-ship) [![npm downloads](https://img.shields.io/npm/dm/@huoye/app-ship.svg)](https://www.npmjs.com/package/@huoye/app-ship) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) ## What's new in 0.3.0 - Eleven standalone MCP tools cover artifact inspection, plan previews, local credential setup/verification, human-confirmed execution, and redacted receipts. - Huawei Android, HarmonyOS, and Google Play share artifact checks, explicit plan confirmation, and localized release notes. HarmonyOS supports multipart App Pack upload and package identity checks. - Plans distinguish test distribution, drafts, review submission, and behavior after approval. Google Play only saves internal or production drafts. - Credentials use local Profile references. Configuration completeness, read-only verification, and successful upload are separate states. Local credential setup and the browser helper are documented in [Credential setup](docs/browser-credentials.md). ## Table of Contents - [⚡ Quick Start (3 minutes)](#-quick-start-3-minutes) - [Features](#features) - [Usage Guide](#usage-guide) - [Supported Platforms](#supported-platforms) - [Configuration Reference](#configuration-reference) - [FAQ](#faq) - [Security & Privacy](#security--privacy) - [Development Guide](#development-guide) - [Community](#community) --- ## ⚡ Quick Start (3 minutes) ### 1️⃣ Install ```bash npm install -g @huoye/app-ship ``` ### 2️⃣ Initialize Configuration ```bash app-ship init ``` This generates your `app-ship.yaml` config file. ### 3️⃣ Migrate legacy credentials On macOS, explicitly migrate legacy YAML or environment-variable credentials into the local encrypted vault with keys protected by Keychain. The command refuses to overwrite the input file: ```bash app-ship credentials migrate -c app-ship.yaml -o app-ship.safe.yaml app-ship credentials list ``` The resulting YAML references a local Profile rather than a secret: ```yaml publish: pgyer: enable: true credentialProfile: app-ship-pgyer access: type: invite # Explicitly choose public, password, or invite ``` ### 4️⃣ Upload ```bash app-ship upload -c app-ship.safe.yaml -f app-release.apk ``` Review the artifact-bound plan, then confirm its current plan ID: ```bash app-ship upload -c app-ship.safe.yaml -f app-release.apk --confirm-plan ``` Do not reuse a plan after changing the artifact, target, or configuration. > 💡 Want to upload to specific platforms only? > > ```bash > app-ship upload -c app-ship.yaml -f app.apk --platform pgyer,huawei > ``` --- ## Features - **12 integrated channels**: Pgyer, Huawei, Xiaomi, OPPO, vivo, Tencent MyApp, Apple, HarmonyOS, Google Play, Honor, Meizu, and Samsung; live acceptance is tracked separately for each channel - **Parallel upload**: Multiple platforms simultaneously with configurable concurrency - **Artifact checks**: Validate APK, AAB, IPA, HAP, or Harmony App Pack against the selected channel and bind identity, version, and SHA-256 to the plan - **Two release targets**: test distribution channels and app stores share artifact verification, release plans, and receipts - **Action-specific retries**: Backoff is limited to permitted steps; review submission and automatic-release actions are not automatically retried - **Local Profiles**: YAML stores non-secret credential references; secrets remain in local secure storage - **Four integration entry points**: CLI, npm library, standalone MCP, and IDE/desktop hosts - **Framework-agnostic**: Works with Flutter, React Native, native, Harmony OS - **Official APIs**: Direct calls to platform APIs, no relay, transparent & open source --- ## Usage Guide ### 1️⃣ CLI (Command Line) Perfect for DevOps, CI/CD pipelines, and CLI users. **Common Commands**: ```bash # List supported platforms app-ship platforms # Upload to all enabled platforms app-ship upload -c app-ship.yaml -f app-release.apk # Upload to specific platforms only app-ship upload -c app-ship.yaml -f app-release.apk --platform pgyer,huawei # Upload with metadata app-ship upload -c app-ship.yaml -f app-release.apk \ --version 2.0.0 \ --build-number 42 \ --changelog "Bug fixes and improvements" # Show detailed logs app-ship upload -c app-ship.yaml -f app-release.apk --verbose # Help app-ship --help app-ship --version ``` **CLI Parameters**: | Parameter | Short | Description | | -------------------- | ----- | ------------------------------------ | | `--config ` | `-c` | Config file path (YAML) | | `--file ` | `-f` | App package path (APK/IPA/AAB/HAP) | | `--platform ` | `-p` | Comma-separated platforms (optional) | | `--version ` | `-v` | Version number (default: "1.0.0") | | `--build-number ` | `-b` | Build number (default: "1") | | `--changelog ` | - | Release notes | | `--verbose` | - | Detailed output | --- ### 2️⃣ npm Library (Programmatic) For building your own publishing systems. `UploadManager` and platform adapters are low-level trusted-process APIs. Use the release executor so a human-bound plan is revalidated before local credentials are resolved or a remote request starts. ```typescript import { ConfigValidator, createDefaultCredentialProfileStore, createReleasePlan, executeReleasePlan, } from '@huoye/app-ship' const config = ConfigValidator.loadAndValidate('./app-ship.safe.yaml') if (!config) throw new Error('Invalid config') const plan = createReleasePlan({ platform: 'google_play', action: 'create_draft', packageName: 'com.example.app', versionName: '1.0.0', buildNumber: '1', artifact: { path: './app-release.aab', sha256: '', sizeBytes: 123 }, credentialProfile: 'play-production', }) const result = await executeReleasePlan({ plan, confirmation: { planId: plan.planId, platform: plan.platform, action: plan.action, artifactSha256: plan.artifact.sha256, confirmedAt: new Date().toISOString(), }, config, projectRoot: process.cwd(), dependencies: { credentialStore: createDefaultCredentialProfileStore() }, }) console.log(result.receipt.id) ``` **Upload to multiple platforms**: ```typescript import { UploadManager, ConfigValidator } from '@huoye/app-ship' // Load & validate config const config = ConfigValidator.loadAndValidate('./app-ship.yaml') // Create upload manager const manager = new UploadManager({ maxConcurrent: 3, continueOnError: true, verbose: true, }) // Execute upload const report = await manager.uploadToMultiplePlatforms('./app-release.apk', config, { version: '2.0.0', buildNumber: '42', changelog: 'Bug fixes and improvements', }) // Check results console.log(`Success: ${report.successCount}, Failed: ${report.failureCount}`) for (const result of report.results) { if (result.success) { console.log(`✅ ${result.platform}: ${result.url}`) } else { console.log(`❌ ${result.platform}: ${result.message}`) } } ``` **Single platform upload**: ```typescript import { PgyerUploader } from '@huoye/app-ship' const uploader = new PgyerUploader() const result = await uploader.upload( './app-release.apk', { enable: true, apiKey: 'YOUR_API_KEY' }, { version: '1.0.0', buildNumber: '1', changelog: 'Initial release' }, ) if (result.success) { console.log(`✅ Download URL: ${result.url}`) console.log(`✅ QR Code: ${result.qrCode}`) } ``` --- ### 3️⃣ VSCode Extension (Visual) Install **Flu CLI** VSCode extension for point-and-click publishing. **Features**: - Real-time build & upload progress - Visual configuration panels - Automatic credential management - Download links + QR codes See [VSCode Extension Guide](https://gitee.com/flu-cli/flu-cli/tree/main/packages/vscode-extension#readme). --- ### 4️⃣ Local MCP (AI host integration) App Ship provides a local `app-ship-mcp` stdio entry point for OpenHands, Codex, and other MCP hosts. There are eleven tools: - `inspect_artifact`: read the real package format, identity, size, and SHA-256 - `preview_release`: generate a test-distribution or store `ReleasePlan` without credentials or remote side effects - `preview_draft_upload`: generate a store draft plan without credentials or upload - `list_release_receipts`: read redacted local release receipt summaries - `execute_release`: request per-platform human confirmation through MCP elicitation, then revalidate and execute the upload and return a redacted receipt - `begin_credential_setup`, `credential_setup_status`, `complete_credential_setup`, `cancel_credential_setup`: manage explicitly targeted local credential setup tasks without uploading artifacts - `preflight_release`, `verify_credential_profile`: perform read-only credential/target checks, not upload acceptance The MCP entry point requires Node.js 20 or newer. `execute_release` requires host elicitation support. If the user declines or the host cannot provide confirmation, App Ship does not resolve credentials or invoke an adapter. Confirmation supports both 2025-era `elicitation/create` and `2026-07-28` `input_required`. Server-signed confirmation state expires after ten minutes and can be used only once. Changes to the target configuration, release arguments, or artifact block execution. Host cancellation blocks execution before upload starts; requests already sent must be checked against receipts and must not be retried automatically. Build first, then register absolute executable paths with Codex: ```bash codex mcp add app-ship -- /absolute/path/to/node /absolute/path/to/app-ship/dist/mcp.js ``` For large uploads, set `tool_timeout_sec = 600` under `[mcp_servers.app-ship]` in the host configuration. Reload MCP and verify the eleven tools and declined confirmations before a real draft upload. Execute Android APK and Harmony App Pack plans separately because they bind different artifacts. --- ## Supported Platforms These are implemented capabilities, not a claim that every channel has passed live-account or upload acceptance. The previewed plan is authoritative for a particular action. | Channel | Artifacts | Action boundary | | ------------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------- | | Pgyer | APK, IPA | Test distribution; explicitly select public, password, or invite access | | Huawei Android | APK, AAB | Draft upload and review submission are separate, explicitly confirmed actions | | HarmonyOS | App Pack (`.app`), legacy HAP | Draft only; HarmonyOS 5+ store delivery uses App Pack, not the legacy HAP interface | | Google Play | AAB | Internal or production drafts only; no review submission, test rollout, or production release | | Xiaomi | APK | Review submission or scheduled release after approval, as stated in the plan | | OPPO, vivo, Tencent MyApp | APK | Current adapters submit for review and automatically release after approval; inspect the plan's risk | | App Store | IPA | Upload a build only; no build selection or review submission | | Honor, Samsung | APK | Drafts; live-account and upload acceptance pending | | Meizu | 64-bit APK | Stage a file only; no version binding, submission, or release; live acceptance pending | TestFlight and Ad Hoc are blocked by the current manager and are not among the twelve available channels. Standalone MCP retains the original nine-channel scope; a trusted native host may explicitly enable the extended scope with target configuration binding and human confirmation. Existing Google Play live-upload evidence covers an internal draft, not production upload. --- ## Configuration Reference ### Safe app-ship.yaml configuration Obtain credentials from the platform's official console, then import them into a local Profile. Raw credentials and service-account JSON do not belong in the project YAML. ```yaml version: '1.0.0' publish: pgyer: enable: true credentialProfile: app-ship-pgyer access: type: invite huawei: enable: false credentialProfile: app-ship-huawei appId: 'YOUR_APP_ID' packageName: 'com.example.app' releaseType: draft harmony: enable: false credentialProfile: app-ship-harmony appId: 'YOUR_APP_ID' packageName: 'com.example.app' google_play: enable: false credentialProfile: app-ship-google_play packageName: 'com.example.app' track: internal ``` Google Play requires an existing Play Console app with a matching package name and accepts AAB only. Production-track permission is checked before sending an AAB; test-track access does not imply production access. The connector preserves existing releases and saves a draft without submitting for review or exposing it to users. A first-ever build may need to be saved manually in Play Console before the Edits API is available. ### Localized release notes The root-level `releaseNotes` field accepts BCP-47 language codes. The adapter matches store languages and reads back the update. See [Localized release notes](docs/localized-release-notes.md) for supported behavior and checks. ### Legacy environment variables `${VAR_NAME}` remains valid only as an explicit migration input. Uploads require local `credentialProfile` references; do not fall back to plaintext YAML or command-line secrets. ```bash app-ship credentials migrate -c app-ship.legacy.yaml -o app-ship.safe.yaml ``` --- ## FAQ ### Q: How do I get API Keys for each platform? **Pgyer**: [pgyer.com](https://www.pgyer.com) → Account Settings → API **Huawei**: [AppGallery Connect](https://developer.huawei.com/consumer/cn/service/josp/agc/index.html) → Projects → Settings → API Key **Xiaomi**: [Developer Platform](https://dev.mi.com/console/) → Apps → Upload Interface **OPPO/vivo/Tencent**: Respective developer platforms → Apps → API Management **Apple**: [App Store Connect](https://appstoreconnect.apple.com) → Users & Access → API Keys --- ### Q: How do I troubleshoot upload failures? 1. Use `--verbose` for detailed logs: ```bash app-ship upload -c app-ship.yaml -f app.apk --verbose ``` 2. Check: - Network connectivity - Platform service status - API Key validity and permissions - App package format 3. See [Issues](https://gitee.com/flu-cli/flu-cli/issues) --- ### Q: Does it work on Windows/Mac? Low-level adapters remain Node.js components, but the secure CLI credential path has only been verified with macOS Keychain and the local encrypted vault. Linux/Windows stop explicitly rather than fall back to plaintext YAML credentials. --- ### Q: Can I use it in CI/CD? Headless CI Keychain sessions and a dedicated CI credential provider have not been verified. Do not bypass the Profile requirement through plaintext configuration or command-line secrets. --- ## Security & Privacy ### 🔐 Credential Management - **Local custody**: Secrets use local secure storage and an encrypted vault; YAML contains only Profile references - **Redacted boundaries**: Logs, receipts, and MCP inputs/outputs do not contain raw credentials or service-account content - **Local Processing**: All auth and signing happens on your machine - **Official APIs**: Direct calls to platforms, no relay services ### 🛡️ Best Practices 1. **Protect config file** - Add to `.gitignore`: ```bash echo "app-ship.yaml" >> .gitignore ``` 2. **Use secure local Profiles** - Environment variables are migration inputs; an unverified headless CI path is not an available upload entry point 3. **Rotate credentials regularly** - Follow platform recommendations 4. **Minimize permissions** - Use least privilege for API Keys ### 📜 Legal Notice By using this tool, you agree to: - Comply with each platform's Terms of Service and API policies - Legally obtain and protect your credentials - Accept responsibility for any misuse The authors assume no liability for violations or damages. --- ## Development Guide ### Project Structure ``` packages/app-ship/ ├── src/ │ ├── index.ts # 📦 Library entry point │ ├── cli.ts # 🖥️ CLI entry point │ ├── types.ts # 📐 Type definitions │ ├── adapters/ # 🔌 Upload adapters │ ├── utils/ # 🔧 Utilities │ └── validators/ # ✅ Validators ├── dist/ ├── package.json └── tsconfig.json ``` ### Local Development ```bash # Install dependencies npm install # Build npm run build # Development mode (watch) npm run dev ``` --- ## Community Scan the QR code or search **Huoye Studio** on WeChat: | Follow Us | Join Group | Support | | :-------------------------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------: | | WeChat
**Huoye** | Group
WeChat: `Huoye-TT`
(note: `flu-cli`) | [Sponsor Us ☕️](http://huozhiye.cn/flu-cli/advanced/rewards/rewards) | > 💡 Click **Sponsor** on the extension details page to support us. --- ## License MIT | Copyright © 2025-2026 Huoye Studio