The Preternatural CLI Tool

The Preternatural command line tool preternatural helps build and update Xcode Projects, Workspaces and Swift packages.

Installation

The installation process done via your Terminal as follows:

1. Install Mint via brew install mint
2. Add Mint to your path by running echo 'export PATH="$HOME/.mint/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc so that tools installed via Mint will be available without having to do mint run (i.e. mint run foo can now just be mint foo)
3. Restart your Terminal app
4. Install the preternatural binary via mint: mint install PreternaturalAI/cli-binary preternatural
5. You can now use the preternatural command from your command line. Try using preternatural --help to see all available preternatural cli tool options.

Commands

Now let’s take a deeper look into each command option:

Preternatural Build

The preternatural build [options] command builds all projects, packages and workspaces that it finds within the current working directory. It also searches in sub-directories. If a project or package is found to be referenced from a workspace, by default this command will prioritize building it from the workspace as opposed to the standalone project or package.

Use preternatural build --help to see all the build options:

• --derived-data-path <path>: Path to the derived data folder. This option allows setting a non-standard derived data root folder for the underlying xcodebuild commands. This option is useful in a case where we want to use a temporary folder for derived data for a fresh compilation of the project or workspace.
• --build-all-platforms: Builds for all supported platforms
• --isolated: Prioritizes building standalone Xcode projects instead of the referenced projects in an Xcode Workspace
• --update-developer-team: Auto-configure the developer team for Xcode projects. Warning - this option updates the Xcode project with a new developer team
• --attempt-automatic-fixes: If build fails for a project or workspace, attempts to fix the build by updating code signing and dependencies. This does not update the original Xcode project or workspace, it makes a temporary copy and tries updating and building the temporary copy

For example, you can use none, one or a combination of options as follows: preternatural build --build-all-platforms --update-developer-team --attempt-automatic-fixes

Preternatural Update

The preternatural update [options] command updates the dependencies of Xcode projects, packages and workspaces.

Use preternatural update --help to see all update options:

• --derived-data-path <path>: Path to the derived data folder
• --verify: Verify the update process. Builds any projects / packages / workspaces that had changes
• --build-all-platforms: Builds for all supported platforms
• --isolated: Prioritizes building standalone Xcode projects instead of the referenced projects in an Xcode Workspace
• --update-developer-team: Auto-configure the developer team for Xcode projects. Warning - this option updates the Xcode project with a new developer team

Example usage: preternatural update --verify --build-all-platforms

This command can also be used to update the Preternatural CLI tool itself as follows: preternatural update preternatural

Preternatural Generate Workspace

The preternatural generate workspace [name] command searches for an Xcode project within the current working directory, and acts on the first project that it finds. It will generate an Xcode workspace, clone all remote dependencies of the Xcode project in a folder called Dependencies and link them as local references in the Workspace.

The name argument refers to the name of the workspace to generate. If no name is specified, it will name the workspace after the Xcode project. Here is the result of what this will look like when this command was run within the ChatWithPDF project directory:

Notice the new ChatWithPDF.xcworkspace workspace file along with the new ChatWithPDF_Dependencies folder, which has the latest project dependencies cloned locally.

Make sure to close your original project before reopening the workspace to see the full results (this is because Xcode does not let you open the same project or package from two different workspaces at the same time).

Preternatural Add Package

The preternatural add <package-url> command will add a Swift package to the Xcode project or workspace. This command will recursively search for Xcode projects and workspaces in the current working directory, and add the package to all projects and workspaces.

Example usage: preternatural add https://github.com/PreternaturalAI/AI

Preternatural Archive

This command will archive and export a notarized and stapled .zip for macOS apps only: preternatural archive [target] [output] [options]

The inputs are as follows:

• target: The target to archive. If no target is specified, it will auto-determine the primary target of the first found project or workspace file and archive it.
• output: The output path for the archived .zip file. If not specified, a default path will be used

Currently, the only option is --debug:

• --debug: Build the app in debug configuration. (It is built in release configuration by default)

Environment Variables: The preternatural archive command allows the setting of the following environment variables.

• NOTARIZATION_APP_STORE_CONNECT_USERNAME: Your App Store Connect username to be used for notarization.
• NOTARIZATION_APP_STORE_CONNECT_PASSWORD: Your app-specific password to be used for notarization. See how to generate an app-specific password here (opens in a new tab).
• NOTARIZATION_APP_STORE_CONNECT_TEAMID: Your App Store Connect Team ID for notarization.

Setting the Environment Variables is optional and can be done via the command line using the export command as follows:

export NOTARIZATION_APP_STORE_CONNECT_USERNAME=username@email.com
export NOTARIZATION_APP_STORE_CONNECT_PASSWORD=correct-horse-battery-staple
export NOTARIZATION_APP_STORE_CONNECT_TEAMID=N2GKHVD123

If the Environment Variables are not provided, the preternatural command will look for a signing certificate in the keychain, and will interactively ask for the notarization username and password when running the script for the first time.

Example usage: preternatural archive MyApp ./output/MyApp.zip --debug

Preternatural Fix Codesigning

The command preternatural fix codesigning [input] fixes codesigning issues by fetching and applying codesigning certificates from the keychain.

The input argument refers to the path to the project or workspace file to be fixed. If not specified, codesigning fixes will be applied to all projects and workspaces in the current directory.

Example usage: preternatural fix codesigning ./MyProject.xcodeproj

Preternatural Clone

The preternatural clone <input> <output> command clones an Xcode workspace or project.

The arguments include:

• input: The input workspace or project file path. Can be a relative or full path to an .xcworkspace or .xcodeproj file. Optionally, you can specify a target using the format: .xcodeproj/ or .xcworkspace/
• output: The output directory path where the cloned project will be saved

Example usage: preternatural clone ./MyProject.xcodeproj ./ClonedProject