Compare. Pick. Validate. Deploy.
Orgbench — compare two Salesforce orgs and deploy only the difference,
without leaving VS Code.
Pick a source and a target — a Salesforce org or a local git repository on
either side — choose the metadata you care about, and Orgbench shows what's
added and what changed, component by component, with a side-by-side diff on any
row. Tick what you want moved. Everything runs on your machine: Orgbench reads
your orgs through your Salesforce CLI, or, if you choose, straight from the
Salesforce APIs with the session your Salesforce CLI already holds (the token
stays in memory and is never stored), and retrieves, deployments and logins run
through the CLI itself: no cloud service, no vendor
account, no managed package in your org, and your metadata never leaves your
laptop unless you turn on Describe differences with Claude Code, which hands two
versions of one component to your own Claude Code.

A native core, not a web app. Orgbench is a single native binary (written
in Rust) driving your local Salesforce CLI — no bundled Node runtime, nothing
installed in your org. It runs outside the editor's process, so a large
comparison — hundreds of components across dozens of metadata types — neither
bloats VS Code's memory nor takes it down. It is the same core that powers the
Orgbench plugin for IntelliJ IDEA, so the comparison and deployment rules are
identical in both.
What you can do with it
Find and pick exactly what to deploy. Filter by label or API name across
objects, fields, Apex, LWC/Aura, Visualforce, layouts, flows — up to 191
items in 15 groups; selections across types accumulate into one
session you can export to a file and import back later. One of those groups,
Revenue Cloud, carries fourteen pricing metadata types and record rows plus 33
configuration records, and is switched off out of the box. Data Cloud and
Tableau Next objects are not offered in any group: Data Cloud moves its own
configuration between orgs with Data Kits and Data Cloud packages, which
Orgbench does not replace.
Compare product bundles and constraint models as whole documents. Two items
of the Revenue Cloud group are records rather than files: a Product Bundle
is one Product2 of type Bundle, and the plugin synthesizes its document out
of the bundle's catalog — classifications and their parent chain, component
groups, related components, the child products they name, selling model options
and price book entries — with every reference written as a natural identity
rather than a record id. A Constraint Model is one constraint ExpressionSet:
its document carries the definition and version shells, the CML text of every
version, and its tags with their addressees resolved. Which fields travel is the
intersection of both orgs' describes, and the document says so in its own
schema section. A bundle's Add row whose record the target already holds under another
name — by the external key, or by that name — names that record instead of Missing in target:
already a bundle there, the row stays Add, and names the rename only when the names differ
and the target can update Name; anything else,
the row is unselectable instead, because Product2.Type is createable but not updateable and no
deploy can ever turn it into a bundle. An Update/No change row (the target already has a
bundle of that name) is unselectable the same way when the key points at a DIFFERENT record
there — deploying would update that other record, not the bundle, leaving the bundle untouched.
Both are compared only between two orgs and both are transferred, in
Best-effort only against a non-production org, as step 2 of a phased Deploy against a recognized production org (after the metadata deployment succeeded), and never to a target whose class the plugin could not determine: a bundle row as records through the REST composite
API; a model row as its definition shell in the same Metadata API package, where
the version the target already runs as active is left out of the package untouched
and every other version travels Inactive, so the package never changes which version is
active — followed by
its tags, CML and activation as REST calls, where nothing in the target is ever deleted and the
row is Succeeded only when the target carries the content the source carries that it could place —
a tag whose addressee the target does not have is left out, counted and named in the row's message
rather than failing it, a product addressee being looked up by the same external key as the
bundle's own record first, and the comparison already names such tags in the model row's summary
(Tags: …) and names separately those whose records a bundle row of the same comparison creates
(bundle row <name> creates — check it to deploy them together,
or bundle rows <name>, <name> create — check those rows to deploy them together when several do) and
those that would fail the row (if the target could not be asked, the tail says so instead — Tags: addressees in the target were not checked: <reason>; compare again to check them — keeping the tags whose failure is known without the target; a model document that could not be read shows Tags not checked: the document could not be read.) — an activation that
did not happen being stated in the row's message instead; a version is activated only when its
CML landed (otherwise did not receive its constraint model), and the version deactivated for it is
activated again when the new one cannot be (was activated again); a call of the activation that
answers with an error is followed by one more read of the model's versions in the target, which
decides what happens next and what the row says (read again). Against a non-production org
checking either row removes the Validate and Deploy buttons and puts Records cannot roll back: Best Effort only. under the row; against a production org a checked row keeps Validate
and Deploy and the records follow the package in phases (see Deploying to a production org
in the full README). Checking a bundle also
brings into the comparison every constraint model whose tags address that bundle — its groups,
components and child products included — as a row marked required by <bundle>, and checks it
as added as dependency — every model the plugin can actually deploy that has an active version in
the source; a model without one stays unchecked, and its row says so (required by <bundle>; not auto-checked: no active version in the source) when the bundle is what brought the model into
the comparison — a model you picked yourself on the selection screen stays unchecked without a note
— as does a No change or blocked model, each showing its own reason — and
the walk stops there: one checkbox reaches the bundle and its active models, never another bundle
through a model — a bundle that CONTAINS bundles still checks them (below) — and every check is
removable on its own row. Checking a constraint model checks that row alone: a model transferred
this way leaves out the tags that address records of some other bundle absent from the target and
names them in its message. The warning Product bundle … is tagged by constraint model …, which is not in this comparison. is left only for a model the plugin could not list, and when the
dependency warnings run past fifty the last line says how many were not shown. A child product that
already exists in the target as an ordinary Product2 under the same name — not itself a bundle —
still receives the document's fields as an update, even though the comparison table never showed
that target record.
Check the target before you compare. Check target, next to Prepare Orgs, reads all
33 Revenue Cloud registry objects of the target org — no source needed, nothing written or
deleted — and opens the Target health check screen with every reference field that points at
a record the target does not have: the record count, up to 20 record ids as links, the query that
lists them all, and what the plugin can do about it. Re-check reads again, Back returns to
the selection as you left it. An expired sign-in of the target stops the check at the object where
such a refusal arrives (usually the first), and the selection view names the target's alias and the + button to sign in again, with the CLI's diagnostic after Details:.
Choose the right record among duplicates. When a bundle record matches several records of
the target, the Target health check screen asks which one the deploy updates: a second table
shows when each was created and last changed, how many records of the transfer point at it and
how many fields already match the source. The deploy updates the record you checked under
Use, and the bundle's records under it follow it — a record of this deploy that points at
another record of the duplicate through a link the target lets change is repointed to the chosen
one; the others stay in the target untouched, and nothing is deleted. A record you cannot choose — a product of another Type, or any record
but the one another record of this deploy points at through a reference Salesforce does not let
change — has its Use disabled, and its Note says why. A choice the target no longer matches
— made for an earlier deploy, or found gone by a Re-check or Fix on the same screen — is
never replaced by another record, and the deploy refuses it. A record that is no longer a duplicate
is shown before anything is sent, as Choice no longer matches; a record that is still a
duplicate has the choice dropped and named in its Problem. Fix drops from the choice a
record it deleted itself, so the deploy creates it anew. With a duplicate left without a choice, no
record under any of its records changes, at any depth: a record of the bundle under it that would
be updated is refused with the reason and the action, and one to be created is refused with the
same reason deeper down, where its own parent exists (directly under the duplicate it reads
<duplicate> was not created); both are counted among the records that depend on the findings. A
record of the target that cannot be saved and hangs under such a duplicate gets no Fix. After you change a choice, Fix first checks the
target again with it and deletes nothing.
Move Revenue Cloud pricing configuration with what it depends on. Pick a
Pricing Recipe, a pricing procedure or a Context Definition and the offline
cascades auto-check what it needs — the decision tables a procedure looks up,
the context it reads, the custom fields and objects a context hydrates from,
the global picklists those fields use — each as a checkbox you can remove. A
Context Definition document deployed into an org is trimmed to the target's
schema before the deploy and, in Best-effort, sent again without what the
target rejected; the whole selection still ships as one package. In every
deploy mode against an org the plugin has confirmed (non-production, or
production with Deploy), a procedure version that is active in the source
while the target runs another version as active is sent Inactive and, once its row succeeds, activated by
the plugin itself (Validate only rewrites but activates nothing — its Quick Deploy does): the target's active version is deactivated first and, when
the new one cannot be activated, activated again (was activated again). A
call of the activation that answers with an error is followed by one more
read of the target's versions, which decides what happens next and what the
row says (read again); the row sends you to Setup only when the target, read
again, has no active version or could not be read. A decision table the target runs as
active travels Inactive the same way and is activated again before the
version, which is activated only when the tables it reads are active; a
deployed Context Definition is checked against the target's context service,
and a tag the service does not show is named on its row. What the plugin
leaves to you — release-gated tags, the platform's cap on pricing elements
per pricing procedure, activating the new procedure version in Setup in any
other case — is listed in the change log. A procedure version the target
already has is never changed: when it differs from the source's, its row cannot
be checked and names the action — clone the version in the source and deploy
the clone.
A decision table update that removes an input column is refused by Salesforce
((499072613)) while an active procedure version of the target reads the table.
The review row names the column and the versions; Deploy first shows the modal
warning Switch off procedure versions? (a production org too), then switches
those versions off for that table's own deployment and switches them on again —
after a refused table, a missing answer or a cancel too. Validate switches
nothing. Keep VS Code open while versions are switched off — reloading the
window during those seconds can leave a version switched off; check it in App
Launcher → the procedure's list → Expression Set Versions.

Move the field and its permissions in one go. Field-level security, object
CRUD, Apex class and Visualforce page access, tab visibility and record type
visibility travel with the components you checked — additively (never revokes)
or as a full sync — into exactly the Permission Sets and Profiles you select.
Managed-package and standard components get rows too, as permission subjects —
their permissions travel while their metadata never deploys. The part change
sets and the CLI leave to you.

Choose how much risk you want. Validate only dry-runs the whole package
against the target. All or nothing sends it as one deployment that rolls back
completely on any failure — or, when Salesforce needs a decision table, a
pricing recipe or procedure versions deployed separately, as several
deployments, each rolled back on its own failure while the earlier ones stay
(the review screen says so). Best-effort sends the same package but keeps every
component Salesforce accepted and reports the ones it rejected — so a big
package lands in one pass, and your next run only deals with what failed.
Quick Deploy promotes an already-validated package without uploading or
re-running tests. Re-Deploy sends again the result rows you check that
the target did not accept, in the same mode; every checked container
receives the permissions of every component sent. After Quick Deploy it
validates again and carries the validation's permission mode and
containers, since a quick deploy reports no permission rows. If the
plugin core refuses the checked rows — for example a field of a new object
whose object row is not checked — nothing is sent: the results screen stays
with your checks and shows the reason under its buttons. A deploy-mode or
license gate still ends on the error screen, as the first deployment would.

Fix it in the diff, ship the fix. The source side of the diff view is
editable for any component whose row is a single document — Apex, Visualforce
pages, objects, fields, flows, layouts and more — and the deployment sends your
edited version. The source org is never modified, the edit is marked on the row
and can be reverted, and it lives only inside that comparison session. Bundles
and multi-component container files stay read-only.
Deploy one field on a page layout, a Lightning page or a report type.
Tick Elements next to that document on the selection screen and move a single
field, related list, Lightning page section or component, or report type
column into the higher org without touching anything else in that document.
A new attribute, tag or mapping of a context definition travels the same way;
what Salesforce's own sync of a lagging definition changes besides is shown on
the row before the deploy.
Use git as either end. Org → org, org → git, git → org, git → git. A git
target ends in one local commit containing only what you selected — Orgbench
never pushes and never switches your branches.
Let dependencies pick themselves. Checking a field pulls in its missing
object; checking a list view pulls in the fields it references — visibly, as
rows you can uncheck. A row you selected that a table filter hides is not forgotten:
beside the deploy buttons the screen says <N> selected row(s) hidden by the table filters.
with a Show them link that clears the filters.
Know before you deploy. A custom field is compared as a whole document (the history
tracking toggles, which never travel, and XML formatting are not differences). A Context
Definition element is shown under a readable label in the Component column, and a
definition that Salesforce will sync on deploy carries a forecast even when it is compared as
one document. Validate only says what a deployment would do (Deploying this would make Dynamic Forms replace the Record Detail component …, Salesforce is expected to sync the target's definition …) and Quick Deploy carries the notes of its validation into its results. The
results screen counts Not activated: N for pricing procedure and constraint model versions
that landed but were not activated (failed, skipped or cancelled) and for decision tables that
landed but could not be activated again.
What it never does
- Never deletes metadata in a target org — a component that exists only in
the target produces no row and is untouched. The one exception is a Revenue
Cloud record: the Target health check screen deletes a leaf record only
when the user marked its finding with Fix — at once in a sandbox; against
a production org the button is Fix during Deploy and the deletion happens
inside Deploy, or inside Quick Deploy after a Validate that carried
product bundles, after the metadata deployment succeeded and before the
records are transferred. Validate itself deletes nothing, and the deletion
cannot be undone; the deploy that follows creates the record again. Quick
Deploy checks the target again before deleting and deletes only findings that
are still there.
- Never deploys the definition of a managed-package or standard
component — such rows exist to carry permissions and deploy nothing; the
one exception is a Lightning page assignment you select in the element mode,
spliced into a fresh copy of the target's own standard application or object
document. A
field's history-tracking toggles never travel either, nor do a custom
object's history and feed tracking settings: a deployed custom field or
custom object keeps the target's own, or is created with them off, and the
row's result names a source toggle that did not travel.
- Never switches off an active procedure version without asking —
only after you confirmed Switch off procedure versions? (never in
Validate, never a version from a managed package, never a version
Salesforce would not switch on again — its start date must be later than its
context's), only for the short
deployment of the one decision table that needs it, and the running extension
switches the version on again; if that fails, the row says so first and names
the action (reloading the VS Code window during those seconds can leave a
version switched off — check it in App Launcher → the procedure's list →
Expression Set Versions).
- Never creates an object you didn't tick: auto-selected dependencies are
visible rows you can uncheck before deploying.
- Never stores your tokens — authentication stays in the Salesforce CLI:
the extension never implements OAuth, never asks for credentials and never
persists a token. By default (
orgbench.orgChannel = cli) every read of an
org runs sf; with api, for its direct calls to the Salesforce APIs — every read of
an org, and the REST record writes of a bundle or model transfer — it uses, in
memory only and for the lifetime of the core process, the access token the
CLI itself reveals for an alias; the token never reaches a log, a diagnostic,
a copy, the session export or the disk, and a refresh is always the CLI's
own. Diagnostics are sanitized before you see them.
- Never opens an org on its own — the icon left of + in an org row and
the Deployment Status link of a deployment into an org run only the
Salesforce CLI's own
sf org open, for an alias the core itself listed or the
target of the running deployment, with a path the core chooses from a fixed
set; its output is never read, logged or returned — on success it carries a
login URL with a session token — and a failure shows only the sanitized
diagnostic.
- Partial deployment never happens unannounced: Best-effort
keeps what succeeds because you chose that trade-off — and it is never offered
against a recognized production org, where Deploy runs in phases: the metadata as one
atomic deployment first, the records only after it succeeded — while All or nothing rolls back a deployment
on any failure of it — and when a selection needs several deployments, the
review screen says so before you deploy. A package carrying Apex or Flows always passes through the
test-selection screen before it goes to any org.
Requirements
- macOS arm64, macOS x64, Windows x64 or Linux x64 (the bundled core is
fail-closed on other platforms). The Windows x64 build is for Windows on
x64; it has not been verified on Windows on ARM, and VS Code itself may
reject installing an x64-targeted VSIX (
targetPlatform: win32-x64) there.
The Linux x64 build is statically linked against musl, so it needs no
particular system libc version; Linux on ARM has no build and the launcher
refuses it rather than running the x64 binary.
- VS Code 1.85 or newer.
- Salesforce CLI (
sf) installed and on PATH. On Windows the core also looks
for sf.exe, sf.cmd, sf.bat and sf in %LOCALAPPDATA%\sf\client\bin.
- Claude Code (
claude), only for Describe differences with Claude Code,
which is off by default: installed and signed in once by running claude in a
terminal; nothing else in the extension needs it.
- git 2.25 or later — only for deploying into a local git repository (Orgbench
passes the file paths to git on standard input); comparing against a git
repository does not need it.
- Two authenticated aliases that resolve to different Salesforce org IDs. The
terminal is not the only way to create them: the + button next to the
Source or Target dropdown runs the CLI's own
sf org login web for
you (see the workflow below).
Install from disk
- Obtain the VSIX for your platform:
orgbench-darwin-arm64.vsix (Apple
silicon), orgbench-darwin-x64.vsix (Intel), orgbench-win32-x64.vsix
(Windows x64) or orgbench-linux-x64.vsix (Linux x64), or build it
(below).
- In VS Code, open the Extensions view, choose Install from VSIX… from the
… menu, and select the file.
- Open the Orgbench view from the Activity Bar.
Workflow
- Choose the Source and the Target. Two orgs must resolve to different
org IDs; either side can be a local git repository instead — see below.
The + button next to either dropdown creates a new alias without leaving
the editor: enter the alias name, choose Production, Sandbox or a My Domain
URL, and sign in in the browser the Salesforce CLI opens. The new alias is
selected on the side you asked from. The extension never sees your
credentials, never sets a default org and never overwrites an existing alias
— a name already in use is refused before the browser opens. While the login
runs, the selection screen stays where it is with its controls disabled and
offers Cancel; cancelling leaves your selection untouched. The icon left
of + opens the selected alias in your browser, on its Lightning home
page, through the Salesforce CLI's own
sf org open and your CLI session; it
is unavailable until an alias is selected and while the screen is busy, a
git row has none, and a refusal of the CLI (for example an expired
authorization) is shown as an error notification with its cause. In a container (Dev Containers, Codespaces: SF_CONTAINER_MODE or SFDX_CONTAINER_MODE set) the CLI does not open a browser, so the extension refuses with that reason and the action — open the org from a terminal on your computer; on a headless host (for example over Remote-SSH) the browser of the machine where the core runs opens — or none does, and the plugin cannot see which.
- Pick a Metadata Type and tick the components you want. Selections
accumulate across types into one session manifest: switching the type does
not discard what you ticked before. The dropdown opens on its first item,
Selected components: every component selected so far, of every type, in
one table with a Metadata Type column. Untick a row there to remove it
from the selection, or the header checkbox to remove every visible row; with
nothing selected the view says Pick a Metadata Type to list its
components. Import Session… returns to this view with every imported
component. A page layout, Lightning page, report type or context
definition also carries an Elements checkbox, in both views: ticked,
the document is compared element by element, unticked, as a whole
document. Ticking a component sets it to the
orgbench.elementMode
setting; to change it after Compare, press Back — the checkboxes
are kept. Export Session… writes the session's
current selections to a scenario file, Import Session… reads one back —
see Session export and import below. Reload Orgs re-reads the alias
list and then the component list of the type on screen. The source and
target orgs you picked last are selected again the next time the selection
screen opens — only their aliases are remembered, on this machine, in the
same private data directory as the license key; a repository endpoint is
not remembered, and an alias the CLI no longer lists is left unselected.
- Choose Compare.
- Review the differences and tick the rows to deploy. Double-click a row to
open both versions of that component side by side — by default the target
org on the left and the source org on the right;
orgbench.diffPaneOrder
set to sourceLeft swaps them. A Context Definition or Decision Table row shows the target
in the source's order; when that moved any block, the tab title names the
target <alias> (in the source's order). Salesforce reorders the repeated
blocks of a context itself when it saves a version, so a context that
differs only in that order is No change. An Apex class, an Apex trigger
and a Visualforce page are two documents each — the body and its
*-meta.xml sidecar — so such a row opens the sidecar in its own read-only
window when the row has attribute differences (an API version, a status or a
label change), and the body window whenever the sidecar window does not open
or the body differs too. A row whose only difference is a sidecar attribute
therefore opens the sidecar alone: there is no body window for it, because
the two bodies are identical. The source pane of the diff is editable while
orgbench.allowSourceEditing is on and the core marked that row editable —
a metadata XML document, or the body of an Apex class, an Apex trigger or a
Visualforce page; a sidecar, a bundle, a rule or label sharing one file, a
single layout, Lightning page or report type element and any row with
nothing to deploy stay
read-only. So
the deployment can send your own increment instead of the whole
current document of the source org: type in it, and about a second and a half
after you stop the draft is sent to the core and the row picks up its
Edited mark. The draft is saved as you type, so the tab never shows
unsaved changes and never asks whether to keep them; closing the tab sends
whatever is left, and pressing a deploy button sends everything still unsent
before the deployment starts. Orgbench: Revert
Edit in the command palette drops the edit and puts the original text back;
it acts on the pane your caret was last in, so click into the source pane
first. Retyping the original text usually drops the edit too, but only the
command is guaranteed to: a body whose line endings are mixed, or one that
starts with a byte-order mark, is not loaded byte for byte. The draft is held
in memory and never written to disk, and it goes away with the comparison.
Revert only works from the comparison screen itself; run it from the test
selection or permission screen and it answers "Revert is available on the
comparison screen." instead of reverting anything.
Pick a permission transfer mode in Settings — search for Orgbench › Fls
Mode (the setting is orgbench.flsMode; its three values read Do not
transfer permissions, Additive permissions and All permissions) — then
start the deployment: against an org the row of final buttons is Validate
(--dry-run, nothing is written), Deploy (all or nothing — one atomic
deployment — several in the cases below — and any failure of a deployment
rolls that deployment back; against a production org the
product bundles and the constraint models' tags, CML and activation follow the package and
cannot be rolled back) and Best Effort (the same
single package sent with --ignore-errors, so Salesforce keeps every
component it accepted and only the ones it named are Failed); Best
Effort is not offered at all against a target the core has recognized as
production. Every mode sends the whole selection as one Metadata API
deployment — there are no waves or batches, and no ordering between
metadata types. The exceptions: a decision table the deployment rewrites to
inactive deploys on its own when the selection has other rows, switched on
again right after it; a pricing recipe deploys on its own before the
procedure versions, when procedure versions are selected (in Validate only, a
recipe that names as its default procedure a definition the selection
creates together with a version of it is validated together with that
definition and its versions); and a
pricing procedure version that reads a decision
table the deployment rewrites to inactive goes in a second package, after
that table is active again, together with the other selected versions of
its procedure, its definition row and the rows that depend on them (Review
names each version of the second package and each table that deploys on
its own, and says that the earlier deployments stay in the target if
Salesforce refuses a later one; if a later one gets no answer its rows are
Failed on the results screen and the earlier ones stay); a validation of
such a selection offers no Quick Deploy, and the results screen says
why. Against a production org a Deployment plan block above the
buttons lists the steps Deploy will take for the rows checked right now.
Validate checks the metadata only; when the selection carries a product
bundle it first shows the Target health check, where Fix during Deploy
deletes nothing and neither does Validate — Quick Deploy deletes the marked
findings after the validated package succeeds and before the records. Quick
Deploy checks the target again before deleting and deletes only findings that
are still there. A selection without a bundle goes through Validate without
the check.
Against a git repository there is a single Deploy.
- If the package contains Apex classes, Apex triggers or flows and the target
is an org, an Apex test screen comes first; an empty selection means no
--test-level is passed, and a production org still runs its own local
tests and enforces 75% coverage.
- With a transfer mode other than Do not transfer permissions, the
containers that will receive the permissions are listed for confirmation
before the deployment runs — provided at least one checked row carries a
permission subject (a field, an object, an Apex class, a Visualforce page,
a tab or a record type); otherwise that screen is skipped, the previous
screen shows the deploy mode buttons directly, and the deployment
produces no permission result rows. The list distinguishes Existing containers,
matched by kind and API name in both orgs, from New Permission Sets
that exist only in the source and are eligible for creation, and can be
filtered by the Presence column. Each row carries two names: the Setup
Label and the metadata full name in the Container column. They
differ for many standard profiles —
Standard User is Standard,
System Administrator is Admin — and only the full name is used to
match, retrieve, package and merge. The label shown is the target org's
for a matched container and the source org's for a newly creatable
Permission Set, so it always names the org where you would go check the
result in Setup. The permission result table shows the
same pair. Which permissions travel is decided by
the rows you checked: a custom field row carries its field-level security,
a custom object or platform event row carries the seven object
permissions — create, read, edit, delete, View All Records, View All
Fields and Modify All Records — an Apex class row and a Visualforce page
row carry access to that component, a custom tab row carries that tab's
visibility, and a record type row carries whether that record type is
visible. A managed-package or standard component gets a row too, so its
permissions can be selected even though its own metadata never deploys: the
Details column reads Permissions only for a managed Apex class,
Visualforce page, tab or record type, a managed or standard field, a
managed or standard object, or a standard tab — nothing of it deploys, so
double-clicking it opens no window. Two boundaries: the default record
type of the target is never
changed by a transfer, and tabs of both kinds are transferred — a custom
tab travels as its own metadata component, while a standard tab such as
standard-Account travels as a Permissions only row whose name is the
permission entry itself. Both kinds of row are visible
only when the UI & Navigation and Objects & Fields metadata
categories are enabled. A selected source-only Permission Set may be
created in the target, populated with only the selected rows' permissions
plus the source document's own description and license — and never a user
permission, an application visibility or a Profile. A New Permission Set
whose license the target org does not have is listed with its checkbox
disabled and the reason on the row, because such a container would be
rejected whole.
- Read the result tables. Copy details copies only the sanitized
diagnostics — never a token. Quick Deploy appears after a successful
Validate run that actually ran Apex tests, and deploys the very package
Salesforce already validated without re-running them; a validation that ran
no tests says so instead, because Salesforce refuses to quick-deploy it.
Check the rows the target did not accept in either table and press
Re-Deploy to deploy those again, in the same mode, without
the test and container screens; a row the deployment already changed in
the target cannot be checked, and its tooltip says why. A refusal of the
checked rows by the plugin core — for example a field of a new object
without its object row — deploys nothing and appears under the buttons of
the same screen until you change a check; a deploy-mode or license gate
still ends on the error screen. New comparison starts over, keeping the marks of the later views as if the session had been exported on the results view and imported on the first one: the checked rows, permission containers, Apex tests and the deploy mode hint (after a Re-Deploy, those of that re-deploy — the rows that went out in it). The permission transfer mode is a setting and is not carried; document edits and the Target health check choice are not carried either. Clear All Selections drops the carried marks, and so do choosing a different source or target org and an org of the pair missing from the org list on load (marks from an imported file are not dropped by those two).
Comparison or deployment can be cancelled from the progress view, and so can a
browser login.
When one deployment — in any deploy mode, or a Re-Deploy — sends more than
one Metadata API package (decision tables one by one, the pricing recipe step,
the package of pricing procedure versions, a Best Effort retry), the package
line counts them: Deploying the package — 2 of 3 · 1m 8s. The count is that
deployment's plan, known before the first package leaves; a Best Effort retry
is added to the number of packages at the moment it starts (a retry before the
table step turns 1 of 2 into 2 of 3), a step that is held back or not sent
takes no number, and a deployment of one package keeps the line without a
counter. While a deployment into an org runs, a Deployment Status link right
of that line opens the target org on Setup → Deployment Status
(lightning/setup/DeployStatus/home) in your browser through sf org open,
where Salesforce shows the progress of the deployment job itself; a git target
has no such link, and a refusal of the CLI is shown as an error notification
while the deployment goes on.
Session export and import
Export Session… writes what the current session has selected so far to a
JSON scenario file (default name session.json). The button is on five views —
object selection, differences, Apex tests, permission containers and results —
and each writes what is known by then. The whole file is still serialized and
written by the extension's core, but the core does not already hold what goes
into it: the webview sends the live marks of the screen the button was
pressed on, and the host only picks the path.
The file holds no snapshot of the comparison — no difference rows, no statuses,
no attribute values — because such a snapshot goes stale the moment either end
changes. It holds no secrets either: metadata names, org aliases, branch names
and modes only, and a git end is written as the repository directory's last
segment plus the branch, never as an absolute path.
An absent field and an empty one mean different things: no apexTests key means
the test view was never reached, "apexTests": [] means it was reached and no
test was checked. deployMode travels with deployModeIsFinal, which is true
only on the results view. The file carries its own version, independent of the
protocol version.
Import Session… is a button on the object selection view that reads a
scenario file back in — a file of any version from 1 to 5, either one written by
Export Session or handed to you by someone else. It restores both endpoints
and the session manifest, the checked comparison rows and the permission
transfer mode, the checked Apex test classes, and the checked permission
containers, each applied once the matching view is built. Every mark is
applied exactly once per set, so a checkbox you clear afterward does not come
back just because the view is rebuilt for another reason. The marks are
dropped by Clear All Selections, by Restart on the error screen, or by
importing another file (a New comparison from the results screen replaces
them with the marks it carries); choosing the source or target org by hand afterwards, or an org missing from the org list,
does not drop them. Import does not
navigate anywhere: you still walk the wizard yourself, and each view shows its
marks already checked when you reach it. A name the file carries but the
extension no longer accepts — renamed, deleted, or changed type since the
file was written — does not fail the import; it is listed instead, on the
view where it turned out to be unaccepted. A git endpoint is never restored,
because the file, like every other output of the extension, carries only the
repository directory's last path segment and the branch name, never the
absolute path — you choose a git endpoint by hand after importing. The deploy
mode recorded in the file is only shown as a text hint next to the deploy
summary; it is never pressed on your behalf.
Git source and target
Each side is chosen independently, so org-to-org, org-to-git, git-to-org and
git-to-git all work. A repository side is an absolute path plus a branch:
Browse… picks the folder, and the extension reads the SFDX layout declared
by its sfdx-project.json. A deployment into a repository ends in exactly one
local commit and never pushes; the extension never checks out a branch in your
repository — another branch is written through a temporary worktree that is
removed afterwards. The + button next to the branch dropdown names a new
branch, which is created by that commit alone; after it the same session treats the
branch as an existing one, and a second deploy of the session (Re-Deploy, or Back and
Deploy again) puts the next commit on it. A component that already lies in one
of the repository's package directories is rewritten where it lies — the first
packageDirectories entry, in file order, that holds it, never through a symlink — and
a component the repository lacks goes to the default package directory. When a whole type is
read from a repository, a branch file with an unsafe path, one git cannot hand over, or one whose name
is the same as another's on this file system (another file of the branch has the same name on this file system (the two names differ only in letter case or in Unicode normalization)) is left out with a warning
(The branch file <path> was left out of the comparison: …, prefixed Source branch: or
Target branch: ) instead of failing the comparison. A skipped path keeps its place: the same path in a later package directory is not compared in its stead. A deployment into a repository checks every destination before it writes anything and is refused, with nothing written, when a symlink or a regular file lies where a folder belongs (The folder <path> of the target branch is a symbolic link or a file, not a real folder, so nothing is written through it. Replace it with a real folder in the branch, or deploy into another branch, then deploy again.) or when the branch ignores a destination (The target branch ignores <paths> (a .gitignore rule or an exclude file of the repository), so the commit could not include them. Remove that rule, or deploy into another branch, then deploy again.). The heading of the error view is then the text of the refusal itself; when the refusal is git's or the file system's own answer, the heading is The git repository operation did not complete. What git or the file system answered is under Details; fix what it names, then try again. and the answer is under Details. A Lightning page assignment in a managed package's application is an unselectable row (… belongs to a managed package, and the plugin never deploys a managed package's application. Assign this page in the target's Lightning App Builder.), and the whole-document row of a custom application sent to an org is sent without the assignments of profiles the target does not have, named in the row's result (Left out: page assignment(s) for profile(s) <names> — …).
Filtering
Every webview table (components, differences, Apex tests, permission
containers, and both result tables) shares one per-column filter row directly
under its header:
- Text columns get a free-text box that matches a substring anywhere in the
value, case-insensitively; a leading and/or trailing
* is optional and
ignored.
- Enum columns — Change, Kind, Presence, Operation, Status — get a
multi-select popup listing every value with checkboxes. Two carry a smart
default: the differences Change popup hides
No change rows (unless the
comparison has no Add and no Update row at all — then every value is
checked), and the permission-results Status popup hides Skipped.
- The selection column gets a tri-state toggle.
Column filters combine with AND. Filtering only hides rows: a row that is
checked and then hidden by a filter keeps its selection, and the selection
column's header checkbox selects or clears only the currently visible,
filtered rows (hidden selections are left untouched). Filters reset to their
defaults when you leave the screen (a new comparison, or stepping between the
review and permission-container screens).
Selections (chosen components, deployable rows, and permission containers), together
with each table's column filters and sort, are preserved when the view is
hidden and shown again, so switching away from the panel never re-checks a
container you deselected before deploying or drops the filters you set. Filters
and sort persist while you stay on a screen and reset only when you leave it.
Sorting
Click any column header except the selection column to sort the table by that
column. Each click cycles the sort: ascending (▲), then descending (▼), then
off (original order). One column sorts at a time. Enum columns sort by their
displayed label; boolean columns (Read/Edit) sort unchecked-before-checked.
Sorting only reorders rows — it never changes which rows a filter has hidden —
and, like the column filters, persists while you stay on a screen, resetting to
the original order when you leave it.
Settings
orgbench.elementMode — Element-level merge: how Page Layouts, Lightning
Pages, Report Types and Context Definitions are compared. whole (Compare and deploy whole
documents) is the default: one row per document, compared over the whole
document, and a deployment replaces the target document with the source
version, so an element that exists only in the target is gone afterwards.
elements (Select elements to merge) compares these documents element by
element — one row is a field or a related list of a layout, a Dynamic Forms
field or a component of a Lightning page, or a column of a report type — and
merges only the selected elements into the target document. A context
definition gets rows for its nodes, attributes, tags and mappings, and only a
new element can be selected: a change to an existing element is shown but
cannot be selected, and against an org target neither can a standard element
the target lacks — each such row names the reason and the action. Against an
org target a context definition row shows, in both modes, what Salesforce's
own sync is expected to add, change and remove when the target's definition
is behind the source's release (the source's definition is assumed to be in
sync with its own release's standard; a target behind its own org's standard
but not behind the source gets no forecast) — hover the row's Details
cell for the full lists. On a Lightning
page a new component brings everything inside it, and Dynamic Forms sections
replace the target page's Record Detail component, which their rows name
before you deploy. This setting is the starting value of the Elements
checkbox on the selection screen: a component you tick starts with it, and
so does each document of an imported session file that carries no Elements
values. Each document then keeps its own checkbox; changing the setting
changes no component already ticked. A document that the comparison adds on
its own is always compared whole. Rows already on screen keep the form they
were built with. The earlier orgbench.layoutMode
is deprecated and still read while orgbench.elementMode is not set at any
level.
orgbench.retryUnexpectedErrorsAlone — Retry rows alone after a Salesforce
unexpected error (Best Effort), off by default. When on, Best Effort against
an org sends a row the target still fails with only its generic "An unexpected
error occurred" text after a whole-set retry of several rows once more on its
own — one extra deployment call per such row. When off, no such call is made
and the row's message names this setting. After either retry the row keeps
the plugin's own notes about the document it sent (a trim, a rewritten
releaseVersion or version status, a procedure definition's shell and tag
notes) between the target's latest text and the retry sentence. Applies to
the next Compare.
orgbench.permissionSetRepairMode — how a standalone Permission Set row is
treated in Best Effort against an org. OFF sends the document
as is with no retry; TRIM_AND_RETRY (the default) trims it by what the target reports and
retries up to three times; TARGET_CONFIRMED sends it as is first and
retries only what the target named, up to four times. In TRIM_AND_RETRY the
target's fields are read through the Tooling API, so a field the CLI user has
no field-level security on still counts as known to the target.
Applies to the next Compare.
orgbench.allowSourceEditing — allow editing metadata in the diff view. On
by default: the source pane is then editable for a row whose document belongs
entirely to it — a metadata XML document, or the body of an Apex class, an
Apex trigger or a Visualforce page — and the deployment sends the edited
document. The *-meta.xml sidecar of those three, a Lightning or Aura
bundle, a rule or label that shares a file with its siblings, a single layout,
Lightning page or report type element and the target pane stay read-only
either way. The key keeps its
historical name so a cleared box survives the upgrade. Clearing it does not
erase edits that already exist — it gates the FIRST edit of a row, not access
to one that already exists, so a row already carrying an edit reopens
editable. The value is read when a window is opened, so a window already on
screen keeps the form it was opened with.
orgbench.diffPaneOrder — Diff pane order: which org is shown on each
side of a row's diff window. targetLeft (the default, Target left, source
right) puts the target on the left and the source on the right, the way a
diff shows the working change on the right; sourceLeft (Source left,
target right) is the order earlier versions used. The tab title names the
two orgs in the order of the panes, and the *-meta.xml sidecar window
follows the same order. Only the source pane is ever editable, in either
order. To copy a changed block from the target into the draft, hover the
block on the strip between the panes and use the diff editor's own
Revert Block arrow (or the Diff Editor: Revert command with the
cursor in the block). VS Code copies blocks only from the left pane into the
right one, so this is offered only with targetLeft; with sourceLeft the
target is on the right and the arrow is absent. The value is read when a
window is opened.
orgbench.describeWithClaudeCode — Describe differences with Claude Code,
off by default. When on, the row menu item of the same name — a right-click on
a Flow, Apex class or Apex trigger row with status Update — hands the
target's and the source's version of that one component to Claude Code on this
computer, which sends them to the model provider it is set up for (Anthropic by
default). Nothing is sent until you choose the item. While Claude Code answers, the review screen is busy and Cancel stops
it; the answer opens as a read-only markdown preview. Switching the setting
takes effect at once. Requires Claude Code (claude) installed and signed in.
orgbench.flsMode — permission transfer mode used by every deployment:
NONE (do not transfer permissions), ADDITIVE (the default) or ALL. The key keeps its
historical name so existing configurations keep working.
orgbench.metadataCategories — which categories of metadata types the
Metadata Type dropdown offers. Core alone is the default.
orgbench.orgChannel — Read orgs through: how the extension reads an
org and sends the REST record writes of a bundle or model transfer. api
(Salesforce API) calls the Salesforce APIs
directly over HTTPS with the session the Salesforce CLI holds for the alias;
cli (the default, Salesforce CLI) starts sf for every read — slower, but over the
CLI's own connection. Applies immediately, with no restart: reads that start
after the change go through the new channel.
orgbench.logLevel — session log detail: off, standard or detailed.
No token ever reaches the file, and no response body either, except the
sanitized diagnostic of a failed call — the same text the UI shows.
The live progress line (phase, step counter, elapsed time) is always shown while
an operation runs; there is no setting for it.
Licensing
Orgbench is free during early access. A paid tier for advanced features is
planned; nothing is gated today, and every feature described above is available
to everyone.
The license path is fully offline: validation is a local signature check inside
the bundled sf-core-server — there is no license server, no phone-home and no
network call of any kind, not even a revocation check. Any licensing failure
degrades to the free tier and keeps working, and safety is never gated: every
boundary the repository's root README.md lists applies in every tier.
Enter or remove a key with the Orgbench: Manage License command — the key
icon in the view title opens it — and the picker's own title shows what the core
decided, including the reason a key was not accepted. The key and the first-run
timestamp live in a single file the core owns, inside your user data directory
(~/Library/Application Support/orgbench/ on macOS, %APPDATA%\orgbench\ on
Windows), so a key entered in either editor applies in both once that editor's
core has restarted and read the file.
There is no telemetry: nothing about you or your orgs is collected or
transmitted unless you turn on Describe differences with Claude Code, which hands
two versions of one component to your own Claude Code. The extension is distributed under the
End User License Agreement; see also the
Privacy Policy and the
third-party notices.
Troubleshooting
The support site https://orgbench.io/ answers questions about the extension and files a ticket; the question-mark icon in the view title opens it, and the link opens only when you choose it.
The Salesforce core process did not start
The extension launches a bundled sf-core-server binary from its bin/
directory. If the view reports that the core process could not start or
terminated, confirm the platform is supported (macOS arm64, macOS x64, Windows
x64 or Linux x64) and that the VSIX was installed without modification. On
Windows the bundled binary is unsigned, so SmartScreen or the antivirus may
quarantine it on first launch. The core process log is written to the Orgbench
Core output channel.
Reading an org fails although sf works
With orgbench.orgChannel set to api, the extension reads an org — component listings, SOQL queries, object
describes and REST sub-resources — by calling the Salesforce APIs directly over
HTTPS with the session the Salesforce CLI holds for the alias, instead of
starting sf for every read; it takes the same HTTPS_PROXY, HTTP_PROXY and
NO_PROXY settings the CLI does. When a proxy or a firewall lets sf through
but not these direct calls, the error details end with the transport error and
Set "Read orgs through" to "Salesforce CLI" in the Orgbench settings and retry. Set orgbench.orgChannel to cli and retry, with no restart: every
read then runs through sf, slower but over the CLI's own connection. The
same setting is the way out when the details say The Salesforce CLI did not reveal a session for the org '<alias>' (SF_TEMP_SHOW_SECRETS was not honoured). An expired session
needs nothing: the core asks the CLI for a fresh session once and repeats the
request. Only a second refusal in a row reaches the screen, and signing in again
would not help there, since the CLI has just refreshed that very session: the
message reads The org '<alias>' rejected the session the Salesforce CLI had just refreshed for it., asks you to set orgbench.orgChannel to cli and
retry, and keeps the org's own INVALID_SESSION_ID: Session expired or invalid
in the details.
No aliases are listed
Use the + button next to the Source or Target dropdown to log in to an
org and create an alias without leaving the editor, or run sf org list --json in
a terminal, authenticate aliases there and use the Reload Orgs button. Entries
without an alias are intentionally not shown.
While a browser login is running, the selection screen stays where it is with its
controls disabled, shows the live progress line and offers Cancel; cancelling
stops the CLI and leaves the browser tab open for you to close. A login that is not
finished within ten minutes is reported as such. In a headless or container
environment the Salesforce CLI refuses a browser login outright, and the extension
reports that instead — authenticate in a terminal there.
Source and target are rejected as the same org
Choose aliases that resolve to different org IDs; two alias names can point to
one org.
Salesforce is a trademark of Salesforce, Inc. Orgbench is an independent
product and is not affiliated with, endorsed by, or sponsored by Salesforce.
| |