Configuration

Running sfdt init creates a .sfdt/ directory in your project root. Every command reads it.

The .sfdt/ directory

• .sfdt
  • config.json
  • environments.json
  • test-config.json
  • pull-config.json
  • *.local.json
  • plugins
  • cache
  • data
  • feature-flags.json
  • telemetry-snapshot.json
  • bridge-token

config.json reference

A representative config.json:

{
  "projectName": "My Salesforce Project",
  "defaultOrg": "my-dev-org",
  "deployment": {
    "coverageThreshold": 75,
    "backupBeforeRollback": true,
    "preflight": {
      "enforceTests": false,
      "enforceBranchNaming": false,
      "enforceChangelog": false
    }
  },
  "features": {
    "ai": true,
    "notifications": false,
    "releaseManagement": true
  },
  "ai": { "provider": "claude", "model": "" },
  "pullCache": { "enabled": true, "parallelism": 5, "batchSize": 100 },
  "mcp": { "enabled": false, "parking": { "enabled": true } },
  "plugins": []
}

Top-level keys

Repo-supplied settings that need an opt-in

.sfdt/config.json is meant to be committed — sfdt init recommends gitignoring only .sfdt/*.local.json — so it arrives with whatever repository you cloned, written by whoever wrote it. Since 0.22.0, the settings in it that execute code or choose where secrets are sent are refused at load time. sfdt names each one it skipped and how to allow it; everything else in the file loads normally.

To allow them:

export SFDT_ALLOW_UNSAFE_CONFIG=1

Unaffected, no opt-in needed: ai.apiKeyEnv and ai.headersEnv (inert once the destination is gone), a loopback ai.baseURL — so Ollama, LM Studio, llama.cpp and vLLM keep working — a channel using webhookUrlEnv, an ordinary Slack webhookUrl with no headersEnv, and defaultOrg.

deployment

features

Feature toggles. All default to true except notifications.

ai

See AI Providers for full setup.

pullCache

mcp

See the MCP Server page for details.

audit, quality, monitoring, docs, data, scratch, soql

ci

Defaults for sfdt ci init. Flags override config; config overrides built-in defaults. (--type scratch also reads the existing scratch.definitionFile key.)

{
  "ci": {
    "authMethod": "sfdx-url",    // sfdx-url | jwt
    "environment": "production", // release approval environment
    "runner": "npx"              // npx | docker | action
  }
}

notifications

Multi-channel push to Slack, Microsoft Teams, Google Chat, email, a generic webhook, or Grafana Loki. Secrets are referenced by env-var name, never inline. The older single-Slack shape is still honored when features.notifications: true.

{
  "features": { "notifications": true },
  "notifications": {
    "enabled": false,                 // master switch for the channels[] system
    "summary": { "enabled": false },  // send AI executive summaries for snapshots
    "channels": [
      // type: slack | teams | googlechat | email | webhook
      // common: name, severityThreshold (ok|warn|error|fail), events[]
      // slack/teams/googlechat: webhookUrl | webhookUrlEnv
      // webhook: url | urlEnv, format (json|loki), headers{}, headersEnv{} (auth — env-var NAMES)
      // email: from, to[], smtp{ hostEnv, portEnv, userEnv, passwordEnv, secure }
    ],
    // legacy single-Slack shape (still honored when features.notifications=true):
    "slack": { "webhookUrl": "", "webhookUrlEnv": "" }
  }
}

See the Notifications page for channel fields and severity routing.

deployment.smart

Settings for Smart Deploy (sfdt deploy --smart).

{
  "deployment": {
    "smart": {
      "enabled": false,
      "deltaBase": "main",
      "noOverwriteManifest": "manifest/package-no-overwrite.xml",
      "impactingTypes": ["ApexClass", "ApexTrigger", "Flow"],
      "downgradeTestsOnNonProd": true,
      "useRelevantTests": false,
      "assumeProd": false
    }
  }
}

deployment.smart.useRelevantTests (default false) opts non-production orgs on API ≥ 66 into Salesforce’s beta RunRelevantTests in place of the RunLocalTests fallback — see Smart Deploy.

ai.headers / ai.headersEnv

Extra request headers for the http provider. headers takes literal values; headersEnv maps a header name to the name of an env var holding its value — use it for anything secret, so the token stays out of .sfdt/config.json. headersEnv overrides a literal of the same name, and an unset variable fails the request naming it rather than calling the endpoint without the header. See AI Providers.

{ "ai": { "headersEnv": { "X-Org-Id": "GATEWAY_ORG_ID" } } }

ai.agent

The bounded coding-agent auto-fix loop for sfdt deploy --smart --ai-fix. Off by default; requires both enabled and allowWrite. See Smart Deploy.

{ "ai": { "agent": { "enabled": false, "maxTurns": 3, "allowWrite": false } } }

Reading & writing config

Use dot notation from the command line:

sfdt config get defaultOrg
sfdt config get deployment.coverageThreshold
sfdt config set deployment.coverageThreshold 80
sfdt config set features.ai true

Values are coerced automatically: "true"/"false" become booleans, numeric strings become numbers, everything else stays a string.