stack:create

Create a new Stack. This will probably be the very first command you run with OrgFlow. You only need to run this command once per stack.

Process

The stack:create command will create a stack that contains the minimum amount of data required for stack based commands to function:

  • A stack record is added to the stack state store, containing:
    • The remote Git repository's URL. This allows further OrgFlow commands to clone the repository.
    • A path relative to the root of the repository to indicate where metadata should be located within the repository (optional).
    • A flag indicating whether or not metadata should be committed in a way that maintains compatibility with other deployment tools (optional) .
    • The Sign-in URL for your production Salesforce organization (optional).
  • The remote Git repository must already exist, but OrgFlow will configure it with a few pre-requisites:
    • The repository will be initialized with a first commit if required. The first commit will be a .gitignore file
    • The branch to back the production environment will be created from the head of the default branch (if the branch does not already exist).
    • A .gitattributes file will be added at the root of the metadata location in the repository. This file ensures that the metadata is committed in a way that is compatible with OrgFlow.
    • A .orgflowinclude File will be added (optional).
  • A production Environment is added to the stack.
  • The metadata from the production Salesforce organization is committed to the repository. We call this process a Flow In.

Options

  • -n|--name=<stackName>

    Required. Prompted for when not specified, and possible to do so. Defaults to Main if not specified.

    The name of the stack to be initialized. Stack names are not case-sensitive.

  • -e|--environmentName=<environmentName>

    Required. Prompted for when not specified, and possible to do so. Defaults to Production if not specified.

    The name of the production environment to be added to the stack. Environment names are not case-sensitive.

  • -r|--gitRepoUrl=<gitUrl>

    Required. Prompted for when not specified, and possible to do so.

    The location of the remote Git repository to contain your metadata. See the git clone docs for examples of valid values. OrgFlow supports all formats with the exception of relative local locations (e.g. ./path/to/repo.git/).

    caution icon
    caution

    Your Salesforce metadata will be committed to this repository, so be careful not to accidentally use a public repository if you are not comfortable making your Salesforce metadata visible to the public.

    warning icon
    warning

    This value will be stored un-encrypted in our state store. Please do not use any URLs that contain authentication secrets (e.g. https://<secrettoken>@github.com/myrepo.git).

  • -b|--gitBranch=<branchName>

    Required. Prompted for when not specified, and possible to do so. Defaults to main if not specified.

    The name of the branch to back the production environment. Metadata that is retrieved from the production organisation is committed to this branch, and metadata changes made in this branch can be deployed to the production Salesforce organisation. The branch will be created from the head of the default branch (only if the branch does not already exist on the remote).

  • -a|--archivePath=<relativePath>

    Defaults to / if not specified.

    The path relative to the root of the repository that Salesforce metadata will be committed to. For example, specify --archivePath=/ to put the metadata at the root fo the repo, or --archivePath=src/ to put the metadata into a folder called src.

  • -i|--include=<category>[,<category>,...]

    Prompted for when not specified, and possible to do so.

    The categories of metadata types that should added to the initial .orgflowinclude for the new stack (see .orgflowinclude File for more information) and included when flowing changes between Salesforce and your Git repository.

    The following categories are supported:

    • code: Apex and VisualForce code components (cannot be modified in production)
    • process: Process customizations (rules, approval processes, flows and workflows)
    • general: Most commonly used point-and-click customizable configuration
    • user: Common user-created metadata such as reports, dashboards and documents (can significantly increase flow times)
    • einstein: Most commonly used Einstein AI component types
    • tableau: Most commonly used Tableau CRM analytics and BI component types
    • sc: Most commonly used Service Cloud component types
    • ec: Most commonly used Experience Cloud component types

    To create the stack with an empty .orgflowinclude file and manually add rules to it later, omit this argument and select no categories if prompted.

    If there is already a .orgflowinclude file in the Git repository, any existing rules will be preserved. Any new types specified by this argument will be prepended to the existing file so that any existing rules will take precedence.

  • -su|--signInUrl=<url>

    If specified, then this URL will be used when authenticating with the production Salesforce organization. This is useful if your organization is configured in a way that authentication is only possible via a 'My Domain' custom domain (e.g. https://myorganisation.my.salesforce.com).

    If not specified, the OrgFlow CLI will use https://login.salesforce.com.

    tip icon
    tip

    If you have 'My Domain' enabled then you should supply this value as it allows a workaround for a known Salesforce issue when authenticating with a recently created sandbox. If you have 'My Domain' enabled and you have your org configured to prevent log in the standard URL then you must supply this value.

  • -u|--username=<username>

    Required. Prompted for when not specified, and possible to do so.

    The username to be used to authenticate with the production Salesforce organization.

  • -p|--password=<password>

    If supplied, then this password will be used to authenticate with the production Salesforce organization. If omitted, an interactive browser-based sign-in flow will be used.

  • --environmentTags=name[:value][,name[:value],...]

    One or more tags to set on the production environment. Omitting a value sets a tag with no value. Tag names may only contain alphanumeric characters, hyphens and underscores. Tag values may contain anything except newline characters. Spaces in tag values can be set using shell-specific quoting. Commas in tag values can be set by escaping them with backslash as \, e.g. --tags=FullName:Payne\,Chris.

  • --saveCredentials=[Local|StateStore]

    If specified, the credentials for Salesforce will be saved so that they can be re-used.

    • Local: The credentials are saved on (and can only be re-used by) the current device.
    • StateStore: The credentials are saved in the state store, and can be re-used by anyone with access to the encryption key and current stack.

    If not specified (and possible to do so), the CLI will guide the user through storing credentials for re-use. This will happen after the stack initialization process has completed.

  • --credentialsScope=[All|ProductionEnvironment]

    Defaults to All.

    • All: The credentials are saved at the stack level, and can be applied to every environment on the stack.
    • ProductionEnvironment: The credentials are only used to authenticate with the production environment.

  • -k|--encryptionKey=<key>

    An encryption key will be generated for you if --saveCredentials is specified and --encryptionKey is omitted.

    The encryption key to be used to encrypt saved credentials (if any).

  • --ensurePortable

    By default, OrgFlow optimizes some metadata types for effective version control, at the expense of compatibility with other tools, when committing your Salesforce metadata to your Git repository. Specifying --ensurePortable configures your stack to instead optimize metadata in your repository for compatibility with other tools, by disabling those optimizations.

  • --keepZipFiles

    If specified, the zip files that are downloaded from the Salesforce Metadata API are kept on disk as opposed to being deleted after they have been unzipped and processed.

The following options are global across all commands:

  • -h|--help

    If specified, prints help for this command instead of executing it.

  • -l|--licenseKey=<key>

    The License Key you were issued to allow you to use the OrgFlow CLI. If a valid key is supplied, it is stored locally on the machine so that it does not need to be specified again on the next execution.

  • --acceptEula

    If specified, you are signifying that you accept our End User License Agreement (EULA). You only need to specify this once per device, because your acceptance will be cached on the device (you can pass --acceptEula=false if you wish to clear this). You must accept our EULA to be able to run most OrgFlow commands.

  • --logTo=<filePath>

    If specified, a log file is written to the specified path. The specified path may contain one or more tokens; see Logging for more information.

  • --logLevel=[Verbose|Debug|Information|Warning|Error|Fatal]

    Default: Information

    The minimum log level to be written to the log file; logs below this level will not be written. Only effective if a valid value for --logTo has been specified.

  • --diagnostic=[Auto|Always|Never]

    Default: Auto

    If the CLI encounters an exception then it will ask (where possible) the user whether or not to create a Diagnostic Bundle and write it to disk. If it is not able to prompt then no action is taken. This is the default behaviour (Auto).

    You can change this default behaviour (and suppress the prompt) by specifying either Always or Never (which will always write the bundle or never write the bundle, respectively). This is particularly useful in a CI/CD context, where the CLI may not be able to prompt, but you still want to create diagnostic bundles for all failures.

  • --diagnosticDirPath=<directoryPath>

    If specified, sets the location to write the Diagnostic Bundle (if any). If not specified, a default location will automatically be chosen. This default location depends on a number of factors, including the operating system and some file-system based restrictions that might be in place. The location that the diagnostic bundle is ultimately written to is always included in the standard error output of the CLI.

  • --noConfirm

    If specified, suppresses confirmation prompts that the CLI might raise before performing destructive or dangerous procedures. If suppressed, the CLI assumes that the prompts would have been answered positively and continues with execution.

  • --progress=[Interactive|Never|Always]

    Default: Interactive

    Controls how progress is printed to the standard error stream:

    • Interactive: Progress is sent to the standard error stream only if the standard error stream is connected to an interactive terminal.
    • Never: Progress is not sent to the standard error stream.
    • Always: Progress is sent to the standard error stream, even if that stream has been redirected.

  • --tempDir=<directoryPath>

    If specified, sets the location to use as storage for files that may need to be stored on disk temporarily during command execution. For example, the location on disk where zip files containing metadata from Salesforce are downloaded to before they are unzipped.

    If not specified, the CLI will automatically choose an appropriate location on disk (usually in the current user's temporary storage location). This automatically chosen location may be deeply nested within a drive, which may be problematic if the operating system imposes limits on file path lengths and the files placed into temporary storage have particularly long paths or names.

  • --json

    Switches the format of the output sent to the standard output stream to JSON. This is the most verbose output available, and is useful for scripting or automation.

  • --forceSignIn.

    If specified, the CLI will ignore any cached Salesforce access tokens, and will require the Salesforce authentication process to be re-completed for each organisation that the command connects to.

  • --maxTransientErrorRetries=<count>.

    If no value is specified, the CLI will indefinitely retry any process that fails due to a transient error. This is the default behaviour, and allows for resilience against temporary issues that might otherwise cause a process to fail.

    Specify a positive integer value to prevent indefinite retries. Each process that fails due to a transient error will be retried up to a maximum amount of times specified. For example, --maxTransientErrorRetries=5: Each process that fails will be re-tried up to a maximum of five times. If an earlier process fails four times but then succeeds on the fifth attempt, the counter is reset for the next process.

    Specify --maxTransientErrorRetries=0 to disable transient failure retries.

  • --maxTransientErrorDelay=<seconds>.

    Default: 60

    Processes retried due to a transient error are delayed by a back-off policy that gradually increases the time to wait between retries. Specify a non-negative integer value as the maximum amount of seconds to wait between attempts.

    Specify --maxTransientErrorDelay=0 to disable the back-off policy and always instantly retry failed processes.

Examples

To be interactively guided through the Creation process:

orgflow stack:create

Create a new stack called NightlyBackup with a production environment called Prod. Commit all metadata to a repository on GitHub, inside a folder called metadata. Use a custom URL to authenticate with Salesforce:

orgflow stack:create --name=NightlyBackup --environmentName=Prod --gitRepoUrl="git@github.com:MyOrg/MyRepo.git" --archivePath=metadata --include=All --signInUrl="https://myorg.my.salesforce.com" --username=user@orgflow.io