deltamanifest

An sf CLI plugin that scans a target org for components changed within the last N hours and writes a package.xml manifest you can hand straight to sf project retrieve start --manifest.

Built for orgs without source tracking (sandboxes, production), where assembling a change list by hand is painful and source tracking is slow or inaccurate.

How it works

1. Calls the Metadata API describe to enumerate every metadata type in the org, including child types (CustomField, ListView, ValidationRule, …).
2. Lists each type (batched, 3 per call, with bounded concurrency). Folder-based types — Report, Dashboard, Document, EmailTemplate — are walked folder-by-folder.
3. Keeps components whose lastModifiedDate falls inside the look-back window. Managed/namespaced components are excluded by default.
4. Groups survivors by type and writes a sorted, de-duplicated package.xml.

Because it reads lastModifiedDate straight from FileProperties, it does not depend on source tracking being enabled.

Install

Public / anyone

sf plugins install deltamanifest

Pin to a specific version (recommended for CI pipelines and internal team usage):

sf plugins install [email protected]

Internal team / CI

When using this plugin inside automated pipelines or across your team, always pin the version. This follows the project's semver discipline and prevents surprises when a new release ships.

Example in a CI script or package.json:

sf plugins install [email protected]

Update the pin only after you have verified the new version (run your NUTs or manual tests against a sandbox).

Local development (contributors)

cd deltamanifest
npm install
sf plugins link .

With tsx in devDependencies, ./bin/dev.js enables live TypeScript execution for linked ESM plugins. Edit files under src/ and re-run the command — no manual rebuild is usually required. You can still run npm run build when you want the compiled lib/ output or before running tests that expect built artifacts.

Verify the installation

sf plugins inspect deltamanifest
sf deltamanifest generate --help

Versioning & Releases

This plugin follows semantic versioning (semver).

• Patch releases: bug fixes, no behavior changes.
• Minor releases: new features, backwards compatible.
• Major releases: breaking changes (very rare for this tool).

For the internal team

• Always pin to an exact version in CI and shared scripts (see Install section above).
• Only move the pin forward after the new version has been exercised (unit tests + NUTs or manual validation on a non-production org).
• The published package on npm is the source of truth for both public users and the team.

Publishing (maintainers)

1. Update code, run npm test, and (ideally) npm run test:nut.
2. npm run prepack (builds + generates oclif.manifest.json).
3. npm version patch|minor|major (updates version + creates a git tag).
4. npm publish.
5. Push the tag: git push --tags.

After publishing, the new version is immediately available via sf plugins install [email protected].

Usage

# Everything changed in the last 24 hours (default) in your default org
sf deltamanifest generate --target-org myOrg

# Look back 2 days (48 hours), custom output path
sf deltamanifest generate -o myOrg --hours 48 --output-file manifest/delta.xml

# Only Apex + Flow changed by a specific developer
sf deltamanifest generate -o myOrg -m ApexClass -m Flow --modified-by "Jane Developer"

# Last 12 hours, skipping noisy types
sf deltamanifest generate -o myOrg -t 12 -x Profile -x PermissionSet

Then retrieve the components:

sf project retrieve start --manifest manifest/package.xml --target-org myOrg

Flags

| Flag | Char | Default | Description | |---|---|---|---| | --target-org | -o | config/env | Org to scan (required). | | --hours | -t | 24 | Look-back window in hours. Use 48 for 2 days, etc. | | --output-file | -f | manifest/package.xml | Where to write the manifest (parent dirs created). | | --metadata | -m | all types | Restrict scan to these type names (repeatable). | | --exclude-metadata | -x | — | Skip these type names (repeatable). | | --modified-by | | — | Keep only components whose last-modified-by name matches (case-insensitive). | | --include-managed | | false | Include managed/namespaced components. | | --concurrency | -c | 5 | Max concurrent listMetadata calls (1–15). Raise for large orgs; lower on rate limits. | | --api-version | | org default | API version for the scan and the <version> element. | | --async | | false | Run the scan in a detached background process; returns a job id immediately. | | --job-dir | | ~/.deltamanifest/jobs | Where background job state is stored. |

Async / background scans

A full-org scan can take a minute or two. Use --async to dispatch it to a detached background process and get a job id back immediately:

sf deltamanifest generate -o myOrg --hours 48 --async
# Job id: 3f2b9c1a-7e5d-4a91-bc34-2d6e8f0a1b2c

The background worker authenticates to the same org, runs the scan, writes the manifest, and records its outcome under ~/.deltamanifest/jobs/<jobId>/status.json. Check on it (optionally blocking) with resume:

# Check once
sf deltamanifest resume --job-id 3f2b9c1a-7e5d-4a91-bc34-2d6e8f0a1b2c

# Block up to 10 minutes for completion
sf deltamanifest resume -i 3f2b9c1a-7e5d-4a91-bc34-2d6e8f0a1b2c --wait 10

resume flags: --job-id (-i, required), --job-dir (defaults to the same root as generate), and --wait <minutes> (poll until the job finishes or the timeout elapses).

JSON contract (--json)

The result shape is a stable public API. Fields may be added in minor versions; renames/removals are major-version breaking changes.

{
  "status": 0,
  "result": {
    "async": false,
    "state": "completed",
    "manifestPath": "manifest/package.xml",
    "apiVersion": "60.0",
    "sinceUtc": "2026-05-29T12:00:00.000Z",
    "hours": 48,
    "typeCount": 7,
    "componentCount": 23,
    "components": [
      {
        "type": "ApexClass",
        "member": "AccountService",
        "lastModifiedDate": "2026-05-30T09:14:22.000Z",
        "lastModifiedBy": "Jane Developer"
      }
    ],
    "skippedTypes": [
      { "type": "SomeUnsupportedType", "reason": "INVALID_TYPE: ..." }
    ]
  },
  "warnings": []
}

For an --async start, state is "running", jobId/jobDir are populated, and the component fields are empty until you resume. A resume on a finished job returns the same shape with state "completed" (or "failed" with an error string).

skippedTypes lists metadata types the org refused to list (unsupported type, permissions, etc.). The scan continues past these rather than failing — they are surfaced as warnings in human output.

Notes & limitations

• A full scan of a large org issues many Metadata API calls and can take a minute or two. Narrow with --metadata / --exclude-metadata for speed.
• lastModifiedDate reflects the metadata component's own last save. Some composite types (e.g. profiles) report coarse timestamps; treat the manifest as a strong starting point and review before retrieving.
• The window is computed from the CLI host clock (now - hours), compared against org timestamps in UTC.

Development

npm install       # after pulling changes that touch package.json (e.g. tsx swap)
npm test          # unit tests (no org required)
npm run test:nut  # end-to-end tests against a scratch org
npm run lint      # type-check only
npm run build     # compile to lib/ (used by the linked production entry and for packaging)