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

fastlane --version

If not installed:

brew install fastlane

Or via RubyGems:

sudo gem install fastlane -NV

After install, add to your shell profile:

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.

1. Generate a key at App Store Connect → Users and Access → Keys.
2. Download the

   .p8

   file.
3. Set environment variables:

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:

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

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:

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

APP_STORE_CONNECT_API_KEY_KEY_ID

APP_STORE_CONNECT_API_KEY_ISSUER_ID

APP_STORE_CONNECT_API_KEY_KEY_FILEPATH

.p8

APP_STORE_CONNECT_API_KEY_KEY

FASTLANE_USER

FASTLANE_PASSWORD

FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD

MATCH_PASSWORD

MATCH_GIT_URL

One-Off Action Execution

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

fastlane run <action_name> key:value key2:value2

Discover available actions:

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

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

Equivalent:

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

With API key:

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

List Builds

fastlane pilot builds

Manage Testers

# 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

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

Common pilot Flags

--ipa

--app_identifier

com.example.app

--skip_waiting_for_build_processing

--distribute_external

--groups

--changelog

--beta_app_review_info

deliver (App Store)

Submit to App Store

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

Equivalent:

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

Upload Metadata Only

fastlane deliver --skip_binary_upload --skip_screenshots

Upload Screenshots Only

fastlane deliver --skip_binary_upload --skip_metadata

Download Existing Metadata

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

Download Existing Screenshots

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

Common deliver Flags

--ipa

--pkg

--app_identifier

--submit_for_review

--automatic_release

--force

--skip_binary_upload

--skip_metadata

--skip_screenshots

--metadata_path

--screenshots_path

--phased_release

--reject_if_possible

gym / build_app (Build)

Build an IPA

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

Equivalent:

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

Build with Xcode Project (no workspace)

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

Export Methods

app-store

ad-hoc

development

enterprise

developer-id

mac-application

validation

Common gym Flags

--workspace

.xcworkspace

--project

.xcodeproj

--scheme

--configuration

--export_method

--output_directory

--output_name

--clean

--include_bitcode

--include_symbols

--xcargs

--derived_data_path

--catalyst_platform

macos

ios

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

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

Equivalent:

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

Sync for Development

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

Sync for Ad Hoc

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

Read-Only Mode (CI)

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)

# 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

--type

appstore

development

adhoc

enterprise

--app_identifier

--git_url

--readonly

--force

--team_id

--storage_mode

git

google_cloud

s3

--verbose

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

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

Equivalent:

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

Run on Multiple Devices

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

Output Formats

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

Common scan Flags

--workspace

.xcworkspace

--project

.xcodeproj

--scheme

--device

--devices

--output_types

html

junit

json

--output_directory

--code_coverage

--clean

--fail_build

--xcargs

--result_bundle

snapshot (Screenshots)

Capture App Store screenshots across devices and languages automatically.

Capture Screenshots

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:

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

--workspace

.xcworkspace

--scheme

--devices

--languages

--output_directory

--clear_previous_screenshots

--stop_after_first_error

--override_status_bar

cert + sigh (Certificates & Profiles)

Standalone certificate and provisioning profile management.

Create/Fetch a Certificate

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

Equivalent:

fastlane run get_certificates development:true

Create/Fetch a Provisioning Profile

# 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:

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

Repair Profiles

fastlane sigh repair

Common Flags

--development

--adhoc

--app_identifier

--team_id

--output_path

--force

--readonly

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.

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

Equivalent:

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.

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

Equivalent:

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

Common pem Flags

--app_identifier

--output_path

--development

--generate_p12

--p12_password

--force

--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.

fastlane frameit --path "./screenshots"

With titles:

fastlane frameit silver --path "./screenshots"

Equivalent:

fastlane run frame_screenshots path:"./screenshots"

A

Framefile.json

Common Workflows

Build + Upload to TestFlight

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

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

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

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

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

FASTLANE_XCODEBUILD_SETTINGS_TIMEOUT

FASTLANE_XCODEBUILD_SETTINGS_RETRIES

FASTLANE_OPT_OUT_USAGE

YES

FL_OUTPUT_DIR

FASTLANE_SKIP_UPDATE_CHECK

FASTLANE_HIDE_TIMESTAMP

FASTLANE_DISABLE_COLORS

CI-Specific

CI

true

FASTLANE_DONT_STORE_PASSWORD

MATCH_KEYCHAIN_NAME

MATCH_KEYCHAIN_PASSWORD

Xcode

GYM_WORKSPACE

GYM_SCHEME

GYM_OUTPUT_DIRECTORY

GYM_EXPORT_METHOD

SCAN_WORKSPACE

SCAN_SCHEME

SCAN_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.