Initial setup and configuration

After downloading and installing the OrgFlow CLI, there's a few more one-time setup steps needed to get up and running.

This topic assumes that you've added the installation folder to the PATH variable of your shell. If you skipped this step, just make sure that the current working directory of your terminal is the directory to which the OrgFlow CLI executable was installed.

Access token

For process commands the OrgFlow CLI relies on an access token to designate which workspace to connect to, and to identify you and verify that you have the required permissions and access to the resources in that workspace (stacks, environments etc.) that you are trying use.

Obtaining the access token

Access tokens are scoped to a workspace. If you do not already have a workspace, our quick start guide explains how to create one. You cannot create a workspace with the OrgFlow CLI — it must be done through the OrgFlow web app. Navigate to the workspace, then go to the settings tab. You'll find the access token under the basic information section.

Keep your access token secret

An access token provides full access to your workspace, equivalent to the administrator role. Keep it a secret and only share with those you trust. Avoid hardcoding your access token in scripts — use a secret store instead.

If you suspect your access token might have been leaked or compromised, contact support@orgflow.io and we can rotate it.

Using the access token

Every process command exposes an --accessToken (-at) argument that allows you to pass in an access token. Once you provide an access token, the token is cached locally so that you don't have to provide it to subsequent commands. To target a different workspace, simply provide the --accessToken (-at) argument again.

If you run a command in interactive mode and an access token has not been provided or previously cached, the OrgFlow CLI will prompt you to provide one.

Encryption key

OrgFlow encrypts sensitive data (such as Salesforce credentials and Git passwords) at rest. To add an extra layer of security, each stack is assigned a unique encryption key. The OrgFlow CLI cannot decrypt these sensitive values without being provided the correct encryption key.

If you run a command that requires the encryption key to decrypt stored sensitive values, you will first need to obtain the correct encryption key through the [OrgFlow web app] and then provide the encryption key to the OrgFlow CLI.

Obtaining the encryption key

Encryption keys are scoped to a stack. If you do not already have a stack, our quick start guide explains how to create one. In the OrgFlow web app, navigate to the stack in question, then go to the settings tab. You'll find the encryption key under the basic information section.

Using the encryption key

The recommended way to provide an encryption key to the OrgFlow CLI is with the auth:key:save command. This command takes an encryption key (and optionally a stack name, see below for information on how to select a stack), and caches it locally so that it can be used in subsequent commands, for example:

$ orgflow auth:key:save --encryptionKey=myencryptionkey --stack=mystack

Alternatively, you can provided encryption keys on a per-command basis by using the --encryptionKey=<key> (-k) argument. This argument is present on every command that might need an encryption key, for example:

$ orgflow env:flowin --environment=dev --encryptionKey=myencryptionkey

Any encryption key provided as command input (e.g. --encryptionKey=<key> (-k)) take precedence over any encryption keys saved using the auth:key:save command. (This pattern applies throughout the OrgFlow CLI, not just to encryption keys.)

Selecting a stack

Most of the work that you do with the OrgFlow CLI will be within the context of a stack. Any process commands that operate within the context of a stack will have a --stack=<stackName> argument or option. For example, to list all environments in a stack:

$ $orgflow env:list --stack=mystack

It's also possible to set a default stack so that you can run commands without having to explicitly specify a stack each time. The command to do this is stack:setdefault, for example:

orgflow stack:setdefault --stack=mystack

The default stack will be used only in cases where you haven't explicitly used the --stack=<stackName> argument.

If you want to view a list of all your stacks, you can run orgflow stack:list. This command also shows the selected default stack, if one has been set.

Configuring Git

The OrgFlow CLI uses your local Git installation and configuration when interacting with your Git repository.

You will need to have Git installed and correctly configured on the device where you run the OrgFlow CLI. This means things like authentication and committer signatures need to be in place before OrgFlow can do any work with Git. A good rule of thumb is that if you are able to clone from and push to the remote repository then OrgFlow CLI will be able to do so too.

The OrgFlow CLI assumes that the Git executable is available at git. If this is not the case then you can change this by setting the ORGFLOW__GIT__EXECUTABLEPATH environment variable.

Setting up in a third-party CI/CD platform

Most of the steps described above are required also when running the OrgFlow CLI on an agent or runner inside a third-party CI/CD platform. The only exception is configuring Git: on CI/CD platforms where an implicit backing Git repository is present (such as GitHub Actions or Azure Pipelines and others) the required Git configuration is usually already present.

For GitHub Actions, this is all taken care of for you if you are using the setup action. For other platforms, you will need to add the required steps to your pipelines or scripts.

Hosted CI/CD agents are usually ephemeral, which means that you'll need to ensure that the installation and configuration steps are performed each time your jobs start.