cirrus-for-sfdx

Cirrus CLI

A lean command-line interface tool for Salesforce development automation.

The Cirrus CLI streamlines repetitive Salesforce tasks by allowing you to automate flows of commonly run commands. Whether you're initializing new scratch orgs, deploying code, installing dependencies, or importing data, Cirrus lets you automate these processes with simple, reusable configurations.

It is intended to be a lightweight alternative to CumulusCI. Unlike CumulusCI, Cirrus is distributed as a standalone binary—so no Python or pip required—so you can get started instantly without extra dependencies.

Cirrus aims to provide a straightforward experience that is powerful enough for most use cases.

Installation

Using npm (recommended)

npm install -g cirrus-for-sfdx

Using npx (no installation required)

npx cirrus-for-sfdx <command>

Quick Start

• Initialize a cirrus.toml configuration file in your project:

  cirrus init
  

• Edit cirrus.toml to define your scratch orgs, commands, and flows

• Run commands or flows:

  cirrus run <command_name>
  cirrus flow <flow_name>
  

Usage

After installation, you can use the cirrus command from anywhere in your terminal:

cirrus <command> [options]

Available Commands

Global Commands

cirrus --help    # Show help information
cirrus --version # Show version information

cirrus init

Initializes a new cirrus.toml configuration file in the current directory.

cirrus init

This creates a cirrus.toml file with commented examples to help you get started.

cirrus run

Executes predefined commands from your cirrus.toml file.

cirrus run <subcommand> [options]

Built-in Subcommands

create_scratch

Creates a Salesforce scratch org based on definitions in your cirrus.toml file.

cirrus run create_scratch -n <org_name> [-a <alias>]

Options:

• -n, --name (required): The name of the scratch org definition to create
• -a, --alias: Optional alias for the scratch org

Example:

cirrus run create_scratch -n default -a my-scratch-org

Custom Commands

Any command defined in the [commands] section of your cirrus.toml can be run:

cirrus run <custom_command_name>

cirrus flow

Executes predefined flows from your cirrus.toml file.

cirrus flow <flow_name>

Flows allow you to orchestrate multiple commands and actions in sequence. Each step in a flow is executed one after another, and the flow stops if any step fails.

Example:

cirrus flow setup
cirrus flow deploy-and-test

cirrus package

Creates a new package version for Salesforce managed or unlocked packages.

cirrus package -p <package_name> [options]

This command automates the package versioning process by:

• Reading your sfdx-project.json file
• Automatically incrementing the version number based on the version type
• Updating the sfdx-project.json with the new version
• Running sf package version create with your specified options

Options:

• -p, --package (required): The name of the package to release, as defined in the sfdx-project.json file
• -t, --version-type: The version type to increment (default: minor)
  • major: Increments X.0.0 (for breaking changes)
  • minor: Increments 0.X.0 (for new features)
  • patch: Increments 0.0.X (for bug fixes)
• --promote: Whether to promote the package version after creation (default: false)
• -a, --name: The name/label for the new version
• -c, --code-coverage: Calculate and store code coverage percentage
• -f, --definition-file: Path to a definition file with required features and org preferences
• -k, --installation-key: Installation key for key-protected packages
• -x, --installation-key-bypass: Bypass the installation key requirement
• -v, --target-dev-hub: Username or alias of the Dev Hub org
• -w, --wait: Number of minutes to wait for package version creation
• --async-validation: Return immediately without waiting for validation
• --skip-validation: Skip validation during creation (can't promote unvalidated versions)
• --verbose: Display verbose command output

Please be aware that at least one of --installation-key or --installation-key-bypass must be provided.

Examples:

# Create a minor version update
cirrus package -p MyPackage

# Create a major version with a specific name
cirrus package -p MyPackage -t major -a "Summer 2024 Release"

# Create a patch version with code coverage
cirrus package -p MyPackage -t patch -c

# Create version with installation key and wait 30 minutes
cirrus package -p MyPackage -k MySecretKey123 -w 30

Configuration (cirrus.toml)

The cirrus.toml file uses TOML format to define scratch org configurations, custom commands, and automation flows.

Scratch Org Definitions

Define scratch orgs using the [[orgs]] array notation. Each org must have:

• name: A unique identifier for the org configuration
• definitionFile: Path to the Salesforce scratch org definition JSON file
• duration (optional): Number of days the scratch org should last (1-30)

[[orgs]]
name = "default"
definitionFile = "config/project-scratch-def.json"
duration = 30

[[orgs]]
name = "dev"
definitionFile = "config/dev-scratch-def.json"
duration = 7

[[orgs]]
name = "testing"
definitionFile = "config/test-scratch-def.json"
# duration is optional, defaults to Salesforce default

Flow Definitions

Flows allow you to execute a sequence of steps one after another.

Define flows using the [flow] syntax. Each flow should have:

• name: A unique name for the flow
• description (optional): A brief description of what the flow does
• steps: A list of steps present in the flow

Supported step types:

• create_scratch: Creates a scratch org
• command: Runs a predefined command

Examples:

# Simple flow to setup and deploy
[flow.setup]
description = "Create scratch org and deploy metadata"
steps = [
  { type = "create_scratch", org = "default" },
  { type = "command", name = "deploy" }
]

# More complex flow with multiple commands
[flow.complete-setup]
description = "Full environment setup with data and tests"
steps = [
  { type = "create_scratch", org = "dev", set-default = true },
  { type = "command", name = "deploy" },
  { type = "command", name = "load-sample-data" },
  { type = "command", name = "run-tests" }
]

# Testing flow
[flow.test]
description = "Run all tests with coverage"
steps = [
  { type = "command", name = "compile" },
  { type = "command", name = "test" },
  { type = "command", name = "coverage-report" }
]

Custom Commands

Define custom commands in the [commands] section. Each command is a key-value pair where:

• Key: The command name (used with cirrus run <name>)
• Value: The shell command to execute

[commands]
# Simple commands
hello = "echo 'Hello, World!'"
status = "sf org list"

# Complex commands with multiple steps
deploy = "sf deploy source --target-org my-org"
test = "sf apex test run --test-level RunLocalTests --code-coverage"

# Commands can use shell features like pipes and redirects
backup = "sf data export --target-org prod --output-dir ./backups"
format = "prettier --write 'force-app/**/*.{cls,trigger,js}'"

Platform Support

Cirrus CLI supports the following platforms:

• Linux (x64)
• macOS (x64, arm64)
• Windows (x64)

Development

This CLI is built with Dart and distributed as platform-specific binaries through npm.

Setting Up for Development

• Install Dart SDK (if not already installed)
• Clone the repository
• Install dependencies:

  dart pub get
  

Running Tests

dart test

Building

dart compile exe bin/cirrus.dart -o bin/cirrus