Run and test

Getting Started

Installation

Single static binary. No JVM, no Node, no Docker. macOS, Linux, and Windows (native, no WSL) are all supported.

# macOS / Linux
curl -fsSL https://install.testnimbus.dev | sh

# Windows — works in cmd.exe, Windows Terminal, or any shell
powershell -c "irm https://install.testnimbus.dev/win | iex"

# Windows alternative: Scoop
scoop bucket add nimbus https://github.com/nimbus-solution/scoop-nimbus
scoop install nimbus

# Verify
nimbus --version

The installer verifies a SHA256 checksum and drops the binary in ~/.local/bin (macOS/Linux) or %LOCALAPPDATA%\Programs\Nimbus (Windows). Re-run any time to upgrade. See the Quickstart guide for platform-specific notes.

Quick Start

From a fresh install to a passing test in five commands:

# 1. Initialize Nimbus in your SFDX project root
cd path/to/your/sfdx-project
nimbus init

# 2. Verify setup
nimbus doctor

# 3. Run all tests
nimbus test

# 4. Run a specific class or method
nimbus test AccountTriggerTest
nimbus test AccountTriggerTest.testInsertCreatesContact

# 5. Run with coverage
nimbus test --coverage

The first run parses your Apex into an AST cache — a few seconds. Subsequent runs are milliseconds. See the full Quickstart guide for the starter project, Dev UI, and org sync steps.

Project Setup

Nimbus stores its state in a .nimbus/ directory at your project root:

.nimbus/
├── db/          # Embedded PostgreSQL data
├── cache/       # Parsed AST cache
└── traces/      # Execution traces (when --trace is used)

Add .nimbus/db/ and .nimbus/cache/ to your .gitignore. Traces can optionally be committed for sharing with your team.

# .gitignore
.nimbus/db/
.nimbus/cache/

User Stubs / Managed Packages

Sometimes Nimbus doesn't natively support a class or API: managed packages (Nebula Logger, FSL, Vlocity), unsupported built-in APIs (ConnectApi, Metadata), or custom code you want to mock. Use stubs to provide your own implementation.

What are stubs?

Stubs are user-provided Apex classes that implement APIs Nimbus doesn't know about. Instead of blocking on missing code, you implement just enough for your tests to run - then commit stubs to git so your team shares the same behavior.

How to use stubs

Create a stubs/ directory in your project root, with one folder per managed package. Each package folder holds everything for that package — Apex classes and namespaced custom objects/fields. Nimbus loads it all with the lowest priority; anything in force-app/ with the same name takes precedence.

my-salesforce-project/
├── force-app/
├── stubs/                                      # User-provided implementations
│   ├── Nebula/                                # one folder per package
│   │   ├── Nebula.cls                         # Apex surface (Nebula.Logger, ...)
│   │   └── objects/                           # namespaced custom objects
│   │       └── Nebula__LogEntryEvent__e/...
│   └── ConnectApi/
│       └── ConnectApi.cls                     # ConnectApi.FeedItem, etc.
└── sfdx-project.json

Adding another package later is just stubs/<NewPackage>/ next to the others. Surfaces stay cleanly separated, no cross-package collisions.

Writing a stub: example approach

Managed packages use namespaced classes like Nebula.Logger. In Apex, the namespace becomes the outer class and the package class becomes an inner class. Create stubs/Nebula.cls:

// stubs/Nebula/Nebula.cls
public class Nebula {

    public class Logger {

        public static LogEntryEventBuilder info(String message) {
            System.debug('INFO: ' + message);
            return new LogEntryEventBuilder();
        }

        public static LogEntryEventBuilder info(String message, SObject record) {
            System.debug('INFO: ' + message);
            return new LogEntryEventBuilder();
        }

        public static LogEntryEventBuilder info(String message, List<SObject> records) {
            System.debug('INFO: ' + message);
            return new LogEntryEventBuilder();
        }

        public static LogEntryEventBuilder info(String message, Id recordId) {
            System.debug('INFO: ' + message);
            return new LogEntryEventBuilder();
        }

        public static LogEntryEventBuilder info(String message, List<Id> recordIds) {
            System.debug('INFO: ' + message);
            return new LogEntryEventBuilder();
        }

        public static LogEntryEventBuilder error(String message) {
            System.debug('ERROR: ' + message);
            return new LogEntryEventBuilder();
        }

        public static LogEntryEventBuilder error(String message, SObject record) {
            System.debug('ERROR: ' + message);
            return new LogEntryEventBuilder();
        }

        public static LogEntryEventBuilder error(String message, List<SObject> records) {
            System.debug('ERROR: ' + message);
            return new LogEntryEventBuilder();
        }

        public static LogEntryEventBuilder error(String message, Id recordId) {
            System.debug('ERROR: ' + message);
            return new LogEntryEventBuilder();
        }

        public static LogEntryEventBuilder error(String message, List<Id> recordIds) {
            System.debug('ERROR: ' + message);
            return new LogEntryEventBuilder();
        }

        public static LogEntryEventBuilder warn(String message) {
            System.debug('WARN: ' + message);
            return new LogEntryEventBuilder();
        }

        public static LogEntryEventBuilder warn(String message, SObject record) {
            System.debug('WARN: ' + message);
            return new LogEntryEventBuilder();
        }

        public static LogEntryEventBuilder warn(String message, List<SObject> records) {
            System.debug('WARN: ' + message);
            return new LogEntryEventBuilder();
        }

        public static LogEntryEventBuilder warn(String message, Id recordId) {
            System.debug('WARN: ' + message);
            return new LogEntryEventBuilder();
        }

        public static LogEntryEventBuilder warn(String message, List<Id> recordIds) {
            System.debug('WARN: ' + message);
            return new LogEntryEventBuilder();
        }

        public static void saveLog() {
            // Stub: no-op
        }
    }

    public class LogEntryEventBuilder {

        public LogEntryEventBuilder addTag(String tag) {
            return this;
        }

        public LogEntryEventBuilder setRecord(Object record) {
            return this;
        }

        public LogEntryEventBuilder setException(Exception ex) {
            return this;
        }

        public LogEntryEventBuilder setExceptionDetails(Exception ex) {
            return this;
        }
    }
}

How stubs are resolved

Stubs are loaded as regular Apex classes — no special namespace mapping. When your production code calls Nebula.Logger.info(), the interpreter resolves Nebula as a class and Logger as an inner class, finding the stub naturally.

If a test calls a managed package class that doesn't have a stub, Nimbus degrades gracefully: it logs a warning and returns null instead of failing the test. Stubs are opt-in — you only need one when you require specific return values or side effects.

Namespaced custom objects

Some managed packages ship custom objects with a namespace prefix (Nebula__LogEntryEvent__e, fflib__Setting__c, etc.). If your tests do DML or SOQL against them, drop the schema XML inside the same package folder under objects/:

stubs/
└── Hoplog/
    ├── Hoplog.cls                              # Apex surface (Hoplog.Logger, ...)
    └── objects/
        └── Hoplog__LogEntry__c/                # namespaced custom object
            ├── Hoplog__LogEntry__c.object-meta.xml
            └── fields/
                ├── Hoplog__Severity__c.field-meta.xml
                ├── Hoplog__EventType__c.field-meta.xml
                └── Hoplog__Message__c.field-meta.xml

Nimbus reads the object/field XML the same way it reads any custom object in force-app/ — creates a matching table in the embedded Postgres so insert new Hoplog__LogEntry__c(...) and SELECT ... FROM Hoplog__LogEntry__c work end-to-end without the package being installed in any org. By convention, capitalize the namespace folder and class name; Apex itself is case-insensitive (so hoplog.Logger and Hoplog.Logger both resolve), but consistent capitalization is clearer on grep and in code review.

Equivalent layout: one file per class

The nested layout above (one file per package, classes as inner classes) co-locates the full Apex surface alongside any namespaced custom objects. An equivalent layout is one file per class — stubs/<ns>/<Class>.clswith public class <Class> { ... } directly, no outer wrapper. The stub loader registers <ns>.<Class> as an alias automatically, so both mp.Logger.info() and Logger.info() resolve to the same stub. Both layouts are first-class — pick whichever fits your editing style. nimbus stub add and nimbus stub auto (Pro) write the per-class layout; the nested layout is the hand-written convention.

Auto-null fallback behavior

When Nimbus encounters an unresolved class, it emits a warning and continues:

[warn] nebula.logger.Logger not found - returning null (add a stub to control behavior)
[warn] fsl.FieldServiceAPI not found - returning null

Tests that don't assert on the return value of those calls will pass. Tests that do assert on the value will fail with a clear message pointing at the missing class. This means you can get your first green run without writing any stubs - add them incrementally as you need control over return values.

Suppressing entire namespaces

For closed managed packages where you don't need specific return values - and can't see the source anyway - the auto-null fallback handles most cases silently. If you want to explicitly declare a namespace as intentionally unsupported (suppressing the warnings), use nimbus.properties:

# nimbus.properties
# Comma-separated list of namespaces to treat as opaque - no warnings, methods
# return null. Matching is case-insensitive.
nimbus.stubs.namespaces=Nebula,fflib,fsl

This is especially useful in CI where you want a clean output: warnings from auto-null suppressed, behavior consistent, no stub files cluttering the repo for namespaces your tests don't assert on.

Best practices

• One folder per package: Drop everything for a managed package under stubs/<Pkg>/ — Apex classes plus any namespaced custom objects. Inside, the outer class name matches the namespace and inner classes match the API
• Keep stubs minimal: Only implement methods your tests actually call
• Match signatures: Parameters, return types, and access modifiers should match the real API
• Use sensible defaults: Return empty lists, null, or debug output to help test behavior
• Commit to git: Stubs are small and help team members reproduce tests locally without external dependencies

For truly closed packages (no public source), the auto-null fallback and nimbus.properties noop declarations are your tools - or the future recording mode.

Roadmap: recording mode

The only fully-automated path for truly closed managed packages - where no source exists and no stub registry can help - is recording mode. Run nimbus test --record -o my-org once against a real org; Nimbus captures the actual runtime return values. All future local test runs replay those values without org access. Same pattern as VCR (Ruby), WireMock (Java), and Polly (JavaScript).

HTTP Mocking

There are two separate contexts for HTTP in Nimbus, and they work differently:

• In tests - Salesforce does not allow real callouts inside @isTest methods. Use Test.setMock() with a standard HttpCalloutMock implementation. Nimbus enforces the same rule as a real org.
• In nimbus exec - Apex runs outside of a test context, so Test.setMock() is not available. Use --mocks to provide a config file that Nimbus uses to intercept and respond to any Http.send() calls.

Test Callouts

Salesforce does not allow real HTTP callouts inside @isTest methods - any call to Http.send()without a registered mock throws System.CalloutException. Nimbus enforces the same rule.

The solution is the standard Salesforce pattern: implement HttpCalloutMock and register it with Test.setMock(). Nimbus supports this natively - no special setup required.

Basic example

@isTest
private class UserServiceTest {

    private class UsersMock implements HttpCalloutMock {
        public HttpResponse respond(HttpRequest req) {
            HttpResponse res = new HttpResponse();
            res.setStatusCode(200);
            res.setHeader('Content-Type', 'application/json');
            res.setBody('[{"id": 1, "name": "Alice"}]');
            return res;
        }
    }

    @isTest
    static void testFetchUsers() {
        Test.setMock(HttpCalloutMock.class, new UsersMock());

        Test.startTest();
        List<User__c> users = UserService.fetchUsers();
        Test.stopTest();

        Assert.areEqual(1, users.size());
        Assert.areEqual('Alice', users[0].Name);
    }
}

This code deploys and runs identically on Salesforce and in Nimbus. No Nimbus-specific classes or imports needed.

Multiple endpoints

A single mock class handles all callouts made during the test. Use the request method and endpoint to route responses:

private class ApiMock implements HttpCalloutMock {
    public HttpResponse respond(HttpRequest req) {
        HttpResponse res = new HttpResponse();
        res.setStatusCode(200);
        res.setHeader('Content-Type', 'application/json');

        if (req.getMethod() == 'GET' && req.getEndpoint().contains('/users')) {
            res.setBody('[{"id": 1}]');
        } else if (req.getMethod() == 'POST' && req.getEndpoint().contains('/orders')) {
            res.setStatusCode(201);
            res.setBody('{"id": "ord-001"}');
        }

        return res;
    }
}

Exec Mocking

When running Apex outside of a test context with nimbus exec, Test.setMock() is not available. Any Http.send() call needs to be intercepted at the Nimbus level.

Pass a mock config file with --mocks. Nimbus intercepts all Http.send() calls and returns the matching configured response - no real network request is made.

Using a mock file

nimbus exec MyClass.run --mocks nimbus.mocks.yaml

# nimbus.mocks.yaml
- method: GET
  url: https://api.example.com/v1/users
  status: 200
  body: '[{"id": 1, "name": "Alice"}]'
  contentType: application/json

- method: POST
  url: https://api.example.com/v1/orders
  status: 201
  body: '{"id": "ord-001", "status": "created"}'
  headers:
    X-Request-Id: abc-123

Inline mocks

For quick one-offs, define mocks directly on the command line:

# method:url:status:body
nimbus exec MyClass.run --mock "GET:https://api.example.com/v1/users:200:[]"

# multiple --mock flags
nimbus exec MyClass.run \
  --mock "GET:https://api.example.com/v1/token:200:{"token":"abc"}" \
  --mock "POST:https://api.example.com/v1/submit:201:{"ok":true}"

Unmatched callouts

If Apex calls an endpoint with no matching mock entry, Nimbus throws an error and halts execution. Use --allow-unmocked to let unmatched calls fall through to the real network instead.

nimbus exec MyClass.run --mocks nimbus.mocks.yaml --allow-unmocked

Sequential responses

List multiple responses for the same endpoint to return them in order. The last response repeats once the list is exhausted.

# First call → 429, second call onward → 200
- method: GET
  url: https://api.example.com/v1/items
  responses:
    - status: 429
      body: '{"error": "rate limited"}'
      contentType: application/json
    - status: 200
      body: '{"items": [{"id": 1}]}'
      contentType: application/json

Config Reference

Full schema for entries in nimbus.mocks.yaml:

Response object (used inside responses:)

Committing mock files

Commit nimbus.mocks.yaml alongside your code so the whole team uses the same mock definitions. Use multiple files to separate concerns - one per integration, one per feature area:

nimbus exec MyClass.run --mocks mocks/auth.yaml --mocks mocks/orders.yaml

URL Patterns Pro

Match endpoints by glob pattern instead of exact URL. Useful when your code constructs URLs with dynamic IDs or path parameters.

Wildcard syntax

# * matches one segment: /api/v1/users/123/profile, /api/v1/users/abc/profile
- method: GET
  url: https://api.example.com/v1/users/*/profile
  status: 200
  body: '{"name": "Alice"}'

# ** matches any path: /api/v1/orders/123/items/456
- method: DELETE
  url: https://api.example.com/v1/orders/**
  status: 204

Priority

Exact URLs always win over patterns. Among patterns, longer (more specific) ones win. If two patterns are equally specific, the first entry in the file wins.

# Priority: low → high (top to bottom in this list)

- method: GET
  url: https://api.example.com/v1/users/**    # broadest - lowest priority
  body: '{"fallback": true}'

- method: GET
  url: https://api.example.com/v1/users/*/settings    # wins for .../users/123/settings
  body: '{"theme": "dark"}'

- method: GET
  url: https://api.example.com/v1/users/me    # exact URL - highest priority
  body: '{"id": "me", "admin": true}'

Commands

nimbus sf

Run any Salesforce CLI core command or installed sf plugin through Nimbus. Arguments, the working directory, terminal input/output, interactive prompts, and the Salesforce process exit code pass through unchanged. Nimbus notices are suppressed so JSON output remains machine-readable.

nimbus sf org login web
nimbus sf data query --query "SELECT Id FROM Account" --target-org dev
nimbus sf project deploy start --source-dir force-app --target-org dev
nimbus sf package version create --package core --code-coverage

Flags after nimbus sf belong to Salesforce CLI; Nimbus does not parse them. The Salesforce CLI plugin intentionally does not expose ansf nimbus sf command because the user is already insidesf. Recursive nimbus sf nimbus ... invocations are rejected.

nimbus toolchain sf

Report which Salesforce CLI Nimbus resolves for remote work, and whether that version is supported. Installation uses Salesforce's official npm package; updates delegate to the resolved Salesforce CLI. Ordinary Nimbus commands never install or replace Salesforce CLI implicitly.

nimbus toolchain sf status
nimbus toolchain sf status --verbose   # resolved path, reported version line, policy
nimbus toolchain sf status --json      # stable shape for CI and editors
nimbus toolchain sf install            # official @salesforce/cli stable package
nimbus toolchain sf install --version 2.142.7
nimbus toolchain sf update --check     # read-only available-version check
nimbus toolchain sf update             # delegate to sf update stable

Resolution order

Flags

Pinning a version

Set nimbus.sf.version in nimbus.properties to assert an exact Salesforce CLI version. Status reports a mismatch so CI can prove it reproduces the configured toolchain.

# nimbus.properties
nimbus.sf.version=2.142.7

Install that exact version through Nimbus's assisted official-package flow:

nimbus toolchain sf install --version 2.142.7

Install and update flags

Exit codes

The command exits non-zero when the toolchain is not usable as configured, so a CI bootstrap step can gate on it: Salesforce CLI missing, a legacy sfdxgeneration, or a violated nimbus.sf.version pin. A version that merely trails the tested one is reported but exits zero.

Nimbus's local loop — test, validate, exec,lsp, daemon — does not need Salesforce CLI at all, andnimbus doctor reports a missing CLI as a warning rather than a failure for that reason.

nimbus deploy

The safe one-shot Salesforce deployment. Nimbus snapshots the selected payload, runs local semantic validation and Apex tests against that snapshot, validates the same bundle in Salesforce, and only then deploys it. This gated path is available on Free; a raw bypass remains explicit as nimbus sf project deploy start ....

nimbus deploy --target-org staging --source-dir force-app
nimbus deploy --target-org production --manifest manifest/package.xml --confirm-production
nimbus deploy --target-org qa --metadata ApexClass:AccountService --metadata ApexClass:AccountServiceTest

Production targets require an interactive typed confirmation or the explicit --confirm-production flag. Nimbus records the org as a one-way fingerprint and never puts the alias, username, access token, or instance URL in the receipt. Generated receipts and bundles live under .nimbus/releases/.

Selection and gate flags

nimbus release Pro

Feature deep-dive: release management.

Split validation from approval and deployment with a portable, immutable receipt. The exact uncompressed bundle is content-addressed; fallback deployment verifies and deploys that stored artifact, while production validation retains Salesforce's org-side job for quick deploy. Missing, changed, expired, wrong-org, or incompatible receipts are rejected with no override flag.

nimbus release plan --target-org staging       # read-only: what would reconciling the org to source change?
nimbus release validate --target-org staging --changed   # bundle and validate only source − org
nimbus release validate --release-profile production
nimbus release deploy --receipt .nimbus/releases/rel_....json --release-profile production --confirm-production
nimbus release run --release-profile staging
nimbus release status                    # org deploy queue + stuck-Pending diagnosis
nimbus release watch 0Af... | rel_...    # live org-side progress until terminal
nimbus release promote rel_... --target-org prod   # same bundle, validated against the next org
nimbus release rollback rel_... --target-org prod --confirm-production   # restore what that deploy overwrote
nimbus release requeue rel_...          # cancel a stuck Pending job, resubmit the validated bundle
nimbus release keygen                   # create a signing key + trust it in this project
nimbus release verify rel_...           # offline: re-hash the bundle, check the signature
nimbus release list
nimbus release get rel_.... --json

With no selector, validate and run default their source to the packageDirectories in sfdx-project.json, the same way sf project deploy start does — so a bare nimbus release validate --target-org <org> just works. An explicit --source-dir, --manifest, or --metadata always wins. After a successful validate, the printed Next: line is copy-paste runnable: it carries the --target-org (or --release-profile) the deploy needs, since the receipt stores only a one-way org fingerprint, never the alias.

Exit codes: 0 success, 20 configuration, 21local gate, 22 Salesforce validation, 23 deploy,24 production confirmation, 25 release integrity violation (tampered / mismatched / missing bundle), 26 deploy submitted but outcome unconfirmed (run nimbus release watch <job>),27 drift — baseline components changed in the org after validation (revalidate, or deploy again with --override-drift),28 plan --fail-on-diff found source↔org differences (for scheduled reconciliation jobs), 29 counter-signature required but missing, or a production deploy by the same identity that validated (segregation).

Receipt and bundle files may be uploaded between CI jobs. When a downloaded receipt is passed by path, Nimbus locks, reads, and updates it beside its sibling bundle instead of silently creating a different local copy.

The deploy job still needs the project skeleton on disk. A receipt and its bundle are not enough on their own: sf deploys in project context, so the checkout that runs nimbus release deploy must containsfdx-project.json and every path its packageDirectoriesdeclares (an empty force-app/ is fine, but the directory must exist). Job-status polling (report / resume / cancel) is decoupled from local project state — Nimbus runs those org-side queries from a neutral throwaway project — so a broken checkout no longer makes a poll die while the org deployment succeeds. But the deploy command itself is still a project-context operation, so check the project skeleton out in the deploy job.

Named profile

# nimbus.properties
nimbus.release.profile=staging
nimbus.release.staging.targetOrg=staging
nimbus.release.staging.source.dirs=force-app
nimbus.release.staging.nimbusTests=*
nimbus.release.staging.minCoverage=75
nimbus.release.staging.minMutationScore=80
nimbus.release.staging.codeAnalyzerThreshold=2
nimbus.release.staging.requireCodeAnalyzer=true
nimbus.release.staging.validateLocal=true
nimbus.release.staging.validateSalesforce=true
nimbus.release.staging.requireCleanGit=true
nimbus.release.staging.mismatchReporting=ask
nimbus.release.staging.permissionSeamPolicy=allow
nimbus.release.staging.sfVersionPolicy=compatible
nimbus.release.staging.requireSigned=false
nimbus.release.production.requireCountersigned=true

codeAnalyzerThreshold (1-5) is optional. When set, the local gate runs Salesforce Code Analyzer (sf code-analyzer) against the staged bundle and fails the release if any violation is at that severity or more severe (1=Critical … 5=Info; e.g. 2 blocks Critical and High). The full violation counts by severity are recorded on the signed receipt whether or not the gate blocks — so the receipt carries static-analysis (form) evidence next to the behavioral (tests, coverage, mutation) evidence, both tamper-evident. It reuses the code-analyzer already in your Salesforce CLI; no separate scanner to install. The receipt also records the ruleSelectorand a policyDigest — a fingerprint over the rule selection, engine versions, and any committed analyzer config — in the signed core, so whichrules produced the counts is itself answerable and tamper-evident.

requireCodeAnalyzer=true makes the gate fail closed — the complement to requireSigned/requireCountersigned. Without it the gate is opt-in and its absence is silent: a receipt with no analysis looks identical to a clean scan. With it, a profile refuses to validate or deploy a receipt that carries no static-analysis result at all (it requires codeAnalyzerThreshold to be set). The setting for a regulated profile that must never ship un-scanned code.

minMutationScore (0-100) is optional. When set, the local gate runs mutation testing against the staged bundle — using nimbusTests as the test selection — after the tests pass, and fails the release if the measured mutation score is below the threshold. It is skipped entirely when unset, since mutation testing is expensive; set it only on profiles where you want tests held to a proven quality bar, not just a coverage percentage.

maxReceiptAge (a duration such as 240h) caps how old a receipt may be at deploy time. It applies to every receipt, not only quick-deployable ones — a validated bundle that has aged past the window deploys against a drifted org, so nimbus release deploy refuses it and asks you to revalidate. It defaults to the 10-day Salesforce quick-deploy window. Independently,nimbus.release.keepReceipts (default 30) caps how many receipts a successful validate retains under .nimbus/releases: the oldest terminal receipts (failed / succeeded / cancelled) beyond the cap are pruned along with their bundles, while still-deployable (org_validated /deploying) receipts and the one just created are always kept.

nimbus release deploy consumes an already-validated receipt, so it honors only --receipt (or the positional receipt), --target-org,--release-profile, --confirm-production, and--json. It reruns no gates and restages no source, so the validate-time selectors and thresholds are not offered there. Passing a receipt both positionally and via --receipt is an error rather than a silent pick.

permissionSeamPolicy is allow (default),block-custom, or block-all. Nimbus runs tests as a sysadmin-equivalent mock user. The two seam classes resolve differently, and conflating them is a common misread:

• FLS / object permissions default to true (allow) outside System.runAs() — a field or object check passes in Nimbus even when the org's running user would be denied. This is the permissive seam.
• Custom permissions ($Permission.X /FeatureManagement.checkPermission) do not default to allow. They resolve against seeded permission-set state and default to deny unless the permission is granted to the mock user. So an ungranted custom permission already reads false, exactly as it would in the org — no seam, nothing to block. A block-custom seam fires when agranted custom permission is read through the default path outsiderunAs: the check passed because the seed granted it, not because the real running user holds it. The gate is deliberately narrow — it is not “unfireable”, it fires precisely on the granted-and-unguarded case.

block-custom fails the release on custom-permission seams (the highest-risk case, because those reads look like business logic, not security) while still allowing the FLS / object-perm seams. block-all blocks on any seam.allow never blocks, but the seam counts are always recorded on the receipt, so the divergence stays visible even under the permissive default.

Deploy queue visibility

Salesforce runs one deployment at a time per org and hides the queue, so a deploy waiting its turn is indistinguishable from a hung one — and a Pending job the scheduler silently dropped is indistinguishable from one about to start.nimbus release status reads the org's deployment queue, shows each job's position, live progress counters, and recent history correlated with your local receipts, and calls out a job that is genuinely stuck — Pending beyond a threshold, never started, with nothing running that explains the wait — together with the exact remedy. Jobs Nimbus did not create are diagnosed but never touched. The threshold is configurable via nimbus.release.stuckPendingAfter. Status is read-only and not Pro-gated: knowing your deploy is stuck is safety.

nimbus release status --json emits a stable, versioned document (schemaVersion, lowerCamelCase fields, whole-second durations) built for scripted gates. Active and in-flight jobs are always shown in full; the terminal recent-history list is capped — default 20, overridable with --limit — so a busy org's full day of deploys never floods a consumer.

Self-healing releases

Release validation and deployment submit asynchronously and own the wait: Nimbus polls the org, streams component and test counters as progress, and — when its own job sits Pending beyond a threshold with nothing running that explains the wait — cancels and resubmits the identical validated bundle automatically, with bounded retries. Nothing has executed org-side for a job that never started, and the payload cannot drift because it is the stored bundle, so no re-confirmation is asked; every recovery attempt is recorded on the receipt. Deployments Nimbus did not create are never touched. nimbus release watch follows any job or receipt read-only and mirrors the outcome in its exit code.

When a job stuck while nothing was attending it, nimbus release requeueapplies the same remedy by hand: it takes a receipt — never a bare job ID — verifies the org matches the receipt's fingerprint and the job is genuinely Pending and never started, then cancels it and resubmits the stored, digest-verified bundle. Foreign jobs are diagnosed by nimbus release status but never touched, so requeue can only ever act on a deployment Nimbus itself validated.

Plan — read-only source ↔ org reconcile

nimbus release plan answers “what would deploying my source actually change?” before any gate runs: it retrieves the org's current copy of the metadata types present in your selection into a throwaway directory, compares normalized content, and reports each component as + new in source,~ changed, unchanged, or - org-only (what a destructive change would remove — plan only ever reports it). Nothing deploys, no receipt is written, and the project's own source is never touched. Line-ending and trailing whitespace differences are not changes.

Human output caps each category at 20 rows so a shared org's thousands of foreign components cannot drown your deployable changes; --json always carries the complete component list plus counts and the compared metadata types (component states use the same camelCase as the count keys: orgOnly,notCompared). Source components whose type plan cannot retrieve for diffing (profiles, for example) are reported as not compared rather than guessed at. Exit is 0 whether or not differences exist — unless--fail-on-diff is set, which exits 28 on any divergence so a scheduled CI job can alert when the org has drifted from source (the compensating control for deploys that bypass Nimbus entirely).

Promote — the same bundle through your environments

nimbus release promote <receipt> --target-org prod carries a validated (or already deployed) release's exact bundle to another org and validates it there, writing a new receipt chained to its origin via promotedFrom. Promote never re-collects from the worktree — the worktree may have moved on; the stored bundle has not — so the bundle digest and source fingerprint are byte-identical across the whole chain. That is the provable claim “what you validated in staging is what reached production”, and it sits under the receipt signature.

What re-runs and what doesn't follows one rule: environment-specific work re-runs, byte-determined work is inherited. Nimbus's local execution is hermetic, so local gate results are a pure function of the bundle bytes — identical bytes carry their proof, recorded as an inheritance note in the transition trail. The Salesforce validation always re-runs against the destination, because every org drifts on its own schedule; a changed-set baseline is likewise recomputed against the destination so the deploy-time drift check guards the org actually being changed. Promote validates only — deploy the receipt it prints, with --confirm-production where required.

Declare your promotion chain once and --next walks it:

# nimbus.properties
nimbus.release.environments = dev, uat, prod

nimbus release promote rel_... --next     # from the receipt's org to the next stage

The receipt stores only a one-way org fingerprint, so --next derives the receipt's position by fingerprinting each configured alias. Promoting past a configured stage (dev straight to prod) is allowed but never silent: the receipt records the number of skipped stages inside the signed core, release get and release list show it, and hiding the jump would break the signature.

Changed-set releases and drift

--changed (on validate, run, anddeploy's free sibling) reduces the payload to source − org: only components that are new in source or differ from the target org are bundled and deployed, plus their -meta.xml companions and the project scaffolding a DX deploy requires. The local gates still stage and run the full suite — a smaller payload never means less proof. On a large org this turns an hours-long full validation into minutes: validate 3 changed classes, not 3,000 unchanged ones. Config equivalent: nimbus.release.<profile>.changedOnly=true. If source already matches the org, validate refuses with “nothing to release” rather than writing an empty receipt.

A changed-set receipt records a baseline: the org-side content digest of every component it will overwrite, captured at validation and covered by the receipt signature. At deploy time Nimbus re-retrieves exactly those components (member-precise, not whole types) and compares. If the org moved underneath the receipt — someone hotfixed a class directly in production after you validated — the deploy is refused with exit 27 and the drifted components are named. There is no silent overwrite: --override-drift lets source win for this one deploy, and the override is recorded on the receipt (outside the signed core, so the validation-time signature stays intact) and in the transition trail. Overriding is deliberately flag-only — it cannot be set in configuration.

Rollback — restore what a deploy overwrote

Just before every deploy, Nimbus captures the org's current content of the payload's components as a snapshot bundle beside the receipt (a changed-set deploy reuses the drift check's retrieve, so it costs no extra org round-trip; capture is best-effort and never blocks the deploy — a skipped capture is recorded in the transition trail). nimbus release rollback <receipt> sends that snapshot back through the assured pipeline — check-only Salesforce validation of the snapshot bytes, then deployment — as a new receipt chained via rollbackOf, in one step, with --confirm-production required on production.

Two limits are stated rather than papered over. Components the rolled-back deploy added are not deleted — the snapshot holds prior content, and a component that did not exist has none; removal is a destructive change and stays a separate, explicit step. And local gates do not run — the payload is the org's own previous state, not developer source, so the org-side validation is its oracle, exactly as when that state first shipped. Both appear in the receipt's transition trail.

Rollback carries its own drift guard: before restoring, Nimbus compares the org's current content of the snapshot's components against what the rolled-back deploy shipped. If the org moved after that deploy — a post-incident hotfix, say — restoring the snapshot would erase that change too, so the rollback refuses (exit 27, components named) unless --override-drift is given; the override is recorded on the receipt with the actor who granted it.

Signed receipts

A receipt states what was validated; a signed receipt also proves who validated it. nimbus release keygen creates an Ed25519 key: the private half lives in ~/.nimbus/release-signing.json (user-only permissions, never inside the project), and the public half is appended to .nimbus/release-signers.json in the project root. Commit that roster — adding or removing a release signer then goes through code review like any other change. If you gitignore .nimbus/ (for the db and receipts), commit the roster with git add -f .nimbus/release-signers.json; once tracked, git follows it normally. An uncommitted roster silently breaks verification for everyone else, so keygen prints the right command for your repo.

Once a key exists, every release validate signs the receipt's immutable core (digests, gates, validation result, org fingerprint, toolchain) automatically, and release deploy verifies signed receipts against the committed roster before anything is sent: a receipt whose signed core was modified after signing, or whose signer is not on the roster, is refused as an integrity violation (exit 25). Verification is fully offline — the receipt embeds the public key, the roster decides trust.

Signing is opt-in per project. Unsigned receipts keep working until a profile sets requireSigned=true, which refuses to deploy any unsigned receipt — the natural setting for a production profile once the team has keys.

Who did what: the signature answers who validated; deploy-time events carry their own actor. When a signing identity exists (a key, or NIMBUS_SIGNING_IDENTITY in CI), the transition trail records who started the deploy, who granted a drift override (driftOverride.by), and who ran a rollback. An optional --change-ref JIRA-1234 on validate/run/rollback links the receipt to the process that authorized it — inside the signed core, so stripping the ticket reference breaks the signature; promote inherits it with the bundle. Receipts still never carry org aliases, but the machine that ran a release keeps a local, non-portable sidecar (.nimbus/org-aliases.json) so release get can say staging instead of a fingerprint — labeled as a local alias, and absent on any other machine.

Key lifecycle: nimbus release keygen --revoke <keyId>marks a key untrusted (lost laptop, leaked CI seed, departed teammate). Revocation is conservative — verification refuses every receipt signed with a revoked key, whenever it was signed, because an unsigned timestamp cannot prove a signature predates the compromise. The entry stays in the roster: the revocation is itself part of the record. Rotate the CI secret, keygen the replacement, revalidate what must stay deployable.

Trust is visible where humans read the evidence, not only at deploy. nimbus release verify <receipt> re-hashes the bundle against the recorded digest and checks the signature against the roster, fully offline — a tampered bundle, a forged field, or an untrusted signer fails with exit25; an unsigned receipt passes with an explicit warning. release get runs the same checks and printsIntegrity: and Signature: lines on every receipt — an unsigned receipt is labeled UNSIGNED — this view is unverified evidence, so an evidence reviewer is never fooled by numbers the file merely claims. Every receipt also records expiresAt (10 days by default,maxReceiptAge to change), so an archived artifact answers “validate Friday, deploy Monday?” on its own.

The displayed signer comes from the roster, not the receipt's own signature.signer string — that string is unsigned, so verification resolves the name from the committed keyId→name binding and flags any mismatch. For gates that must fail closed, release verify --require-signed exits25 on an unsigned receipt instead of passing with a warning.

Two attestations: validation and deploy. The validation signature covers the facts fixed at validation time — gates, digests, change ref, target org, toolchain, baseline. A separate deploy counter-signature covers the terminal deploy outcome — who deployed, the final status, any drift override — chained to the receipt so it can't be lifted onto another release. release get and verify show both:Deploy: counter-signed by <name> when attested, ornot counter-signed (status and actor are recorded, not attested) otherwise. This closes the gap where a signed receipt's deploy status and actor could be appended without breaking the signature.

Counter-signing is per-profile: nimbus.release.production.requireCountersigned=truedemands it. When required, the deploy must carry a signing identity (a dev's key or CI's NIMBUS_SIGNING_KEY), and on a production target that identity must differ from the validator — segregation of duties, so authorization is distinct from execution. A production deploy by the same identity that validated is refused with exit 29; a second person must deploy.

nimbus release keygen                          # key + roster entry for git config user.email
nimbus release keygen --signer you@team.dev    # explicit identity
nimbus release keygen --ci                     # also print the seed once, for a CI secret

# headless CI signs via environment
NIMBUS_SIGNING_KEY=<seed> NIMBUS_SIGNING_IDENTITY=release-bot nimbus release validate ...

# refuse unsigned receipts on production
nimbus.release.production.requireSigned=true

Salesforce test level

Leave salesforceTestLevel unset and Nimbus resolves it from the target org: RunLocalTests for production, which Salesforce requires, andNoTestRun everywhere else. Nimbus has already run the whole suite locally in seconds by that point, so having a sandbox re-run every test in the org pays twice for the same answer and is the most expensive thing a release does. The org stage on a sandbox is there to prove deployability against real org metadata, which needs no tests.

Set it explicitly to override. On Winter '26 and later,RunRelevantTests runs only the tests relevant to the deployed metadata — Salesforce measures it at roughly 93% faster thanRunLocalTests — and is the better production choice where the org supports it.

nimbus.release.production.salesforceTestLevel=RunRelevantTests

A validation that runs no tests cannot be quick-deployed, so Nimbus records no quick-deploy window for it and a later deploy re-sends the verified bundle.

Select a named profile with --release-profile. This is deliberately distinct from the global --profile, which activates a Quarkus-style%profile. configuration overlay.

Mismatch reporting

When Salesforce rejects the exact payload your local gates passed, and Nimbus classifies the rejection conservatively as a likely Nimbus compatibility gap — every reported problem looks like a compiler diagnostic Nimbus claims to cover, and no org- or project-dependency pattern matched — Nimbus can send a small, sanitized report so that gap becomes a permanent regression case. Org and project mismatches (missing dependency, managed package, coverage policy, org-only field) are never treated as Nimbus defects, and the deploy stays failed regardless of reporting.

A report contains only: the Nimbus and Salesforce CLI versions, the API version, the org kind (production/sandbox/…), the Salesforce test level, the classification, a dedupe fingerprint, the local-gate summary (validate/tests passed, tests run, coverage), and the rejection's error lines after they pass through the anonymizer. It never contains source code, org IDs, aliases or usernames, file paths, instance URLs, or record data — custom identifiers and paths are renamed while line numbers and standard platform vocabulary (Method does not exist, ApexClass) survive so the report stays diagnosable.

Reporting is opt-in. The mode is nimbus.release.<profile>.mismatchReporting=never|ask|always; ask is the default and only prompts in an interactive terminal — in CI, and inside a --json contract, ask behaves as never. --report-mismatch opts in for a single run and --no-report-mismatch always wins. When prompted, Nimbus prints the full sanitized record and the count of renamed identifiers before asking, defaulting to No. Every eligible record is always saved locally under .nimbus/releases/<releaseId>.mismatch.json for review, whether or not it is sent, and reporting never changes the release command's outcome or exit code. Set NIMBUS_REPORT_URL=disabled to switch submission off entirely regardless of configuration, or point it at your own endpoint for staging.

In the VS Code and IntelliJ release surfaces, the preview dialogis the prompt. When a validate or deploy fails this way, the editor offers to review an anonymized report; choosing to review shows exactly the sanitized record that would be sent, plus the count of renamed identifiers, and asks Send report / Save locally only / Cancel, defaulting to not sending. The daemon builds and sanitizes the record — the editor never sanitizes client-side and never sees raw problem text in the consent path — so what the dialog displays is byte-for-byte what submission would post. Both editors show the same wording and the same three choices.

Exit codes

nimbus assurance Pro

Feature overview: the Assurance console.

The Assurance console: a self-hosted web view of every release's signed evidence, for the whole team — including the people who read releases but never open a terminal. Your code and receipts never leave your infrastructure: Nimbus hosts nothing, the console reads local receipts and is read-only, and it never contacts a Salesforce org and never deploys. The only outbound connection is Nimbus's own licence check on startup — no code, no receipts, no org data — the same as any Nimbus command.

nimbus assurance                      # open the console for this project
nimbus assurance --addr 0.0.0.0:8090  # share it with the team on your network

Each release shows, in plain language: who validated it, who deployed it, whether the checks passed (tests, coverage, static analysis), whether it drifted, its change reference, and — verified live in the browser — whether the bundle and signatures are intact. A dashboard summarises the set: production deploys, signed vs unsigned, counter-signed, and anything that failed verification. The verification is the same path release verify runs, so a tampered bundle or a forged signer name reads identically in the console and on the command line.

Access. On localhost the console is open — it's your machine. The moment you bind beyond loopback it requires an access token, so an evidence server reachable on the network is never wide-open: pass --tokenor set NIMBUS_ASSURANCE_TOKEN for a stable token, or let a network bind generate a per-session one and print a ready-to-open URL. The console (the page) is always served; only the evidence behind it is gated.

Evidence export and offline re-verification

nimbus release export writes the verified receipt set plus the signer roster into one self-verifying JSON document — the file you archive to your own immutable / WORM store for retention. It carries no source, no org aliases, and no credentials: it is evidence, not payload. The console offers the same as an export evidence download.

nimbus release export --org-kind production --since 2026-07-01 --output evidence-2026Q3.json
nimbus release verify-export evidence-2026Q3.json                        # re-check every signature, offline
nimbus release verify-export --require-signed evidence-2026Q3.json       # CI gate: fail unless fully signed
nimbus release verify-export --roster .nimbus/release-signers.json ev.json # prove authenticity vs a trusted roster

nimbus release verify-export re-checks every signature and counter-signature against the roster embedded in the export — fully offline, on any machine, years later. It needs no Nimbus licence: an auditor who holds the file can re-verify it with no vendor relationship (authoring an export stays a Pro workflow; re-checking one is free). It exits 25 if any signature fails. Bundle integrity isn't re-checkable from an export (it carries no bundles), but each receipt's signed core — what was validated, and by which key — re-verifies forever.

A bare run reports what it finds and only fails on a signature that verifies incorrectly, so an empty or all-unsigned file still exits 0. Add --require-signed to turn it into a gate: it fails (25) unless the set is non-empty and every receipt carries a valid signature — the form to wire into a retention-integrity check.

Internal consistency vs. authenticity

By default verify-export checks each signature against the roster embedded in the same file — it answers "are these signatures internally consistent?", which is necessary but is not proof of provenance: a file could carry its own roster. To prove authenticity, pin an external trust anchor you already trust — the project's committed .nimbus/release-signers.jsonvia --roster, or a specific --expect-signer <keyId>. Any signature by a key outside the anchor is reported and fails (25). The anchor, not the file, becomes the root of trust.

What a signature attests — validation, not the deploy

The validation signature covers the immutable core (digests, gates, target, toolchain) fixed at validate time — not the status, actor, or transition trail, which change afterward at deploy time. So a succeededstatus is only proven when a deploy counter-signature backs it; otherwise it is self-reported. verify-export and the console label a deploy that is not counter-signed as self-reported, so a green "signature verified" is never mistaken for proof of who deployed, or when. Turn on requireCountersigned to make the deploy attestable (and, on production, enforce a second identity — exit 29).

Reading a receipt as change-management evidence

A signed receipt maps directly onto the assertions a change-management review asks for — so an auditor can read one as evidence:

nimbus test

Run Apex test classes locally. This is the core command you'll use every day.

Pattern matching

nimbus test                              # Run all tests
nimbus test MyTestClass                  # All methods in a class
nimbus test MyTestClass.testMyMethod     # Single test method
nimbus test Calculator*                  # Classes starting with "Calculator"
nimbus test *Test                        # Classes ending with "Test"
nimbus test *Calculator*                 # Classes containing "Calculator"

Path patterns

nimbus test force-app/main/default/classes/MyTest.cls   # Specific file
nimbus test force-app/main/default/classes/              # All in directory

Running nimbus test with no pattern from inside a package subdirectory (e.g. after cd’ing intoforce-app/main/default/classes/billing) auto-scopes to that subdirectory instead of the whole project.

Parallel execution Pro

nimbus test -p 8     # 8 parallel workers (Pro)
nimbus test -p 16    # Push it harder on fast machines
nimbus test           # Sequential (Free tier default)

Coverage

nimbus test --coverage                              # Print summary to console
nimbus test --coverage --coverage-output json       # JSON to console (for scripting)
nimbus test --coverage --coverage-report out.json   # Save JSON to file
nimbus test --coverage --coverage-report out.html   # Save HTML report
nimbus test --coverage --coverage-report out.xml    # Save Cobertura XML (Team)

Org fallback Pro

nimbus test -f -o my-org    # Fall back to SF CLI when Nimbus can't handle a test
nimbus test --fetch-missing -o my-org  # Fetch missing metadata and re-run

When Nimbus surfaces missing metadata (Apex classes, custom fields, custom labels, custom objects, custom metadata types), it also writes a standard SFDX manifest at manifest/nimbus-missing.xml — regardless of whether --fetch-missing is set. You can hand it to sf directly: sf project retrieve start --manifest manifest/nimbus-missing.xml -o <alias>. The filename is distinct from package.xml so it won't clobber a user-managed deployment manifest.

Tracing / debugging

nimbus test --trace                          # Enable execution tracing
nimbus test --trace --trace-level debug      # Verbose trace
nimbus test --trace --trace-output ./traces  # Save traces to custom dir

Org defaults (custom settings)

Seed custom setting org-default records before tests run. Can be specified via CLI flag or committed to nimbus.properties for repeatability.

# CLI flag (one field per flag, or comma-separated fields)
nimbus test --org-default "TriggerSettings__c.IsEnabled__c=true"
nimbus test --org-default "MySettings__c.Field1__c=foo,Field2__c=bar"

# nimbus.properties (committable, profile-aware)
nimbus.seed.org-default.TriggerSettings__c=IsEnabled__c=true
nimbus.seed.org-default.MySettings__c=Field1__c=foo,Field2__c=bar

Exclusions

nimbus test -e __tests__       # Exclude paths containing "__tests__"
nimbus test -e legacy -e wip   # Multiple exclusions

Parallel sharding

Split your test suite across multiple CI jobs with --shard N/M. Job N runs only its assigned slice of test classes. All N jobs run concurrently in a CI matrix, cutting wall-clock time proportionally.

Classes are distributed by recorded test duration (not just count), so shards finish in roughly equal wall time even when a few classes dominate the runtime. Duration data is recorded automatically by full test runs and persisted in your project; a project with no history yet falls back to an even split by class name. All methods within a class are always kept together so @testSetup runs correctly.

When combined with --results-xml, each shard's JUnit XML output includes a shard="N/M" attribute on the root <testsuites> element, allowing CI aggregators to merge results across shards.

# GitHub Actions matrix example
strategy:
  matrix:
    shard: [1, 2, 3, 4]
steps:
  - run: nimbus test --shard ${{ matrix.shard }}/4 --format junit

Tuning parallel execution

The default of 8 workers is a safe starting point for most machines and projects. You can push higher, but there's a ceiling — and it's not CPU or memory.

Why conflicts happen

Each parallel test worker runs inside its own database transaction. When two workers insert, update, or delete rows in the same table at the same time, PostgreSQL acquires row-level locks. If worker A holds a lock that worker B needs (and vice versa), you get a deadlock or a lock timeout.

Nimbus handles this automatically: transient database errors (deadlocks, lock timeouts, constraint violations) are retried up to 3 times with exponential backoff. If retries are exhausted, the test is re-run sequentially after the parallel phase completes. Your test still passes — it just takes longer. To disable this sequential re-run fallback, set nimbus.test.rerun-failed=false in nimbus.properties.

The problem is probability. With 4 workers, lock conflicts are rare. With 8, they're occasional and retries handle them. With 16+, conflicts become frequent enough that retries are exhausted, sequential re-runs pile up, and total wall-clock time can actually increase.

Finding your sweet spot

The optimal worker count depends on your codebase, not your hardware. Projects where tests touch many different objects can run more workers. Projects where most tests insert into the same few objects (Account, Contact, Lead) hit contention earlier.

# Start with 8 workers
nimbus test -p 8

# If you see 0 sequential re-runs, try pushing higher
nimbus test -p 12

# If you see many sequential re-runs, back off
nimbus test -p 4

# CI: use nimbus.properties so the settings are committed
%ci.nimbus.test.parallel=8
# Disable sequential re-run fallback if you want hard failures instead
%ci.nimbus.test.rerun-failed=false

Watch the test summary for "re-run sequentially" messages. If you see more than a handful, your worker count is too high for the contention profile of your project. Back off until re-runs drop to near zero.

Scaling beyond the single-machine limit

If you've maxed out parallel workers on one machine and still want faster runs, use --shard to distribute across multiple CI jobs. Sharding splits tests across entirely separate processes — each with their own database — so there's zero lock contention between shards. This scales linearly.

Local shards Pro

--local-shards N runs the same sharding model on one machine: N concurrent nimbus test processes, each with its own embedded Postgres instance, splitting the suite the same way --shard does. Pass a number, or auto to let Nimbus decide: it picks a shard count based on available cores, but won't shard at all if the suite's recorded run time (from the last full run, tracked in .nimbus/test-durations.json) is too short to be worth the per-shard process overhead — or if there's no recorded run yet. Tune the cutoff with nimbus.test.local-shards-auto-threshold-ms (default 8000).

nimbus test --local-shards 4       # 4 concurrent shards, 4 separate databases
nimbus test --local-shards auto    # Let Nimbus choose (by cores and suite length)

Each shard gets a persistent background daemon (visible in nimbus daemon list) that stays warm across runs, so repeat invocations skip database startup. Results, JUnit XML, and JSON output are merged into a single report as if the suite had run in one process. --local-shards is mutually exclusive with --shard, requires the embedded database provider, and does not currently support --coverage, --dry-run, --interactive, --write-stubs, --fetch-missing, or --impacted.

Each shard is a separate OS process, so it pays its own startup cost — Go runtime init, daemon handshake, config parsing — once per invocation. On short suites that fixed cost can outweigh the benefit of a second Postgres instance; on longer-running suites it's a smaller fraction of total wall time, so the separate-database win has more room to show through. If you're not seeing a win, try a lower shard count before a higher one — splitting workers across more processes also means fewer workers per shard, which can offset the extra database parallelism.

Per-worker isolation (opt-in)

Set nimbus.test.isolation=per-worker-schema to give each worker its own cloned Postgres schema. Row-level locks and writes stay inside the worker, so -p can scale to your CPU count without cross-worker contention. Default is shared to keep startup cost low — see Parallel Isolation for details.

nimbus test:watch Pro

Continuous testing mode. Watches your Apex files and automatically re-runs tests whenever you save.

nimbus test:watch              # Watch all tests
nimbus test:watch -i           # Select package scope interactively

While watching:

r    # Manually trigger a re-run
c    # Clear the output
q    # Quit (or Ctrl+C)

Watch mode uses test impact selection automatically once an impact map exists: the first run runs everything and builds the map, and each later run narrows to the tests affected by the files you changed (e.g. 3 of 412 tests impacted by AccountService.cls), falling back to a full run when a schema file changes. Pass --no-impact to run the full pattern on every change.

nimbus validate

Check Apex files for syntax errors and apiVersion mismatches without running tests. Fast — no database or runtime needed. Errors come from the parser; warnings come from the apiVersion check, which reads each file’s *-meta.xml for the declared apiVersion and flags any referenced symbol whose introduction version is newer than that. Catches mistakes like a v52 class callingDatabase.getCursor (v66) before the deploy does.

Beyond warnings, validate flags a handful of deploy blockers — things Salesforce rejects at compile/deploy — and exits non-zero when any are found: REST resource methods with an unsupported return type; setting an AutoNumber field in an SObject constructor (new Log__c(Name = 'x') — AutoNumber fields aren’t writeable); and a concrete class that declaresimplements but doesn’t define every method of the interface. The field and interface checks resolve schema and interfaces from the local project, and skip conservatively when a type can’t be resolved (e.g. a managed-package or cross-file interface) so they never block a deploy they can’t be sure of.

validate also runs semantic analysis across your whole project’s type universe — resolving every type reference, variable, method call, and field against your classes, the Salesforce standard library, and your SObject schema. It flags things the parser accepts but the platform rejects at deploy: unknown types, undefined variables (including through the inheritance chain), unknown, wrong-arity, or wrong-argument-type methods and constructors (s.frobnicate(),add(1, 'two') against add(Integer, Integer),new Widget(1, 2) with no matching constructor — on the standard library and on your own classes), calling another class's private method, instance members from static context (and statics through an instance), duplicate fields, methods, and variables (including block-scope and parameter shadowing), constructing an abstract class, extending a non-virtual class, overriding a non-virtual method or omitting the override keyword, unimplemented abstract methods, reassigning a final field, missing returns and unreachable statements, break outside a loop, illegal assignments, returns, and ternaries (Integer x = 'hello';,List<Integer> xs = new List<String>();, assigning avoid call), non-Boolean conditions, catching or throwing non-exceptions, DML on non-records, iterating non-collections (and loop variables that can't hold the element type), impossible casts and always-false instanceof, incompatible comparisons, ! and ++ on non-numeric types, interface conformance (implementing every interface method — and notimplements-ing a class, or the same interface twice),switch rules (non-switchable expression types, duplicate and type-mismatched when values), SOQL bind variables and unknown columns, source-absent unnamespaced custom SObjects (checked-in SFDX and stubs metadata is authoritative), typed SObject field assignments, integer-only SOQL LIMIT/OFFSET binds, and unknown SOSL return fields,Datetime-to-Date narrowing, this()/super()constructor chaining, private field access across classes, protected members and@isTest methods in the wrong kind of class, abstract methods with bodies, access modifiers on interface methods, @future and@InvocableMethod shape rules, test-setup and web-exposure annotation contracts (@AuraEnabled, @RemoteAction, REST, andwebservice), illegal class, constructor, field, and method modifiers, annotation placement and context rules for @testSetup,@ReadOnly, and HTTP methods, REST URL mappings and per-verb method cardinality, property, nested-class, interface-method, and enum modifiers, circular self-inheritance, constructor-chain placement, generic type arity, inner-class nesting and static rules, abstract/static modifier combinations, catch ordering, property accessor visibility, global members in non-global classes, duplicate and unknown enum values, duplicate declaration scopes, protected/static field combinations, nested override visibility and return types, class-qualified instance calls, generic array shapes,@InvocableVariable field contracts, annotation property names,@SuppressWarnings arguments, duplicate and illegally modified method parameters, interface return and visibility contracts, classes extending interfaces, instance-initializer returns, construction of the built-in Exception, conflicting sharing modes, @AuraEnabled enums, private@RemoteAction methods, @TestVisible parameters, and unknown fields on your classes and SObjects. Method and conversion rules run against a catalog generated from the platform compiler's own symbol table and are verified against real check-only deploys — quirks likeDatabase.insert(records, false), ''.isBlank(), variables that shadow type names, methods named like their class, conversion-covariant collections, and keyword-less abstract-method implementations all resolve exactly as the org compiler would.

The current differential corpus catches 233 of 235 org-rejected error classes, each verified against a real check-only deploy, with zero intrinsic false rejects in the deployable-source gate. The two deferred cases both require managed-package context to decide whether an identifier may use @Deprecated.

Resolution is conservative by design: anything it can’t disprove — managed-package namespaces, inherited members, and unsynced field types — resolves rather than flags, so it never reports a deployable file. Every rule is gated on a corpus of thousands of real, deployable open-source classes before release. Findings are deploy blockers by default — like the platform, validate fails on code a check-only deploy would reject. Use --sema=warn to downgrade findings to warnings (e.g. while a stale schema sync is being refreshed), or --sema=off to disable.

nimbus validate                  # Validate all Apex files
nimbus validate MyClass          # Files matching "MyClass"
nimbus validate *Service*        # Files matching "*Service*"
nimbus validate -e __tests__     # Exclude paths containing "__tests__"
nimbus validate --sema=warn      # Downgrade semantic findings to warnings
nimbus validate --json           # Machine-readable JSON output (for editor integration)

Path patterns

nimbus validate force-app/main/default/classes/MyClass.cls   # Specific file
nimbus validate force-app/main/default/classes/               # All files in directory
nimbus validate src/tests/                                    # All files under path

Suppress an individual apiVersion warning with // nimbus:ignore on the same line as the call (or the line directly above). Add a comma-separated rule list to scope to specific rules.

Run from inside a package subdirectory (e.g. after cd’ing intoforce-app/main/default/classes/billing) to auto-scope to that subdirectory instead of the whole project — no pattern argument needed. Same behavior applies to nimbus test.

For CI gates, the standalone apex-version-lint CLI runs the same check against an SFDX project tree and exits non-zero with -strict:

apex-version-lint              # warn-only, exit 0
apex-version-lint -strict      # exit 1 if any diagnostic was emitted
apex-version-lint path/to/src  # walk a specific subtree

nimbus exec

Execute anonymous Apex - like Salesforce's "Execute Anonymous", but locally.

# From a file
nimbus exec script.apex

# Inline expression (auto-wrapped in System.debug)
nimbus exec -c "Calculator.add(1, 2)"
nimbus exec -c "new Account(Name = 'Test').Name"

# Multi-statement inline
nimbus exec -c "Integer x = 5; Integer y = 10; System.debug(x + y);"

nimbus serve Pro

Start a local Salesforce-compatible API server. See the Local Server guide for full documentation.

nimbus serve

nimbus app Pro

Feature overview: local app hosting.

Run a Salesforce Multi-Framework UI bundle (React + Vite app) against the local Nimbus runtime. Replaces sf ui-bundle dev for offline development: no scratch org, no sandbox, no internet required. The dev experience is identical — HMR, source maps, npm run dev all work — but every /services/data/* and /services/apexrest/* call from the React app hits Nimbus's Apex interpreter and embedded Postgres instead of a real org.

What it does:

1. Discovers UI bundles under force-app/**/uiBundles/<name>/ (marker: *.uibundle-meta.xml)
2. Spawns the bundle's dev server (default: npm run dev) — Vite, HMR, source maps, the lot
3. Starts a proxy on 127.0.0.1:4545 (same default as sf ui-bundle dev) that injects window.SFDC_ENV (basePath, accessToken, instanceUrl, apiVersion, userId) into the served HTML
4. Routes the React app's API calls to the embedded Salesforce-compatible API surface (REST sobjects, SOQL query, Apex REST, GraphQL UIAPI with mutations and introspection, UI API REST, Connect API)
5. Opens the browser

# Auto-discover the single bundle in this project and run it
nimbus app

# Pick a specific bundle by name
nimbus app reactRecipes

# Don't spawn vite — connect to one you started yourself
nimbus app reactRecipes --no-spawn

# List every bundle nimbus can see
nimbus app list

# Generate a GraphQL SDL from your local SObject metadata (replaces
# "npm run graphql:schema" which requires a real org)
nimbus app schema > schema.graphql

# Or fetch the same SDL from the live server
curl http://localhost:4545/__nimbus/app/schema > schema.graphql

# Run the bundle's production build (npm run build, no deploy)
nimbus app build reactRecipes

API surface served (full coverage of what Salesforce Multi-Framework production apps reach for):

• OAuth — POST /services/oauth2/token, GET /services/oauth2/userinfo (OIDC identity)
• SObject REST — /services/data/v{ver}/sobjects/<Object> full CRUD; POST /sobjects/ContentVersion handles multipart/form-data file uploads
• SOQL — GET /query?q=...
• SOSL (Search) — GET /search?q=FIND ... RETURNING ..., /parameterizedSearch — translated to per-object SOQL with LIKE clauses across text fields
• GraphQL UIAPI — POST /graphql. Queries: first/after cursor pagination, multi-field orderBy with NULLS FIRST/LAST, full where (eq/ne/lt/lte/gt/gte/like/nlike/in/nin + and/or/not combinators that nest), byId shortcut, child-relationship subqueries via nested edges/node, parent lookups via dotted paths. Aggregates: count, sum(field:), avg(field:), min(field:), max(field:) on every Connection. Pagination: real cursors with pageInfo (hasNextPage, hasPreviousPage, startCursor, endCursor). Directives: @skip, @include, @optional. Variables: resolved from request payload. Mutations: <Object>Create, <Object>Update, <Object>Delete per SObject. Introspection: __schema served from a model built at startup — codegen tools work directly against the running server.
• UI API REST — /ui-api/object-info/<Obj> (describe with picklists + record types + child relationships + defaults), /object-info/<Obj>/picklist-values/<rtId>[/<field>], /records[/<id>] (GET/POST/PATCH/DELETE), /record-defaults/create/<Obj> + /clone/<id>, /list-ui/<Obj> + /list-records/<listId>, /mru-list-ui/<Obj> + /mru-list-records/<Obj>, /related-list-info/<Obj>/<rel> + /related-list-records/<parentId>/<rel>, /layout/<Obj>, /actions/record/<id>, /duplicates/<Obj>
• Composite API — POST /composite (allOrNone with referenceId chaining), POST /composite/batch (independent requests), POST /composite/tree/<Obj> (nested record insert), POST /composite/sobjects (multi-type batch), GET /composite/sobjects/<Obj>?ids=...&fields=... (multi-get)
• Bulk API 2.0 — full lifecycle for /jobs/ingest (POST create → PUT batches CSV → PATCH UploadComplete → GET state + /successfulResults / /failedResults) and /jobs/query (POST → poll → /results). Nimbus processes synchronously on UploadComplete since the runtime is in-process; the polling shape stays faithful.
• Apex Invocable Actions — POST /actions/custom/apex/<ClassName> dispatches to the class's @InvocableMethod via the interpreter
• Apex REST — /services/apexrest/<path> for your @RestResource classes
• Connect / Chatter — /chatter/users/me (sourced from local User SObject if present), /chatter/users/<id>, /chatter/feeds/news/.../feed-elements, /connect/communities, /connect/cms/delivery/channels
• Limits — /limits returns a stub governor-limits envelope so diagnostic UIs render
• Diagnostics — /__nimbus/app/status (JSON), /__nimbus/app/schema (live SDL), /__nimbus/app/dashboard (HTML)
• Everything else falls through to Vite (HMR websocket, @vite/client, source maps, assets)

What's still not covered: sharing rules / FLS enforcement, picklist value dependencies as bitmaps (validFor arrays are empty), per-record-type picklist filtering, JWT / OAuth web-flow authentication, Tooling API, Reports/Dashboards, Wave Analytics, Surveys, Knowledge, TLS / HTTPS, live schema reload on metadata change, and production deploy (build only — deploy goes through sf project deploy). Anything not in the served list returns 501 NOT_IMPLEMENTED with the path so you see exactly what to fill in.

Bundle selection:

• One bundle in the project → used automatically
• Multiple bundles, name passed as argument → that bundle is used
• Multiple bundles, no argument, terminal → interactive numbered picker
• Multiple bundles, no argument, non-TTY (CI) → errors with the bundle list
• --all → every bundle served simultaneously under /lwr/application/<name>/ with an HTML index page at root. Each bundle gets its own vite dev server with output prefixed by bundle name. Use --primary to pick which one opens in the browser by default.

If the bundle has no node_modules/, nimbus fails early with the exact command to run rather than letting vite die with the cryptic sh: vite: command not found. Pass --install to have nimbus run npm install itself. Common vite failure modes (exit 127, EADDRINUSE) are recognised and surfaced with hints during the readiness wait — no more 30-second timeout waiting for a process that's already dead.

Subcommands:

nimbus mcp

Start a Model Context Protocol server over stdio. AI coding agents (Claude Code, Cursor, and any other MCP-compatible client) call Nimbus's local test runner directly through structured tool calls instead of parsing CLI output.

The runner is initialised once at server start (database, project sources) and reused across tool calls. The agent disconnects when stdin closes; the server tears the runner down on exit.

Tools exposed:

• run_apex_tests — run tests by pattern ("*", class name, Class.method, or path). Returns pass/fail counts, failure objects with file/line, and total duration. Optional arguments: timeout_seconds (default 300, 0 disables) caps wall time and surfaces a structured error on overrun; max_failures (default 50, 0 disables) caps the failure list returned to the agent — total_failures always reflects the true count and failures_truncated signals when the cap dropped entries. Each failure now carries a diagnostics object built for one-shot fixing: exception_type, message, the exact assert_file/assert_line, structured expected/actual for assertion failures (is_assertion), and recent_operations — the tail of SOQL queries and DML statements the test ran before it broke.
• get_coverage — per-class line coverage from the most recent run.
• list_test_classes — every @isTest class discovered in the project, returned as {name, file} pairs so the agent can jump straight to the source file. Does not run tests.
• get_governor_usage — per-test governor-limit usage (SOQL queries, DML statements, CPU, heap, …) from the most recent run, plus the peak per limit. Optional class filter. Lets an agent spot a limit that scales with record count — the signature of un-bulkified code — without re-running.
• execute_anonymous — run a block of anonymous Apex (like nimbus exec) in a fresh, rolled-back transaction. Argument: apex. Returns success, captured debug output, and the exception error on failure.
• query — run a read-only SOQL SELECT against the local database and get the records back as JSON plus a row_count. Argument: soql. DML and non-SELECT statements are rejected — use execute_anonymous for writes.
• describe_schema — describe an SObject: its fields (name, type, required, unique, reference_to, relationship_name, picklist values) and child relationships. Argument: sobject (optional — omit to list every SObject the project has schema for). Reads loaded metadata; runs nothing.
• run_mutation_tests (Pro) — run mutation testing and return the mutation score plus surviving mutants (the changes your tests failed to catch). Arguments: pattern, class (mutate one class — recommended), timeout_seconds (per mutant, default 30), survivors_only (default true, returns just the actionable set).
• query_graph — what a change to one class can reach: classes that reference it directly and transitively, what it references, and related tests. Where a coverage map exists, the tests that actually executed it come back separately, plus any that no syntactic path reaches. Argument: class. Returns limits, which agents must read — this is reachability for navigation, not a set of affected tests, and metadata-dispatched callers are invisible to it.
• explain_failure — explain one failure in structured form: exception type, message, source location, assertion operands, and the SOQL/DML tail before it failed, plus what the explanation could not establish. Arguments: test (Class.method), redact (default false). Answers from the previous run when it covered that test, otherwise runs just that test. Returns the same nimbus.explain/v1 payload as nimbus explain --json, so agent and human never diverge.

Operator visibility. The server logs each tool call to stderr in structured form (mcp.run_apex_tests.start, ...complete, ...timeout, ...failed) so you can tail the agent's MCP transport and see exactly what's happening. --verbose raises the log level to debug.

Register with Claude Code:

claude mcp add nimbus -- nimbus mcp

Agentic Resource Discovery. Nimbus publishes an ARD catalog so compatible registries and coding agents can discover this MCP server from task intent. ARD only handles discovery: after selecting Nimbus, the client still installs the local binary and invokes nimbus mcp over stdio.

Stdio safety. Stdout is reserved for JSON-RPC framing. The runner writes nothing to stdout, and the process-global os.Stdout is rerouted to stderr for the server's lifetime so any stray prints elsewhere in the call tree can't corrupt the protocol stream. Use stderr for any out-of-band logging; --verbose is safe.

Recommended skills

MCP exposes the primitives; skills are short playbooks that tell an agent when and how to use them. Install with nimbus skills install — the binary fetches from nimbus-skills and writes to the right path for your agent. Three skills to start:

• fix-failing-apex-test — the inner loop. Read failure → narrow → edit → re-run, until green.
• bootstrap-nimbus — set Nimbus up on a fresh SFDX project, including a CI snippet.
• apex-coverage-uplift — raise coverage by writing targeted tests for uncovered branches.

nimbus skills

Install agent skills from the nimbus-skills repo. Skills are short, opinionated playbooks (one per workflow) that pair with MCP to give your agent both the primitives and the recipes to use them. The binary embeds no skill content — every install fetches from GitHub at runtime, so the skills repo evolves independently of nimbus releases.

Subcommands:

nimbus skills list                    # available + which are installed locally
nimbus skills install fix-failing-apex-test
nimbus skills install all             # install every skill the agent supports
nimbus skills remove fix-failing-apex-test
nimbus skills path                    # print the install dir for the detected agent

Agent detection. Run from your project root and Nimbus picks the right agent automatically:

• .claude/ present → Claude Code, writes to .claude/skills/<name>/SKILL.md
• .cursor/ present → Cursor, writes to .cursor/rules/<name>.mdc
• .aider.conf.yml or CONVENTIONS.md present → Aider, writes a single CONVENTIONS.md bundle
• AGENTS.md or opencode.json present → generic AGENTS.md (also covers OpenCode), writes a single AGENTS.md bundle
• .kiro/ present → Kiro, writes to .kiro/steering/<name>.md with manual-inclusion frontmatter (load via #<name> in your Kiro prompt)
• Nothing matched → defaults to Claude Code (use --global to write to ~/.claude/skills/ instead).

If two markers are present, Nimbus refuses to guess — pass --agent to disambiguate.

Idempotent. Re-running install on a skill whose local copy is byte-identical to upstream is a no-op. If the local copy differs, the install fails until you pass --force — protects hand edits.

nimbus sync

Sync your project's schema (SObject definitions, fields, relationships) into the local database. nimbus test reconciles the schema automatically before every run, so an explicit sync is mainly for warming the database up front or after large metadata changes.

Sync is incremental by default: it creates missing tables and adds missing columns without dropping anything, so a re-sync with no changes is near-instant even on orgs with hundreds of objects. Use --rebuild to force a full drop-and-recreate (the only mode that applies column type changes — it also wipes table data). Use -s to scope work to specific objects while iterating.

nimbus sync                                        # Incremental sync of all objects
nimbus sync -s Account,Contact,Lead                # Sync only these objects
nimbus sync --rebuild                              # Full drop-and-recreate of all tables
nimbus sync -s My_Object__c --rebuild              # Rebuild just one object

nimbus init

Initialize Nimbus for the current project. Creates the .nimbus/ directory and starts the embedded database. Only needs to be run once per project.

# Run from your project root (where sfdx-project.json is)
nimbus init

After init, run nimbus sync -o <org> to populate the schema, then nimbus test.

nimbus new

Scaffold a new Apex class or trigger (and its -meta.xml) into your project's default package — the SFDX main/default/classes (or /triggers) convention. The API version comes from sourceApiVersion in sfdx-project.json.

nimbus new test AccountServiceTest      # @IsTest class with a starter method
nimbus new queueable SyncContactsJob    # Queueable implementation
nimbus new batch NightlyRollup          # Database.Batchable<SObject>
nimbus new trigger AccountTrigger --sobject Account

Kinds: class, test, trigger, triggerhandler, batch, queueable, schedulable.

nimbus fixture

Feature overview: test data.

Generate a TestDataFactory with a create<SObject>() method per object, with required fields pre-filled from the local schema. Standard objects work with zero sync (Nimbus ships their describes); custom objects need a sync. Prints to stdout by default.

nimbus fixture Account Contact          # print a TestDataFactory to stdout
nimbus fixture My_Object__c --write     # save it to the default package

Required lookups are generated, not left as TODOs

When an object has a required lookup, Nimbus follows it: the parent object is added to the factory automatically (even if you did not name it), methods are emitted parents-first so they can actually be inserted in order, and a create<SObject>WithParents() method inserts the parents and wires the child to them.

$ nimbus fixture LoyaltyTransaction__c

    static Account createAccount() { ... }

    static LoyaltyTransaction__c createLoyaltyTransaction__c() {
        return new LoyaltyTransaction__c(
            Points__c = 1,
            Reason__c = 'Purchase'
        );
    }

    // Inserts the required parents, then returns an un-inserted record wired to them.
    static LoyaltyTransaction__c createLoyaltyTransaction__cWithParents() {
        Account parent0 = createAccount();
        insert parent0;
        LoyaltyTransaction__c record = createLoyaltyTransaction__c();
        record.Account__c = parent0.Id;
        return record;
    }

A required lookup to the object's own type has no root to generate from, so it becomes an explicit TODO rather than infinite recursion. Lookup cycles between two objects are reported as a warning instead of being silently broken. A required parent with no local schema also becomes a named TODO (plus a warning to run nimbus sync) — never a call to a create method that was not generated, which would produce a factory that does not compile.

Values the schema vouches for

Picklist fields use a real value from the field's value set, not a placeholder — a restricted picklist rejects anything else, so a fabricated value produces a factory that always fails on insert. When the local schema has no value set, the field is marked unresolved rather than guessed. The generated class is deterministic: the same project always produces the same file, so it diffs cleanly.

nimbus coverage diff

Compare two JSON coverage reports (from nimbus test --coverage-report cov.json) and report the overall coverage delta, per-file regressions and improvements, and the exact lines that went from covered to uncovered. Built for PR coverage gates.

# baseline on main, then the branch:
nimbus test "*" --coverage-report base.json
nimbus test "*" --coverage-report pr.json
nimbus coverage diff base.json pr.json --fail-on-drop

nimbus daemon Pro

The daemon is a long-lived background process that pre-parses your entire codebase, loads flows, record types, custom metadata, labels, and validation rules into memory at startup. Every subsequent test run — CLI or VS Code — connects to the already-warm daemon and starts executing immediately.

On a project with ~1,000 Apex files, cold-start parsing alone takes 10–15 seconds per run. With the daemon running, that startup cost drops to near zero.

See the daemon overview page for a full explanation of how the warm-up works and what stays in memory.

nimbus daemon start          # Start the daemon (detaches to background)
nimbus daemon start --clean  # Start with a fresh database
nimbus daemon status         # Show uptime, files loaded, connection count
nimbus daemon list           # List running daemons across all projects
nimbus daemon stop           # Stop the daemon for the current project
nimbus daemon stop --all     # Stop every running daemon across all projects

Flags

VS Code integration

The VS Code extension starts the daemon automatically when it detects a Pro license. You do not need to run nimbus daemon start manually. The status bar shows a Nimbus indicator — if it shows a slash, run Nimbus: Restart Daemon from the command palette.

Free-tier users can still run tests from the CLI with full coverage and governor limit support. The daemon and live editor integration (inline results, trace viewer, coverage gutters, history) require Pro.

nimbus login

Activate Nimbus on this machine via your browser. No license keys to copy or paste — sign in with the same account you use in the portal and the CLI registers itself.

nimbus login       # Open the browser, sign in, register this machine
nimbus logout      # Deactivate this machine and free up a seat
nimbus whoami      # Show the current account and license tier

Licenses are validated online and cached locally; a 7-day offline grace period is built in for outages and travel.

Headless / CI: set NIMBUS_LICENSE_KEY in the environment instead of running nimbus login. Team plans include a dedicated CI runner license with its own machine pool.

nimbus dev

Launch the interactive Dev UI in your default browser. Provides a visual interface for running tests, viewing coverage, exploring schema, and inspecting traces.

nimbus dev           # Launch Dev UI on default port
nimbus dev --port 9000  # Launch on custom port

nimbus status

Show the current Nimbus status - database state, project info, daemon status, and license info at a glance.

nimbus status

nimbus doctor

Run diagnostic checks on the current Salesforce project. Reports setup problems - missing configuration, no synced schemas, broken database, unknown config keys - with a concrete fix for each issue. Think brew doctor or gh auth status.

nimbus doctor           # Run all checks
nimbus doctor --verbose # Show fix details for all checks, not just failures
nimbus doctor --json    # Output results as JSON

Checks

Exit codes

CI usage

Gate your pipeline on a clean setup before running tests:

nimbus doctor && nimbus test

nimbus orgs

List Salesforce orgs authenticated via SF CLI that Nimbus can use for sync and fallback operations.

nimbus orgs

nimbus schema

Open a visual schema explorer showing synced SObjects, their fields, relationships, and field types. Useful for verifying your local database matches your org metadata.

nimbus schema

nimbus cache

Manage the parsed AST cache. Nimbus caches parsed Apex classes to speed up subsequent test runs.

nimbus cache stats   # Show cache hit rate, size, entry count
nimbus cache clear   # Clear all cached ASTs

nimbus config

Manage Nimbus configuration via the nimbus.properties file.

nimbus config show         # Display current effective configuration
nimbus config init         # Create an example nimbus.properties file
nimbus config properties   # List all available configuration properties

nimbus reset

Reset the .nimbus/ directory for the current project - clears the database, AST cache, and trace files. Useful when things get into a bad state.

nimbus reset

nimbus db

Manage the embedded PostgreSQL database directly.

nimbus db status   # Show database status (running, port, data size)
nimbus db start    # Start the embedded database
nimbus db stop     # Stop the embedded database
nimbus db reset    # Reset the database (equivalent to nimbus reset)

nimbus stub

Scaffold and inspect stubs/ — the directory Nimbus loads before the main source tree so tests can reference managed-package classes that aren't in the project. See also the User Stubs / Managed Packages section.

List existing stubs

nimbus stub list    # Show every .cls under stubs/
nimbus stub path    # Print the absolute stubs/ directory

Scaffold a new stub class

# Minimal stub with an invoke() no-op
nimbus stub add Logger

# Nebula-style stub with specific method signatures
nimbus stub add Logger \
  --method info:void \
  --method error:void \
  --method saveLog:void

# Typed arg lists (emits "public static void info(String arg0)")
nimbus stub add Logger --method 'info(String):void'

# Replace an existing stub
nimbus stub add Logger --method debug:Boolean --force

Each generated class exposes public static Integer callCount and public static List<String> calls so tests can assert on how the stub was exercised. Edit the file freely — it's plain Apex.

Namespace-scoped stubs

Managed-package classes accessed as ns.ClassName (e.g. mp.Logger.info('hi')) need both a simple class name and the ns. prefix to resolve. Nimbus writes namespace stubs to a subdirectory matching the namespace, and the runner registers both lookup keys automatically.

# Either form is accepted — the dot is treated as a namespace prefix
nimbus stub add mp.Logger --method 'info(String):void'
nimbus stub add Logger --namespace mp --method 'info(String):void'

# Writes: stubs/mp/Logger.cls (class body still says "public class Logger")
# Test code can call: mp.Logger.info('hi');

If you prefer to hand-author, just put the file under stubs/<ns>/<Class>.cls. The first-level subdirectory is the namespace; deeper nesting is ignored.

Remove a stub

nimbus stub remove Logger

Auto-generate stubs from project source Pro

nimbus stub auto walks every Apex source file, finds references to classes Nimbus can't resolve (managed packages, missing project files), and writes one .cls per class — methods, constructors, and fields scaffolded from how your code actually uses them. Return types are inferred from assignment LHS, return statements, casts, logical operators (Boolean), and string concatenation (String). Generic type arguments (List<MyType>) are preserved.

# Preview what would be written
nimbus stub auto --dry-run

# Generate (skips existing files; safe to re-run)
nimbus stub auto

# Re-run after adding new project usage
nimbus stub auto --merge        # appends new methods, preserves hand edits
nimbus stub auto --force        # full rewrite (discards hand edits)

Or fold it into the test loop:

nimbus test --write-stubs                       # generates after a green run
nimbus test --write-stubs --write-stubs-merge   # appends to existing stubs
nimbus test --write-stubs --write-stubs-force   # rewrites existing stubs

Layout. Auto-stub writes one file per class under the namespace folder — stubs/Nebula/Logger.cls with public class Logger { ... }. The stub loader registers both Logger and Nebula.Logger as aliases, so test code can call Nebula.Logger.info() the same way it would against the installed package. The hand-written nested-class convention (stubs/Nebula/Nebula.cls with Logger as an inner class) is equally valid; both resolve identically at runtime.

What's not inferred. Parameter names aren't carried by call sites — generated stubs use arg0, arg1. Method bodies are an audit-friendly default: callCount++ and calls.add('methodName'), returning a type-default. Hand-edit either after generation; --merge on subsequent runs leaves your edits alone.

See the User Stubs page for the full workflow including dual-layout details.

nimbus upgrade

Check for a newer version of nimbus and upgrade the binary in-place.

nimbus upgrade          # Download and install the latest version
nimbus upgrade --force  # Re-install even if already on the latest version

Nimbus also prints a one-line notice after every command when a newer version is available. Set NIMBUS_NO_UPDATE_CHECK=1 to disable this check.

nimbus lsp

Start the Nimbus Language Server on stdio. Any editor that speaks LSP — VSCode, JetBrains IDEs, Neovim, Zed, Helix, Emacs — can launch this command to get Apex completion, hover, go-to-definition, inline coverage hints, mutation-score annotations, and live SOQL-column validation, all backed by the same parser, schema cache, and test data that powers nimbus test.

See the Language Server section for per-editor setup and a full capability list. This page covers only the CLI entry point.

nimbus lsp                           # Start on stdio (what editors launch)
nimbus lsp --log /tmp/nimbus-lsp.log # Write a protocol trace to a file
nimbus lsp --stdio                   # Accepted for client compatibility (stdio is the default)

The server reads JSON-RPC 2.0 messages with Content-Length framing from stdin and writes responses to stdout. Never invoke this directly in an interactive shell — there is no TUI, just protocol bytes.

nimbus dap

Start a Debug Adapter Protocol server on stdio. Any editor that speaks DAP — VSCode, Neovim DAP, IntelliJ DAP — can launch this command to step through Apex tests with real breakpoints, a call stack view, and expandable local-variable inspection.

nimbus dap   # Editors launch this; don't run in a shell

Supported DAP requests: initialize, launch, setBreakpoints, configurationDone, threads, stackTrace, scopes, variables, continue, next, stepIn, stepOut, stepBack, reverseContinue, disconnect, terminate. Emits initialized, stopped, thread, output, and terminated events.

Launch arguments (set in .vscode/launch.json or equivalent):

Trace replay (time-travel)

Replay mode steps through a recorded test run instead of executing anything. Record once with tracing on, then scrub through the captured execution — forwards and backwards — with the same breakpoints, call stack, and variable panels as a live session. Because nothing re-runs, a replay session is instant and perfectly deterministic.

First, record a trace at verbose (or higher) so statement-level steps are captured:

nimbus test "CalculatorTest.*" --trace --trace-level verbose

Then point a DAP launch config at it:

{
  "type": "nimbus",
  "request": "launch",
  "name": "Replay last trace",
  "mode": "replay",
  "traceFile": ".nimbus/traces/2026-07-03T02-11-09_da70fda6/trace.jsonl"
}

In replay mode the debugger advertises supportsStepBack, so stepBack and reverseContinue walk the timeline in reverse; breakpoints stop the cursor at the next matchingfile:line. next, stepIn, and stepOut each advance one recorded step (the trace is line-granular). Variable values come straight from the trace, so fidelity depends on the level you recorded at — verbose captures locals; a trace recorded below verbose has no steppable events and replay returns a clear error asking you to re-record.

nimbus mutate Pro

Run mutation testing against your Apex code. Nimbus introduces small changes (mutations) to your production code - flipping operators, negating conditions, changing return values - then runs your tests against each mutant. If your tests catch the change, the mutant is "killed." If all tests still pass, the mutant "survived," revealing a gap in your test suite.

This is a technique widely used in Java (PITest), JavaScript (Stryker), C# (Stryker.NET), and Python (mutmut) - but has never been possible for Apex because org-based test execution is too slow. Nimbus runs tests locally in milliseconds, making hundreds of mutations feasible in seconds.

The positional pattern selects which production classes to mutate. If it resolves only to test classes (e.g. AccountServiceTest), Nimbus mutates the class under test instead — derived by stripping conventional Test prefixes/suffixes — and runs that test class against each mutant. This makes nimbus mutate AccountServiceTest answer the natural question: "is this test suite actually any good?"

# Mutate all production classes, run all tests
nimbus mutate

# Mutate a specific class
nimbus mutate AccountService

# Pass a test class — Nimbus mutates the class under test and runs that test
nimbus mutate AccountServiceTest

# Mutate a class, only run specific tests per mutant
nimbus mutate --class AccountService --test AccountServiceTest

# Increase per-mutant timeout to 60 seconds
nimbus mutate --timeout 60

# Only print surviving mutants during the run (kills suppressed)
nimbus mutate --survivors-only

# Fail the run (exit code 1) if mutation score is below 80%
nimbus mutate --min-score 80

# Emit a machine-readable JSON report for CI (exit code still set by --min-score)
nimbus mutate --json --min-score 80

Mutation Types

Flags

Understanding the Score

The mutation score = killed mutants / total mutants × 100%. A project with 95% line coverage but 40% mutation score has tests that execute code without verifying behavior. Think of it as the difference between "I walked through every room" and "I checked every room for problems."

nimbus explain

Feature overview: failure intelligence.

Explain one test's outcome in full: the exception, the source location, the assertion's expected and actual values, and the SOQL and DML executed just before it failed.nimbus test output stays terse - this is the explicit expansion, so nothing about a normal run changes.

# Explain a specific failure
nimbus explain AccountServiceTest.testInsertAccount

# Structured output for scripts and agents
nimbus explain AccountServiceTest.testInsertAccount --json

# Mask runtime values before pasting into an issue or chat
nimbus explain AccountServiceTest.testInsertAccount --redact

# What does this command keep, and where?
nimbus explain --retention-policy

What it prints

ZZDiagFailTest.assertionFailsWithOperationTail — FAILED (8ms)

  System.AssertException
  Assertion failed: expected 999, got 1. diagnostics fixture: expected 999 accounts

  at force-app/main/default/classes/ZZDiagFailTest.cls:23

  Assertion
    expected  999
    actual    1

  Last operations before the failure (most recent last)
    dml   insert Account  (1 row)  ZZDiagFailTest.cls:18
    soql  SELECT Id, Name FROM Account WHERE Name = 'Diagnostics Fixture Co'  ZZDiagFailTest.cls:20

  Not established by this explanation
    - Explanation is derived from local execution only; the org remains the final authority.
    - Record-level mutation provenance is not recorded.
    - No comparison against a previous passing run is available.

Last passed

When history holds a run in which the test passed, the report says when — and whether the Apex source has changed since. An unchanged fingerprint means the code is not what differs, which separates a regression from non-determinism. It does not close the question: test data, ordering, time, configuration and org metadata all sit outside the fingerprint, and the report says so.

It states what it does not know

Every explanation ends with what it could not establish. Nimbus runs Apex locally at high fidelity, but it is not the Salesforce platform: an absent record in the evidence means "not observed", not "did not happen". The report says so rather than letting you assume otherwise - and it names the boundaries of the feature itself, so an empty operation tail is never mistaken for a test that ran no queries.

Flags

Retention and redaction

Explanations are computed in-process and are not written to disk, cached, or uploaded. Operands and SOQL text are shown verbatim by default, because the local developer already has that data in front of them. Use --redact for output that leaves the machine; it deliberately over-masks, keeping structure (object, fields, exception type, location) so a redacted report stays diagnosable.

Same contract for agents

The MCP tool explain_failure returns the same versioned payload, built from the same code path, so a human and an agent never read divergent accounts of one failure. It answers from the previous run when possible and otherwise runs just that test.

nimbus triage

Run tests and group the failures by the cause the engine recorded when each one happened. Built for the first run on an unfamiliar codebase, where the output is a wall of failures and the question is "how many distinct problems is this, really?"

# Triage the whole suite
nimbus triage

# Triage one class
nimbus triage "AccountTest.*"

# Structured output (schema: nimbus.triage/v1)
nimbus triage --json

# Show at most 3 tests per group
nimbus triage --limit 3

What it prints

Triage — 133 failed of 2357 tests (*)

  Grouped by engine-assigned cause

    assertion.failed             93 test(s)
      An assertion in the test did not hold

    loaddata.resource-not-found  2 test(s)
      Test.loadData referenced a static resource the project does not contain
      fix: Retrieve the static resource, or check the resource name passed to Test.loadData.

  No cause recorded (40) — listed individually, not grouped
    ACCT_IndividualAccounts_TEST.testOwnerLastNameUpdate — Invalid field Owner for Account

  Run-level evidence (2) — not attributed to any failure
    Apex Classes             ABadClass

It is not a classifier

Every group corresponds to a cause some part of the engine assigned at the moment of failure — a Test.loadData resource that was absent, a @testSetup that threw, a field the schema provider looked up and did not find. Nothing inspects message text to decide where a failure belongs.

Failures the engine could not classify are listed individually, never folded into whichever group looks plausible. A null-pointer exception is a symptom whose cause could be a missing stub, an unpopulated field, or a genuine bug — no pattern match can tell those apart, and a wrong grouping sends you to fix the wrong thing while hiding the failure inside a count.

Run-level evidence

Missing metadata is reported separately and deliberately not attributed to individual failures. Nimbus degrades an absent definition to null or zero rows instead of throwing, so the failure surfaces later, somewhere that no longer knows a schema gap caused it. The gap is real and worth fixing; which test it broke is not something the engine can honestly claim.

Flags

Suite health in doctor

nimbus doctor --suite runs the same triage and appends a ranked "fix in this order" list to doctor's setup checks - largest cause first, so a red suite becomes a short ordered worklist instead of a wall of failures. It is opt-in because it runs the tests; plain nimbus doctor stays fast enough for a pre-flight check. With --json the report appears undersuite_health.

nimbus history

Browse past test runs in an interactive TUI. Every nimbus test run is recorded under .nimbus/history/; this command reads it back — recent runs, their pass/fail breakdowns, and a flaky-test report. Free.

# Browse recent test runs
nimbus history

# Flaky report: same test, same conditions, different outcome
nimbus history --flaky

# Show the last 50 runs
nimbus history --limit 50

Piped output is JSON

When stdout is not a terminal — a pipe, a CI runner — nimbus history skips the TUI and emits the run list as JSON, so nimbus history --limit 50 | jq works without a TTY.

Flags

History also powers nimbus explain's "last passed" comparison and the trend views in traces & analytics.

nimbus graph

Feature overview: dependency graph.

Show which classes reference a class — directly and transitively — and which tests relate to it. A navigation aid for "what does changing this touch?"

nimbus graph                     # project overview: size, cycles, most-depended-upon
nimbus graph AccountService      # what reaches one class
nimbus graph AccountService --json

Bare nimbus graph prints the orientation view: how many classes, triggers and edges, the cycle count, and the most-depended-upon classes — the step before you know which class to ask about. With --json it emits the full nimbus.graph/v1 payload instead.

It is not a test-selection decision

This reads syntactic references. We measured that reading against real coverage across five projects and found it unsafe for choosing which tests to skip: a trigger dispatching through custom metadata reaches its handler with no reference to follow, so on one real project it found 1 of the 46 test classes that genuinely exercise a handler. The command says so, and refuses to present itself as a selection tool.

Measured alongside, not merged

When a coverage map exists, the tests that actually executed the class are shown as a separate answer, along with any that no syntactic path reaches — a direct measurement of the gap:

ACCT_IndividualAccounts_TDTM — reachability

  Tests reached syntactically (1)
      ACCT_IndividualAccounts_TEST

  Tests a coverage run actually observed executing it (46)
      ACCT_AdministrativeNameRefresh_TEST
      ...

  Observed but NOT reachable syntactically (45) — the blind spot, measured

  Not established by this view
    - Syntactic references only. A trigger dispatching through custom metadata
      reaches handlers with no reference to follow.
    - This is reachability, not a test-selection decision.

The two are deliberately not combined into one number. Where they disagree, the disagreement is the useful part.

Circular dependencies

nimbus graph --cycles lists every circular dependency, largest first, with a shortest loop through each — so the output says where to cut rather than only that a cycle exists.

$ nimbus graph --cycles

    8 classes: Advancement_Adapter, Advancement_Info, TDTM_Config, ...
      shortest loop: Advancement_Adapter → Advancement_Info → Advancement_Adapter
      cut any one edge on that loop to break it

Classes that reference themselves are counted separately rather than listed: in Apex that is nearly always a class qualifying its own statics or an inner class, and printing dozens of them buries the finding that matters. Reported cycles are a lower bound — edges invisible to a syntactic reading may close further loops.

Export and visualise

--format dot|mermaid|json exports the graph. Edges only a coverage run revealed are drawn dashed, triggers get a distinct shape, and the limits travel inside the file as comments — an exported diagram outlives the session that explained it. Past 300 nodes the export refuses and tells you how to narrow, rather than emitting an unreadable hairball.

nimbus graph --format dot | dot -Tsvg -o graph.svg
nimbus graph AccountService --depth 2 --format mermaid

# Raw Mermaid is not meant to be read in a terminal. Write a .md instead and
# open it — VS Code's preview, GitHub and Obsidian all render the diagram.
nimbus graph AccountService --out graph.md

With --out, a .md path wraps the diagram in a Markdown document: a fenced Mermaid block that renders natively, the cycles listed underneath, and the limits as prose rather than as comments — a comment is invisible once rendered, which is exactly when someone is most likely to read the picture as complete.

An interactive view is available in the Dev UI, VS Code (Nimbus: Show Dependency Graph) and IntelliJ, all rendering the same nimbus.graph/v1 payload. It reads like a note-graph tool: hovering a class highlights its direct neighbourhood and fades the rest, clicking pins the highlight, and search filters by name. Test classes and unconnected nodes can be hidden, the layout forces are adjustable, and nodes can be dragged. Labels appear on hubs first and fade in as you zoom. In VS Code, double-clicking a node opens the file.

Flags

nimbus bench Pro

Run a test method N times and report timing statistics: mean, median, p95, p99, min, max. Useful for catching slow SOQL, comparing performance before and after refactors, and setting performance budgets in CI.

While the benchmark runs, a live progress view updates with rolling stats after each sample. Press q to stop early and show results from completed runs.

# Benchmark a test method (100 runs, warmup enabled by default)
nimbus bench AccountServiceTest.testInsertAccount

# 50 runs, no warmup
nimbus bench AccountServiceTest.testInsertAccount --runs 50 --warmup=false

# JSON output - pipe to jq for CI integration
nimbus bench AccountServiceTest.testQuery --format json

# CSV output - one row per sample
nimbus bench AccountServiceTest.testQuery --format csv > results.csv

CI integration

JSON output pipes cleanly to jq. Fail your pipeline if p95 exceeds a threshold:

nimbus bench AccountServiceTest.testQuery --runs 50 --format json \
  | jq 'if .p95_ms > 100 then error("p95 exceeded 100ms") else . end'

Flags

Bench history

After each run, results are appended to .nimbus/bench-history.jsonl - one JSON line per benchmark with timestamp, method, and all timing stats. Use this file to track performance trends over time in external tooling.

Configuration

Global Flags

These flags work with every command:

Database Options

By default, Nimbus uses an embedded PostgreSQL instance in .nimbus/db/. For CI/CD or advanced setups, you can point at an external database.

External database

# Use a Neon, RDS, or any managed Postgres
nimbus test --db-url "postgresql://user:pass@host:5432/mydb"

CI with external DB

# In CI: use a service container or Neon ephemeral branch
nimbus test --db-url "$NIMBUS_DB_URL" --coverage --coverage-output json

Platform Fidelity Mode

Nimbus runs a compat validator pass against every program it loads. Inner-class restrictions, missing master-detail parents, exhausted governor limits, and similar rules surface as diagnostics tagged with a compat rule ID.

nimbus.compat.mode decides how diagnostics surface.

# nimbus.properties
nimbus.compat.mode=strict

# Relaxed for day-to-day dev, strict in CI:
%dev.nimbus.compat.mode=warn
%ci.nimbus.compat.mode=strict

Governor Limits

Nimbus enforces Salesforce governor limits during execution and exposes them through the Apex Limits class. nimbus.governor.modecontrols how a limit breach is handled.

Limits follow the platform by execution context. Synchronous code gets 100 SOQL queries; asynchronous code (Queueable, @future, Batch) gets 200. CPU time and heap likewise rise in async contexts. Both enforcement and the Limits class observe the context-appropriate value.

Orgs with Salesforce-raised limits can raise the ceilings to match. An explicit override is authoritative and applies in every context — it drives both enforcement and the Limits.getLimitQueries() / Limits.getLimitDmlStatements() return values. Leave a key unset to keep the context-aware platform default.

# nimbus.properties — match an org with Salesforce-raised limits
nimbus.governor.mode=strict
nimbus.governor.soql-queries=300
nimbus.governor.dml-statements=300

Parallel Isolation

Every test runs inside its own Postgres transaction that rolls back at the end, so per-test state is always clean. When running in parallel, however, all workers share the same public schema by default and can hit row-level lock contention on hot tables.

Opt in to per-worker-schema to give each parallel worker its own cloned schema. On setup Nimbus replicates every public table (structure + seed rows) into a worker_N schema; every worker pins its transactions’ search_path there so row writes, locks, and visibility are physically confined per worker.

# nimbus.properties
nimbus.test.isolation=per-worker-schema

# Typical pattern: shared locally for speed, isolated in CI for safety
%ci.nimbus.test.isolation=per-worker-schema

Org Simulation

Nimbus simulates the running org via UserInfo and the singleton Organization SOQL row. These values default to en_US / USD / Developer Edition / not-sandbox, which works for most tests. When your code branches on locale, currency, sandbox flag, or org features (Multi-Currency, Person Accounts), set the matching key in nimbus.properties or pass the equivalent CLI flag.

# nimbus.properties
nimbus.org.currency=EUR
nimbus.org.locale=de_DE
nimbus.org.sandbox=true
nimbus.org.features=MultiCurrency
nimbus.org.faketime=2030-01-15T12:00:00Z

Equivalent CLI flags on nimbus test override the config file when both are set: --sandbox, --feature MultiCurrency,PersonAccounts, --faketime 2030-01-15T12:00:00Z.

Permission Seam Visibility

Nimbus runs tests as a sysadmin-equivalent default user. Outside System.runAs(), FLS checks return true, WITH SECURITY_ENFORCED passes through, and $Permission.X / FeatureManagement.checkPermission() resolve against the default mock user (005000000000000AAA). This is faithful to Salesforce's "tests run as the configured user" model — but it creates a silent divergence: a test can pass under Nimbus and fail in a real org when the org's running user isn't assigned the perm.

Permission seams make every such case visible per-test. When a passing test consulted a permission outside a runAs block, the runner records a seam: the kind of check (FLS, object perm, SOQL user-mode, custom permission), the subject, and how it resolved (default-allow for FLS/object/SOQL; default-mock-user for custom perms granted via seeded nimbus.mock.permission-sets or test-inserted PSAs). Custom-permission seams use a distinct CUSTOM PERM prefix because they look like business logic, not security, in the test code — the most damaging variant of the divergence.

By default the runner shows a single end-of-run summary line with totals. --show-permission-seams expands it to a per-test list. --strict-permissions fails any test whose passing path consulted a permission outside runAs — opt-in for CI users who want to enforce the discipline.

# Default summary (no flags) — single line under the test summary block:
# Permission seams: 12 tests consulted permissions outside System.runAs()
#   8 custom permission checks ($Permission / FeatureManagement.checkPermission)
#   4 FLS / object / SOQL user-mode checks

# Per-test detail:
nimbus test --show-permission-seams

# CI gate — fail tests with seams:
nimbus test --strict-permissions

# nimbus.properties (committable, profile-aware):
nimbus.test.permission-seams.show=true
%ci.nimbus.test.permission-seams.strict=true

Tests that explicitly use System.runAs() produce zero seams — the test author opted in to an explicit identity, so any divergence is by design. The fix when strict mode flags a test is to wrap the assertion in System.runAs(user) where user has the required PSA.

Under --json, a run that crossed at least one seam adds a top-level permission_seams block — { total, customPermission, flsObject, seams: [{ kind, subject, path, file?, line?, custom }] } — so agents and the release gate can read the divergence without scraping human output. It is omitted entirely on a clean run (zero seams). This is the block a release profile's permissionSeamPolicy reads to block a release that passed only through the default-allow path.

Read-only Mode

Refuse any DML inside tests via --readonly. Useful for CI stages that should only observe — e.g. post-merge sanity checks that re-run the suite against frozen data. When enabled, any insert, update, delete, orupsert statement inside a test throws System.DmlException with a diagnostic message.

# nimbus.properties
nimbus.test.readonly=true

# Or per-profile:
%ci.nimbus.test.readonly=true

# Or as a one-off CLI flag:
# nimbus test --readonly

Setup-time DML (seeding profiles, list views, custom setting records) still succeeds — only DML inside an @IsTest method is rejected.

CI/CD Integration

Nimbus runs without a Salesforce org, which means your CI pipeline has no JWT certificates, no DevHub dependency, and no scratch org pool to exhaust. Install the binary, run tests, collect output. See the CI/CD guide for full GitHub Actions, GitLab CI, SonarQube, and Codecov examples.

CI requires Pro Pro

Running nimbus test in a CI environment requires a Pro license. The Free tier is for local development only. Nimbus auto-detects GitHub Actions, GitLab CI, CircleCI, Travis, Jenkins, Buildkite, Azure Pipelines, Bitbucket, Drone, TeamCity, CodeBuild, AppVeyor, Semaphore, and any environment that sets CI=true.

Set NIMBUS_LICENSE_KEY as a secret in your CI platform. AI coding agents (Claude Code, Cursor, Aider, Codex, Continue) are detected and allowed to run Nimbus locally on the Free tier even if CI env vars leak through.

Sessions authenticated via NIMBUS_LICENSE_KEY register a machine on your license, just like nimbus login does. CI usage registers a single machine per CI provider (named CI — GitHub Actions etc.) no matter how many runners execute; an AI agent driving a local CLI registers that actual machine. Both appear in your portal and can be deactivated there.

After a Pro license validates, Nimbus records one privacy-minimal headless activation per license fingerprint, CI provider, and installation source. Repeated pipeline runs do not create additional activation rows. No license key, repository, branch, workflow, command arguments, or project content is sent. Set NIMBUS_TELEMETRY=false (or NIMBUS_NO_TRACKING=1) to disable it.

Pull requests from forks: GitHub does not expose repository secrets to pull_request runs that originate from a fork, so NIMBUS_LICENSE_KEY is empty there and the run fails with Set NIMBUS_LICENSE_KEY. Add a preflight step (shown below) so this surfaces clearly, and run tests on push or restrict the job to same-repo PRs.

Salesforce CLI Plugin

Install Nimbus through the Salesforce CLI and run the local runtime under the familiar sf command. The plugin installs the native Nimbus binary automatically on first use, verifies its release checksum, and preserves Nimbus output and exit codes.

sf plugins install @nimbus-solution/nimbus-sf-plugin

sf nimbus login
sf nimbus test "*"
sf nimbus validate --sema error
sf nimbus deploy --target-org staging --source-dir force-app
sf nimbus release validate --release-profile production
sf nimbus exec --code "System.debug(1 + 1);"
sf nimbus mutate AccountService --min-score 80
sf nimbus doctor

The plugin uses the same Nimbus account and ~/.nimbus/license.json as the native CLI. Run sf nimbus login once to activate Pro features on the machine, sf nimbus whoami to inspect the active plan, andsf nimbus logout to deactivate the machine and free its license slot. This login is separate from Salesforce org authentication and survives runtime updates.

Salesforce-style Apex aliases are available when they fit existing CLI muscle memory:

sf nimbus apex run test AccountServiceTest --coverage
sf nimbus apex validate --json
sf nimbus apex run --code "System.debug('local');"

Every native Nimbus flag passes through unchanged. Use sf nimbus installto update the plugin-managed runtime, --version to pin a release, or set NIMBUS_BINARY_PATH to run a development build.

Native nimbus sf is intentionally not mirrored assf nimbus sf: from inside Salesforce CLI, run the desiredsf command directly.

sf nimbus install
sf nimbus install --version 1.7.0
sf nimbus version

GitHub Actions

Minimal working example. Set NIMBUS_PROFILE=ci to activate CI-specific settings from your nimbus.properties file.

name: Apex Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: nimbus-solution/setup-nimbus@v1

      - name: Check license secret
        # Fails clearly if the secret is missing or withheld (fork PR),
        # instead of a confusing "Set NIMBUS_LICENSE_KEY" later.
        env:
          NIMBUS_LICENSE_KEY: ${{ secrets.NIMBUS_LICENSE_KEY }}
        run: |
          if [ -z "$NIMBUS_LICENSE_KEY" ]; then
            echo "::error::NIMBUS_LICENSE_KEY is empty — secret not set or withheld (fork PR)."
            exit 1
          fi

      - name: Run tests
        run: |
          nimbus test \
            --coverage --coverage-report coverage.xml \
            --results-xml results.xml
        env:
          NIMBUS_LICENSE_KEY: ${{ secrets.NIMBUS_LICENSE_KEY }}
          NIMBUS_PROFILE: ci

      - name: Publish test results
        uses: EnricoMi/publish-unit-test-result-action@v2
        if: always()
        with:
          files: results.xml

      - name: Upload coverage to Codecov
        uses: codecov/codecov-action@v4
        with:
          files: coverage.xml
          token: ${{ secrets.CODECOV_TOKEN }}

For GitLab CI, SonarQube integration, external database setup, and caching, see the full CI/CD guide.

Release in CI Pro

The assured release workflow is two commands with a human decision between them, and it is built to run across two separate CI jobs.nimbus release validate runs the local gates and a Salesforce check-only validation, then writes an immutable receipt (.nimbus/releases/<releaseId>.json) and its content-addressed bundle. A later nimbus release deploy deploys that exact receipt — it does not re-validate. It reuses the validated org-side job where Salesforce supports quick-deploy and otherwise re-sends the stored bundle, so the deployed bytes are always the validated bytes.

The split is deliberate: validate and deploy run in different jobs on different runners, so a platform approval can sit between them. The receipt and bundle travel as a pipeline artifact — uploaded after validate, downloaded unchanged into the gated deploy job. The receipt is self-verifying: at deploy time Nimbus checks the org fingerprint, the quick-deploy expiry, the bundle digest, and the toolchain version policy, and fails closed on any drift. That verification is the safety net for the artifact hand-off.

The human gate is your platform's own environment protection — GitHub required reviewers, GitLab manual jobs, an Azure Environment approval check, or a shell prompt. Nimbus's --confirm-production is not that approval; it is the non-interactive acknowledgement that the gate was already passed, needed because a CI runner has no terminal to type the confirmation into.

Ready-to-copy templates for the four major platforms:

• GitHub Actions — a gated environment: production deploy job.
• GitLab CI/CD — a when: manual deploy on a protected environment.
• Azure DevOps — a deployment job to an Environment with an approval check.
• Generic shell — a portable two-phase script for self-hosted runners.

All four read the same ci release profile and pin the Salesforce CLI with nimbus toolchain sf install --version + nimbus toolchain sf status, so the runner provably reproduces the configured toolchain. See therelease-in-CI guidefor the secrets, the profile keys, and the exit-code contract.

Coverage Reports

Feature overview: code coverage.

Nimbus auto-detects the coverage format from the file extension passed to --coverage-report.

Console summary (Free)

nimbus test --coverage

JSON - custom tooling, dashboards (Free)

nimbus test --coverage --coverage-report coverage.json

HTML - visual report, browsable in your browser (Pro)

nimbus test --coverage --coverage-report coverage.html
open coverage.html

XML Outputs Pro

XML formats integrate with SonarQube, Codecov, GitHub quality gates, and CI dashboards. Both flags can be combined in the same run.

Cobertura XML - coverage for SonarQube / Codecov / GitHub Actions

nimbus test --coverage --coverage-report coverage.xml

JUnit XML - test results for CI dashboards and PR annotations

nimbus test --results-xml results.xml

Both together

nimbus test \
  --coverage --coverage-report coverage.xml \
  --results-xml results.xml

References

Salesforce Profiles

Profiles are a legacy Salesforce concept - they define permissions per object and field and are assigned to every user. Unlike most metadata, they are not deployable as discrete records and they live in a separate namespace from permission sets.

Nimbus models Profile as a standard SOQL-queryable object backed by a local database table. A set of standard profiles is always seeded so common test patterns work out of the box:

Profiles in Nimbus are lookup-only. Nimbus does not enforce profile-based object or field permissions (FLS/CRUD). Tests run with full data access regardless of which profile the running user is assigned to. Field-level writeability comes from synced schema metadata (nimbus sync), not from profile assignments.

Running user profile

Every test runs as a mock user (ID 005000000000000AAA). The profile assigned to that user - what UserInfo.getProfileId() resolves to - defaults to Standard User. Override it with nimbus.mock.user-profile.

This matters when your code branches on the running user's profile name, e.g.:

// Example: trigger framework checking profile to decide whether to fire
String profileName = profileMapById.get(UserInfo.getProfileId()).Name;
if (profileName == 'My Profile') { return; }

# nimbus.properties
nimbus.mock.user-profile=My Profile

Project-specific profiles

If your tests query for profiles not in the built-in set, seed them with nimbus.seed.profiles. Comma-separated list of profile names. Seeded profiles get a deterministic ID and are assigned Standard user type with the Salesforce license - sufficient for the vast majority of test patterns.

# nimbus.properties
nimbus.seed.profiles=Field Sales,Partner Community

These profiles are then findable via SOQL:

Profile p = [SELECT Id FROM Profile WHERE Name = 'Field Sales' LIMIT 1];
User u = new User(profileId = p.Id, ...);

Default record types

In Salesforce, records inserted without an explicit RecordTypeId get the running user's profile default. Nimbus defaults to the Master record type. If your org uses custom record types and flows or triggers branch on RecordTypeId, configure per-object defaults:

# nimbus.properties
nimbus.default-record-type.Lead=Applicant_Record_Type
nimbus.default-record-type.Case=Support_Case

List views

Nimbus auto-discovers .listView-meta.xml files from your project and seeds them into the database. For standard object list views that aren't in your repo (Salesforce includes built-in views like "All Leads"), seed them via config:

# nimbus.properties — format: nimbus.seed.list-view.<Object>.<DeveloperName>=<Label>
nimbus.seed.list-view.Lead.AllLeads=All Leads
nimbus.seed.list-view.Lead.MyLeads=My Leads
nimbus.seed.list-view.Case.AllCases=All Cases

Standard reference data

Some standard objects are org-managed reference data that always exists on a real org but isn't carried by nimbus sync(which brings schema, not rows). Nimbus seeds the common ones with their standard out-of-box values so test-setup idioms that read them work without per-repo stubs:

These match a default org. If your org customises the picklist (e.g. custom opportunity stages), the seeded labels may differ from your StageName values — seed the records you need explicitly with nimbus.seed.record (below) to override.

Tabs (Schema.describeTabs())

Schema.describeTabs() returns a single tab set whose tabs are read from your project's *.tab-meta.xml (CustomTab) metadata — source-driven, like the rest of the schema. An object tab resolves its getSobjectName() and label from the object; web/VF/Lightning tabs carry their own label. Code that resolves a tab or icon for an SObject finds it; a project with no tab metadata gets a present-but-empty set.

Named SObject records (list custom settings)

List Custom Settings are accessible in real Salesforce tests as org-level data. In Nimbus, the local database starts empty, so code that reads them via CustomSetting__c.getAll() gets nothing. Seed the records you need with nimbus.seed.record:

# nimbus.properties — format: nimbus.seed.record.<Object>.<Name>=<Field=value,...>
nimbus.seed.record.CountryCodeSetting__c.de=Land__c=Deutschland,Liefergebiete__c=Berlin
nimbus.seed.record.CountryCodeSetting__c.nl=Land__c=Niederlande,Liefergebiete__c=Amsterdam

The Name in the key becomes the record's Name field. Existing records (same name) are skipped, so tests that insert their own records during @testSetup are unaffected.

Sites

Code that queries Site or SiteDetail (e.g. SELECT Id FROM Site WHERE Name = '...') will find no rows unless you seed them via config:

# nimbus.properties — format: nimbus.seed.site.<Name>=<secureUrl>
nimbus.seed.site.My Portal=https://myportal.my.site.com
nimbus.seed.site.Partner Community=https://partners.my.site.com

Each entry inserts a Site row (status Active) and a matching SiteDetail row with the given secure URL. IDs are generated deterministically from the name so they are stable across runs.

Public Groups

Standing Public Groups (regional or team groups like Sales - EMEA or Support Tier 1) are usually created once by an admin and never checked into repo metadata. Code that queries them by name — often user-trigger automation that adds users to groups on country/team change — comes up empty in Nimbus. Seed them via config:

# nimbus.properties — format: nimbus.seed.group.<Name>=<Type>
# Type defaults to "Regular" when omitted
nimbus.seed.group.Sales - EMEA=Regular
nimbus.seed.group.Support Tier 1=Regular

Each entry inserts a Group row with a deterministic 00G-prefix Id from the name. The key is written to both Name and DeveloperName — test factories that look groups up either way (WHERE Name = 'X' or WHERE DeveloperName = 'X') resolve the same row. Idempotent across runs.

Queues

Queues are Group rows with Type='Queue' plus QueueSobject children mapping each queue to the SObjectTypes it routes. Case/lead/custom assignment automation looks them up by DeveloperName and joins through QueueSobject to find owner candidates. Seed both halves in one entry:

# nimbus.properties — format: nimbus.seed.queue.<DeveloperName>=<SObject1>,<SObject2>
nimbus.seed.queue.Lead_Triage_DE=Lead,Case
nimbus.seed.queue.High_Value=Opportunity

Each entry inserts a Group row (Type=Queue) plus a QueueSobject row per listed SObjectType. Empty value still creates the queue Group row without any routing rows.

UserRoles

Role-hierarchy lookups and user-factory routines that assign UserRoleId need rows to exist; UserRole metadata is rarely checked into the repo. Seed by DeveloperName with the human label as the value:

# nimbus.properties — format: nimbus.seed.role.<DeveloperName>=<Name>
# Value defaults to the DeveloperName when omitted
nimbus.seed.role.EMEA_Manager=EMEA Manager
nimbus.seed.role.APAC_Sales=APAC Sales

When at least one role is seeded the built-in CEO mock UserRole steps aside — WHERE DeveloperName = '...' and other clauses run against the real seeded rows. Tests that don't seed any role still receive the mock for backward compatibility.

Networks (Experience Cloud)

Code that gates on a community resolves it by name — [SELECT Id FROM Network WHERE Name = 'Member Hub']. The Network object is org-resident and rarely checked into repo metadata. Seed by Name; the value is the Status (defaults to Live):

# nimbus.properties — format: nimbus.seed.network.<Name>=<Status>
nimbus.seed.network.Member Hub=Live
nimbus.seed.network.Partner Portal=UnderConstruction

Named Users

Factories that look up integration or system users by name — [SELECT Id FROM User WHERE Name = 'System Salesforce'] — need those rows to exist. Seed by the full Name; the value is an optional Username (derived from the Name when omitted):

# nimbus.properties — format: nimbus.seed.user.<Name>=<Username>
nimbus.seed.user.System Salesforce=
nimbus.seed.user.Integration Bot=integ.bot@example.com

The seed Name is split on the first space into FirstName / LastName so the generated Name field reconstructs exactly.

Pulling setup data from the org

Instead of hand-editing seed entries for every Group/Queue/UserRole/Network the tests rely on, run sync with --include-setup-data to populate them from the connected org:

nimbus sync --include-setup-data

The command queries the org for Group, QueueSobject,UserRole, and Network rows and writes the matching nimbus.seed.{group,role,queue,network}.* entries into nimbus.properties under a delimited block. Re-running refreshes the block; hand-authored seed lines outside the block are preserved. Named Users are not bulk-synced — a large org has thousands — so seed them explicitly with nimbus.seed.user.<Name>.

Each object type is pulled independently. If the org can't query one — an org without Experience Cloud has no queryable Network, for example — that type is skipped with a warning and the rest still land. The pull only fails outright when no setup object can be queried at all (usually a bad org alias or no connection).

Pulling permission sets from the org

Most orgs grant object access through permission sets rather than profiles. If your tests build a user, assign a permission set or permission set group, and then query under WITH USER_MODE or inside System.runAs, nimbus needs to know what those grants contain:

nimbus sync --include-permissions

This pulls PermissionSet, their ObjectPermissions and FieldPermissions, and PermissionSetGroup composition into .nimbus/permissions.json, which the test runner seeds before each run. Profile-owned rows are excluded — every profile has a shadow permission set on the platform, and nimbus models profiles separately through their default footprint.

Permission sets defined in your own project metadata always win: local .permissionset-meta.xml files are loaded after the synced data, so the repo stays the source of truth and the sync only fills what isn't checked in.

Without this, a permission set group whose contents nimbus has no record of is treated as unknown rather than empty, and access is left unrestricted — better a missed denial than failing a test that passes in the org. Once permissions are synced, groups are enforced for real.

Custom Label overrides

Some repos ship Custom Labels with placeholder values (PLACEHOLDER,TBD) that admins replace post-deploy with environment-specific IDs — profile Ids, webhook URLs, signing keys. Tests that branch onLabel.X resolve to the repo value in Nimbus and diverge from prod. Override them at runtime:

# nimbus.properties — format: nimbus.seed.label.<FullName>=<value>
nimbus.seed.label.StandardUserProfileId=00e000000000003AAA
nimbus.seed.label.WebhookEndpoint=https://test.example.com/hook

The override wins over any value parsed from .labels-meta.xml files and over language-specific translations. The labels XML parser also tolerates bare <labels> fragments that ship without the <?xml?> header or <CustomLabels> wrapper.

Excluding seed records from specific tests

By default every test receives the seeded records. Use nimbus.seed.record.exclude to opt specific test classes (or individual methods) out of seed injection. When a test matches, getAll() returns only test-inserted records — as if the org has no data for that custom setting type. Useful for selector tests that assert getAll() returns empty.

# nimbus.properties
# Comma-separated ClassName or ClassName.method patterns
nimbus.seed.record.exclude=CountryCodeSettingSelectorTest,OtherTest.specificMethod

Full profile example

# nimbus.properties

# Running user's profile (UserInfo.getProfileId() target)
nimbus.mock.user-profile=My Profile

# Additional profiles your tests query against
nimbus.seed.profiles=Field Sales,Partner Community

# Default record types for inserts without explicit RecordTypeId
nimbus.default-record-type.Lead=Applicant_Record_Type

# Seed list views not in repo metadata
nimbus.seed.list-view.Lead.AllLeads=All Leads

# Seed Site records for SOQL queries on Site/SiteDetail
nimbus.seed.site.My Portal=https://myportal.my.site.com

# Seed list custom setting org data
nimbus.seed.record.CountryCodeSetting__c.de=Land__c=Deutschland,Liefergebiete__c=Berlin

Custom Permissions

Custom permissions are boolean flags that code checks at runtime via FeatureManagement.checkPermission('My_Permission'). They are defined as .customPermission-meta.xml files and granted to users via permission sets (or profiles).

Nimbus loads all .customPermission-meta.xml files from the project automatically. It also parses the <customPermissions> blocks in every .permissionset-meta.xml file and wires up the underlying SetupEntityAccess records. All that remains is assigning the right permission sets to the running test user.

Assigning permission sets to the running user

Use nimbus.mock.permission-sets to specify which permission sets the running user holds. These must be API names matching your .permissionset-meta.xml filenames (without the extension).

# nimbus.properties
nimbus.mock.permission-sets=Inventory_Manager,Support_Agent

With this set, FeatureManagement.checkPermission() returns true for any custom permission granted by those sets:

// In production code:
if (FeatureManagement.checkPermission('Manage_Inventory')) {
    // This branch now executes in tests when Inventory_Manager PS is assigned
}

How it works end-to-end

Nimbus models the full Salesforce permission chain without hitting an org:

1. .customPermission-meta.xml → CustomPermission record seeded in DB
2. .permissionset-meta.xml → PermissionSet record + SetupEntityAccess linking PS → CustomPermission
3. nimbus.mock.permission-sets → PermissionSetAssignment linking running user → PermissionSet
4. FeatureManagement.checkPermission(name) → queries this chain and returns true

Full permissions example

# nimbus.properties

# Running user's profile
nimbus.mock.user-profile=My Profile

# Permission sets assigned to the running user
# API names match .permissionset-meta.xml filenames
nimbus.mock.permission-sets=Inventory_Manager,Support_Agent

# Additional profiles to seed for user creation in tests
nimbus.seed.profiles=Field Sales,Partner Community

Supported Metadata

Nimbus reads metadata directly from your SFDX project directory. No org sync required for most types — just point at your repo and run. This page lists every metadata type Nimbus understands today and what it does with each one.

Code

Automation

Salesforce has been deprecating Process Builder and Workflow Rules in favor of Flow since 2022. We recommend converting them to flows using Salesforce's Migrate to Flow tool. Nimbus support for both is planned but not a priority.

Data & Schema

Security & Access

Configuration

Language Server (LSP)

Overview

Nimbus ships an LSP 3.17 server for Apex. Any editor that speaks the Language Server Protocol — VSCode, JetBrains IDEs, Neovim, Zed, Helix, Emacs — gets the same experience: schema-aware completion, hover documentation, go-to-definition, live SOQL column validation, per-line coverage hints, mutation score annotations, and code lenses that let you run or debug any @IsTest method inline.

Unlike Salesforce's stock Apex Language Server, which makes network round-trips to an org for metadata, Nimbus's LSP runs fully offline against the local .nimbus/schemas/ cache and surfaces platform truth — coverage %, surviving mutants, test flakiness — from your last nimbus test run.

The server is a thin layer over the same parser, schema provider, and test-data infrastructure that powers the CLI. Reparsing a file takes a few milliseconds; diagnostics land before your hand leaves the keyboard.

# Start the server (editors launch this for you)
nimbus lsp

# Debug: write every JSON-RPC message to a log
nimbus lsp --log /tmp/nimbus-lsp.log

Features

The server advertises these LSP capabilities at initialize. Exactly what shows up in your editor depends on the client — VSCode renders everything; leaner clients may render a subset.

Editing intelligence

Navigation & refactoring

Code actions (quick fixes and refactors)

Platform-data overlays (Nimbus-exclusive)

Still on the roadmap: inline values while debugging (blocked on LSP ↔ DAP co-hosting), coverage-filtered call hierarchy, extract- variable / inline-variable / inline-method refactors, and long- tail protocol polish (pull-model diagnostics, completion resolve, cross-workspace monikers). See LSP_ROADMAP.md in the source for the full plan.

VSCode

The Nimbus VSCode extension auto-starts the LSP when the extension activates on a Salesforce project. No extra configuration needed. Toggle it off with the nimbus.lsp.enabled setting if you want to fall back to Salesforce's stock Apex LSP.

// .vscode/settings.json
{
  "nimbus.lsp.enabled": true,      // default
  "nimbus.binaryPath": "nimbus"    // if 'nimbus' is not on PATH, point here
}

Check that the server is running: View → Output, pick Nimbus Apex Language Server from the dropdown. You should see JSON-RPC messages for each keystroke. The Nimbus LSP Trace channel has the protocol-level detail if you need to debug further.

Neovim

Neovim 0.11+ has native LSP support. Drop this into your config:

-- ~/.config/nvim/init.lua (or any loaded file)
vim.lsp.config.nimbus = {
  cmd = { 'nimbus', 'lsp' },
  filetypes = { 'apex', 'apexcode' },
  root_markers = { 'sfdx-project.json' },
  -- Optional: write a protocol trace for debugging
  -- cmd = { 'nimbus', 'lsp', '--log', '/tmp/nimbus-lsp.log' },
}
vim.lsp.enable('nimbus')

-- .cls and .trigger don't have a built-in filetype; teach Neovim:
vim.filetype.add({
  extension = {
    cls = 'apex',
    trigger = 'apex',
  },
})

For older Neovim (0.8–0.10) using nvim-lspconfig:

require('lspconfig.configs').nimbus = {
  default_config = {
    cmd = { 'nimbus', 'lsp' },
    filetypes = { 'apex' },
    root_dir = require('lspconfig.util').root_pattern('sfdx-project.json'),
    settings = {},
  },
}
require('lspconfig').nimbus.setup({})

Zed

Zed uses per-language server configuration in settings.json:

// ~/.config/zed/settings.json
{
  "lsp": {
    "nimbus": {
      "binary": { "path": "nimbus", "arguments": ["lsp"] }
    }
  },
  "languages": {
    "Apex": { "language_servers": ["nimbus"] }
  },
  "file_types": {
    "Apex": ["cls", "trigger"]
  }
}

Helix

Helix wires LSP via languages.toml:

# ~/.config/helix/languages.toml
[language-server.nimbus-lsp]
command = "nimbus"
args = ["lsp"]

[[language]]
name = "apex"
scope = "source.apex"
file-types = ["cls", "trigger"]
roots = ["sfdx-project.json"]
language-servers = ["nimbus-lsp"]

JetBrains (IntelliJ, WebStorm, etc.)

The simplest path is the dedicated Nimbus JetBrains plugin — it wires up the language server, test running, debugging, coverage, and tool windows for you. Install Nimbus — Local Apex Runtime from the Marketplace and you’re done.

If you’d rather wire the language server by hand, JetBrains 2023.2+ supports generic LSP servers via the LSP4IJ plugin (or built-in LSP support in paid editions). After installing LSP4IJ:

1. Settings → Languages & Frameworks → Language Servers → +
2. Name: Nimbus Apex
3. Command: nimbus lsp
4. Mappings: file type *.cls and *.trigger

Code lenses, inlay hints, completion, and hover all render natively in the JetBrains UI. Go-to-definition uses the standard Cmd+B / Ctrl+B shortcut.

Emacs

With lsp-mode:

(use-package lsp-mode
  :hook ((apex-mode . lsp)))

(with-eval-after-load 'lsp-mode
  (lsp-register-client
    (make-lsp-client :new-connection (lsp-stdio-connection '("nimbus" "lsp"))
                     :major-modes '(apex-mode)
                     :server-id 'nimbus-lsp)))

With eglot (built-in since Emacs 29):

(with-eval-after-load 'eglot
  (add-to-list 'eglot-server-programs
               '(apex-mode . ("nimbus" "lsp"))))

Troubleshooting

The server fails to start

• Run nimbus --version in a terminal to confirm the binary is on PATH.
• Start the server manually: nimbus lsp --log /tmp/nimbus-lsp.log. Type a few characters and hit Ctrl+C. The log should show JSON-RPC messages; if the file is empty, the binary isn't being found by the editor.

Diagnostics don't appear

• Check the editor's LSP status — most editors surface a connection indicator. In VSCode, View → Output → Nimbus Apex Language Server.
• Verify the file extension is mapped to apex language. Neovim in particular doesn't auto-detect .cls.

Completion is empty after `a.`

• The LSP needs the variable's declared type. If a is declared in a different file, cross-file type resolution isn't wired yet — declare it locally, or use the fully-qualified class name: Account.Name instead ofa.Name.
• Custom SObjects appear after running nimbus sync once to populate .nimbus/schemas/.

Coverage / mutation inlay hints don't show

• Inlay hints require a recent nimbus test --coverage run so .nimbus/coverage/latest.json exists. Mutation hints need nimbus mutate to have populated .nimbus/mutations/latest.json.
• Some editors hide inlay hints by default — check the "Editor: Inlay Hints" toggle in your settings.

The Salesforce LSP and Nimbus LSP are both running in VSCode

The Salesforce Apex extension and the Nimbus extension can coexist, but you'll get duplicate completion entries. Set nimbus.lsp.enabled: false to fall back to Salesforce's LSP, or disable the Salesforce Apex extension to use only Nimbus.

VSCode Extension

Overview

The Nimbus VSCode extension brings the full test runner into your editor — inline results, coverage gutters, a debugger, execution traces, governor limit tracking, and more. It communicates with the nimbus daemon over a local JSON-RPC connection, so test runs feel instant: no cold-start, no reloading metadata on every run.

The extension also auto-starts the Nimbus Language Server for editing intelligence — completion, hover, go-to-definition, SOQL column validation, and coverage inlay hints. The LSP is a sibling subsystem to the test runner, independent of the daemon socket. Toggle it with nimbus.lsp.enabled in settings.

The extension activates automatically when it detects a Salesforce project (sfdx-project.json, force-app/, or any .cls file). Check the status bar — a Nimbus indicator shows whether the daemon is connected. If it shows a slash through it, run Nimbus: Restart Daemon from the command palette and check the Nimbus output channel for details.

New install? Open Help → Welcome → Get Started with Nimbus for a seven-step walkthrough covering the test runner, watch mode, coverage, the dependency graph, and the sidebar views. Common actions — run tests in file, validate, execute anonymous, dependency graph — are also on the right-click menu in any Apex file, and the dependency graph has a dedicated hierarchy icon in the editor title bar.

The daemon requires a Pro license. Free-tier users can still run tests from the CLI with full coverage and governor limit support, but the live editor integration (inline results, trace viewer, history) requires Pro.

Running Tests

Inline buttons (CodeLens)

Every @isTest class shows action buttons directly above the code — no menus needed.

Test Explorer

Nimbus integrates with VSCode's native Test Explorer. Tests are discovered automatically when the daemon connects — no configuration needed. Run, debug, and filter tests from the standard VSCode testing UI.

Understanding results

After a test run:

• A notification shows the pass/fail summary and total time
• The Nimbus output channel shows results grouped by class and method
• Inline pass/fail decorations appear on executed lines in the editor
• The status bar shows live progress during the run (3/10 tests...)

Debugging

Nimbus supports the full VSCode debug protocol — breakpoints, stepping, variable inspection, call stack.

Debug a test method

1. Open a test class
2. Set breakpoints by clicking the gutter on any line
3. Click Debug Test above an @isTest method
4. Use the debug toolbar: Step Over (F10), Step In (F11), Step Out (Shift+F11), Continue (F5)
5. Inspect locals in the Variables panel; view the call stack in Call Stack

Debug any public method

Not limited to tests. Click Debug above any public method in a non-test class. If the method has parameters, Nimbus prompts you to enter values before starting.

Launch configurations

You can also configure debug targets in .vscode/launch.json:

{
  "type": "nimbus-apex",
  "request": "launch",
  "name": "Debug My Test",
  "test": "MyTestClass.myTestMethod",
  "stopOnEntry": false
}

Coverage

Enable coverage collection by setting nimbus.coverage.enabled to true, or pass --coverage from the CLI. After a test run with coverage enabled:

Gutter icons

Colored icons appear in the editor gutter next to each line:

Toggle gutter icons with the nimbus.coverage.showGutterIcons setting.

Method coverage annotations

An inline annotation appears after each method signature:

public static void processRecords(List<Account> accounts)  // 75% (3/4 lines)

Run Nimbus: Show Coverage from the command palette for the full coverage report in the output channel.

Trace Viewer Pro

The trace viewer shows a detailed execution trace for every method call, branch decision, and variable assignment during a test run. Click View Trace above any test method after running it, or run Nimbus: View Execution Trace from the command palette.

The trace viewer opens as a side panel with three tabs:

Selecting any span in any tab updates the right sidebar with the captured local variables,System.debug() output, and span metadata (source file, line number, status).

Sidebar Views

Click the Nimbus icon in the activity bar to open the dedicated views.

Tools

A launcher at the top of the panel. One click opens the dependency graph, coverage, history trends, execute anonymous, or toggles watch mode — no command palette needed.

Test History

Shows past test runs sorted newest first. Each run shows a pass/fail icon and summary (e.g. 3/3 passed (250ms)). Expand any run to see results by class, then by method.

From the view title bar, Show History Trends opens a chart of pass rate over the last 30 days plus a flaky test table — tests that flip between pass and fail across runs.

Right-click any run and choose Compare With... to open a side-by-side diff of two runs. The diff highlights flipped tests, duration changes, and new or removed methods.

Governor Limits

Shows Salesforce governor limit consumption per test method, updated automatically after each run. Expand any method to see individual limits:

Governor limit annotations also appear inline in the editor as CodeLens above each method. Toggle with the nimbus.governor.showCodeLens setting.

Schema Explorer

Browse the local PostgreSQL schema that Nimbus uses to store SObject data. Expand any table to see columns (name, type, constraints), outgoing foreign keys, and incoming references from other tables. Use the refresh button after importing new metadata.

Watch Mode Pro

Automatically re-run tests whenever Apex files change.

1. Click the Watch: off button in the status bar, or run Nimbus: Toggle Watch Mode
2. If your project has multiple package directories, choose All Packages or a specific package
3. The status bar updates to show the active scope (e.g. Watch: force-app)
4. Save any .cls or .trigger file — tests re-run automatically
5. After each watch-triggered run the status bar briefly shows the result (Watch: all passed or Watch: 2 failed)
6. Click the button again to disable

Diagnostics & Validation

Nimbus validates Apex syntax in real time and surfaces errors in the Problems panel (Cmd+Shift+M).

• On save — when nimbus.validateOnSave is enabled (default: true), every .cls and .trigger file is checked automatically
• Manual — run Nimbus: Validate Current File to check the active file
• Quick fixes — some parse errors offer a lightbulb with suggested fixes (e.g. adding a missing semicolon)

Errors appear as red squiggles in the editor and as entries in the Problems panel.

Execute Anonymous & Run Any Method

Execute Anonymous Apex

Run arbitrary Apex without creating a class. Run Nimbus: Execute Anonymous Apexfrom the command palette. If text is selected, only the selection runs — otherwise the entire file runs. Output (including System.debug()) appears in theNimbus output channel.

Run any public method

Click Run above any public method in a non-test class. If the method has parameters, input boxes appear for each one with type hints. The return value and execution time appear as an inline annotation next to the method signature.

Auto-retrieve missing metadata

When tests fail due to missing SObjects, fields, or other metadata not in your local project, Nimbus detects what's missing and shows a warning notification. Choose:

You can also trigger this manually with Nimbus: Fetch Missing Metadata & Re-run.

Commands

All commands are available from the command palette (Cmd+Shift+P) with the Nimbus: prefix.

Settings

All settings are under the nimbus.* namespace in VSCode settings.

JetBrains Plugin

Feature overview: Nimbus for JetBrains.

The Nimbus plugin brings the full local Apex runtime to IntelliJ IDEA and every other JetBrains IDE — both Community and the paid editions. It shares the same two engines as the VSCode extension: the nimbus lsp language server (completion, hover, navigation, rename, diagnostics, code lenses, inlay hints) and the nimbus daemon JSON-RPC server (test running, debugging, coverage, traces, history, schema, governor limits).

Editor intelligence is delivered through LSP4IJ, which the plugin pulls in automatically from the JetBrains Marketplace.

The plugin also bundles native Apex/SOQL live templates — type an abbreviation and press Tab to expand, then Tab through the placeholders. A few: sysd → System.debug(), tm → an @IsTest method, tc → a test class, soqlf → a bulk-safe SOQL for-loop, bulkt → a 200-record test-data block, mapid → Map<Id, SObject> from a list. The full set lives under Settings → Editor → Live Templates → Nimbus Apex.

Install

Install Nimbus — Local Apex Runtime from Settings → Plugins → Marketplace. The Marketplace resolves the LSP4IJ dependency for you. You also need the nimbus CLI on your PATH:

curl -fsSL https://install.testnimbus.dev | sh

On first open of a Salesforce project the plugin starts the daemon and warms the language server. If the CLI isn’t found, set its location in Settings → Tools → Nimbus.

Running & Debugging

Code lenses appear above @IsTest classes and methods — Run, Debug, Coverage, Trace, Bench, and Mutate. Results stream live into the standard IntelliJ test runner tree, with inline ✔ passed / ✖ failed markers and timings on each test method, return values, and coverage gutter bars in the editor.

The debugger is a native IntelliJ debug session: set line breakpoints in.cls/.trigger files, then Debug a test — step over/into/out, inspect variables and the call stack, all driven by the local runtime (no org, no replay log).

Coverage delta. Run a coverage pass, then Set Coverage Baseline(Nimbus menu) to snapshot it. Toggle Coverage Delta overlays the change vs that baseline in the gutter — green for newly-covered lines, orange for regressions. The same overlay and commands ship in the VSCode extension.

You can also create a Nimbus Apex Test run configuration directly (Run → Edit Configurations) to run a glob pattern or an explicitClass.method list.

Tool Window

The Nimbus tool window (right dock) has six tabs:

• Tests — every discovered @IsTest class → method; double-click to jump to source, or run/debug the selection from the toolbar.
• Coverage — per-class line coverage from the last coverage-enabled run.
• History — past runs → classes → methods, with a Trends chart and run comparison.
• Schema — the local PostgreSQL tables, columns, and PK/FK relationships.
• Releases — validation receipts and the deploy queue for nimbus release workflows.
• Governor — per-method SOQL/DML usage vs. limits from the last run.

A graph button on the tool-window header opens the interactive dependency graph — also available from the Apex editor right-click menu and Nimbus → Show Dependency Graph.

Graph, trace, Trends, and run-diff visualizations open in embedded browser panels (JCEF), the same views shipped in the VSCode extension.

Settings

Settings live under Settings → Tools → Nimbus (stored per project).