@sfdt/cli

Production-grade CLI for Salesforce DX deployment, testing, quality analysis, and release management.

Features

• Interactive deployment workflows with preflight validation, tagging, and PR creation
• Automated release manifest generation from git diffs
• Parallel Apex test execution with configurable coverage enforcement
• Code and test quality analysis with AI-powered fix plans
• Pre-release validation checklist (sfdt preflight)
• Deployment rollback with pre-rollback org state backup
• Post-deploy smoke testing
• Org metadata drift detection
• Multi-package project support — scope manifests and deploys to individual packageDirectories with --package and --name; deploy source folders directly with --source-dir
• Smart package.xml generator from git diffs with AI dependency cleanup (sfdt manifest)
• AI deployment error log interpreter with heuristic fallback for offline use (sfdt explain)
• AI-generated PR descriptions and Slack messages from deployment changes (sfdt pr-description)
• AI-powered code review, test failure analysis, changelog generation, and release notes — optional, works with Claude, Gemini, or OpenAI
• Org metadata comparison — diff two orgs or local source vs org with optional package.xml export (sfdt compare)
• Local web dashboard for test results, preflight, drift monitoring, and org comparison (sfdt ui)
• Plugin architecture — extend sfdt with sfdt-plugin-* npm packages or local .sfdt/plugins/ scripts
• Slack notifications for deployment events
• Works with any Salesforce DX project — no project-specific values hardcoded

For in-depth command walkthroughs and workflow examples, see docs/USAGE.md.

Repository layout

@sfdt/cli is one of four workspaces in this monorepo:

| Workspace | What it is | Status | |---|---|---| | @sfdt/cli (/src, /bin, /scripts) | The npm CLI documented below. | Published to npm | | @sfdt/extension (/extension) | Chrome extension for Salesforce Flow Builder + Setup productivity. Talks to the CLI via the local bridge for deploy / rollback / quality / AI features. See extension/README.md and extension/PRIVACY.md. | Pre-Web-Store | | @sfdt/host (/host) | Native messaging host used as the extension's fallback transport when sfdt ui isn't running. Installed with sfdt extension install-host. | Bundled with CLI | | @sfdt/flow-core (/packages/flow-core) | Shared TypeScript library — Flow normalization, rules engine, scoring, and the versioned bridge contract. Consumed by both CLI and extension. | Workspace-only (not yet on npm) |

The CLI's sfdt ui command starts a local web dashboard (/gui) that exposes the same bridge endpoints the extension uses.

Quick Start

npm install -g @sfdt/cli
cd your-salesforce-project
sfdt init
sfdt deploy

Commands Reference

Core

| Command | Description | Key Options | |---|---|---| | sfdt init | Initialize .sfdt/ config (interactive) | — | | sfdt deploy | Deploy to a Salesforce org | --managed, --skip-preflight, --dry-run, --source-dir <path> | | sfdt release | Generate release manifest + optional AI release notes | --package <name\|all>, --name <label> | | sfdt test | Run Apex tests with the enhanced test runner | --legacy, --analyze, --dry-run | | sfdt pull | Pull metadata from the configured org | --dry-run | | sfdt preflight | Run pre-deployment validation checks | --strict, --dry-run | | sfdt rollback | Roll back a deployment to a target org | --org <alias>, --dry-run, --json | | sfdt smoke | Post-deploy smoke tests | --org <alias>, --dry-run | | sfdt drift | Detect metadata drift between local source and an org | --org <alias>, --json | | sfdt compare | Compare metadata between two orgs or local source vs an org | --source <alias\|local>, --target <alias>, --output <file> | | sfdt scan | Fetch complete metadata inventory from an org | --org <alias>, --output <file>, --format json\|table | | sfdt notify | Send Slack deployment notifications | --org <alias>, --version <ver>, --message <msg> | | sfdt config get <key> | Print a config value using dot notation (e.g. defaultOrg) | — | | sfdt config set <key> <value> | Set a config value using dot notation (e.g. deployment.coverageThreshold) | — | | sfdt completion <shell> | Print shell completion script (bash, zsh, fish) | — | | sfdt version | Print the current sfdt version | — | | sfdt update | Update sfdt to the latest version from npm | --force |

AI & Intelligence (Phase 3)

| Command | Description | Key Options | |---|---|---| | sfdt manifest | Build package.xml from git diffs | --base <ref>, --head <ref>, --package <name\|all>, --name <label>, --output <path>, --destructive <path>, --ai-cleanup, --print | | sfdt explain [file] | Analyze a deployment error log with AI + heuristics | --from-stdin, --latest | | sfdt pr-description | Generate a PR description or Slack message | --base <ref>, --head <ref>, --format github\|slack\|markdown, --output <path>, --commit-limit <n> | | sfdt review | AI code review of current branch changes | --base <branch> | | sfdt changelog | Manage changelog files (global or per-package) | subcommands: generate, release <version>, check; --package <name> scopes to a specific package | | sfdt quality | Code & test quality analysis | --tests, --all, --fix-plan, --generate-stubs, --dry-run | | sfdt ai prompt <text> | Run a prompt through the configured AI provider and print the result | — |

Platform (Phase 4)

| Command | Description | Key Options | |---|---|---| | sfdt ui | Launch local Salesforce Lightning Design System dashboard | --port <n> (default 7654), --no-open |

Extension & bridge

| Command | Description | Key Options | |---|---|---| | sfdt extension install-host | Register the Chrome native messaging host so the extension can fall back to native transport when sfdt ui isn't running | --extension-id <id>, --browser <chrome\|edge\|brave\|chromium\|vivaldi\|all> | | sfdt extension uninstall-host | Remove the native host manifest | --browser <browser> | | sfdt extension status | Report which browsers have the native host installed | --json | | sfdt extension stats | Show the latest telemetry snapshot the extension pushed to .sfdt/telemetry-snapshot.json | --json, --limit <n> | | sfdt feature-flags list | List remotely-disabled features from .sfdt/feature-flags.json | --json | | sfdt feature-flags disable <id> | Add a feature id to the kill-switch | --json | | sfdt feature-flags enable <id> | Remove a feature id from the kill-switch | --json | | sfdt feature-flags clear | Re-enable everything | --remove, --json | | sfdt doctor --extension | Diagnose the extension stack (bridge reachable, native host, kill-switch file, telemetry) | --port <n>, --json |

Configuration

Running sfdt init creates a .sfdt/ directory in your project root:

.sfdt/
  config.json          # Core settings: org aliases, feature flags, AI provider, coverage threshold
  environments.json    # Named environments and org aliases
  test-config.json     # Test classes, coverage threshold, test level
  pull-config.json     # Metadata types to pull from org

config.json

{
  "projectName": "My Salesforce Project",
  "defaultOrg": "my-dev-org",
  "deployment": {
    "coverageThreshold": 75,
    "preflight": {
      "enforceTests": false,
      "enforceBranchNaming": false,
      "enforceChangelog": false
    }
  },
  "features": {
    "ai": true,
    "notifications": false,
    "releaseManagement": true
  },
  "ai": {
    "provider": "claude",
    "model": ""
  },
  "plugins": []
}

AI Features

AI-powered commands (review, explain, manifest --ai-cleanup, quality --fix-plan, pr-description, changelog generate, release) work with Claude, Gemini, or OpenAI/Codex CLI providers. The provider is configured during sfdt init or by editing .sfdt/config.json.

Claude (default)

Requires the Claude Code CLI:

npm install -g @anthropic-ai/claude-code

{ "ai": { "provider": "claude" } }

Claude's interactive mode lets AI commands read your repository files directly with tool use.

Gemini

Requires the Gemini CLI:

npm install -g @google/gemini-cli

{ "ai": { "provider": "gemini", "model": "" } }

Authentication and model selection are handled by the Gemini CLI.

OpenAI

Requires the Codex CLI:

npm install -g @openai/codex

{ "ai": { "provider": "openai", "model": "" } }

Authentication and model selection are handled by the Codex CLI.

Disabling AI

Set features.ai to false to disable all AI prompts. Heuristic fallbacks still run in sfdt explain.

{ "features": { "ai": false } }

Web Dashboard (sfdt ui)

sfdt ui starts a local Express server and opens a Salesforce Lightning Design System dashboard in your browser:

sfdt ui                   # opens http://localhost:7654
sfdt ui --port 8080       # custom port
sfdt ui --no-open         # start server without opening browser

Dashboard pages:

• Dashboard — summary stat cards, recent test runs, preflight and drift status
• Test Runs — Apex test history with coverage colouring; run tests directly from the UI
• Preflight — per-check pass/fail list; run preflight directly from the UI
• Drift Detection — filterable component table (All / Clean / Drift); run drift check from the UI
• Compare — diff two orgs or local source vs an org, export source-only items as package.xml
• Scan — fetch and browse full metadata inventory from any org; writes logs/scan-latest.json
• Logs — searchable log viewer for deploy and rollback history with pagination and raw output

The dashboard reads log files from the project's configured logDir (defaults to <project>/logs). Data appears automatically after running sfdt test, sfdt preflight, or sfdt drift when those commands write JSON result files.

Build the GUI (required after cloning from source):

npm run build:gui

The pre-built gui/dist/ is included in the published npm package so end users don't need to build it.

Plugin Architecture

Extend sfdt with custom subcommands by creating a plugin.

npm package plugin

Create a package named sfdt-plugin-<name> and publish it to npm:

// sfdt-plugin-my-thing/index.js
export function register(program) {
  program
    .command('my-thing')
    .description('My custom command')
    .action(async () => {
      console.log('Hello from my-thing!');
    });
}

Install it in your Salesforce project:

npm install --save-dev sfdt-plugin-my-thing

sfdt auto-discovers all sfdt-plugin-* packages in your project's node_modules/ on startup — no config required.

Local plugin

Drop a .js file in .sfdt/plugins/:

// .sfdt/plugins/custom-deploy.js
export function register(program) {
  program.command('custom-deploy').action(async () => { ... });
}

Explicit plugin list

List plugin package names in config.plugins to load them in a specific order:

{ "plugins": ["sfdt-plugin-my-thing", "@myorg/sfdt-plugin-audit"] }

Docker

An official Docker image is available for CI/CD pipelines. It ships Node 20, Salesforce CLI, git, bash, and jq.

Build from source:

docker build -t sfdt .

Run against a mounted project:

docker run --rm \
  -v "$(pwd):/project" \
  -e SFDX_AUTH_URL="$SFDX_AUTH_URL" \
  sfdt deploy

GitHub Actions example:

- name: Deploy
  run: |
    docker run --rm \
      -v "${{ github.workspace }}:/project" \
      -e SF_ORG_INSTANCE_URL="${{ secrets.SF_ORG_INSTANCE_URL }}" \
      sfdt deploy --skip-preflight

Install the selected AI provider CLI in the container when using AI features:

docker run --rm -v "$(pwd):/project" \
  sfdt explain --latest

Pull Groups

Pull groups let you define named sets of metadata types in .sfdt/pull-config.json:

{
  "metadataTypes": [
    "ApexClass",
    "ApexTrigger",
    "LightningComponentBundle",
    "CustomObject",
    "CustomField",
    "Layout",
    "FlexiPage",
    "PermissionSet",
    "Flow"
  ],
  "targetDir": "force-app/main/default"
}

Use sfdt pull to retrieve all configured metadata types from the default org.

Pull Cache

sfdt pull uses a SQLite cache (stored in .sfdt/cache/) to track retrieved components and their modification dates. On subsequent runs, only components that have changed in the org are re-fetched, significantly reducing retrieval time for large orgs.

Cache behavior is controlled via pullCache in .sfdt/config.json:

{
  "pullCache": {
    "enabled": true,
    "parallelism": 5,
    "batchSize": 100
  }
}

| Flag | Description | |------|-------------| | sfdt pull | Incremental pull — only retrieves changed components | | sfdt pull --full | Force full retrieve and rebuild the cache | | sfdt pull --status | Show cache status (last pull time, component counts) |

Requirements

• Node.js >= 22.15.0 (uses the built-in node:sqlite module, unflagged in Node 22.15)
• Salesforce CLI (sf) installed and authenticated to target orgs
• bash 4.0+ (macOS users: brew install bash)
• jq 1.6+ (required by several shell scripts)
• Optional: Claude Code CLI for AI features with the claude provider
• Optional: Gemini CLI or Codex CLI for AI features with the gemini or openai provider
• Optional: GitHub CLI (gh) for PR creation during deployments

Development

git clone https://github.com/scoobydrew83/sfdt.git
cd sfdt
npm install
npm link              # makes `sfdt` available globally from your checkout

# Build the web dashboard
npm run build:gui

# Run tests
npm test

# Lint
npm run lint

After npm link, the sfdt command points to your local checkout.

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/your-feature)
3. Make your changes with tests
4. Run the test suite (npm test) and linter (npm run lint)
5. Commit with a descriptive message
6. Push to your fork and open a Pull Request

Please ensure all tests pass and linting is clean before submitting.

Security

To report a vulnerability, use GitHub's private security advisory feature rather than opening a public issue. See SECURITY.md for the full policy.

License

MIT