zuke.tools.apple

class AltoolSettings(ToolSettings)

• file(path: str) -> Self

  The .ipa or .pkg to upload or validate (--file); required.

• type_(platform: Literal['ios', 'macos', 'appletvos', 'visionos']) -> Self

  The app's platform (--type); required.

• api_key(key_id: str, issuer_id: str) -> Self

  Authenticate with an App Store Connect API key: its key id and issuer id (--apiKey, --apiIssuer). altool finds AuthKey_<keyId>.p8 in ~/.appstoreconnect/private_keys and its other search directories, or in apiPrivateKeysDir.

• api_private_keys_dir(path: str) -> Self

  The directory holding AuthKey_<keyId>.p8, passed to altool as API_PRIVATE_KEYS_DIR.

• apple_id(username: str, password: str) -> Self

  Authenticate with an Apple ID and an app-specific password (--username, --password). The password is handed to altool in an environment variable it reads through @env:, so it is never on the command line, and it is registered with the run's redactor.

class AltoolTasks

• static async upload_app(ctx: ServiceContext, configure: Callable[[AltoolSettings], AltoolSettings]) -> ExecResult

  Upload an app to App Store Connect: xcrun altool --upload-app.

• static async validate_app(ctx: ServiceContext, configure: Callable[[AltoolSettings], AltoolSettings]) -> ExecResult

  Validate an app without uploading it: xcrun altool --validate-app.

class AppStoreConnectSettings(Settings)

• issuer_id(id: str) -> Self

  The API key's issuer id, a UUID.

• key_id(id: str) -> Self

  The API key's id, e.g. ABC123.

• private_key(pem: str) -> Self

  The private key, as the PEM text of AuthKey_<keyId>.p8.

• private_key_file(path: str) -> Self

  Read the private key from AuthKey_<keyId>.p8.

• api_url(url: str) -> Self

  The API's base URL, https://api.appstoreconnect.apple.com by default. It carries the token, so it must be https: unless it is loopback or ZUKE_ALLOW_INSECURE_URL is set.

class CodesignDisplaySettings(CodesignSettings)

class CodesignSettings(ToolSettings)

• file(*paths: str) -> Self

  The code to act on (positional) — an app bundle, framework, binary or disk image; repeatable. A relative path starting with - is passed as ./-… so codesign cannot read it as an option.

• verbose(level: float | None=None) -> Self

  More output (--verbose, or --verbose=<level> with a level). display shows more of the signature at each level; 4 lists everything.

class CodesignSignSettings(CodesignSettings)

• identity(value: str) -> Self

  The signing identity (--sign <identity>): a certificate's common name, a substring of it, or its SHA-1 hash. - signs ad hoc. Required.

• force() -> Self

  Replace an existing signature (--force).

• deep() -> Self

  Sign nested code as well (--deep). Apple discourages it for signing.

• options(*flags: str) -> Self

  Signature option flags (--options, comma-joined); repeatable. runtime enables the hardened runtime notarization requires.

• timestamp(url: str | None=None) -> Self

  Request a secure timestamp (--timestamp), from url when given (--timestamp=<url>). Notarization requires one.

• entitlements(path: str) -> Self

  The entitlements plist to embed (--entitlements).

• keychain(path: str) -> Self

  Look the identity up in this keychain only (--keychain).

• identifier(value: str) -> Self

  The code's identifier (--identifier), overriding the bundle id.

class CodesignTasks

• static async sign(ctx: ServiceContext, configure: Callable[[CodesignSignSettings], CodesignSignSettings]) -> ExecResult

  Sign code with codesign --sign.

• static async verify(ctx: ServiceContext, configure: Callable[[CodesignVerifySettings], CodesignVerifySettings]) -> ExecResult

  Check a signature with codesign --verify; a bad one fails the run.

• static async display(ctx: ServiceContext, configure: Callable[[CodesignDisplaySettings], CodesignDisplaySettings]) -> object

  Describe a signature with codesign --display. codesign prints the description on stderr, so it is returned parsed, with the raw text and the command output alongside.

class CodesignVerifySettings(CodesignSettings)

• strict() -> Self

  Apply the strict validation rules notarization uses (--strict).

• deep() -> Self

  Verify nested code as well (--deep).

class DittoSettings(ToolSettings)

• create() -> Self

  Create an archive rather than copy (-c).

• extract() -> Self

  Extract an archive rather than copy (-x).

• pkzip() -> Self

  Use the PKZip format for the archive (-k) instead of CPIO.

• sequester_rsrc() -> Self

  Keep resource forks and HFS metadata in a __MACOSX directory inside the archive (--sequesterRsrc), the way the Finder's own compress does.

• keep_parent() -> Self

  Put the source directory itself in the archive, not only its contents (--keepParent) — what makes a zipped MyApp.app unzip as MyApp.app.

• source(path: str) -> Self

  What to copy or archive (positional). Required.

• destination(path: str) -> Self

  Where to write it (positional). Required.

class DittoTasks

• static async copy(ctx: ServiceContext, configure: Callable[[DittoSettings], DittoSettings]) -> ExecResult

  Copy a file or directory tree with ditto, metadata intact.

• static async archive(ctx: ServiceContext, configure: Callable[[DittoSettings], DittoSettings]) -> ExecResult

  Write a zip archive: ditto -c -k, then the lambda's settings.

• static async extract(ctx: ServiceContext, configure: Callable[[DittoSettings], DittoSettings]) -> ExecResult

  Unpack a zip archive: ditto -x -k, then the lambda's settings.

class ExportOptionsSettings(Settings)

• method(method: Literal['app-store-connect', 'release-testing', 'enterprise', 'debugging', 'developer-id', 'mac-application', 'validation', 'app-store', 'ad-hoc', 'development']) -> Self

  How the archive is exported (method); required.

• team_id(id: str) -> Self

  The developer team id (teamID).

• signing_style(style: Literal['automatic', 'manual']) -> Self

  Automatic or manual signing (signingStyle).

• signing_certificate(name: str) -> Self

  The certificate to sign with, e.g. Apple Distribution (signingCertificate).

• provisioning_profile(bundle_id: str, profile: str) -> Self

  The provisioning profile, by name or UUID, for one bundle identifier (provisioningProfiles); repeatable, once per app and extension.

• destination(destination: Literal['export', 'upload']) -> Self

  Export to a directory, or upload to App Store Connect (destination).

• upload_symbols(enabled: bool) -> Self

  Include symbols for crash reports (uploadSymbols).

• manage_app_version_and_build_number(enabled: bool) -> Self

  Let App Store Connect manage the version and build number (manageAppVersionAndBuildNumber).

• strip_swift_symbols(enabled: bool) -> Self

  Strip Swift symbols from the binary (stripSwiftSymbols).

• test_flight_internal_testing_only(enabled: bool) -> Self

  Limit a TestFlight upload to internal testers (testFlightInternalTestingOnly).

class NotarytoolHistorySettings(NotarytoolSettings)

class NotarytoolInfoSettings(NotarytoolSettings)

• submission_id(id: str) -> Self

  The submission to describe (positional). Required.

class NotarytoolLogSettings(NotarytoolSettings)

• submission_id(id: str) -> Self

  The submission whose log to fetch (positional). Required.

class NotarytoolSettings(ToolSettings)

• key(path: str) -> Self

  The App Store Connect API private key file, AuthKey_<id>.p8 (--key).

• key_id(id: str) -> Self

  The API key's id (--key-id).

• issuer(uuid: str) -> Self

  The API key's issuer UUID (--issuer); omit it for an individual key.

• keychain_profile(name: str) -> Self

  Authenticate with credentials saved by notarytool store-credentials (--keychain-profile).

• keychain(path: str) -> Self

  The keychain to read the keychainProfile from (--keychain).

• apple_id(email: str) -> Self

  The Apple ID to authenticate as (--apple-id).

• password(value: str) -> Self

  The Apple ID's app-specific password (--password). Registered with the run's redactor and masked out of any error this run raises.

• team_id(id: str) -> Self

  The developer team id the Apple ID signs for (--team-id).

• tool_path(path: str) -> Self

  Override the binary, remembered so a follow-up command uses it too.

• env(record: Mapping[str, str]) -> Self

  Merge environment variables, remembered for a follow-up command too.

• cwd(path: str) -> Self

  Set the working directory, remembered for a follow-up command too.

class NotarytoolSubmitSettings(NotarytoolSettings)

• file(path: str) -> Self

  The archive to notarize — a .zip, .pkg or .dmg (positional). Required.

• wait() -> Self

  Wait for Apple to finish processing (--wait). With it the result carries the final status, and NotarytoolTasks.submit throws a NotarizationError for anything but Accepted.

• timeout(duration: str) -> Self

  How long --wait waits, e.g. 30m or 1h (--timeout). Needs wait.

• log_for(id: str) -> NotarytoolLogSettings

  Settings for notarytool log <id> that reuse this submission's credentials, binary, environment and working directory.

class NotarytoolTasks

• static async submit(ctx: ServiceContext, configure: Callable[[NotarytoolSubmitSettings], NotarytoolSubmitSettings]) -> object

  Upload an archive with notarytool submit and return the parsed result. With .wait(), a final status other than Accepted fetches the submission's log and throws a NotarizationError listing its issues — unless .noThrow() was set, when the result is returned for the caller to inspect.

• static async info(ctx: ServiceContext, configure: Callable[[NotarytoolInfoSettings], NotarytoolInfoSettings]) -> object

  Read a submission's status with notarytool info.

• static async log(ctx: ServiceContext, configure: Callable[[NotarytoolLogSettings], NotarytoolLogSettings]) -> object

  Fetch and parse a submission's notarization log with notarytool log.

• static async history(ctx: ServiceContext, configure: Callable[[NotarytoolHistorySettings], NotarytoolHistorySettings]) -> object

  List the team's past submissions with notarytool history.

class ProvisioningProfileSettings(Settings)

• file(path: str) -> Self

  Read the profile from a .mobileprovision file.

• base64(text: str) -> Self

  Take the profile as base64 — how a CI secret usually holds it (base64 -i profile.mobileprovision).

• directory(path: str) -> Self

  Install into this directory instead of Xcode's two defaults; repeatable.

• allow_expired() -> Self

  Install the profile even if it has expired.

class ProvisioningProfileTasks

• static async inspect(ctx: ServiceContext, configure: Callable[[ProvisioningProfileSettings], ProvisioningProfileSettings]) -> object

  Read what a profile says about itself, without installing it.

• static async install(ctx: ServiceContext, configure: Callable[[ProvisioningProfileSettings], ProvisioningProfileSettings]) -> object

  Install a profile where Xcode looks for it, named by its UUID. Refuses an expired profile unless .allowExpired().

class SecurityCreateKeychainSettings(SecuritySettings)

• password(value: str) -> Self

  The new keychain's password (-p). A secret: masked in every rendering of the command. Without it security prompts for one.

• keychain(*paths: str) -> Self

  The keychain(s) to create (positional); repeatable. Required.

class SecurityDeleteKeychainSettings(SecuritySettings)

• keychain(*paths: str) -> Self

  The keychain(s) to delete (positional); repeatable. Required.

class SecurityFindIdentitySettings(SecuritySettings)

• policy(name: str) -> Self

  Only identities usable under this policy (-p), e.g. codesigning.

• search(value: str) -> Self

  Only identities whose name contains this string (-s).

• valid() -> Self

  Only valid identities (-v) — not expired, revoked or untrusted.

• keychain(*paths: str) -> Self

  The keychain(s) to search (positional); the search list when omitted.

class SecurityImportSettings(SecuritySettings)

• file(path: str) -> Self

  The file to import, e.g. a .p12 (positional). Required.

• keychain(path: str) -> Self

  The keychain to import into (-k); the default keychain when omitted.

• passphrase(value: str) -> Self

  The file's passphrase (-P), e.g. a .p12's export password. A secret: masked in every rendering of the command.

• application(*paths: str) -> Self

  An application allowed to use the imported key without a prompt (-T), e.g. /usr/bin/codesign; repeatable.

• type_(value: Literal['pub', 'priv', 'session', 'cert', 'agg']) -> Self

  The type of item in the file (-t).

• format(value: Literal['openssl', 'openssh1', 'openssh2', 'bsafe', 'raw', 'pkcs7', 'pkcs8', 'pkcs12', 'netscape', 'x509', 'pemseq']) -> Self

  The file's format (-f), e.g. pkcs12.

• non_extractable() -> Self

  Make the imported private key non-extractable (-x).

class SecurityListKeychainsSettings(SecuritySettings)

• domain(value: Literal['user', 'system', 'common', 'dynamic']) -> Self

  The preference domain to read or set (-d).

• set(*keychains: str) -> Self

  Replace the search list with these keychains (-s), in order. Called with none, it empties the list. Repeat calls append.

class SecuritySetKeychainSettings(SecuritySettings)

• lock_on_sleep() -> Self

  Lock the keychain when the machine sleeps (-l).

• lock_after_timeout() -> Self

  Lock the keychain after timeout seconds of inactivity (-u).

• timeout(seconds: float) -> Self

  The inactivity timeout, in seconds (-t).

• keychain(path: str) -> Self

  The keychain to configure (positional); the default keychain when omitted.

class SecuritySetKeyPartitionListSettings(SecuritySettings)

• partition_list(*ids: str) -> Self

  Partition ids to allow (-S, comma-joined); repeatable. apple-tool: and apple: cover codesign and the other Apple tools.

• private_keys() -> Self

  Match private keys only (-s).

• password(value: str) -> Self

  The keychain's password (-k). A secret: masked in every rendering of the command. Without it security prompts for one.

• keychain(path: str) -> Self

  The keychain to modify (positional); the default keychain when omitted.

class SecuritySettings(ToolSettings)

class SecurityTasks

• static async create_keychain(ctx: ServiceContext, configure: Callable[[SecurityCreateKeychainSettings], SecurityCreateKeychainSettings]) -> ExecResult

  Create a keychain with security create-keychain.

• static async delete_keychain(ctx: ServiceContext, configure: Callable[[SecurityDeleteKeychainSettings], SecurityDeleteKeychainSettings]) -> ExecResult

  Delete a keychain with security delete-keychain.

• static async unlock_keychain(ctx: ServiceContext, configure: Callable[[SecurityUnlockKeychainSettings], SecurityUnlockKeychainSettings]) -> ExecResult

  Unlock a keychain with security unlock-keychain.

• static async set_keychain_settings(ctx: ServiceContext, configure: Callable[[SecuritySetKeychainSettings], SecuritySetKeychainSettings]) -> ExecResult

  Change a keychain's lock settings with security set-keychain-settings.

• static async import_(ctx: ServiceContext, configure: Callable[[SecurityImportSettings], SecurityImportSettings]) -> ExecResult

  Import a certificate or key with security import.

• static async set_key_partition_list(ctx: ServiceContext, configure: Callable[[SecuritySetKeyPartitionListSettings], SecuritySetKeyPartitionListSettings]) -> ExecResult

  Set which tools may use a key with security set-key-partition-list.

• static async list_keychains(ctx: ServiceContext, configure: Callable[[SecurityListKeychainsSettings], SecurityListKeychainsSettings] | None=None) -> object

  Read — or, with .set(...), replace — the keychain search list with security list-keychains. Returns the listed paths; empty after a set, which prints nothing.

• static async find_identity(ctx: ServiceContext, configure: Callable[[SecurityFindIdentitySettings], SecurityFindIdentitySettings] | None=None) -> object

  List signing identities with security find-identity, parsed.

class SecurityUnlockKeychainSettings(SecuritySettings)

• password(value: str) -> Self

  The keychain's password (-p). A secret: masked in every rendering of the command. Without it security prompts for one.

• keychain(path: str) -> Self

  The keychain to unlock (positional); the default keychain when omitted.

class TemporaryKeychainSettings(Settings)

• certificate(base64_p12: str) -> Self

  The signing certificate and its private key, as a base64-encoded .p12 — the form CI secrets hold it in. Whitespace is ignored. Required. It is decoded only into a 0600 file that is deleted straight after import, and never appears in a command line or an error message.

• certificate_password(value: str) -> Self

  The .p12's export password, handed to security import -P. A secret: masked in every rendering of that command. Defaults to empty, for a .p12 exported without one — security would otherwise prompt.

• identity(filter: str) -> Self

  Pick the identity whose name contains filter, or whose SHA-1 hash it is. Needed only when the .p12 holds more than one codesigning identity.

• application(*paths: str) -> Self

  An application allowed to use the imported key (security import -T); repeatable. Defaults to /usr/bin/codesign when none is named.

• tool_path(path: str) -> Self

  Run this security binary instead of the one on PATH.

class TestFlightSettings(AppStoreConnectSettings)

• bundle_id(id: str) -> Self

  The app's bundle id, e.g. com.example.app; required.

• build_number(number: str | float) -> Self

  The uploaded build's number, CFBundleVersion; required.

• version(version: str) -> Self

  The uploaded build's version, CFBundleShortVersionString — needed when the same build number exists under several versions.

• platform(platform: Literal['IOS', 'MAC_OS', 'TV_OS', 'VISION_OS']) -> Self

  The build's platform — needed when the app ships on several.

• timeout(duration: str | float) -> Self

  The longest wait for the build to finish processing ("45m", or ms); default 30 minutes.

• poll_interval(duration: str | float) -> Self

  The time between two looks at the build ("1m", or ms); default 30 seconds.

• uses_non_exempt_encryption(uses: bool) -> Self

  Answer the export-compliance question: whether the app uses encryption beyond the exempt kinds. Until it is answered — here, or by ITSAppUsesNonExemptEncryption in Info.plist — the build sits at *Missing Compliance* and no tester can install it.

• what_to_test(text: str, locale: str | None=None) -> Self

  The "What to Test" notes testers see, per locale; default locale en-US.

• group(name: str) -> Self

  Add the build to this beta group, by name; repeatable.

• submit_for_beta_review() -> Self

  Submit the build for beta review, which external testing needs.

class TestFlightTasks

• static async distribute(ctx: ServiceContext, configure: Callable[[TestFlightSettings], TestFlightSettings]) -> object

  Wait for an uploaded build to be processed, then distribute it in TestFlight as configured.

class XcodebuildArchiveSettings(XcodebuildProjectSettings)

• archive_path(path: str) -> Self

  Where to write the .xcarchive (-archivePath); required.

class XcodebuildExportArchiveSettings(XcodebuildSettings)

• archive_path(path: str) -> Self

  The .xcarchive to export (-archivePath); required.

• export_path(path: str) -> Self

  The directory to write the export to (-exportPath); required.

• export_options_plist(path: str) -> Self

  The export options (-exportOptionsPlist); required. Write one with XcodebuildTasks.writeExportOptions.

class XcodebuildProjectSettings(XcodebuildSettings)

• workspace(path: str) -> Self

  The workspace to build, e.g. App.xcworkspace (-workspace).

• project(path: str) -> Self

  The project to build, e.g. App.xcodeproj (-project).

• scheme(name: str) -> Self

  The scheme to build (-scheme); required with a workspace. A later call replaces it.

• configuration(name: str) -> Self

  The build configuration, e.g. Release (-configuration). A later call replaces it.

• sdk(name: str) -> Self

  The SDK, e.g. iphoneos or iphonesimulator (-sdk). A later call replaces it.

• destination(specifier: str) -> Self

  A destination, e.g. generic/platform=iOS or platform=iOS Simulator,name=iPhone 16 (-destination); repeatable.

• derived_data_path(path: str) -> Self

  Where intermediate build files go (-derivedDataPath).

• cloned_source_packages_dir_path(path: str) -> Self

  Where Swift packages are checked out (-clonedSourcePackagesDirPath).

• result_bundle_path(path: str) -> Self

  Write an .xcresult bundle with the logs and results (-resultBundlePath).

• xcconfig(path: str) -> Self

  Apply an .xcconfig file's settings over every target (-xcconfig).

• build_setting(name: str, value: str) -> Self

  Override a build setting for every target, e.g. ("DEVELOPMENT_TEAM", "ABCDE12345") → DEVELOPMENT_TEAM=ABCDE12345; repeatable. A condition goes in the name: CODE_SIGN_IDENTITY[sdk=iphoneos*].

class XcodebuildSettings(ToolSettings)

• quiet_output() -> Self

  Print only warnings and errors (-quiet).

• allow_provisioning_updates() -> Self

  Let Xcode create and update provisioning profiles and certificates (-allowProvisioningUpdates); on CI, pair it with authenticationKey.

• authentication_key(path: str, key_id: str, issuer_id: str) -> Self

  Sign in to the developer account with an App Store Connect API key instead of an Xcode account: the AuthKey_<id>.p8 file, its key id and its issuer id (-authenticationKeyPath, -authenticationKeyID, -authenticationKeyIssuerID).

class XcodebuildShowBuildSettings(XcodebuildProjectSettings)

• json() -> Self

  Print the settings as JSON (-json).

class XcodebuildTasks

• static async archive(ctx: ServiceContext, configure: Callable[[XcodebuildArchiveSettings], XcodebuildArchiveSettings]) -> ExecResult

  Build an .xcarchive: xcodebuild archive.

• static async export_archive(ctx: ServiceContext, configure: Callable[[XcodebuildExportArchiveSettings], XcodebuildExportArchiveSettings]) -> ExecResult

  Export an archive to an .ipa, or upload it: xcodebuild -exportArchive.

• static async show_build_settings(ctx: ServiceContext, configure: Callable[[XcodebuildShowBuildSettings], XcodebuildShowBuildSettings] | None=None) -> ExecResult

  Print the resolved build settings: xcodebuild -showBuildSettings.

• static async write_export_options(ctx: ServiceContext, path: str, configure: Callable[[ExportOptionsSettings], ExportOptionsSettings]) -> None

  Write an ExportOptions.plist for exportArchive to path. Runs no subprocess.