appship-ai
English · Tiếng Việt · Website
Release Android (Google Play) and iOS (App Store) apps from a single config file, powered by fastlane.
Each project only gets a release/ folder with its config, store listing and questionnaire answers. All release logic lives in the tool, so updating appship updates every project that uses it.
▶ Watch the 30-second intro on YouTube
# install (Node 22+ and fastlane required, see Install below)
npm i -g appship-ai
appship init # once per project
appship doctor # check everything before releasing
appship first-release # first time on the stores
appship upload --build # build, then push to TestFlight / a Google Play track
appship submit # iOS: send for App Review · Android: promote to production
Status: v0.3.0, early. The code is covered by tests and dry-runs, but it has not yet been run against the live stores. Try --dry-run and read-only commands such as appship status first. See the roadmap (Vietnamese).
Why
Shipping a mobile app means more than uploading a binary. There is the store listing, the screenshots, the age rating, privacy labels, export compliance, reviewer contacts, tracks and staged rollouts, across two consoles that each change often. fastlane can already do most of this, but every project ends up with its own copy-pasted Fastfile.
appship wraps fastlane in a small CLI:
- One config per project (
release/release.yml). There is no Fastfile to maintain in your app repo.
- Store questionnaires answered once (
release/questionnaire.yml). appship fills in whatever the store APIs allow. For the rest, it writes a CHECKLIST.md with your answers ready to copy into the console.
appship doctor catches problems before the stores do: character limits, placeholder text, image sizes, missing or malformed keys, and keys accidentally committed to git.- Keys are handled safely. You can use a named profile in
~/.appship, files in a gitignored release/keys/, or environment variables for CI.
- Works with any stack. appship runs your build command and picks up the
.ipa / .aab. Flutter, React Native, Cocos Creator and native projects are detected automatically.
What is automated
| iOS | Android |
|---|
| Create the app | first-release --create-app (needs an Apple ID login) | Manual: Google Play has no API. You get a checklist |
| Upload a build | TestFlight | internal / alpha / beta / production, staged rollout |
| Listing text and screenshots | push / pull | push / pull |
| Product Page Header image | upload to Asset Library and place on an editable version | — |
| Store questionnaires | Age rating, export compliance, content rights, review contact, App Privacy | Checklist pre-filled with your answers (content rating, data safety, target audience, ads, app access) |
| Submit | App Review | Promote a track to production |
| Status | Live / in review / pending / editable, latest TestFlight build | Version codes per track |
Requirements
- macOS for iOS builds and uploads. Android-only use also works on Linux.
- Node.js 22+
- fastlane:
brew install fastlane
- An Apple Developer Program account and/or a Google Play Console account
Install
brew install fastlane
# from npm: installs the `appship` command (alias: `appship-ai`)
npm i -g appship-ai
appship --help
npx appship-ai --help # or run without installing
# from GitHub
npm i -g git+https://github.com/ketchstudio/appship-ai.git
# from source
git clone https://github.com/ketchstudio/appship-ai.git
cd appship-ai && npm install && npm link
Quick start
# 1. Store keys, once per developer account
# App Store Connect API key (.p8) and/or a Google Play service account JSON
appship credentials add my-company
# 2. Set up a project
cd ~/Projects/my-app
appship init # detects framework, bundle id and package name
# 3. Fill in release/questionnaire.yml and release/*/metadata, add screenshots
# (for an app that is already live: appship metadata pull)
appship doctor # repeat until there are no errors
# 4. First release
appship first-release --create-app
# then follow release/CHECKLIST.md for the steps the stores keep manual
# 5. Every release after that
appship upload --build
appship submit
appship status
Every command that writes to a store asks for confirmation. Pass --yes in CI, and use --dry-run to see exactly what would be sent.
Set up with an AI agent
Paste this into an AI coding agent (Claude Code, Codex, Antigravity, Cursor…) opened at your project root. It installs appship, runs init, tells you which store keys to create, fills in the listing and questionnaire with the bundled skills, and runs appship doctor until it passes. It never writes to a store unless you ask, and never touches your key files.
Set up appship-ai in this project so I can release it to the App Store and Google Play.
appship is a CLI that wraps fastlane. Guide: https://appship.ketchsoft.com/docs.html
1. Check node (22+), fastlane and appship (`appship --version`). Tell me what is missing and ask before installing anything globally (`brew install fastlane`, `npm i -g appship-ai`).
2. Run `appship init --yes --agents <you>` at the project root, where <you> is claude, codex or antigravity (the agent you are; use claude if none fits). Compare release/release.yml with the project (build_command, artifact paths, bundle id, package name), fix what is wrong and tell me what you changed.
3. Store keys: tell me what I need (App Store Connect API key, Google Play service account JSON) and how to create them, following "Get store keys" in the guide. I will run `appship credentials add <profile>` in my own terminal. Then set credentials.profile in release.yml.
4. Fill the store content with the skills that init installed: app-content for release/questionnaire.yml, the listing text in release/*/metadata, then store-screenshots. If the skills are not loaded in this session, read their SKILL.md files in .claude/skills/ or .agents/skills/ and follow them. If the app is already live, ask me whether to run `appship metadata pull` first. Ask me for anything the code cannot tell you; leave contacts, demo accounts and passwords as TODO until I give them.
5. Run `appship doctor` and fix until there is no ✗. List the remaining warnings (!).
6. Finish with a short summary: what is done, what I still have to do by hand, and the next command to run.
Rules:
- Never run a command that writes to a store (upload, metadata push, submit, promote, first-release, signing import, header) unless I ask. Then run it with --dry-run first and wait for my OK. Add --yes only after I approved the dry run in this chat.
- Never open, print, copy or commit key files (*.p8, *.p12, *.jks, *.keystore, service account JSON) or anything in release/keys/.
- Do not commit or push.
- Reply in the language I write in.
More ready-made prompts (CI, every release, iOS signing without owner access) are in docs/prompts.md (explanations in Vietnamese, prompts in English) and on the website.
Project layout
my-app/
└── release/
├── release.yml # ids, artifacts, build commands, tracks, credentials
├── questionnaire.yml # answers to store questions
├── CHECKLIST.md # generated: manual console steps with your answers
├── ios/metadata/<locale>/*.txt
├── ios/screenshots/<locale>/*.png
├── android/metadata/<locale>/{*.txt, images/}
├── keys/ # gitignored; only if you don't use a profile
└── .appship/ # gitignored; scratch files for fastlane runs
Release notes in several languages
Both stores accept per-language release notes. Each locale is a folder:
- iOS ("What's New", max 4000 characters):
release/ios/metadata/<locale>/release_notes.txt, e.g. en-US, vi, ja, zh-Hans. Missing locales are created on App Store Connect automatically. Leave it empty for the very first version, which Apple does not accept notes for.
- Android (max 500 characters):
release/android/metadata/<locale>/changelogs/default.txt. The language must be enabled in Play Console first.
appship init also installs a release-notes skill for your AI coding agent (see AI agent skills). Ask the agent to "write the release notes": it reads git log since the last tag, writes the primary-locale text, translates it into every locale folder, fits the store limits, and runs appship doctor. It only edits the files above; you review them and push. Release notes stay plain files, so you can always edit them by hand.
Declare the languages per platform in release.yml (optional; without it every folder is used):
ios:
locales: [en-US, vi, ja]
android:
locales: [en-US, vi, ja-JP]
appship doctor then errors on a listed locale that has no folder, warns about a folder that is not listed, and rejects invalid App Store locale names before fastlane does. iOS and Android locale codes differ (zh-Hans vs zh-CN), so name the folders per platform. appship doctor checks length and warns when some locales have release notes and others don't. The full list of valid iOS locales is in docs/configuration.md (Vietnamese).
Suggested languages
To expand beyond the primary language, appship init --locales preset (or --locales es,ja) creates folders for Spanish (Spain and Latin America), Brazilian Portuguese, German, French, Japanese and Korean, and writes locales for each platform with that store's own codes:
| Language | iOS folder | Android folder |
|---|
| Spanish, Spain / Latin America | es-ES / es-MX | es-ES / es-419 |
| Portuguese, Brazil | pt-BR | pt-BR |
| German | de-DE | de-DE |
| French | fr-FR | fr-FR |
| Japanese | ja | ja-JP |
| Korean | ko | ko-KR |
The new folders hold TODO placeholders that appship doctor fails on until you translate them. doctor also warns about an Android folder that is not a Google Play language code (for example ja instead of ja-JP) and suggests the right one. The release-notes skill knows each language's conventions (formal or informal address, regional variants, Japanese punctuation, French spacing). Details are in docs/configuration.md (Vietnamese).
Credentials
For each value, the first source found wins:
- Environment variables (CI):
APPSHIP_ASC_KEY_ID, APPSHIP_ASC_ISSUER_ID, APPSHIP_ASC_KEY (the .p8 contents, plain or base64), APPSHIP_PLAY_JSON, …
release/release.yml: paths to files in the gitignored release/keys/.- A profile:
appship credentials add <name> copies the keys to ~/.appship/credentials/<name>/ with mode 600. Projects then only reference credentials.profile: <name>.
A ready-to-use GitHub Actions workflow is in examples/github-actions.yml.
iOS signing when you are not the account owner
Team API keys need an Account Holder or Admin, and so does creating certificates and profiles. If the owner gave you files instead, appship can work from them (it still doesn't build or sign for you; it audits the files, installs them and hands the signing setup to your build command):
ios:
build_command: 'flutter build ipa --release --export-options-plist="$APPSHIP_EXPORT_OPTIONS"'
signing:
style: manual
certificate: release/keys/AppleDistribution.p12 # Apple Distribution certificate + private key
profiles: [release/keys/AppStore.mobileprovision] # App Store profile, one per bundle id
APPSHIP_P12_PASSWORD=... appship signing import # install profiles, import the .p12
appship doctor # profile type/expiry/team/bundle id, keychain, the built .ipa
- No team API key? Create an individual key (no Issuer ID, leave
issuer_id empty). Not verified against a real account yet.
- No API key at all? Sign and build the same way, then upload the
.ipa with Transporter or Xcode.
- All five cases, CI usage and what
doctor checks: docs/signing.md (Vietnamese).
Commands
| Command | What it does |
|---|
init | Create release/ with config, questionnaire and metadata templates, and update .gitignore |
doctor | Check tools, config, credentials, git safety, artifacts, listing and questionnaire |
credentials add/list/remove | Manage credential profiles |
signing import / signing export-options | iOS: install the profiles and certificate you were given; write ExportOptions.plist for your build command |
build | Run the configured build commands |
upload | .ipa to TestFlight, .aab to a Play track (--track, --rollout 20%) |
metadata [push|pull] | Sync listing text and screenshots |
header --file <path> --app-version <version> | Upload and place an iOS Product Page Header image |
submit | iOS App Review / Android promote to production |
promote | Move an Android release between tracks or raise its rollout |
status | Review state and versions on both stores |
first-release | Create the iOS app, push the listing and App Privacy, write the checklist |
checklist | Regenerate release/CHECKLIST.md |
skills [list|add] | Install or update the bundled AI agent skills (.claude/skills/ for Claude Code, .agents/skills/ for Codex and Antigravity) |
Run appship <command> --help for all options.
AI agent skills (Claude Code, Codex, Antigravity)
appship ships three skills, plain SKILL.md instruction files that an AI coding agent follows. appship never calls an AI itself: open your agent at the project root, signed in with your own account, and ask. Each skill only writes files under release/, runs appship doctor, and hands back to you; none of them pushes to a store.
| Skill | Ask the agent | What it does |
|---|
release-notes | "write the release notes" | Notes from git log in every locale, within the store limits |
store-screenshots | "make the store screenshots" | Captures screens from the iOS Simulator or an Android emulator, adds a translated headline per language, renders exact store sizes (iPhone 6.9", iPad 13", Play 1080x1920), plus the Play icon and feature graphic |
app-content | "fill in the store questionnaire" | Fills questionnaire.yml (age rating, App Privacy, export compliance, Data safety, content rating, target audience, ads) from your dependencies, permissions and code, asks what code cannot show, keeps both stores consistent |
The same files work in each agent; only the folder and the way to call them differ:
| Agent | Skill folder | Run a skill |
|---|
| Claude Code | .claude/skills/ | /store-screenshots |
| Codex (CLI or IDE) | .agents/skills/ | $store-screenshots, or /skills |
| Antigravity | .agents/skills/ | "use the store-screenshots skill" |
appship init asks which agents you use (--agents claude,codex,antigravity, all or none; default Claude Code). Later, appship skills shows what each agent has and appship skills add --agent codex installs more (missing ones only; --force replaces edited copies). Setup per agent is in docs/skills.md (Vietnamese).
Documentation
The detailed guides are currently in Vietnamese:
Contributing
Issues and pull requests are welcome at ketchstudio/appship-ai.
npm install
npm test
Support
appship is free and MIT-licensed. If it saves you time, you can buy the maintainer a coffee on Ko-fi.
License
MIT © Ketchsoft. appship is a product powered by Ketchsoft.
