Salesforce Metadata Toolkit

A VS Code extension for Salesforce developers that streamlines day-to-day work without leaving the editor: browse and retrieve org components, generate package.xml files from your selection or branch changes, and pull component lists from Jira. Optional Git workflow tools for branch management and environment promotion.

Features

Browse & Retrieve Org Components

Query your connected Salesforce org for metadata across any metadata type. Pick what you want and retrieve it into your local project — fast.

• Two-pane layout — types on the left, components on the right. Ticking a type loads its components instantly.
• Per-type loading in All Metadata mode — clicking a type checkbox fires a single-type query, with an inline spinner per type.
• Cancel mid-retrieve — the Retrieve button becomes Cancel during the operation; click to abort.
• Supports scratch orgs, sandboxes, and production
• Filter, sort (case-insensitive), and search by type, name, or modified-by
• Smart retrieval routing: jsforce readMetadata() for non-code types (10–100× faster than SF CLI on small selections) and SF CLI for code types (Apex/Aura/LWC), Profile selections, and >200-component bulk pulls. Override with salesforceMetadataToolkit.retrieveMethod = "sfCli" to force SF CLI for everything.
• All CLI/API activity logged to the Salesforce Metadata Toolkit output channel

Recent Changes (source-tracked orgs)

When the org has source tracking enabled, the browser auto-queries the Tooling API SourceMember table on open and shows everything that's changed since you last pulled. The type list is scoped to types with actual changes, so picking a metadata type narrows the view to just what was modified — no manual selection needed. On non-source-tracked orgs, the browser falls back to All Metadata mode automatically.

Generate package.xml from selection

After picking components in the browser, click Generate package.xml to produce a deployment manifest from your current selection. Wildcard members (<members>*</members>) are auto-emitted for types where every loaded component is selected.

Bulk Select from a list

Paste a list of components (any common format — markdown table, tab-separated, vertical Jira copy, plain Type: Name) and the parser figures it out:

• Header-aware (Type, Component Type, Name, API, Component Name)
• Type-anchored fallback for headerless lists
• Auto-reformats clipboard paste into a clean Type: Name view
• Smart matching: handles missing __c/__mdt suffixes, exact + suffix + ambiguous resolution

Retrieve from Jira

Pull the component list directly from a custom field on a Jira issue, parse it, and pre-fill the Bulk Select textarea. Configure the field name once (e.g. Salesforce Components) and the extension resolves the field ID via Jira's REST API.

Generate package.xml from branch changes

Generate a deployment manifest from changes on the current branch — including committed changes, not just uncommitted ones.

• Uses git log --first-parent --no-merges to capture only what was directly committed on this branch (excludes content brought in by main syncs or branch merges)
• Adds staged, unstaged, and untracked files
• Maps file paths to Salesforce metadata types
• Auto-generates and shows the package.xml preview
• Saves directly to manifest/<STORY-KEY>.xml when the current branch matches a configured Jira ticket prefix
• Sorts type and member names with locale-aware case-insensitive collation
• Reads sourceApiVersion from sfdx-project.json

Sign in to Jira

A guided sign-in panel collects your Atlassian email + API token (with a link to create one), tests the credentials, and stores:

• Settings (User scope): jiraBaseUrl, jiraEmail — synced and shareable
• Token: in VS Code's encrypted SecretStorage — never written to settings.json, never synced

Available as Salesforce Metadata Toolkit: Sign in to Jira and Salesforce Metadata Toolkit: Sign out of Jira.

Branch & Promotion (optional)

For Salesforce admins and developers who don't live in Git day-to-day, this section wraps the typical story-branch workflow into one-click sidebar actions — no terminal commands, no merge syntax to memorize. The flows handle branching from main, syncing in upstream changes, committing, pushing, and opening a PR for review.

• Create New Branch / Continue Existing Branch — guided flows for starting or resuming feature work
• Commit Changes — fast staging + commit, optionally checks for changes before saving
• Promote to Environment — push the current branch and open a PR against a configured environment branch (e.g. dev, staging)

These sections appear automatically in the sidebar when their dependencies are satisfied (e.g. Promote shows when promotionTargets is configured).

Merge Release Stories (rare)

Merge every story branch in a Jira release / fixVersion onto your current branch in one step. The extension queries Jira for the release's stories, locates the matching git branches, shows a confirmation table, and merges them sequentially — per-story conflicts are aborted and reported so the rest keeps going. Nothing is pushed; review the result before committing further. Hidden by default; enable via salesforceMetadataToolkit.enableRelease.

Requirements

• Salesforce CLI (sf) installed and on your PATH
• An authenticated Salesforce org (sf org login)
• A Salesforce DX project open in VS Code (for retrieve and package.xml flows)
• Git installed (for Branch / Promotion / Release flows)
• Jira Cloud account + API token (only if you use Jira features)

Quick Start

1. Open your Salesforce DX project in VS Code
2. The Salesforce Metadata Toolkit sidebar appears in the activity bar
3. Click Browse Org Components to start retrieving metadata
4. Optionally run Salesforce Metadata Toolkit: Sign in to Jira to enable Jira-backed features

Commands

Available from the command palette (open with Cmd/Ctrl+Shift+P). Promote runs only from the sidebar buttons since it's parameterized per environment.

Settings

All settings are optional — the extension works out of the box with sensible defaults. Configure these only if you use the matching feature.

For Jira features

For Branch / Promotion / Release

Other

Privacy

All Jira and GitHub network requests are initiated by user actions (sign-in, fetching a story, opening a PR). The extension does not send telemetry. Credentials are stored in VS Code's encrypted SecretStorage; never logged or synced.

Known Limitations

• On source-tracked orgs, Recent Changes shows up to the most recent 5,000 modified components. Beyond that, narrow the type selection or use the search filter.
• The package.xml generator includes files tracked by git on the current branch (committed + working tree). Files brought in by merges from other branches are excluded.
• Jira features require Jira Cloud (the /rest/api/3/search/jql endpoint). Server / Data Center support is not implemented.
• Retrieve and release operations require an open Salesforce DX project folder.

Development

npm install                # one-time
npm run compile            # tsc + esbuild bundle of metadataApi
npx vsce package           # produces salesforce-metadata-toolkit-<version>.vsix

To run the extension locally: open this folder in VS Code and press F5 to launch an Extension Development Host. From inside the host, open a separate Salesforce DX project folder to test against.

The build runs tsc -p ./ followed by node esbuild.metadataApi.mjs. The esbuild step bundles src/metadataApi.ts together with jsforce into a single out/metadataApi.js (~1.3 MB) so jsforce doesn't need to ship as a dependency in the VSIX.

License

MIT.