Introduction to OrgFlow CLI

The OrgFlow CLI is a command line tool that packages the functionality of OrgFlow into a downloadable cross-platform executable. It complements OrgFlow Web for scenarios where running DevOps workflows from a terminal, in custom scripts or inside a CI/CD platform is preferable to running them through a web UI.

Use cases

For most use cases OrgFlow Web will be preferred for day-to-day Salesforce DevOps operations. However, there are certain use cases where it might make more sense to use the OrgFlow CLI instead.

CI/CD platform integration

The most common use case for the OrgFlow CLI is probably as part of a pipeline in a third-party CI/CD platform (such as GitHub Actions, Azure Pipelines, Bitbucket Pipelines, GitLab CI/CD, or something else entirely). An example of this can be found in our GitHub Actions demo repo.

As long as the agent or runner that is executing the pipeline has the OrgFlow CLI installed, you can create rich and powerful scripts to integrate OrgFlow into your pipelines. We provide the OrgFlow CLI executable in a variety of download formats for easy installation on your agents, manually or scripted. We also provide a Docker image and a ready-made GitHub action to make it even easier to get the OrgFlow CLI installed on your agents.

Third-party CI/CD pipelines can also usually be triggered by events that jobs in OrgFlow Web cannot be triggered by. An example of this is a pipeline that is triggered when a pull request is opened in order to validate the result of the proposed merge and the resulting deployment into the target org.

Local metadata processing

OrgFlow CLI enables you to run OrgFlow on your local device, on a server that your company maintains, in cloud-based environments, or on a build agent hosted by a third party (such as GitHub, Bitbucket, or GitLab).

When you run a command with OrgFlow CLI, all of the processing work is performed locally (on the device where you are running the OrgFlow CLI). This is useful in scenarios where you don't want your Salesforce metadata to be stored or processed on a device that is outside your organization's compliance boundary.

Scripting and automation

Being a command line tool, OrgFlow CLI allows you to script, automate, and chain processes together. You can create scripts (in Bash, PowerShell or any other scripting language) to automate your most frequently run tasks, or you can create runbooks and share them with your teams to help bring consistency to your DevOps work — just to name a few examples.

OrgFlow CLI can run in any terminal on macOS, Windows and Linux. Some people also use it in Visual Studio Code (aka. VS Code) to complement their Salesforce development work by running OrgFlow commands directly from VS Code's integrated terminal. You can even create VS Code tasks that invoke the OrgFlow CLI to help automate some common workflows.

OrgFlow CLI can optionally produce JSON formatted output, allowing you to take the output of a command and use it as input to something else. One example use case for this is to report on the outcome of a deployment by converting the output JSON into a human-readable Slack message and posting it in a Slack channel.

OrgFlow CLI vs OrgFlow Web

OrgFlow CLI is intended to complement OrgFlow Web. The two interfaces and their feature sets are optimized for different scenarios. Some functionality is available in one but not the other; other things are possible in both but can make more sense in one, depending on your needs and preferences.

The main comparison points are:

Feature	OrgFlow Web	OrgFlow CLI
Create and manage workspaces and members	✓
Manage subscriptions and billing	✓
Create and manage stacks	✓
Low to no setup	✓
Compute provided by OrgFlow	✓
View historical Apex test runs	✓
View historical jobs	✓
Schedules	✓
Create and manage environments	✓	✓
Flow metadata changes in and out	✓	✓
Merge metadata between environments	✓	✓
Run Apex tests	✓	✓
Snapshots and rollbacks		✓
Toolbox commands		✓
Local processing		✓
Advanced scripting and integrations		✓
CI/CD platform integration		✓

Commands

To interact with the OrgFlow CLI, you give it a command to run. Commands are made up of two parts: the command's name followed by the arguments and options for that command. Arguments are required inputs, and most commands will have these. Options are optional inputs, and every command has these. Options can occasionally become required based on the values of other inputs.

Commands are passed into the OrgFlow CLI executable (usually named orgflow), so to run a command, you'll type orgflow <commandName> <arguments>.

Discovering available commands

Running orgflow --help will give you a list of available commands, along with a brief description of each.

Discovering arguments and options

Once you know which command you'd like to run, you'll need to know which arguments and options are available for that command.

Running orgflow <commandName> --help (for example orgflow env:test --help) will give you a list of all the arguments and options for the command. You'll also be given a list of global options. Global options are options that apply to every command in the OrgFlow CLI. They tend to control things like logging, output, error handling etc.

An abridged version of this output might look like this:

$ orgflow env:test --help

USAGE: orgflow env:test --environment=<environmentName> [options]

Arguments:
    --environment=<environmentName> (-e)
        Name of environment to run tests in

Options:
    --encryptionKey=<key> (-k)
        Key used to encrypt/decrypt stored credentials
    --classes=<testClass>[,<testClass>,...] (-c)
        Names of test classes to run
...
    --runAllTests[=true|false] (-a)
        Include non-local tests (default: false)

Global options:
    --logLevel=verbose|debug|information|warning|error|fatal
        Verbosity level for diagnostic log file (default: information)

Argument and option names are prefixed with --. Some common arguments and options also have a short form alias, which is prefixed with -. Short form aliases are displayed enclosed in parentheses (as you can see in the example above). For example, --environment=prod and -e=prod are equivalent.

Names and values are separated by =. Each name/value pair must be separated by whitespace, for example --environment=prod --encryptionKey=123. If you need to use = or whitespace characters in the input values, you can wrap the value in quotes (e.g. --encryptionKey="my secret key ===").

Sometimes empty strings are valid values. This usually denotes that a previously set value should be unset, for example --encryptionKey=.

The output above shows argument and option names alongside their value notations. To interperet value notations:

• <> indicates free form values
• | indicates the value must be one of the values listed (separated by |)
• [] indicates the value is optional
• , indicates a list value - you can enter more than one value, separated by a ,

Omitting the value when specifying an argument or option name is only valid for true|false values. If you omit a value in this case, it's equivalent to specifying true. For example, --runAllTests and --runAllTests=true are equivalent.

All of the following are valid examples:

• orgflow env:test --environment=uat --classes=test1,test2
• orgflow env:test -e=uat --runAllTests
• orgflow env:test --environment='my test env' --classes=test1,test2 -a=false

None of the following are valid:

• orgflow env:test (required argument --environment not specified)
• orgflow env:test -e=my env --runAllTests (whitespace in the -e value not surrounded by quotes)
• orgflow env:test --environment=prod --logLevel=max (max is not a valid value for --logLevel )

Command categories

OrgFlow CLI comes with a number of commands that are split into two categories:

• Process commands are the high-level commands that you will use day to day. They act within the context of your workspace in the OrgFlow cloud, and interact with your stacks and environments. Process commands usually combine state management with the orchestration of multiple low-level operations. Most process commands are prefixed with the namespaces stack:, and env:.
• Toolbox commands are low-level commands that allow you to interact directly with a Salesforce org, Salesforce metadata or a Git repository, independently of any workspace, stacks or environments. They allow you to do things like retrieve metadata from a Salesforce org, refresh a sandbox, or compare two metadata archives that are already on your local disk. Most toolbox commands are prefixed with the namespaces md:, sb:, and tool:.

An example of how a process command is composed of several toolbox commands is the env:flowin command which will:

• Clone the remote Git repository and check out the correct branch
• Retrieve the correct metadata from the Salesforce org (equivalent to md:retrieve)
• Inspect the environment state in the OrgFlow cloud in order to determine how metadata should be applied
• Selectively (based on the environment state) apply the retrieved metadata to the metadata in the cloned Git repository (equivalent to md:apply)
• Selectively (based on the environment state) commit the applied metadata to the clonedGit repository (equivalent to md:gitcommit)
• Merge those commits back to the correct branch for the environment
• Update the environment state in the OrgFlow cloud
• Push the changes to the remote Git repository

Interactive and unattended modes

In some cases, the OrgFlow CLI can prompt for values and input if needed. Examples of this might be prompting for values for required arguments that weren't supplied, or prompting for confirmation to begin a deployment.

The OrgFlow CLI can only prompt if it is able to receive input from the user. This is determined by checking whether or not the input stream (stdin) has been redirected. If the input stream has not been redirected, the OrgFlow CLI runs in interactive mode, and it is able to prompt. If the input stream has been redirected, the OrgFlow CLI runs in unattended mode, and it is unable to prompt.

For example, unattended mode will be enabled if you run the OrgFlow CLI on a build agent as part of a CI/CD pipeline (because the agent will redirect the input stream and you as a user cannot provide input).

Output

The OrgFlow CLI sends output to two streams: standard error (stderr) and standard output (stdout). Standard output is used for the final output of a command; standard error is used for everything else (prompts, progress, error and information messages, etc.).

This distinction is mostly pertinent in automation and scripting scenarios. In these cases, you can get the final output of each command (without worring about having to filter out the other lines that are printed) by reading or piping only the standard output stream.

By default, the final output of each command is written in human readable form. This is great if you're manually running commands and want to inspect the output visually. However, in automation and scripting scenarios, you'll probably want the output in a machine readable format. Every command exposes a --json option that produces verbose JSON output. This allows you to take the output of a command and use it in your script to perform further tasks.