The Codegen CLI

The Codegen CLI provides a command line tool that streamlines the process of running code generation. The CLI can be ran manually from Terminal (or any other shell program) or can be called into from bash scripts.

The Codegen CLI has three primary commands:

• Initialize: Initializes an apollo-codegen-configuration.json file that can be used to configure how the CLI generates code.
• Fetch Schema: Fetches your GraphQL schema and writes it to a file. The schema is required in order to run code generation.
  • To learn how to configure schema fetching, see Downloading a schema.
• Generate: Runs the code generation engine using the configuration in your apollo-codegen-configuration.json file.
• Generate Operation Manifest: Generates the operation manifest for persisted queries using the configuration in your apollo-codegen-configuration.json file.

Installation

When Apollo iOS is included as a dependency through Swift Package Manager (SPM) or Cocoapods, the CLI is built and packaged with the dependency automatically. This ensures you always have a valid version of the CLI for the version of Apollo iOS you are using and you never have to worry about installation or updates.

To learn how to run the Codegen CLI with your chosen package manager, open the appropriate section:

1
swift package --allow-writing-to-package-directory apollo-cli-install

SPM with Xcode Project

The Apollo iOS SPM package includes the Codegen CLI as an executable target. This ensures you always have a valid CLI version for your Apollo iOS version.

To simplify accessing the Codegen CLI, you can run the included InstallCLI SPM plugin.

This plugin builds the CLI and creates a symbolic link to the executable in your project root.

If you use Swift packages through Xcode, you can right-click on your project in the Xcode file explorer, revealing an Install CLI plugin command. Selecting this command presents a dialog allowing you to grant the plugin "write" access to your project directory.

After the plugin installs, it creates a symbolic link to the Codegen CLI (named apollo-ios-cli) in your project root folder. You can now run the CLI from the command line with ./apollo-ios-cli.

Note: Because the apollo-ios-cli in your project root is only a symbolic link, it only works if the compiled CLI executable exists. This is generally located in your Xcode Derived Data or the .build folder. If these are cleared, you can rerun the Install CLI plugin to rebuild the CLI executable.

1
./Pods/Apollo/apollo-ios-cli ${Command Name} -${Command Arguments}

1
./apollo-ios-cli ${Command Name} -${Command Arguments}

1
make build-cli

1
./.build/release/apollo-ios-cli ${Command Name} -${Command Arguments}

Usage

The Apollo iOS Codegen CLI is a command like utility for Apollo iOS code generation.

apollo-ios-cli <subcommand>

Options:

Subcommands:

See apollo-ios-cli help <subcommand> for detailed help.

Initialize

Creates an apollo-codegen-configuration.json file with default values. The Codegen CLI reads this file to configure how the CLI generates code.

The default configuration will:

• Find all GraphQL schema files ending with the file extension .graphqls within your project directory.
• Find all GraphQL operation and fragment definition files ending with the file extension .graphql within your project directory.
• Create a Swift Package for your generated schema with the schema-name provided.
• Generate operation and fragment models relative to the .graphql files that define them.

Command:

apollo-ios-cli init --schema-namespace <namespace> --module-type <type> [--target-name <target name>]

Options:

Fetch Schema

Downloads a GraphQL schema from the Apollo Registry or GraphQL introspection and writes it to a file. The schema is required in order to run code generation.

Command:

apollo-ios-cli fetch-schema [--path <path>] [--string <string>]

Options:

Generate

Runs the code generation engine to generate Swift source code using the configuration in your apollo-codegen-configuration.json file.

Command:

apollo-ios-cli generate [--path <path>] [--string <string>]

Options:

Generate Operation Manifest

Generates the operation manifest for persisted queries using the configuration in your apollo-codegen-configuration.json file.

Command:

apollo-ios-cli generate-operation-manifest [--path <path>] [--string <string>]

Options: