Cheat Sheet

CumulusCI offers a great deal of functionality out of the box. This cheat sheet is intended to provide a very brief summary of the most important commands to start working in scratch orgs using CumulusCI, using the basic flows and tasks supplied with the tool.

Naming and Manipulating Orgs

CumulusCI supplies a collection of named org configurations by default. To see what org configurations are available, run cci org list. You can provide those names to any of the commands in this guide. Common examples include dev, qa, beta, and release. Org names are associated with a scratch org definition file stored in the project’s orgs directory. The definition file determines how the scratch org is set up.

It’s not necessary to name your own orgs, but you may choose to do so if, for example, you’d like to maintain multiple orgs of the same type.

Name a new scratch org

$ cci org scratch <configuration_name> <org_name>

This creates a new named org that inherits its setup from the configuration name provided.

Get information about a scratch org

$ cci org info <org_name>

This includes information like the org’s domain, username, and password

Open a scratch org in your web browser

$ cci org browser <org_name>

Set a default scratch org

$ cci org default <org_name>

This asks CumulusCI to run all flows and tasks against the named org unless otherwise specified. You don’t have to specify a default org. You can always direct CumulusCI to use a specific org with the --org option when you run a flow or a task.

Delete a scratch org, but leave the org name

$ cci org scratch_delete <org_name>

Run this command to delete a scratch org so that you can rebuild it, while using the same name.

Remove an org name

$ cci org remove <org_name>

Note that you will not be able to remove built-in org names, but you can remove names you created with cci org scratch.

Connect to a persistent org (sandbox, Developer Edition)

$ cci org connect <org_name>

Use the --sandbox option if this is a sandbox, or any org that uses the test.salesforce.com login endpoint.

Building Orgs

Every CumulusCI project includes one or more flows that build an org for a specific purpose or workflow. These flows may be customized for the project, or may be unique to the project. Below are a collection of the standard org building flows that you should expect to find in any CumulusCI project.

Note

This section relies on concepts introduced in the Key Concepts section of the documentation.

Note

Each flow should be run against a named org configuration using the --org option, or allowed to run against a configured default org.

Flows for Building Orgs

qa_org

This flow builds an unmanaged org that is designed for QA use. Should be used with an org whose configuration is qa.

dev_org

This flow builds an unmanaged org that is designed for development use. Should be used with an org whose configuration is dev or dev_namespaced

install_beta

This flow builds a managed org with the latest beta release installed. Should be used with an org whose configuration is beta

install_prod

This flow builds a managed org with the latest release installed. Should be used with an org whose configuration is release

regression_org

This flow builds a managed org that starts with the latest release installed and is then upgraded to the latest beta to simulate a subscriber upgrade. Should be used with an org whose configuration is release

Your project may provide additional org-building flows. Consult the project’s automation documentation for more details.

Caution

We do not recommend running an org-building flow against the same scratch org multiple times. While this may work in some situations, in many cases it will fail and/or leave the org in an inconsistent state. If you need to rebuild an org, delete it first. If you need to redeploy updated code into an org, see below.

Common Tasks

Note

Note that each task should be run against a named org configuration using the --org option. If not specified, the task will run against a configured default org.

Deploy updated code into an org (any project)

$ cci task run deploy_unmanaged

Deploy updated code into an org (Salesforce DX projects only)

$ cci task run dx_push

Execute Apex unit tests in an org

$ cci task run run_tests

Execute Robot browser tests

$ cci task run robot

Review changes to metadata in an org

$ cci task run list_changes

Retrieve changes to local repository

$ cci task run retrieve_changes