Fastlane

iOS/macOS app automation — builds, signing, TestFlight, App Store via CLI

Install

openclaw skills install @alexissan/fastlane

Fastlane

Automate iOS and macOS builds, code signing, TestFlight distribution, and App Store submissions — all from one-off CLI commands. No Fastfile required.

Verify Installation

bash

fastlane --version

If not installed:

bash

brew install fastlane

Or via RubyGems:

bash

sudo gem install fastlane -NV

After install, add to your shell profile:

bash

export PATH="$HOME/.fastlane/bin:$PATH"

Authentication

App Store Connect API Key (Preferred)

API keys avoid 2FA prompts and are the recommended approach for automation and CI.

Generate a key at App Store Connect → Users and Access → Keys.
Download the .p8 file.
Set environment variables:

bash

export APP_STORE_CONNECT_API_KEY_KEY_ID="XXXXXXXXXX"
export APP_STORE_CONNECT_API_KEY_ISSUER_ID="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
export APP_STORE_CONNECT_API_KEY_KEY_FILEPATH="/path/to/AuthKey_XXXXXXXXXX.p8"

Or pass the key inline as JSON:

bash

export APP_STORE_CONNECT_API_KEY_KEY='{"key_id":"XXXXXXXXXX","issuer_id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","key_filepath":"/path/to/AuthKey.p8"}'

Agent guidance: Always prefer API key authentication. Only fall back to Apple ID when the user explicitly does not have API key access.

Apple ID Fallback

bash

export FASTLANE_USER="user@example.com"
export FASTLANE_PASSWORD="app-specific-password"

Generate an app-specific password at appleid.apple.com. If 2FA is enabled, you may also need:

bash

export FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD="xxxx-xxxx-xxxx-xxxx"
export SPACESHIP_2FA_SMS_DEFAULT_PHONE_NUMBER="+1 (xxx) xxx-xxxx"

Environment Variables — Authentication Reference

Variable	Purpose
`APP_STORE_CONNECT_API_KEY_KEY_ID`	API key ID from App Store Connect
`APP_STORE_CONNECT_API_KEY_ISSUER_ID`	Issuer ID from App Store Connect
`APP_STORE_CONNECT_API_KEY_KEY_FILEPATH`	Path to the `.p8` private key file
`APP_STORE_CONNECT_API_KEY_KEY`	Inline JSON containing all key fields
`FASTLANE_USER`	Apple ID email
`FASTLANE_PASSWORD`	Apple ID password or app-specific password
`FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD`	App-specific password for 2FA accounts
`MATCH_PASSWORD`	Encryption password for match certificates repo
`MATCH_GIT_URL`	Git URL for match certificates repository

One-Off Action Execution

Fastlane actions can be run directly from the CLI without a Fastfile:

bash

fastlane run <action_name> key:value key2:value2

Discover available actions:

bash

fastlane actions                    # List all actions
fastlane action <action_name>      # Show details for one action
fastlane search_actions <query>    # Search by keyword

Agent guidance: Use fastlane run <action> for one-off tasks. This is the core pattern — every section below shows both the shorthand tool command and the fastlane run equivalent.

pilot (TestFlight)

Upload a Build to TestFlight

bash

fastlane pilot upload --ipa "/path/to/App.ipa"

Equivalent:

bash

fastlane run upload_to_testflight ipa:"/path/to/App.ipa"

With API key:

bash

fastlane pilot upload \
  --ipa "/path/to/App.ipa" \
  --api_key_path "/path/to/api_key.json"

List Builds

bash

fastlane pilot builds

Manage Testers

bash

# Add a tester
fastlane pilot add email:"tester@example.com" group_name:"Beta Testers"

# Remove a tester
fastlane pilot remove email:"tester@example.com"

# List testers
fastlane pilot list

Distribute to External Testers

bash

fastlane pilot distribute \
  --build_number "42" \
  --groups "External Beta" \
  --changelog "Bug fixes and performance improvements"

Common pilot Flags

Flag	Purpose
`--ipa`	Path to IPA file
`--app_identifier`	Bundle ID (e.g., `com.example.app`)
`--skip_waiting_for_build_processing`	Don't wait for Apple's processing
`--distribute_external`	Send to external testers
`--groups`	Tester group names (comma-separated)
`--changelog`	What to Test text
`--beta_app_review_info`	JSON with review info

deliver (App Store)

Submit to App Store

bash

fastlane deliver --ipa "/path/to/App.ipa" --submit_for_review

Equivalent:

bash

fastlane run upload_to_app_store ipa:"/path/to/App.ipa" submit_for_review:true

Upload Metadata Only

bash

fastlane deliver --skip_binary_upload --skip_screenshots

Upload Screenshots Only

bash

fastlane deliver --skip_binary_upload --skip_metadata

Download Existing Metadata

bash

fastlane deliver download_metadata --app_identifier "com.example.app"

Download Existing Screenshots

bash

fastlane deliver download_screenshots --app_identifier "com.example.app"

Common deliver Flags

Flag	Purpose
`--ipa`	Path to IPA file
`--pkg`	Path to PKG file (macOS)
`--app_identifier`	Bundle ID
`--submit_for_review`	Auto-submit after upload
`--automatic_release`	Release automatically after approval
`--force`	Skip HTML preview verification
`--skip_binary_upload`	Metadata/screenshots only
`--skip_metadata`	Binary/screenshots only
`--skip_screenshots`	Binary/metadata only
`--metadata_path`	Custom metadata folder path
`--screenshots_path`	Custom screenshots folder path
`--phased_release`	Enable phased release
`--reject_if_possible`	Reject current version before uploading

gym / build_app (Build)

Build an IPA

bash

fastlane gym \
  --workspace "App.xcworkspace" \
  --scheme "App" \
  --export_method "app-store" \
  --output_directory "./build"

Equivalent:

bash

fastlane run build_app \
  workspace:"App.xcworkspace" \
  scheme:"App" \
  export_method:"app-store" \
  output_directory:"./build"

Build with Xcode Project (no workspace)

bash

fastlane gym \
  --project "App.xcodeproj" \
  --scheme "App" \
  --export_method "app-store"

Export Methods

Method	Use Case
`app-store`	App Store and TestFlight submission
`ad-hoc`	Direct device installation via profile
`development`	Debug builds for registered devices
`enterprise`	In-house enterprise distribution
`developer-id`	macOS distribution outside App Store
`mac-application`	macOS App Store
`validation`	Validate without exporting

Common gym Flags

Flag	Purpose
`--workspace`	Path to `.xcworkspace`
`--project`	Path to `.xcodeproj`
`--scheme`	Build scheme
`--configuration`	Build config (Debug/Release)
`--export_method`	See export methods table
`--output_directory`	Where to save the IPA
`--output_name`	Custom IPA filename
`--clean`	Clean before building
`--include_bitcode`	Include bitcode
`--include_symbols`	Include dSYM symbols
`--xcargs`	Extra xcodebuild arguments
`--derived_data_path`	Custom DerivedData path
`--catalyst_platform`	`macos` or `ios` for Catalyst apps

Agent guidance: If the project has a .xcworkspace (e.g., uses CocoaPods or SPM), always use --workspace. Only use --project when there is no workspace.

match (Code Signing)

Sync certificates and provisioning profiles from a shared Git repo or cloud storage.

Sync for App Store

bash

fastlane match appstore --app_identifier "com.example.app"

Equivalent:

bash

fastlane run sync_code_signing type:"appstore" app_identifier:"com.example.app"

Sync for Development

bash

fastlane match development --app_identifier "com.example.app"

Sync for Ad Hoc

bash

fastlane match adhoc --app_identifier "com.example.app"

Read-Only Mode (CI)

bash

fastlane match appstore --readonly --app_identifier "com.example.app"

Agent guidance: Always use --readonly on CI servers. This prevents accidentally creating new certificates and disrupting the team.

Nuke (Reset All Certificates)

bash

# Remove all certificates and profiles for a type
fastlane match nuke appstore
fastlane match nuke development

Warning: Nuke is destructive and irreversible. Always confirm with the user before running nuke commands.

Common match Flags

Flag	Purpose
`--type`	`appstore`, `development`, `adhoc`, `enterprise`
`--app_identifier`	Bundle ID(s), comma-separated for multiple
`--git_url`	Git repo URL for certificates
`--readonly`	Don't create new certs/profiles
`--force`	Renew existing profile
`--team_id`	Apple Developer team ID
`--storage_mode`	`git`, `google_cloud`, `s3`
`--verbose`	Detailed output

Agent guidance: Prefer match over cert + sigh for teams. It centralizes signing and avoids the "works on my machine" problem.

scan / run_tests (Testing)

Run Tests

bash

fastlane scan \
  --workspace "App.xcworkspace" \
  --scheme "AppTests" \
  --device "iPhone 16 Pro"

Equivalent:

bash

fastlane run run_tests \
  workspace:"App.xcworkspace" \
  scheme:"AppTests" \
  device:"iPhone 16 Pro"

Run on Multiple Devices

bash

fastlane scan \
  --workspace "App.xcworkspace" \
  --scheme "AppTests" \
  --devices "iPhone 16 Pro,iPad Pro (13-inch) (M4)"

Output Formats

bash

fastlane scan \
  --scheme "AppTests" \
  --output_types "html,junit" \
  --output_directory "./test_results"

Common scan Flags

Flag	Purpose
`--workspace`	Path to `.xcworkspace`
`--project`	Path to `.xcodeproj`
`--scheme`	Test scheme
`--device`	Simulator device name
`--devices`	Multiple simulators (comma-separated)
`--output_types`	`html`, `junit`, `json`
`--output_directory`	Where to save results
`--code_coverage`	Enable code coverage
`--clean`	Clean before testing
`--fail_build`	Fail on test failures (default: true)
`--xcargs`	Extra xcodebuild arguments
`--result_bundle`	Generate Xcode result bundle

snapshot (Screenshots)

Capture App Store screenshots across devices and languages automatically.

Capture Screenshots

bash

fastlane snapshot \
  --workspace "App.xcworkspace" \
  --scheme "AppUITests" \
  --devices "iPhone 16 Pro Max,iPhone SE (3rd generation),iPad Pro (13-inch) (M4)" \
  --languages "en-US,es-ES,fr-FR" \
  --output_directory "./screenshots"

Equivalent:

bash

fastlane run capture_screenshots \
  workspace:"App.xcworkspace" \
  scheme:"AppUITests" \
  devices:"iPhone 16 Pro Max,iPhone SE (3rd generation),iPad Pro (13-inch) (M4)" \
  languages:"en-US,es-ES,fr-FR" \
  output_directory:"./screenshots"

Common snapshot Flags

Flag	Purpose
`--workspace`	Path to `.xcworkspace`
`--scheme`	UI test scheme with snapshot calls
`--devices`	Simulator names (comma-separated)
`--languages`	Locale codes (comma-separated)
`--output_directory`	Where to save screenshots
`--clear_previous_screenshots`	Clean output folder first
`--stop_after_first_error`	Abort on first failure
`--override_status_bar`	Clean status bar (9:41, full battery)

cert + sigh (Certificates & Profiles)

Standalone certificate and provisioning profile management.

Create/Fetch a Certificate

bash

fastlane cert --development
fastlane cert  # Distribution certificate by default

Equivalent:

bash

fastlane run get_certificates development:true

Create/Fetch a Provisioning Profile

bash

# App Store profile
fastlane sigh --app_identifier "com.example.app"

# Development profile
fastlane sigh --development --app_identifier "com.example.app"

# Ad hoc profile
fastlane sigh --adhoc --app_identifier "com.example.app"

Equivalent:

bash

fastlane run get_provisioning_profile app_identifier:"com.example.app"

Repair Profiles

bash

fastlane sigh repair

Common Flags

Flag	Purpose
`--development`	Development cert/profile
`--adhoc`	Ad hoc profile
`--app_identifier`	Bundle ID
`--team_id`	Developer team ID
`--output_path`	Where to save profile
`--force`	Renew even if current is valid
`--readonly`	Don't create, only fetch

Agent guidance: For individual developers, cert + sigh works fine. For teams, recommend match instead — it prevents certificate conflicts.

precheck (Validation)

Validate app metadata before submitting to avoid App Store Review rejections.

bash

fastlane precheck --app_identifier "com.example.app"

Equivalent:

bash

fastlane run check_app_store_metadata app_identifier:"com.example.app"

What precheck Validates

Unreachable URLs in metadata
Mentions of other platforms (Android, etc.)
Profanity or inappropriate content
Placeholder text
Copyright date accuracy

pem (Push Notification Certificates)

Generate push notification certificates for APNs.

bash

fastlane pem --app_identifier "com.example.app" --output_path "./certs"

Equivalent:

bash

fastlane run get_push_certificate app_identifier:"com.example.app" output_path:"./certs"

Common pem Flags

Flag	Purpose
`--app_identifier`	Bundle ID
`--output_path`	Where to save certs
`--development`	Development push cert
`--generate_p12`	Also generate .p12 file
`--p12_password`	Password for .p12
`--force`	Create new even if existing is valid
`--team_id`	Developer team ID

Agent guidance: For modern projects using token-based APNs (.p8 key), push certs are unnecessary. Only use pem if the project specifically uses certificate-based APNs.

frameit (Screenshot Frames)

Add device bezels and titles to screenshots for App Store presentation.

bash

fastlane frameit --path "./screenshots"

With titles:

bash

fastlane frameit silver --path "./screenshots"

Equivalent:

bash

fastlane run frame_screenshots path:"./screenshots"

A Framefile.json in the screenshots directory controls titles, fonts, and colors.

Common Workflows

Build + Upload to TestFlight

bash

fastlane gym \
  --workspace "App.xcworkspace" \
  --scheme "App" \
  --export_method "app-store" \
  --output_directory "./build" && \
fastlane pilot upload \
  --ipa "./build/App.ipa" \
  --changelog "Latest build from CI"

Build + Submit to App Store

bash

fastlane gym \
  --workspace "App.xcworkspace" \
  --scheme "App" \
  --export_method "app-store" \
  --output_directory "./build" && \
fastlane deliver \
  --ipa "./build/App.ipa" \
  --submit_for_review \
  --automatic_release \
  --force

Sync Signing + Build + Upload

bash

fastlane match appstore \
  --app_identifier "com.example.app" \
  --readonly && \
fastlane gym \
  --workspace "App.xcworkspace" \
  --scheme "App" \
  --export_method "app-store" \
  --output_directory "./build" && \
fastlane pilot upload \
  --ipa "./build/App.ipa"

Test + Build + Upload

bash

fastlane scan \
  --workspace "App.xcworkspace" \
  --scheme "AppTests" && \
fastlane gym \
  --workspace "App.xcworkspace" \
  --scheme "App" \
  --export_method "app-store" \
  --output_directory "./build" && \
fastlane pilot upload \
  --ipa "./build/App.ipa"

Screenshots + Frames + Upload

bash

fastlane snapshot \
  --workspace "App.xcworkspace" \
  --scheme "AppUITests" \
  --output_directory "./screenshots" && \
fastlane frameit silver --path "./screenshots" && \
fastlane deliver --skip_binary_upload --skip_metadata

Environment Variables

General

Variable	Purpose
`FASTLANE_XCODEBUILD_SETTINGS_TIMEOUT`	Timeout for xcodebuild settings (seconds)
`FASTLANE_XCODEBUILD_SETTINGS_RETRIES`	Retry count for xcodebuild
`FASTLANE_OPT_OUT_USAGE`	Set to `YES` to disable analytics
`FL_OUTPUT_DIR`	Default output directory
`FASTLANE_SKIP_UPDATE_CHECK`	Skip update prompts
`FASTLANE_HIDE_TIMESTAMP`	Hide log timestamps
`FASTLANE_DISABLE_COLORS`	Disable colored output

CI-Specific

Variable	Purpose
`CI`	Set to `true` on CI environments
`FASTLANE_DONT_STORE_PASSWORD`	Don't save passwords to keychain
`MATCH_KEYCHAIN_NAME`	Keychain name for CI
`MATCH_KEYCHAIN_PASSWORD`	Keychain password for CI

Xcode

Variable	Purpose
`GYM_WORKSPACE`	Default workspace path
`GYM_SCHEME`	Default scheme
`GYM_OUTPUT_DIRECTORY`	Default output directory
`GYM_EXPORT_METHOD`	Default export method
`SCAN_WORKSPACE`	Default workspace for tests
`SCAN_SCHEME`	Default test scheme
`SCAN_DEVICE`	Default test device

Notes

CLI Syntax Rules

All fastlane run parameters use key:value syntax (no dashes, no equals signs).
Tool shorthand commands (fastlane gym, fastlane pilot) use --key value or --key "value" syntax.
Boolean parameters: true/false for fastlane run, --flag/no flag for shorthand.
Array parameters: comma-separated strings (e.g., devices:"iPhone 16,iPad Pro").
Paths with spaces must be quoted.

Error Handling

Session expired: Re-authenticate with fastlane spaceauth -u user@example.com or refresh API key.
Code signing errors: Run fastlane match to sync, or security find-identity -v -p codesigning to verify local certs.
"Could not find App": Verify app_identifier matches the bundle ID registered in App Store Connect.
Timeout on upload: Set FASTLANE_XCODEBUILD_SETTINGS_TIMEOUT=120 and retry.
Profile mismatch: Run fastlane sigh repair or fastlane match with --force.

Agent Tips

When a user asks to "deploy" or "release" an iOS app, the typical flow is: match (sign) → gym (build) → pilot (TestFlight) or deliver (App Store).

If the user has a Fastfile, respect it. But for one-off commands, always use the CLI syntax shown in this skill.

Always check for an existing .xcworkspace before defaulting to .xcodeproj. Run ls *.xcworkspace to verify.

For CI environments, always use --readonly with match and set the CI=true environment variable.

When in doubt about which action to use, run fastlane actions or fastlane search_actions <keyword> to discover the right one.

Fastlane

Install

Fastlane

Verify Installation

Authentication

App Store Connect API Key (Preferred)

Apple ID Fallback

Environment Variables — Authentication Reference

One-Off Action Execution

pilot (TestFlight)

Upload a Build to TestFlight

List Builds

Manage Testers

Distribute to External Testers

Common pilot Flags

deliver (App Store)

Submit to App Store

Upload Metadata Only

Upload Screenshots Only

Download Existing Metadata

Download Existing Screenshots

Common deliver Flags

gym / build_app (Build)

Build an IPA

Build with Xcode Project (no workspace)

Export Methods

Common gym Flags

match (Code Signing)

Sync for App Store

Sync for Development

Sync for Ad Hoc

Read-Only Mode (CI)

Nuke (Reset All Certificates)

Common match Flags

scan / run_tests (Testing)

Run Tests

Run on Multiple Devices

Output Formats

Common scan Flags

snapshot (Screenshots)

Capture Screenshots

Common snapshot Flags

cert + sigh (Certificates & Profiles)

Create/Fetch a Certificate

Create/Fetch a Provisioning Profile

Repair Profiles

Common Flags

precheck (Validation)

What precheck Validates

pem (Push Notification Certificates)

Common pem Flags

frameit (Screenshot Frames)

Common Workflows

Build + Upload to TestFlight

Build + Submit to App Store

Sync Signing + Build + Upload

Test + Build + Upload

Screenshots + Frames + Upload

Environment Variables

General

CI-Specific

Xcode

Notes

CLI Syntax Rules

Error Handling

Agent Tips

Related skills