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

CODEBLOCK0

If not installed:

CODEBLOCK1

Or via RubyGems:

CODEBLOCK2

After install, add to your shell profile:

CODEBLOCK3

---

Authentication

App Store Connect API Key (Preferred)

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

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

CODEBLOCK4

Or pass the key inline as JSON:

CODEBLOCK5

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

CODEBLOCK6

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

CODEBLOCK7

Environment Variables — Authentication Reference

Variable	Purpose
INLINECODE1	API key ID from App Store Connect
INLINECODE2

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:

CODEBLOCK8

Discover available actions:

CODEBLOCK9

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

CODEBLOCK10

Equivalent:

CODEBLOCK11

With API key:

CODEBLOCK12

List Builds

CODEBLOCK13

Manage Testers

CODEBLOCK14

Distribute to External Testers

CODEBLOCK15

Common pilot Flags

Flag	Purpose
INLINECODE13	Path to IPA file
INLINECODE14

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

CODEBLOCK16

Equivalent:

CODEBLOCK17

Upload Metadata Only

CODEBLOCK18

Upload Screenshots Only

CODEBLOCK19

Download Existing Metadata

CODEBLOCK20

Download Existing Screenshots

CODEBLOCK21

Common deliver Flags

Flag	Purpose
INLINECODE21	Path to IPA file
INLINECODE22

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

CODEBLOCK22

Equivalent:

CODEBLOCK23

Build with Xcode Project (no workspace)

CODEBLOCK24

Export Methods

Method	Use Case
INLINECODE34	App Store and TestFlight submission
INLINECODE35

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
INLINECODE41	Path to INLINECODE42
INLINECODE43

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

CODEBLOCK25

Equivalent:

CODEBLOCK26

Sync for Development

CODEBLOCK27

Sync for Ad Hoc

CODEBLOCK28

Read-Only Mode (CI)

CODEBLOCK29

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

Nuke (Reset All Certificates)

CODEBLOCK30

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

Common match Flags

Flag	Purpose
INLINECODE62	INLINECODE63, development, adhoc, INLINECODE66
INLINECODE67

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

CODEBLOCK31

Equivalent:

CODEBLOCK32

Run on Multiple Devices

CODEBLOCK33

Output Formats

CODEBLOCK34

Common scan Flags

Flag	Purpose
INLINECODE79	Path to INLINECODE80
INLINECODE81

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

CODEBLOCK35

Equivalent:

CODEBLOCK36

Common snapshot Flags

Flag	Purpose
INLINECODE96	Path to INLINECODE97
INLINECODE98

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

CODEBLOCK37

Equivalent:

CODEBLOCK38

Create/Fetch a Provisioning Profile

CODEBLOCK39

Equivalent:

CODEBLOCK40

Repair Profiles

CODEBLOCK41

Common Flags

Flag	Purpose
INLINECODE105	Development cert/profile
INLINECODE106

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.

CODEBLOCK42

Equivalent:

CODEBLOCK43

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.

CODEBLOCK44

Equivalent:

CODEBLOCK45

Common pem Flags

Flag	Purpose
INLINECODE114	Bundle ID
INLINECODE115

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.

CODEBLOCK46

With titles:

CODEBLOCK47

Equivalent:

CODEBLOCK48

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

---

Common Workflows

Build + Upload to TestFlight

CODEBLOCK49

Build + Submit to App Store

CODEBLOCK50

Sync Signing + Build + Upload

CODEBLOCK51

Test + Build + Upload

CODEBLOCK52

Screenshots + Frames + Upload

CODEBLOCK53

---

Environment Variables

General

Variable	Purpose
INLINECODE124	Timeout for xcodebuild settings (seconds)
INLINECODE125

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
INLINECODE132	Set to true on CI environments
INLINECODE134

Don't save passwords to keychain | | MATCH_KEYCHAIN_NAME | Keychain name for CI | | MATCH_KEYCHAIN_PASSWORD | Keychain password for CI |

Xcode

Variable	Purpose
INLINECODE137	Default workspace path
INLINECODE138

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.