Org Health & Operations

Most commands here accept --org <alias> (defaults to config.defaultOrg) and --json.

sfdt audit

Diagnoses org health. Run a single check or all.

sfdt audit all
sfdt audit mfa
sfdt audit licenses --org production --json
sfdt audit all --notify          # also push the snapshot to notification channels

Results are written to logs/audit-latest.json (consumed by the dashboard and the VS Code Org Health sidebar). audit all exits non-zero when any check is fail or error, so it doubles as a CI gate.

sfdt monitor

Monitors org operational health. Run a single check or all.

sfdt monitor all
sfdt monitor limits
sfdt monitor all --backup    # include a metadata backup in the run
sfdt monitor all --notify    # push the snapshot to notification channels

Results land in logs/monitor-latest.json. monitor all exits non-zero when any check is fail or error.

Graceful degradation

Some checks depend on Beta or license-gated objects (MetadataComponentDependency, DeployRequest, FlowInterview, ConnectedApplication, ValidationRule/WorkflowRule, EventLogFile). When an org can’t run one of these, the check returns warn (“unavailable …”) rather than error, so audit all / monitor all never fail CI just because an org lacks a particular API or license.

sfdt monitor backup

Retrieves a full metadata backup into monitoring.backupDir.

sfdt monitor backup
sfdt monitor backup --org production --json

sfdt docs

Generates documentation and diagrams from your org/source.

sfdt docs generate                       # objects, Apex, flows (MkDocs-compatible)
sfdt docs generate --ai                  # force the AI overview on
sfdt docs generate --no-ai               # force the AI overview off
sfdt docs generate --roles developer,admin   # per-component role guides (AI)
sfdt docs generate --no-diagrams         # skip the standalone ER-diagram page
sfdt docs diagram                        # print a Mermaid ER diagram
sfdt docs diagram --output erd.mmd

sfdt data

Manages data sets via the native sf data tree, for seeding sandboxes and scratch orgs.

sfdt data list
sfdt data export AccountsAndContacts
sfdt data import AccountsAndContacts
sfdt data delete AccountsAndContacts --yes

Common options: --org <alias>, --json.

load and delete both write, so both carry a production guard (--production) and a confirmation that refuses rather than auto-confirms when non-interactive (--yes to skip it). load inserts or upserts, and an upsert overwrites records that are already there. Neither is recorded in the ledger: sfdt ledger undo covers org configuration, not bulk data writes.

sfdt scratch

Creates, deletes, lists, and pools scratch orgs.

sfdt scratch create --alias feature-x --days 7
sfdt scratch list
sfdt scratch delete --alias feature-x
sfdt scratch pool --size 3

Options: --alias <name>, --days <n>, --size <n>, --json.

sfdt notify

Pushes a deployment-lifecycle event or an org-health snapshot to configured notification channels (Slack, Microsoft Teams, Google Chat, email, generic webhook, or Grafana Loki).

sfdt notify deploy-success
sfdt notify deploy-failure --org production --version 1.5.0
sfdt notify test-failure --message "Coverage dropped below threshold"
sfdt notify release-created --version 1.5.0
sfdt notify snapshot --type monitor       # push the latest monitor snapshot
sfdt notify snapshot --type audit

sfdt automation

The on/off grid across every kind of Salesforce automation, and the toggles behind it.

sfdt automation list
sfdt automation list --type validation-rule
sfdt automation disable validation-rule Account.Region_Required --dry-run
sfdt automation disable validation-rule Account.Region_Required
sfdt automation enable flow Set_Region

The five types do not cost the same to toggle, and the grid says so at the point of use. Flows, validation rules and duplicate rules are Tooling record writes. Workflow rules and Apex triggers need a metadata deploy — and a production deploy runs tests, so toggling a trigger there is a deployment with everything that implies.

Common options: --org <alias>, --dry-run, --yes, --production, --json.

sfdt permissions

Object and field access — what is granted, by which profile or permission set, and where the org disagrees with your repository.

sfdt permissions matrix --object Account
sfdt permissions drift Account
sfdt permissions grant Account.Region__c --parent "Sales Ops" --level edit
sfdt permissions revoke Account.SSN__c --parent "Sales Ops"
sfdt permissions fix Account --dry-run

Reports what is granted, never “effective”: muting permission sets cannot be queried, and a stronger claim would be an upper bound presented as a fact.

Profiles are refused by name. Salesforce does not permit direct DML on profile-owned permission entries — those must go through the Metadata API, so change them in source and deploy. Refusing up front beats an opaque INSUFFICIENT_ACCESS_OR_READONLY that reads like a problem with your own access.

fix applies only missing-in-org rows. Grants the org has that source does not are deliberately left alone — removing access nobody asked to remove is a different, and riskier, decision.

Common options: --org <alias>, --dry-run, --yes, --production, --json.

sfdt record

Read, edit, or clone a single record, using the same editability model as the Chrome extension’s inspector — so a field refused here is refused for the identical stated reason in the browser.

sfdt record get 001800000000001AAA
sfdt record edit 001800000000001AAA --set Name="Acme Corp" --set AnnualRevenue=250000
sfdt record clone 001800000000001AAA --set Name="Acme Corp (copy)"

Non-editable fields are refused locally, by name, before anything reaches the org — formula fields, auto-numbers, and fields your permissions do not cover. A field hidden from you by field-level security is never written as null over a value you were not allowed to see.

A save reports exactly one of three outcomes: saved, nothing was saved, or outcome unknown — the last when a request times out and the write may in fact have committed. Exiting 0 on an unknown outcome would tell a script the change landed.

Common options: --org <alias>, --sobject <name>, --dry-run, --json.

sfdt events

Platform Events and Change Data Capture.

sfdt events list
sfdt events tail Order_Placed__e
sfdt events tail AccountChangeEvent --replay all
sfdt events publish Order_Placed__e --field Order_Id__c=A-1

A channel whose query is refused is reported as unchecked — it never silently becomes “your org has none”.

Common options: --org <alias>, --dry-run, --yes, --production, --json.

sfdt packages

Installed package inventory, your own annotations, and version drift between orgs.

sfdt packages list
sfdt packages compare --source prod --target uat
sfdt packages note ecflc --owner "Platform team" --latest 1.7.0

note writes .sfdt/packages.json, a committed file — so an annotation is shared and code-reviewed rather than trapped on one machine. Merges are additive: fields you do not supply are left alone, including keys written by a newer sfdt that this one does not understand.

Common options: --org <alias>, --json.

sfdt history

Shows recent runs from the local run index so org-health, coverage, test, and deploy outcomes can be trended over time instead of only reading the latest snapshot. Every audit, monitor, quality, test, deploy, rollback, and agent-test run is recorded to a compact SQLite index (logs/history.db); audit and monitor also archive full timestamped snapshots under logs/audit-results/ and logs/monitor-results/. Recording is best-effort — a history failure never fails the command.

sfdt history
sfdt history --type audit
sfdt history --type deploy --limit 50
sfdt history --json

sfdt versions

Audit Salesforce API versions across local source and the org: which versions your Apex classes/triggers, Flows, LWC, and Aura components are on, compared against the org’s max API version. The local scan reads only the -meta.xml sidecars, so it works fully offline; components whose meta omits <apiVersion> are reported as unspecified (they inherit sourceApiVersion at deploy time) and never counted as outdated.

sfdt versions                    # local scan + org comparison (default org)
sfdt versions --org uat          # against a specific org
sfdt versions --local-only       # fully offline — no org calls
sfdt versions --json             # full report for scripting / MCP

Output shows per-type version histograms (red = below audit.minApiVersion, yellow = behind the org ceiling when audit.apiVersionWarnBehind is set), the org’s max API version and release (e.g. Org max: v67 — Summer '26), and the outlier components with a below-floor / behind-ceiling reason each.

The report is informational (exit 0) — the CI-gating surface is sfdt audit api-versions, which shares the same thresholds. The MCP server exposes the same report as the read-only sfdt_api_versions tool, and the Chrome extension’s api-version-audit feature shows the org-side histograms as a Setup pill.

--advise — registry-grounded AI upgrade advice

With features.ai enabled, sfdt versions --advise explains what upgrading unlocks and what breaks: value, risks, breaking changes in the upgrade path, effort (S/M/L), minimal code changes, an upgrade order across component types, and verification steps (including sfdt quality --api67 when the path crosses v67).

sfdt versions --advise                       # advise toward the org max (or registry max offline)
sfdt versions --advise --target 67           # explicit target version
sfdt versions --advise --type apex           # only Apex classes/triggers

The advice is grounded by a curated per-version registry shipped with the CLI: the AI may cite version facts only from the registry, and answers “unknown — not in registry” for anything it lacks — it never states version facts from model memory. The advisory is strictly read-only: CLI providers may read component source to ground their analysis (which is how the advice can cite your actual files and lines), but nothing is ever written or auto-fixed. The prompt is user-editable as api-upgrade-advisor in the prompt editor.