Orgbench

Version 0.1.5 · Synced 2026-10-28 · Source vscode/README.md · Download .md

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.

Select Source and Target

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.

Review Differences with a side-by-side diff

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.

Select Permission Containers

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.

Deployment Results

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

  1. 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).
  2. In VS Code, open the Extensions view, choose Install from VSIX… from the … menu, and select the file.
  3. Open the Orgbench view from the Activity Bar.

Workflow

  1. 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.
  2. 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.
  3. Choose Compare.
  4. 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.
  5. 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.
  6. 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.
  7. 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.