Skip to content

Configuration

A Browserforce config file is a JSON file whose settings object holds one key per setting to apply. The Settings section describes each of them, with examples.

{
  "$schema": "https://raw.githubusercontent.com/amtrack/sfdx-browserforce-plugin/main/src/plugins/schema.json",
  "settings": {
    "companyInformation": {
      "defaultCurrencyIsoCode": "English (South Africa) - ZAR"
    }
  }
}

Apply it to an org:

sf browserforce apply -f ./config/currency.json --target-org myOrg@example.com

Key concepts

  • 🔧 JSON Schema: the $schema line gives completion, validation and documentation links in editors like VS Code, similar to the Scratch Org Definition Configuration. Start from an empty configuration or explore a full-blown example.
  • 🧠 Idempotency: apply reads the current state of the org first and only changes what differs, so it can be run again and again (a concept similar to terraform). A second run with the same config reports no action necessary.
  • 👀 Dry run: sf browserforce apply --dry-run shows the changes it would make without applying them.
  • 🏎️ Browser automation powered by Playwright, for the settings that the Metadata API does not support.

Environment variables in config files

A value written exactly as "${VARIABLE_NAME}" is read from the environment variable VARIABLE_NAME when running sf browserforce apply. Use it to keep secrets out of config files, for example in a CI pipeline:

{
  "settings": {
    "authProviders": {
      "MyAuthProvider": {
        "consumerKey": "my-consumer-key",
        "consumerSecret": "${MY_AUTH_PROVIDER_SECRET}"
      }
    }
  }
}
  • The value is converted to the type the setting expects: true/false for a checkbox, a number, or JSON for a list or an object.
  • A variable that is not set, or empty, stops the command before logging in, naming the setting and the variable.
  • Values coming from environment variables are shown as **** in the output.
  • Only a value that is exactly ${NAME} is replaced: "prefix-${NAME}" stays as written.
  • To keep the literal text ${NAME} as a value, write $${NAME}.

Describe and validate settings without an org

  • sf browserforce plugins list --json describes every setting: its documentation page (docUrl), its JSON Schema, its fields, examples, and warnings (irreversible changes, Classic-only features, org prerequisites). Tools building Browserforce configurations, like sfdx-hardis deployment actions, read it.
  • sf browserforce plugins validate -f ./config/currency.json checks a config file and reports each error with its path and the documentation page of the setting. Environment variable references are accepted and listed.
  • sf browserforce apply --json returns the planned changes of each setting (applied, or only planned with --dry-run), with secrets and values from environment variables masked.

See the Commands reference for every flag.