Reference Guide

After you mastered the basic concepts, you can come back to this page to learn what commands Appollo offers. You can learn more about individual Appollo commands with appollo COMMAND --help.

appollo

Command line tool to build & release your flutter apps easily.

Github : https://github.com/Appollo-CLI/Appollo

Documentation : https://appollo.readthedocs.io/en/master/

Download : https://pypi.org/project/appollo/

How does it work ?

The Appollo tool is composed of :

• Appollo-Remote : The pre-configured build machines which handle the setup, build and release of your app

• Appollo-cli : The CLI command line that works as an interface to start Appollo-Remote build machines

This reference guide only covers the Appollo-cli features.

Note

Appollo-Remotes are MacOS build machines on which the flutter build of your application is executed.

Usage:

appollo [OPTIONS] COMMAND [ARGS]...

Options

--version

Show the version and exit.

appollo app

Subcommands to manage your applications on Appollo.

appollo app [OPTIONS] COMMAND [ARGS]...

appollo app import

Imports an app identifier from Apple Developer to Appollo.

appollo app import [OPTIONS]

Options

--name <name>

Your app identifier name (e.g.: your app’s name)

--bundle-id <bundle_id>

The bundle ID for your app on Apple (e.g.: com.company.appname)

--account-key <account_key>

Appollo key to the Apple Developer Account

appollo app link

Links an app identifier to Appollo team with key “KEY”.

Warning

All users who are in a team linked to an Apple Developer Account have full control over it.

appollo app link [OPTIONS] [KEY]

Options

--team-key <team_key>

Key of the team to link

Arguments

KEY

Optional argument

appollo app ls

Lists the app identifiers to which the logged in user has access.

Example output:

Usage:

appollo app ls [OPTIONS]

appollo app mk

Creates a new app identifier.

..note: This will also create an app identifier with this bundle ID on your Developer Account. This allows us to verify the validity of your bundle ID

appollo app mk [OPTIONS]

Options

--name <name>

Your app identifier name (e.g.: your app’s name)

--bundle-id <bundle_id>

The bundle ID for your app on Apple (e.g.: com.company.appname)

--account-key <account_key>

Appollo key to the Apple Developer Account

appollo app rm

Deletes the app identifier with key “KEY” from Appollo and on Apple if specified.

appollo app rm [OPTIONS] [KEY]

Options

--delete-on-apple

Also delete the app identifier on Apple

Arguments

KEY

Optional argument

appollo app screenshots

Returns a link to the screenshot editor for the app with key “KEY”.

appollo app screenshots [OPTIONS] [KEY]

Arguments

KEY

Optional argument

appollo app unlink

Links or unlinks an app identifier to Appollo team with key “KEY”.

appollo app unlink [OPTIONS] [KEY]

Options

--team-key <team_key>

Key of the team to link

Arguments

KEY

Optional argument

appollo apple

Subcommands to manage Apple specific settings for Appollo.

Access to an Apple developer account makes it possible for Appollo to retrieve and/or create all information necessary to create a build of your application that you will be able to publish on the app store.

A number of Apple specific objects is linked to each developer account and make it possible for Appollo to build iOS apps :

• Certificates : The certificates resource represents the digital certificates you use to sign your iOS or Mac apps for development and distribution. These are managed automatically by Appollo.

• Profiles : A provisioning profile is a collection of digital entities that uniquely ties developers and devices to an authorized iPhone Development Team and enables a device to be used for testing. These are managed automatically by Appollo.

• Identifiers : Uniquely identifies your app throughout the Apple eco-system. These are imported or created in Appollo through command : $ appollo app

• Devices : List of devices on which you want to be able to test your builds prior to release on the App Store. At least one device should be added to the device list for Appollo to be able to build apps.

These can be added, modified or deleted through https://developers.apple.com.

Danger

Deletion or modification of Certificates, Profiles or Identifiers managed by Appollo through https://developers.apple.com may break Appollo.

Usage :

appollo apple [OPTIONS] COMMAND [ARGS]...

appollo apple add

Add access to an Apple developer account for Appollo.

Warning

Once the developer account has been created there is no way to retrieve the private key from Appollo.

Note

We have no way to verify your developer account’s ID on Apple. In case of error, your builds will fail.

appollo apple add [OPTIONS]

Options

--apple-id <apple_id>

Required ID of your developer account on Apple

--name <name>

A user friendly name for Appollo

--key-id <key_id>

Required API key “Key ID” on App Store Connect

--issuer-id <issuer_id>

Required Issuer ID on App Store Connect

--private-key <private_key>

Required Path to the private key downloaded from App Store Connect

--team <team>

Key of the team to add the account to. Can be specified multiple times

appollo apple detail

Gets detailed information about your Apple Developer Account with key “KEY” on Appollo.

Returned information :

• General information

• Devices

• Certificates

• Provisioning profiles

Note

Appollo updates Apple Developer Account information automatically when starting a build with Appollo.

Example output :

Usage :

appollo apple detail [OPTIONS] [KEY]

Arguments

KEY

Optional argument

appollo apple edit

Edit properties of a developer account linked to Appollo.

Note

We have no way to verify your developer account’s ID on Apple. In case of error, your builds will fail.

appollo apple edit [OPTIONS] [KEY]

Options

--apple-id <apple_id>

ID of your developer account on Apple

--name <name>

A user friendly name for Appollo

Arguments

KEY

Optional argument

appollo apple link

Links the developer account with key “KEY” to an Appollo team.

By default a newly added Apple Developer Account created on Appollo is only linked to the user having created it. When using this command you can link the Apple Developer Account directly to one of your teams on Appollo giving full access to your team members.

Warning

All users who are in a team linked to an Apple Developer Account have full control over it.

Note

Once the developer account has been created, there is no way to retrieve the private key from Appollo. Making it impossible for team members to “steal” your Apple Developer account.

appollo apple link [OPTIONS] [KEY]

Options

--team-key <team_key>

Key of the team to link

Arguments

KEY

Optional argument

appollo apple ls

Lists Apple Developer Accounts to which you have access.

Example output :

Usage :

appollo apple ls [OPTIONS]

appollo apple refresh-devices

Synchronizes the list of devices on Appollo with the Apple Developer account

This command is used when you have just added or removed a new device from your Apple Developer account and you need it on Appollo.

appollo apple refresh-devices [OPTIONS] [KEY]

Options

-q, --quiet

Flag to know if the refreshed list of devices should be hidden or not

Arguments

KEY

Optional argument

appollo apple rm

Removes access to Apple Developer account with key “KEY” for Appollo.

This does not remove the Apple Developer account from Apple, it only removes the link between Appollo and Apple.

..note::

This will also remove every application, every build, every devices, every certificate, every profile and every objects related to that Apple Developer account on Appollo (it will not remove these from Apple).

appollo apple rm [OPTIONS] [KEY]

Options

--yes

Confirm the action without prompting.

Arguments

KEY

Optional argument

appollo apple unlink

Unlinks the developer account with key “KEY” from an Appollo team.

appollo apple unlink [OPTIONS] [KEY]

Options

--team-key <team_key>

Key of the team to unlink

Arguments

KEY

Optional argument

appollo build

Subcommands to build an app and track builds.

When starting a new project commands are mostly executed in this order :

1. appollo build start --build-type="configuration [DIRECTORY]" to create an Appollo-Remote with the right environment for your application.

2. appollo build connect to get your connection settings and access the Appolo Remote on which you can test and setup your application with XCode.

3. appollo build stop to stop your Appolo Remote when you’re done editing your settings.

4. appollo build patch to retrieve the changes made on the Appollo-Remote.

5. git apply appollo.patch to apply the changes locally.

6. appollo build start [OPTIONS] [DIRECTORY] to build your app with Flutter and generate an IPA or to publish your app on the App Store.

Usage:

appollo build [OPTIONS] COMMAND [ARGS]...

appollo build connect

Get the connection information for an Appollo-Remote linked to a build.

This command is mainly used when it is needed to connect to the Appollo-Remote with a Remote Desktop client :

- Xcode configuration

- Debugging and detailed log analysis

- Correcting code and restarting a build after failure

- Testing the application on the iPhone or iPad simulator.

This command will start an Appollo-Remote and return connection settings and credentials for you to connect with a remote desktop client to the Appollo-Remote.

Note

Appollo-Remotes are active for 30 minutes before being closed automatically.

Note

Appollo-Remotes are MacOS build machines on which the flutter build of your application is executed.

Note

The connection uses the VNC protocol, your Remote Desktop client must support it to allow you to use an Appollo-Remote.

appollo build connect [OPTIONS] [KEY]

Options

--tunnel-port <tunnel_port>

Start a reverse SSH tunnel, forwarding to this port. Note: this only applies to configuration builds

--tunnel-host <tunnel_host>

If –tunnel-port is specified, this is the host to forward to (defaults to localhost)

--tunnel-remote-port <tunnel_remote_port>

If –tunnel-port is specified, this is the port on the VM (defaults to the same port, except for 22 and 5900)

-y, --yes

Automatically create an Appollo Remote if your build was not setup for remote desktop

Arguments

KEY

Optional argument

appollo build detail

Fetches detailed information of a build.

Returns the location of the logs and application artifacts.

appollo build detail [OPTIONS] [KEY]

Arguments

KEY

Optional argument

appollo build download

Get the modified source code of a build.

This command is used when a build is finished or stopped to retrieve its entire directory on the remote machine.

appollo build download [OPTIONS] [KEY]

Options

-o, --output <output>

Output filename (default: source.zip)

Arguments

KEY

Optional argument

appollo build flutter-versions

Lists the Flutter versions available on Appollo.

appollo build flutter-versions [OPTIONS]

appollo build ipa

Get the ipa file of a build.

This command is used when a build of type ad-hoc, ipa, validation or publication has succeeded.

It returns an url to get the IPA, either to download it, or to install it if opened from an iOS device.

appollo build ipa [OPTIONS] [KEY]

Arguments

KEY

Optional argument

appollo build logs

Outputs the logs of a build

Note

Logs are printed only when a command has finished its execution. In particular, Flutter logs are only printed when the flutter command execution has ended.

appollo build logs [OPTIONS] [KEY]

Arguments

KEY

Optional argument

appollo build ls

Lists builds on Appollo.

appollo build ls [OPTIONS]

Options

-a, --all

shows your builds and the builds from your teams

appollo build patch

Retrieve a patch that gathers all changes made to the source code of a build.

This command is used when a build is finished and succeeded or when you have stopped an Appollo Remote on which you configured an app with XCode.

Note

The patch was made on a blank Git repo.

appollo build patch [OPTIONS] [KEY]

Options

-o, --output <output>

Output filename (default: appollo.patch)

Arguments

KEY

Optional argument

appollo build rm

Deletes a build and its corresponding Appollo-Remote.

Note

Appollo-Remotes are MacOS build machines on which the flutter build of your application is executed.

appollo build rm [OPTIONS] [KEY]

Arguments

KEY

Optional argument

appollo build start

Start a new build from scratch

DIRECTORY : Home directory of the flutter project. If not provided, gets the current directory.

The Appollo tool is composed of:

• Appollo-Remote : The pre-configured build machines which handle the setup, build and release of your app

• Appollo-cli : The CLI command line that works as an interface to start Appollo-Remote build machines

appollo build start [DIRECTORY] --build-type <build-type> creates an Appollo-Remote and builds the app either for development, ad-hoc, distribution, validation or publication

• Configuration: launch an Appollo-Remote to allow you to configure your project on XCode

• Development : builds the app for testing on an iOS simulator.

• Ad-hoc : Build an .ipa file for testing on the devices listed in your developer account. For the list of devices check appollo apple detail <apple-dev-account-key>.

• Distribution : Build an .ipa file that can be distributed on any device.

• Validation : Build an .ipa file and validates that it can be released on the App Store.

• Publication : Build an .ipa file and publish it on the App Store. Once this build succeeds you have to go on the App Store to complete information and screenshots related to your new application version.

Killing this command will not stop the build. You can check the progress of all your Appollo-Remotes by running appollo build ls or get detailed information by running appollo build detail and selecting your build.

To avoid having to specify all the parameters each time, you can create a .appollo file in the directory where the command is run. Each parameter is specified on a line in the form PARAM=VALUE. For example:

app-key=123
flutter=3.0.0
minimal-ios-version=11.0

All files and directories in the provided directory will be uploaded, except:

• build/

• windows/

• linux/

• .dart_tool/

• .pub-cache/

• .pub/

• .git/

• .gradle/

• source.zip

• .app.zip

• appollo.patch

You can also specify additional files and directories in a .appolloignore file, with each files and directories you want to ignore on separate lines, with directories ending with ‘/’

appollo build start [OPTIONS] [APP_KEY] [DIRECTORY]

Options

--build-type <build_type>

Build type

Options

configuration | development | ad-hoc | distribution | validation | publication

--flutter <flutter>

Flutter version for your build (example “2.8.1”). Use appollo build flutter-versions to see all available versions

--minimal-ios-version <minimal_ios_version>

Minimal iOS version for you application (example “9.0”)

--app-version <app_version>

App version to set for this build (for example “1.3.1”). If not set, the version in pubspec.yaml will be used

--build-number <build_number>

Build number to set for this build (the number after ‘+’ in the version in pubspec.yaml). If not set, the build number in pubspec.yaml will be used

--mode <mode>

Mode to build the app in. Defaults to release

Options

release | profile | debug

--target <target>

The main entry-point file of the application. Defaults to lib/main.dart

--flavor <flavor>

Custom app flavor

--tunnel-port <tunnel_port>

Start a reverse SSH tunnel when the build is started, forwarding to this port. Note: this only applies to configuration builds

--tunnel-host <tunnel_host>

If –tunnel-port is specified, this is the host to forward to (defaults to localhost)

--tunnel-remote-port <tunnel_remote_port>

If –tunnel-port is specified, this is the port on the VM (defaults to the same port, except for 22 and 5900)

--no-progress

Do not display the progress and exit the command immediately.

--no-flutter-warning

Do not display a warning if no flutter version is specified and the local flutter version does not match the build version.

Arguments

APP_KEY

Optional argument

DIRECTORY

Optional argument

appollo build stop

Stops a running build

appollo build stop [OPTIONS] [KEY]

Arguments

KEY

Optional argument

appollo build tunnel

Create a reverse ssh tunnel between this computer and the VM

This allows you to access a port of this computer or any host accessible frow this computer, from the VM.

For example if you have a web server running on port 8000, type the command

appollo build tunnel –port 8000

and your web server will be accessible on the VM at localhost:8000, which will enable you to run your app in the simulator while connecting to your local web server.

appollo build tunnel [OPTIONS] [KEY]

Options

--port <port>

Required Port to forward to

--remote-port <remote_port>

Port on the VM (defaults to the same port, except for 22 and 5900)

--host <host>

Host to forward to (defaults to localhost)

Arguments

KEY

Optional argument

appollo profile

Profile of the logged in user.

Example output :

The top part displays the user account information and the location of the Appollo config.ini file on your system.

The bottom part either :

• Displays the list of Teams to which the logged in user has access. The Admin field is shown in green if the logged in user is the admin of the team.

• Is not shown if the logged in user has no teams or has not been added to any teams.

Usage :

appollo profile [OPTIONS]

Options

--ini

Highlight config.ini path

appollo signin

Logs in to your Appollo account.

Login is based on e-mail and password. This command stores the connection token for future commands in a config.ini file. To get the location of the config.ini file run appollo profile --ini once connected.

appollo signin [OPTIONS]

Options

--email <email>

--password <password>

appollo signout

Log out of your Appollo account.

This command deletes the connection token from the config.ini file associated with Appollo. To get the location of the config.ini file run appollo profile --ini

appollo signout [OPTIONS]

appollo signup

Creates an Appollo user account.

E-mail, username and password are required

appollo signup [OPTIONS]

Options

--email <email>

--username <username>

--password <password>

appollo team

Subcommands to manage teams and corresponding users.

A user can be part of multiple teams. Each team has only one admin. The admin can add or remove users based on their username.

The team system is used in case a user wants to share access to his Apple Developer Account, his app identifiers or his builds to other developers with whom he collaborates.

Warning

If an object (App or Apple Developer Account) is linked to a team then all members of this team have full control over the object.

Usage :

appollo team [OPTIONS] COMMAND [ARGS]...

appollo team ls

Lists the teams to which the logged in user has access.

Returns a list with :

• General team information

• List of team members

• List of app identifiers in the team

• List of Apple Developer accounts to which the team has access

Example output :

Usage :

appollo team ls [OPTIONS]

appollo team member

Commands to manage team members.

appollo team member [OPTIONS] COMMAND [ARGS]...

appollo team member add

Adds a user to a team.

appollo team member add [OPTIONS] [KEY]

Options

--username <username>

username of the new team member

Arguments

KEY

Optional argument

appollo team member rm

Removes a user from a team.

appollo team member rm [OPTIONS] [KEY]

Options

--username <username>

username of the team member to remove

--yes

Confirm the action without prompting.

Arguments

KEY

Optional argument

appollo team mk

Creates a team and sets the logged in user as team admin.

appollo team mk [OPTIONS]

Options

--name <name>

appollo team rm

Deletes a team.

appollo team rm [OPTIONS] [KEY]

Options

--yes

Confirm the action without prompting.

Arguments

KEY

Optional argument