AI agents

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.

Namespaced custom labels

Managed packages ship custom labels too, and Apex reads them as Label.npe03.RecurringDonationStageName — the dotted form is the only spelling the platform compiles for a packaged label. Because a retrieved CustomLabels file carries no namespace element, Nimbus puts the namespace in the file name:

stubs/
└── labels/
    ├── CustomLabels.labels-meta.xml   # unnamespaced labels → Label.MyLabel
    ├── npe03.labels-meta.xml          # → Label.npe03.<Name>
    └── npo02.labels-meta.xml          # → Label.npo02.<Name>

The file contents are ordinary CustomLabels metadata — the same XML sf project retrieve writes:

<?xml version="1.0" encoding="UTF-8"?>
<CustomLabels xmlns="http://soap.sforce.com/2006/04/metadata">
    <labels>
        <fullName>RecurringDonationStageName</fullName>
        <language>en_US</language>
        <protected>false</protected>
        <shortDescription>RecurringDonationStageName</shortDescription>
        <value>Pledged</value>
    </labels>
</CustomLabels>

Stub labels only fill gaps: a label the project itself defines always wins the unnamespaced lookup. A label that resolves nowhere still degrades to an empty string with a warning naming the ns.Name it could not find, so adding label stubs never introduces a new hard failure.

Write them by hand, scaffold one with nimbus stub label, or pull an entire package's labels out of an org that has it installed with nimbus stub pull.

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}'

AI agents

Overview

Your agent can write Apex anywhere. Here it can also run it — instantly, locally, with no org — and get evidence back: which tests passed, what each line cost, who wrote every field on every record.

That is the whole difference. Salesforce ships an MCP server for metadata; several tools will read your source. None of them can execute the code. An agent that cannot execute is guessing, and an agent that guesses about Apex guesses about triggers, order of execution, governor limits and null semantics — the four things it is worst at.

nimbus mcp is a Model Context Protocol server over stdio. It starts one runner — database, project sources, schema — and holds it open for the session, so a tool call costs a test run, not a cold start.

What an agent gets that it does not have today:

• Execution. Run the suite, one class, one method, or a block of anonymous Apex. Sub-second on a warm runner.
• Evidence. Not a log to parse — structured failure diagnostics with the assertion's operands, the SOQL/DML tail before the break, and the source around it.
• A recording. When a test fails, Nimbus re-runs it with tracing on. The agent gets a span tree of what actually executed and what each step cost.
• Causality. Every field write of that run, with the layer that made it — Apex, trigger, flow, roll-up, formula, platform default — and the exact frame. Why is this value what it is stops being a guess.
• Safety. Everything is rolled back unless the agent explicitly asks to commit.

Nothing here reaches a Salesforce org. There is no sandbox to refresh, no deploy to wait for, and no shared org for the agent to break.

Setup

The server discovers your project from its working directory, so point cwd at the folder containing sfdx-project.json.

Claude Code — one command, run from the project root:

claude mcp add nimbus -- nimbus mcp

Cursor — .cursor/mcp.json in the project root:

{
  "mcpServers": {
    "nimbus": {
      "command": "nimbus",
      "args": ["mcp"]
    }
  }
}

Any other MCP client — the same shape, with an explicit working directory when the client does not launch the server from your project:

{
  "mcpServers": {
    "nimbus": {
      "command": "nimbus",
      "args": ["mcp", "--parallel", "4"],
      "cwd": "/absolute/path/to/your/salesforce/project"
    }
  }
}

First call. Have the agent call nimbus_capabilities. It returns the tool catalog, the versioned payload schemas, the licence tier, and what this particular server can answer right now — cheaper than discovering the surface by trying tools and reading errors.

Stdio safety. Stdout carries JSON-RPC framing and nothing else. The runner writes to io.Discard, and the process-global stdout is rerouted to stderr for the server's lifetime so a stray print anywhere in the call tree cannot corrupt the stream. Tail stderr to watch the agent work: every tool call logs a structured start/complete line.

Tool catalog

Grouped by what an agent is trying to do. Every payload is bounded — a truncated list always reports the true count alongside — and every payload states what it does not establish, because an agent that reads a filtered result as the whole picture is the failure mode worth engineering against. For the authoritative list at any version, have the agent call nimbus_capabilities.

Run things

Understand a failure

Read the project

Write metadata

Discover

Why scaffold rather than write the XML. The metadata file vocabulary is not the describe vocabulary: a file wants Html, EncryptedText, MultiselectPicklist where a describe answers TEXTAREA, ENCRYPTEDSTRING, MULTIPICKLIST. An agent writing from memory reaches for the describe spelling, the field is created, it deploys, and it behaves wrongly. Every kind scaffold_metadata emits has a round-trip test proving Nimbus can read back what it wrote.

Resources

A tool call is a verb an agent spends a turn on. A resource is a noun it can attach: a stable URI, an unchanging shape, no arguments to get wrong, and cacheable by the client — so re-reading your project's schema costs nothing.

Everything under nimbus:// is read-only and executes nothing: no test run, no Apex, no DML, no files written. That is what makes them safe to fetch speculatively, and it is why neither a safety cap nor read-only mode ever refuses one. An agent that has spent its entire budget can still read every resource below.

The two templated URIs are RFC 6570 resource templates, and each one's list endpoint enumerates its members — so an agent never has to guess a valid substitution. Every payload is bounded and publishes the true count beside a possibly-truncated list.

An empty answer always says why. Read nimbus://coverage before anything has run and you get available: false with a reason, not a zero-percent report. An empty payload that reads like a real measurement is the one wrong answer an agent acts on with total confidence.

No subscriptions. Nimbus does not advertise resources/subscribe. Coverage does change after a run, so a subscription would be genuinely useful — but the transport cannot service one, and advertising a capability that answers method-not-found is worse than not having it. Each payload states the staleness instead: coverage is the last run's, and re-reading after a run is how you get the new one.

The agent loop

The tools are shaped for one sequence, and it is worth putting in your agent's instructions:

run_apex_tests { "pattern": "AccountServiceTest" }
  -> 2 failed; each failure carries trace_run_id

get_test_failure { "test": "AccountServiceTest.testInsert" }
  -> the assertion, its operands, the SOQL/DML tail, the source lines

  ... edit the class ...

run_apex_tests { "pattern": "AccountServiceTest.testInsert" }
  -> green

When the failure is not obvious from the assertion, the evidence chain goes one level deeper:

get_execution_trace { "run_id": "<from the failure>",
                      "test": "AccountServiceTest.testInsert",
                      "kinds": ["soql", "dml", "trigger"] }
  -> what actually ran, in order, and what each step cost

query_field_history { "run_id": "<the same>", "field": "Account.Rating" }
  -> Rating was "" -> "Hot", written by AccountTrigger.beforeInsert:7

On an unfamiliar codebase where the first run returns hundreds of failures, start with triage_failures instead. Grouping a wall of messages is exactly the task a model does confidently and wrongly; the engine already recorded the cause of each one.

Start narrow. Every payload reports the true count of what it capped, so an agent can always widen deliberately. The defaults are chosen so a first call is cheap.

Writes and rollback

An agent is allowed to execute arbitrary Apex here because by default it can observe anything and change nothing.

execute_anonymous and run_method run inside an isolating transaction that is discarded the moment the call finishes. Every response carries a committed field saying which happened, so the agent never has to infer it. Passing commit: true is a separate, explicit act, and the response's limits then say the writes are still there.

Two boundaries worth knowing, both stated in the payloads themselves:

• The isolating transaction defers constraint checks, so an insert that would violate a unique or foreign-key constraint on commit reports success under rollback.
• Seed data is committed deliberately, before the transaction opens. Rollback never reverts seeding.

Test runs are unaffected either way: each test already runs in its own transaction and is rolled back after.

scaffold_metadata is the one tool that writes to your source tree. It refuses to overwrite an existing file unless asked, refuses to write outside the project root, and dry_run: true reports what it would create without creating it.

Safety caps

An MCP session hands an autonomous agent a warm runner and no natural stopping point. A loop that re-runs the suite after every edit, or retries a failing block with a slightly different guess, costs the agent nothing it can feel — so nothing stops it. These are the ceilings that make an unattended session bounded.

All of them are off by default. An interactive developer should never meet a limit they did not set. Turn them on where a session is unattended or shared.

A refusal always names itself. Exceeding a cap is a tool error stating which cap, what it was set to, how much was used, and the exact property that set it. Nothing stalls, and nothing quietly returns less than it was asked for — an agent that cannot see what refused it retries against a wall it does not know is there.

Reads are never metered. The caps apply only to calls that run something. Every read tool and every nimbus:// resource keeps working after a budget is spent, so an agent can always collect the results the session already produced.

Read-only mode

nimbus mcp --read-only is the safe default for a shared machine or a CI job. What it refuses is narrower than it sounds, and deliberately so:

• execute_anonymous and run_method with commit: true — the same call without commit still runs, and you still get the result, the debug output and the exception. Only the writes are discarded.
• scaffold_metadata unless dry_run: true, which returns the exact files it would have written.

Tests still run. Every test already executes in its own transaction and rolls back, so a test run leaves nothing behind — refusing them would make read-only mode useless on a test runner while adding no safety. What the mode gates on is whether a change can outlive the call, not whether the call touches the database.

The flag and the property compose one way only: either turns the mode on, and neither turns it off. A safety switch a config file can silently disarm is not a safety switch.

Both the caps and the mode are startup-bound and reported in nimbus_capabilities under state.budget, with used, limit and remaining, so an agent can pace itself rather than discover a ceiling by hitting it.

Execution traces

A replayable trace is not a cheap trace. Stepping through an execution needs per-line spans, which only exist at verbose tracing, and verbose costs roughly 65% more interpreter time and tens of megabytes per run — measured, not estimated. Recording every run to keep the few that matter is a bad trade.

So Nimbus retraces instead. When a run fails, the failing tests are executed a second time with tracing on. It pays only when something failed, and only for what failed: on a 1,212-test suite with 24 failures, that is about 2% of the work rather than all of it.

run_apex_tests does this automatically and returns the recording's id on every failure it covers. Pass record_trace: false to skip it.

Three things a reader of a trace must not get wrong, all of which the payload states outright:

• A retrace is a second execution, not a replay of the first. A test that passes the second time is order-dependent or flaky. The manifest records reproduced: false and the trace's limits say the recording shows a passing execution — it is never presented as showing the failure.
• A test that declares its failures deliberate is not recorded. A fixture that is supposed to fail is not a failure anyone needs to replay.
• An absent governor number means "not measurable", not zero. Counters reset inside a span — Test.startTest does exactly that — make the delta meaningless, and claiming a number would be a lie.

Span schema v1

get_execution_trace returns nimbus.span/v1, stamped with schemaVersion: 1. It is an API, not an output format: integrations persist and diff these payloads, so the shape is fixed.

• Additive only within version 1. Fields are added; none is removed, renamed, retyped or given a new meaning.
• A breaking change ships as version 2 alongside 1, never in place. A consumer pinned to 1 keeps working.
• Consumers must ignore unknown fields, and must treat an unknown span kind as opaque rather than an error — new kinds appear within v1 as the engine grows.
• An absent number means "not measurable", never zero.

The document:

{
  "schema": "nimbus.span/v1",
  "schemaVersion": 1,
  "run": {
    "run_id": "2026-08-26T10-11-12_ab12cd34",
    "kind": "failure",
    "spans_recorded": 812,
    "spans_returned": 200,
    "truncated": true,
    "steppable": true,
    "failure": { "tests": [ { "class": "...", "method": "...", "reproduced": true } ] }
  },
  "filters": { "max_spans": 200, "include_events": true, "include_attributes": false },
  "spans": [
    {
      "span_id": "a1b2c3d4e5f60718",
      "parent_span_id": "0918273645abcdef",
      "kind": "dml",
      "name": "apex.dml.insert",
      "start_ms": 12.5,
      "duration_ms": 43.0,
      "depth": 3,
      "status": "ok",
      "test": "AccountServiceTest.testInsert",
      "line": 42,
      "governor": { "dml": 1, "dml_rows": 200 },
      "dml": { "operation": "insert", "sobject": "Account", "records": 200 },
      "events": [ { "name": "apex.field.write", "at": "...", "attributes": { } } ]
    }
  ],
  "limits": [ "spans are what the recorded run captured at its trace level, ..." ]
}

Span kinds. session, test, setup, method, soql, dml, trigger, flow, validation, rollup, async, assign, branch, loop, eval, db, http, parse, lex, ast, interpreter, other. The raw span name is always carried verbatim in name; kind is a grouping over it.

Read the details. status: "unset" is OpenTelemetry's default and means no status was reported — not that the span succeeded. depth and test are computed by walking parent links, so a span whose parent is missing from a truncated file reports depth 0. Filtering by kinds can leave parent_span_id pointing at a span that is not in the document.

The full reference, including every kind-specific detail object and every event name, is committed alongside the code as docs/mcp-span-schema-v1.md, with a machine-readable JSON Schema at internal/mcp/schema/span-v1.schema.json. The emitted payload is validated against that schema in CI, so the document and the code cannot drift apart.

Field history Pro

query_field_history answers the question that costs Salesforce developers the most time and that no static tool can answer at all: why is this value what it is?

Every SObject field write a recorded run performed, in order, with what it replaced, which layer wrote it — apex, trigger, flow, rollup, formula, default, platform — and the exact frame: Class.Method:line, TriggerName.Operation:line, a flow's name, a roll-up definition, or the save-pipeline phase.

{
  "schema": "nimbus.field-history/v1",
  "run": { "run_id": "2026-08-26T10-11-12_ab12cd34", "ledger": "derived" },
  "count": 3,
  "total": 3,
  "writes": [
    { "test": "AccountServiceTest.testInsert", "seq": 1,
      "sobject": "Account", "field": "Rating",
      "identity": "rec-1", "record_id": "",
      "old": "", "new": "Hot",
      "writer": "trigger", "location": "AccountTrigger.beforeInsert:7" }
  ],
  "limits": [ "writes are only those the recorded run performed — ..." ]
}

Filter by sobject, field (either "Rating" or "Account.Rating"), record (an Id or a ledger identity), or test.

Identity, not Id. A record's writes before the save pipeline assigned it an Id carry an empty record_id. Follow identity to see the whole chain across that boundary.

The queryable index is derived from the recording on demand when it is missing, so a run recorded before Pro was active is still readable. The raw writes live in the trace either way — only the queryable surface is Pro.

Agent skills

MCP exposes the primitives. Skills are short playbooks that tell an agent when and how to reach for them — which tool answers which question, and in what order. Install them with nimbus skills install; the binary fetches from nimbus-skills and writes to the right path for your agent.

• fix-failing-apex-test — the inner loop above, written out.
• bootstrap-nimbus — set Nimbus up on a fresh SFDX project, CI snippet included.
• apex-coverage-uplift — raise coverage by targeting the uncovered branches get_coverage reports, not by adding call-only tests.

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

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 .... The whole cycle runs through the Salesforce CLI's Metadata API deploy, which is what stages a bundle, validates it and produces a job id to quick-deploy later.

For the inner loop — the file you just edited, into a sandbox, now — reach for nimbus metadata deploy instead. It pushes what you name without staging, validating or writing a receipt, which is exactly what keeps the two commands from being confused for one another: this one is the gate, that one is the shortcut past it.

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.

An explicit pattern that matches no tests is an error: the run reports No tests ran and exits non-zero, so a typo’d pattern can’t produce a green CI run. Running with no pattern on a project that has no test classes prints a warning and exits 0.

Intentional failures

A test class whose leading doc comment contains EXPECTED TO FAIL (case-insensitive) declares its failures deliberate — a demo fixture, a documented reproduction, an org-comparison probe. Those failures are tagged [expected], listed after the real ones, counted separately in the summary line (✗ 2 test(s) failed · 5 intentional demo failures), reported as expected_failures under --json, and excluded from the exit code. Anything else that fails still exits non-zero.

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

Replay on failure

When a run has failures, Nimbus re-runs just the failed tests with tracing on and prints the command that reopens each one:

Failed Tests:

  AccountServiceTest.testCreate
    Assertion failed: expected 99, got 4

    Class.AccountServiceTest.testCreate: line 12, column 1
    replay: nimbus trace AccountServiceTest.testCreate --run 2026-08-26T02-08-59_5ba1f24e

This is on by default and costs nothing on a green run — nothing is recorded and nothing is written. Traces are recorded at verbose, the level the replay debugger needs to step line by line.

Tests whose class declares its failures deliberate are skipped, and a test that passes when re-run is reported as such rather than presented as a recording of the failure. With --json, each failed test carries trace_path, trace_run_id and replay, so an editor can offer "replay this failure" without guessing where the trace landed.

Retention is bounded: the last nimbus.test.trace-on-failure.keep automatic traces are kept and older ones pruned. Traces you recorded yourself with --trace are never pruned.

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 lint

The governor-safety and best-practice checks every Salesforce developer is trained to look for: SOQL, DML, async enqueues and callouts inside loops, hardcoded record Ids, swallowed exceptions, and seeAllData tests. Where nimbus validate asks whether the platform would accept the file, lint asks whether you want what it does.

Every other Apex linter is purely static, so every one of them says the same thing about a query inside a for: that it might run many times. Nimbus ran the code. Point it at a recorded run and the finding stops being a warning about the future and becomes a report about the past.

nimbus lint                            # every class and trigger
nimbus lint AccountService             # files matching "AccountService"
nimbus lint *Service*                  # files matching "*Service*"
nimbus lint force-app/main/default/classes/   # everything under a path
nimbus lint --rules                    # what each rule protects against
nimbus lint --json                     # schema nimbus.lint/v1

Without a run, it speaks in the conditional

AccountService.cls
  5:35  warning  soql-in-loop
    SOQL query inside the for-each loop at line 4. Every iteration that
    reaches it spends one of the transaction's 100 queries.

1 finding: 1 soql-in-loop in 2 files.

No recorded run: every message above says what the code MIGHT do.
Record one to see what it did:  nimbus test "*" --evidence

With one, it reports what happened

nimbus test "*" --evidence
nimbus lint

AccountService.cls
  5:35  warning  soql-in-loop
    SOQL query inside the for-each loop at line 4. Run
    2026-08-27T17-35-45_0031534d issued it 47 times, seen in
    AccountServiceTest.testBulkInsert. A transaction may issue 100.

A message never claims anything ran unless a recording covers that exact line. When a run covered the file and missed the line, the finding says so instead of guessing — untested code carrying a governor-safety defect is a sharper finding than the defect alone, and it is one no static linter can produce.

The rules

What the rules refuse to flag

A rule that fires on correct code is worse than a rule that does not exist, so each one is measured against ~23,000 Apex files from about forty real open-source Salesforce repositories before it ships. The whole corpus produces 188 findings, and the exclusions are as deliberate as the rules:

• for (Account a : [SELECT ...]) evaluates its query once, on entry. It is the bulk-safe idiom, not the defect, and it is the first false positive a naive implementation produces.
• for (Account[] batch : [SELECT ...]) is handed 200 records at a time precisely so the body can do one DML per batch, sodml-in-loop stays quiet inside it.
• A statement followed by an unconditional break orreturn runs at most once, so it is not one per iteration.
• hardcoded-id verifies the real 18-character checksum, or a key prefix the bundled describes actually list. AccountNumber12 is the right length and the right character set and is not an Id.
• empty-catch and hardcoded-id do not judge test code: an empty catch after Assert.fail() is the success path, and a fabricated Id is how a unit test avoids a DML. The loop rules do judge tests, because a test transaction has the same 100 queries as any other.

Exit status is 1 when any finding survives the severity threshold, so nimbus lint can gate a build; 2means the command could not run. Files that do not parse are skipped rather than reported — judging a half-built tree is how a linter invents defects — and the count of skipped files appears in the summary.

The same rules appear in the editor as the nimbus/lint diagnostic family, with the rule id as the diagnostic code so you can mute one rule without muting Nimbus. They read the same recording, so the squiggle carries the same counts. Turn them off withnimbus.diagnostics.lint: false. They ship no quick fixes on purpose: flipping seeAllData to false hands back a broken suite, “log the exception” cannot know which logger the codebase uses, and the loop rules need a refactor rather than a text edit.

lint reads every class in the project, so it resolves an@future method called through another class. The editor, which cannot promise a current project index, deliberately under-reports that one case.

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);"

# Ends in a statement, so it runs as written - nothing is wrapped
nimbus exec -c "Account a = new Account(Name = 'T'); insert a;"

-c wraps the code in System.debug() only when it ends in a bare expression. Anything ending in a semicolon or a closing brace is already executable and runs verbatim.

nimbus run-method

Call one method of one class and report what it returned. Where nimbus exec runs a block of Apex you wrote, run-method takes a method that already exists and generates the invocation for you — including constructing the receiver, so an instance method needs no new of your own.

# Static method, no arguments
nimbus run-method AccountService.createDefault

# Arguments are Apex expressions, one --param each
nimbus run-method Calculator.add --param a=2 --param b=3

# Note the inner quotes: the value is Apex source, not a literal
nimbus run-method AccountService.byName --param name="'Acme'"

# Structured result, including per-line variable snapshots
nimbus run-method AccountService.createDefault --json

Whether the method is static and what it returns are read from your project's source, so the argument is just Class.method — the last dot splits it, which keeps an inner class's qualified name intact (Outer.Inner.method).

Because a --param value is Apex source rather than a string literal, it can be anything the parameter accepts: a list, a new Account(Name = 'Acme'), or a call to a factory. Only the first = separates, so a value that is itself an assignment or a map literal survives intact.

Flags

The two overrides exist for a method nimbus cannot resolve — one that lives in a managed-package stub, say. Resolution failure is an error on its own; pass both --static and --return-type and the call goes ahead anyway.

Output

The default output is the return value with its Apex type, any System.debug lines with the file and line that produced them, a count of the lines that executed and the files they were in, and the duration. A method that threw exits non-zero and prints the failure.

--json adds what the terminal cannot usefully show: variables carries a per-line snapshot of every local in scope (file, line, and each variable's name, value and type), and executedLines maps each file to the lines that ran. This is the same document the VS Code and JetBrains plugins render as inline annotations — the editors' "Run method" code lens and this command are one implementation.

The method runs against the local database with the same configuration nimbus exec uses — seeded rows, org defaults, and managed-package stub namespaces all present — but inside the same isolating transaction a test gets, and that transaction is rolled back when the command exits. Its DML does not survive the run, which is the difference between it and nimbus exec: you can call a method that inserts records without leaving them behind.

nimbus compare

Run the same thing locally and on a connected org, then diff the two results structurally. Three inputs: a snippet of anonymous Apex (-c), a SOQL query (-q), or a whole test selection (--tests). For the first two the verdict leads: identical, different, or which side errored.

# Compare a computation
nimbus compare -c "System.debug(Decimal.valueOf('1.5').round());"

# Compare a query against a specific org
nimbus compare -q "SELECT Name FROM Profile WHERE Name = 'System Administrator'" -o my-sandbox

# Compare a whole test class, then the whole suite
nimbus compare --tests AccountServiceTest -o my-sandbox
nimbus compare --tests "*" -o my-sandbox

# Machine-readable result
nimbus compare -c "System.debug(1+1);" --json

What can never match is normalized out and every normalization is reported: record Ids (org and local Ids never agree, so Id values are excluded from comparison), audit fields (CreatedDate and friends), row order when the query has no ORDER BY (with one, order is part of the contract and is compared), and number/datetime formatting. Differences are typed — row counts, cells, columns, output lines, exceptions — and classified with a confidence: data, schema, engine, nondeterminism, or unknown.

The local side always rolls back — a compare never writes to the local database. The org side is a real org call, so anonymous Apex really executes in the org. A sanitized repro is written under .nimbus/differential/<timestamp>/.

Comparing a test run

--tests runs the selection on both sides and reports a verdict per test method:

• match — both sides agree. If both failed, the normalized messages agree too.
• divergence — the two sides reached different outcomes. This is the one to look at.
• message-divergence — both failed, with different messages. Softer on purpose: Nimbus and Salesforce word the same assertion failure differently, so this bucket is expected to be noisy and is counted apart.
• org-only-error — the org produced no trustworthy outcome for that test (a class it could not compile, a run that never finished).
• missing-in-org / missing-in-local — one side never ran it.

An org test run can fail for reasons that say nothing about your code: an expired session, an exhausted API budget, a run still queued when Nimbus stops waiting. None of those is ever reported as a divergence. They are surfaced as environmental failures, in their own section, above the counts.

The org side is a real org test run: it takes as long as one normally does, and any data those tests create is created in the org. Failure messages are normalized before comparison — record Ids, durations, timestamps, whitespace — and every normalization is reported.

The selection has to be one the org can be asked for: *, a class name, a Class.method, or a comma-separated list of those. A wildcard inside a name (Account*Test) is refused rather than guessed at — running two different sets of tests and calling the difference a divergence would be worse than not answering.

The repro report

When tests disagree, a sanitized repro is written under .nimbus/differential/testrun_<timestamp>/ — the same pattern the snippet modes follow. It records what ran, both sides for the divergent methods only, the normalizations applied, the environmental block verbatim, and the org test run id so the run can be found again in the org. The org identity is masked to its alias; a full username is replaced outright, because a masked local part with an intact domain still names the org. A run where the two sides agreed writes nothing — there is nothing to reproduce. --no-report turns it off, and the path is printed when one is written.

Comparing coverage

--coverage adds a second table: each class's covered percentage on both sides and the gap between them, biggest gap first. The local side is the same collection nimbus test --coverage uses; the org side is sf apex ... --code-coverage. Percentages are recomputed from line counts on both sides, because the org's own figure is an already-rounded integer.

Coverage is a table beside the verdicts and never one of them. The two engines instrument different lines, so a gap is a fact to look at — not a disagreement about behaviour, and never a divergence. A side that could not report coverage says so and is never shown as 0%: this class has no coverage and nobody told us about this class are different findings. Classes only one side reported are listed after the table without a delta, and every exclusion the comparison applied is named.

--tests "*" asks the org for RunLocalTests, which is every unmanaged test in the org — a superset of this project's suite whenever the org carries classes you don't. Those are reported as missing-in-local and counted separately, not as divergences. Naming the classes is the precise way to ask.

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 App preview target — React bundles, LWC components,
# Visualforce pages
nimbus app list

# The same listing as JSON, with each LWC package's component inventory
nimbus app list --json

# 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

# Run the bundle's own test suite (npm test)
nimbus app test reactRecipes

# Serve the built artifact instead of the HMR dev server (npm run preview)
nimbus app preview reactRecipes

# Score what the local LWC preview actually renders, per component
nimbus app scorecard

# The same run as a committable Markdown artifact
nimbus app scorecard --markdown > lwc-scorecard.md

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:

build, test and preview are deliberately thin: Nimbus does not reimplement Vite or Vitest. Each discovers the bundle and runs that bundle's own package.json script (npm run build, npm test, npm run preview) in its directory, with stdio wired through to your terminal and its exit code passed back. What they add is the discovery and script resolution — a CI job runs nimbus app test and needs no bundle-aware logic of its own. A bundle with no package.json is an error rather than a silent no-op.

Their bundle selection is simpler than the dev server's: a named argument picks that bundle, a project with exactly one bundle needs no argument, and anything ambiguous is an error listing the candidates — there is no interactive picker on these three, TTY or not.

Note that preview starts the bundle's own preview server and nothing else. Unlike nimbus app, it does not stand up the Nimbus proxy, so the previewed build gets no SFDC_ENV injection and its /services/data/* calls do not reach the local runtime. It verifies that the optimised bundle builds and serves; verifying it against Nimbus's API surface still means running nimbus app.

scorecard measures the local LWC preview instead of describing it. For every component it can see, it records four tiers: whether the preview's own toolchain compiles the component, whether the real preview page mounts it in a headless browser, which platform data adapters (lightning/ui*Api, lightning/messageService, @salesforce/apex/*) it needs, and which other platform modules (@salesforce/*, lightning/*) it needs. The first two tiers are measured by running the real pipeline; the last two are classified statically against the renderer's own module tables, and the report says which is which rather than blending them. A component blocked at an unsupported platform import is reported as a declared boundary, not a defect — the renderer fails that import on purpose instead of returning invented platform data. Anything the machine cannot measure (no dependency cache, no headless browser) is marked unmeasured with the reason; it never becomes a pass, and Nimbus downloads nothing to produce a number.

--serve boots a local Nimbus runtime on an ephemeral port behind the measured page, so a mounted component's wire adapters and Apex calls reach the real interpreter and the embedded database instead of nothing. Without it a component that needs platform data still mounts — proving its modules loaded, not that its data path works — and the report says which of the two it measured. The run records what each mounted component actually rendered, which is the difference between a green row and evidence. It starts an embedded Postgres, so it is opt-in.

What the org-free renderer supplies. @salesforce/label/<ns>.<Name> and @salesforce/schema/<Object>[.<Field>] resolve at build time, the way the platform compiler resolves them: a label becomes the value your project's .labels-meta.xml declares, and a schema import becomes the same { objectApiName, fieldApiName } descriptor the platform emits. Neither reaches a server, in an org or here. A label your project does not declare fails by name rather than resolving to an empty string, and scoring a component set that has no Salesforce project behind it refuses labels outright — the report's environment block says which of the two applied.

lightning/uiRecordApi and lightning/uiObjectInfoApi are supplied too, wired to the UI API endpoints Nimbus already serves: getRecord, getRecords, getRecordCreateDefaults, getObjectInfo, getObjectInfos, getPicklistValues, getPicklistValuesByRecordType, the imperative createRecord/updateRecord/deleteRecord, and the pure helpers (getFieldValue, getFieldDisplayValue, the generateRecordInput* family). The records are real — rows in the embedded Postgres, written through the same handlers a React bundle uses, firing the project's own triggers. What is not there is the Lightning Data Service: no normalised cache, so two components wiring the same record issue two requests and a write does not re-emit to a sibling's wire. getRecordNotifyChange and notifyRecordUpdateAvailable exist only to invalidate that cache, so they are visible no-ops that announce themselves in the preview header rather than pretending to do something. The scorecard reports both modules as stubs for exactly this reason — the data is right, the behaviour is local.

@salesforce/apex/<Class>.<method> resolves to the same callable-adapter value the platform's compiler generates — one export that returns a Promise when called imperatively and provisions a property when used with @wire. The call reaches the local Apex interpreter and runs the project's own method against the embedded Postgres, returning what JSON.serialize would. Only methods annotated @AuraEnabled are reachable: anything else is refused by name, because a bridge that called any method on any class would be an arbitrary RPC into your source rather than a preview of Salesforce. A thrown Apex exception arrives as error.body.message / error.body.exceptionType, the shape an org sends for a controller call.

Two differences are reported rather than imitated. @AuraEnabled(cacheable=true) runs the method on every provision here — there is no Lightning Data Service cache to populate — and the response says so on X-Nimbus-Apex-Cacheable, which the preview surfaces as a header badge. If a cacheable method performs DML, something the platform refuses outright, Nimbus reports the statement count on X-Nimbus-Apex-Cacheable-Dml and lets the call stand instead of raising an exception whose exact org wording is not yet verified. refreshApex re-runs the request behind the value you hand it; with no cache there is no cross-component invalidation, and a value that did not come from an Apex wire is announced rather than silently treated as refreshed.

lightning/messageService and lightning/empApi remain blocked at compile time, as do the lightning/ui*Api families with no local endpoint behind them.

TypeScript components. A bundle whose class lives in <name>.ts is a component on the same terms as a .js one — discovered, previewed, hot-reloaded, and scored, with the scorecard's Lang column saying which language each row was written in. A .js beside a .ts resolves the way the platform compiler resolves it: .js wins. The bundle metadata stays <name>.js-meta.xml in both cases.

The renderer strips the type annotations ahead of the LWC compiler and pins two settings while doing it — experimentalDecorators: false and useDefineForClassFields: true — overriding whatever your tsconfig.json says. Both decide whether @api, @wire and @track are still decorators by the time the compiler sees them; with either the other way they are rewritten first and the component compiles, mounts, and silently has no public properties. Worth checking in your own build too: the failure has no error message.

The Pro gate is on nimbus app itself — the dev server and its Salesforce API surface. list, schema, build, test, preview and scorecard run on the free tier.

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.

The tool catalog, the setup files for each client, and the frozen span schema live in AI agents. This section covers the command itself. An agent can also get the catalog at runtime by calling nimbus_capabilities, which is always in step with the binary it is talking to.

Tools exposed: run_apex_tests, execute_anonymous, run_method, run_mutation_tests (Pro), get_test_failure, explain_failure, triage_failures, get_execution_trace, query_field_history (Pro), get_governor_usage, query, describe_schema, get_coverage, list_test_classes, query_graph, scaffold_metadata, nimbus_capabilities.

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.

Does the verification loop actually help? That is an empirical question, so it gets an experiment rather than a claim. The Nimbus repository ships verifybench, a harness that measures an agent's fix rate on real failing Apex tests with and without this toolset, over a frozen, hashed task set. The harness and its methodology are available now; no registered run has been executed, so there is no result to report yet. We will publish the task set, the raw per-attempt records, and the report together, or not at all.

Resources exposed: nimbus://capabilities, nimbus://project, nimbus://parity, nimbus://coverage (and nimbus://coverage/{class}), nimbus://schema (and nimbus://schema/{object}). All read-only; they execute nothing and are never refused by a cap or by read-only mode.

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. A refused call logs too — mcp.refused.read_only or mcp.refused.budget. --verbose raises the log level to debug.

Register with Claude Code:

claude mcp add nimbus -- nimbus mcp

For a shared machine or CI, start it read-only — tests and Apex still run, but nothing they write survives the call and no files are written:

nimbus mcp --read-only

Per-session ceilings (nimbus.mcp.max-test-runs-per-session, nimbus.mcp.max-apex-executions, nimbus.mcp.max-wall-clock) bound an unattended agent and are off until a project sets them. Full details under Safety caps.

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 sync -s WorkOrder -o myorg                  # Pull a standard object Nimbus doesn't ship a describe for

-s also reaches objects Nimbus has never heard of. Standard-object describes ship with Nimbus, and there is no .object-meta.xml a project could write for a standard object — so when one is missing, naming it explicitly alongside -o describes it from your org and caches it. It is remembered, so later syncs keep it, and a release that adds the describe quietly takes over.

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 Salesforce source — Apex, Lightning components, objects, fields, labels, custom metadata, and the admin surface from page layouts to approval processes — into your project's default package, following the standardforce-app/main/default/… layout. Every type writes its -meta.xml companion, and the API version comes from sourceApiVersion in sfdx-project.json.

nimbus new apex-class AccountService --test
nimbus new apex-trigger AccountTrigger --object Account --events before-insert,after-update
nimbus new lwc orderPanel --expose --targets lightning__RecordPage
nimbus new lwc typedPanel --ts   # a .ts class module; automatic when lwc/ has a tsconfig.json
nimbus new custom-object Delivery_Area__c --label "Delivery Area"
nimbus new custom-field Zone__c --object Delivery_Area__c --type Text --length 80
nimbus new layout "Delivery Area Layout" --object Delivery_Area__c --field Name --field Zone__c
nimbus new lightning-page Delivery_Area_Record_Page --type RecordPage --object Delivery_Area__c

Types

The older Apex spellings still work: class, test, trigger, triggerhandler, batch, queueable and schedulable route to the same generator, and --sobject remains an alias for --object.

New metadata is queryable immediately

Objects, fields, labels and custom metadata are picked up by the next nimbus test without a sync. Nimbus rescans the project's own metadata on every run, so a field you created a second ago is already a column. nimbus sync is for pulling schema from an org, which is a different job.

Field types use the metadata vocabulary

--type takes the name the Metadata API uses in <type>, which is not always the name a describe call answers with. Rich text is Html, not RichTextArea; a multi-select picklist is MultiselectPicklist, not MultiPicklist. Pass a describe spelling and Nimbus tells you the metadata one rather than writing a field that silently behaves as text.

$ nimbus new custom-field Tags__c --object Account --type MultiPicklist
Error: "MultiPicklist" is a describe type name, not a metadata FieldType — use
"MultiselectPicklist" (metadata XML and describe results spell several types differently)

Accepted: AutoNumber, Checkbox, Currency, Date, DateTime, Email, Lookup, MasterDetail, Number, Percent, Phone, Picklist, MultiselectPicklist, Text, TextArea, LongTextArea, Html, Time, Url.

Roll-up summaries (Summary), geolocations (Location), encrypted text (EncryptedText), hierarchical relationships (Hierarchy) and metadata relationships (MetadataRelationship) are creatable too — each takes the extra flags listed below. External and indirect lookups are not, and neither are formula fields: an external lookup's target exists only through an external data source, and a local project has none to offer or check against. Naming one tells you that, rather than treating it as a typo.

Flags

Data types are the Metadata API vocabulary, not the one a describe call answers with — rich text is Html, a multi-select picklist is MultiselectPicklist, encrypted text is EncryptedText. A describe spelling is refused with the metadata name given, rather than written into a file that would silently behave as text.

Summary, Location, EncryptedText, Hierarchy and MetadataRelationship are generated. ExternalLookup and IndirectLookup are not, and the refusal names the reason: both need a referenceTo pointing at an external object, which exists only through an external data source — a local project has none, so there is nothing to offer and nothing to validate a typed name against. Write those two by hand.

The four object children — field-set, record-type, validation-rule and list-view — require an object that already exists, in the project or on the platform; a name matching neither is refused rather than written one directory deep. A child lands beside its own object, so an object in a second package directory keeps its children there.

Nimbus evaluates validation rules during local DML, and skips any rule whose formula it cannot read. Creating a rule therefore parses its errorConditionFormula first and warns when the formula engine cannot — the rule still deploys and still fires in the org, but local runs let the save through, so a green suite would not mean what it looks like.

--list --json is what the IntelliJ plugin reads to build its New menu, so its dialogs always describe the CLI you actually have installed.

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 coverage lines

What a line cost, not whether it ran. A coverage report says line 42 was executed. This says line 42 ran 47 times, issued 47 SOQL queries — 47 of the 100 a transaction gets — and spent 1.2 seconds in the database, and that AccountServiceTest.testBulk is the test that did it.

The counts are the governor's own: a query is attributed to a line from the same call that charges it against Limits.getQueries(), so the per-line numbers and the transaction's usage cannot disagree. Record with --evidence, read with this.

nimbus test "*" --evidence
nimbus coverage lines AccountService
nimbus coverage lines force-app/main/default/classes/AccountService.cls --all
nimbus coverage lines AccountService --json

By default only lines that issued a query or wrote a row are listed — those are the lines a limit is spent on. Database time is attributed to the outermost line that opened the operation, so an insert accounts; reports the time its triggers spent too; counts are not rolled up that way, so a query inside a trigger is counted on the trigger's own line.

nimbus budget Pro

Per-test ceilings on the governor counters, enforced as a CI regression gate — a performance budget for Apex. The platform's own limits are a cliff at 100 SOQL and 150 DML: a test sits at 94 queries for a year, someone adds a loop, and the failure arrives in production. A budget is the line you draw well below that cliff and defend on every pull request.

Five counters are budgetable: soql, soql_rows, dml, dml_rows and cpu_ms. All five are machine-independent. Four are exact counts; cpu_ms is Nimbus's virtual CPU clock, which counts operations rather than wall time — the same test produces the same number on a laptop and on a CI runner, which is what makes a CPU budget checkable at all.

nimbus budget init            # measure the suite, write nimbus.budgets.json
nimbus budget check           # re-measure, exit 1 if any test is over budget
nimbus budget check --json    # machine-readable result for CI

The budget file

nimbus.budgets.json at the project root. nimbus budget init writes it; it is meant to be committed and read in code review.

{
  "version": 1,
  "defaults": {
    "soql": 50,
    "dml": 30
  },
  "tests": {
    "OrderServiceTest.*":             { "soql": 20, "dml_rows": 60 },
    "OrderServiceTest.testBulkOrder": { "soql": 5 }
  }
}

Keys under tests use the same wildcard syntax as nimbus test <pattern>, matched against ClassName.methodName. An unknown counter name is a hard error, not a silently ignored key.

Which budget applies

Resolution is per counter and layered, most specific first:

1. Every tests pattern matching the test, ordered by specificity: an exact test name (no *) beats any wildcard; otherwise the pattern with more literal characters wins; ties break on the pattern string ascending.
2. The defaults block.

The first level that names the counter wins, and counters it does not name keep falling through. So OrderServiceTest.testBulkOrder above takes soql: 5 from its exact entry and dml_rows: 60 from the class wildcard. A counter no level names is unbudgeted for that test and is never reported. Every violation line names the key its budget came from, so you know which line of the file to edit.

Adopting budgets

nimbus budget init runs the suite and writes measured usage plus headroom.defaults gets the suite's worst observed value per counter — the ceiling a newly written test must stay under — and every measured test gets an entry at its own usage plus headroom. The per-test entries are what actually catch a regression: a single test doubling its queries would still sit far below the suite-wide default. Derived budgets are raised to a small per-counter floor, so a test that issues one query is not broken by its second, and clamped to the platform limit, so no budget is written that could never fire.

What is measured

A test's usage is what Limits reports when the test method ends. Test.startTest() resets the governor counters and Test.stopTest() restores them — platform behaviour, which Nimbus reproduces exactly — so work inside that block is not counted, and a budget on such a test covers only what it does outside the block. Both commands say so out loud when they see it, rather than letting a suite look green while budgeting nothing.

Tests that fail or are skipped are reported but not judged: a test that threw on its third line stopped consuming counters there, so its usage says nothing about what it costs when it works.

Exit codes

nimbus budget check flags

nimbus budget init flags

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
nimbus whoami --json # Structured status for editor and tooling integrations

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

Re-running nimbus login is always safe: if nothing changed it says so, and if your account's license changed since this machine last signed in, the machine is moved to the current license automatically.

nimbus whoami --json returns plan, activation state, a shortened machine identifier, capability lists, and account URLs. It never returns a license key or full machine identifier.

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 which database this project will use, what decides that database's connection, and which org the org-facing commands will reach. For a health check with fixes attached, use nimbus doctor instead.

nimbus status         # Human-readable summary
nimbus status --json  # The same facts, machine-readable

--json

Three objects with stable lowercase keys. project carries found and path; database carries provider, url_source (flag, environment or embedded) and data_dir for the embedded provider; org carries target and source (flag, config or none).

The connection URL is never included, only what decides it — a URL can carry credentials and this output is meant to be safe to paste into an issue. When no org is configured, target is empty rather than the placeholder the human-readable output prints.

{
  "project":  { "found": true, "path": "/work/my-project" },
  "database": { "provider": "embedded", "url_source": "embedded", "data_dir": ".nimbus/db" },
  "org":      { "target": "my-sandbox", "source": "config" }
}

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 org doctor

Report which Salesforce login Nimbus found, and which org operations it performs natively versus through the Salesforce CLI.

The native org engine

The org operations Nimbus makes most often go straight to the Salesforce APIs, using the login sf org login web already wrote to your sfdx auth store. No Node process starts, and Nimbus works on a machine whose Salesforce CLI is missing, broken, or mid-upgrade.

The Metadata rows carry a boundary, and that boundary decides which of your commands is fast. Source format keeps most types in a single file, and those Nimbus converts and moves itself. It does not keep an object in one file — a Salesforce DX project splits an object across per-field, per-record-type and per-list-view files, and reassembling those is the Salesforce CLI's job. Workflows, sharing rules, Lightning and Aura bundles, and anything held in a folder are the same story. nimbus org doctor names the count and the exclusions on those rows rather than reporting a bare "native":

Capabilities
  execute anonymous Apex     native
  SOQL query                 native
  run org tests              native
  read org test results      native
  retrieve Apex source       native  (Apex classes and triggers by name, over the Tooling API)
  deploy a class or trigger  native  (single Apex files, over the Tooling API's container flow)
  retrieve metadata          native  (29 metadata types; objects, workflows, bundles and folder contents retrieve via Salesforce CLI)
  deploy metadata            native  (29 metadata types; objects, workflows, bundles and folder contents deploy via Salesforce CLI)
  list org metadata          native  (describeMetadata and listMetadata, every type the org exposes)

The split is per call, not per component: a manifest naming even one excluded type runs through the Salesforce CLI whole. Two retrieves are two snapshots of an org that changed in between, and two deploys are two transactions, which makes rollback-on-error a promise a pair of them cannot keep.

Everything else — the nimbus deploy assurance cycle, org creation, package operations, nimbus sf passthrough — still runs through the Salesforce CLI, which stays a supported dependency.

Fallback, never replacement

Every native call falls back to the exact Salesforce CLI invocation it replaced if anything goes wrong — no login, an expired refresh token, an org that will not answer. You get one line saying so, once per capability:

native org call failed (SOQL query: ...), using sf CLI

Nimbus never runs an OAuth flow of its own. If there is no sfdx login it says which command creates one, rather than authenticating an org that sf would not be able to see.

The Salesforce CLI encrypts the tokens in its auth store, so Nimbus reads the same key from your OS credential store (Keychain on macOS, libsecret on Linux, or the CLI's key.json where neither exists). If that key is unavailable — a locked keychain, a restricted CI runner — nimbus org doctor reports the tokens as encrypted (no key available) and every call falls back to the Salesforce CLI, which reaches the credential store through its own bindings. Nimbus will not send a secret it could not decode.

Reading the report

nimbus org doctor                 # the default target org
nimbus org doctor -o my-sandbox   # a specific org
nimbus org doctor --probe         # also make one live call to prove reachability
nimbus org doctor --json          # the same report, structured

Everything except --probe is answered from local files, so this works offline and on an org whose session has expired. Access and refresh tokens are never printed — the fields shown are the ones sf org list already displays. The command exits non-zero when there is no usable login, or when --probe was passed and the org did not answer.

Turning it off

Set org.native=false in nimbus.properties. Every org call then goes through the Salesforce CLI exactly as it did before — the fallback path is the old behaviour, so nothing else changes.

# nimbus.properties
org.native=false

Tracing

NIMBUS_ORG_NATIVE_TRACE=1 logs a redacted summary of every native call to stderr: method, endpoint, status, timing and body size. Never a request body, never a query string's contents, and never a token.

NIMBUS_ORG_NATIVE_TRACE=1 nimbus soql -o my-org "SELECT Id FROM Account LIMIT 1"

nimbus org status

Report whether the org's copy of your files changed since you took them. This is the read-only half of nimbus metadata deploy's conflict detection: same registry, same query, nothing written and nothing deployed.

nimbus org status                    # everything tracked for the target org
nimbus org status AccountService     # one class
nimbus org status --json             # the same rows, structured

Sync base — my-sandbox (00D5f000004XXXXEAA)
  .nimbus/org-base.json — this checkout only, not for git

  ApexClass  AccountService  current     synced 2026-08-26 09:15
  ApexClass  ContactService  local edit  synced 2026-08-25 14:00, edited since
  ApexClass  OrderService    ORG NEWER   changed 2026-08-26 11:02 by Dana Ruiz

  3 entities tracked, 1 newer in the org — `nimbus metadata deploy` will refuse those.

A project with no rows has simply never retrieved or deployed through Nimbus — that is the brownfield starting state, and a deploy in it warns once and proceeds. The command exits non-zero when any row is ORG NEWER, which makes it usable directly as a pre-push check.

Distinct from nimbus org doctor on purpose: doctor answers "can Nimbus talk to this org natively" from local files and works offline, while this asks the org about data and needs a live connection.

nimbus agent (experimental)

Test an Agentforce agent's action surface locally — the actions, never the planner. nimbus agent list reads the agent's declared actions from your source (both GenAi metadata generations and Agent Script) and shows how each resolves against this project; nimbus agent test executes them through the local runtime with per-action results, governor cost, and rollback by default. An action whose declared inputs don't match its Apex request wrapper is refused by name — a correspondence nothing org-side checks.

nimbus agent list --coverage answers the other question: which actions has no local test reached? Each action is marked observed — a coverage run recorded a test executing its target's file — or static, meaning no run recorded anything and a test merely reaches the target through source references. The two are never merged into one "covered" column: one is a measurement and the other is a reading, and only the first is evidence. An action nothing reaches at all is marked NONE; one with no local target is marked n/a rather than uncovered, because nothing here could ever cover it. Reaching a target is also not the same as testing the action — the input contract is nimbus agent list's job and executing it is nimbus agent test's.

nimbus agent list                      # every action, and how each one resolves
nimbus agent list --coverage           # ...and what no local test has reached

# One action, with the inputs the planner would have supplied at runtime.
nimbus agent test Support_Agent --action Submit_Case --template
nimbus agent test Support_Agent --params inputs.json

Experimental: the shape of these files and flags may still change.

What nimbus will not test

This list is the shape of the product, not a backlog. Read it before the rest of the section, because everything below is only worth as much as this is honest.

Conversation fixtures

Agentforce metadata declares an action's input shape and never an example value — the planner fills inputs from the conversation at runtime, so there is nothing on disk to replay. A fixture file is where those inputs live, which is what turns a one-shot CLI invocation into something a pull request can be red about.

# agent-tests/support-agent.agenttest.yaml
schema: nimbus.agenttest/v1
agent: Support_Agent

actions:
  Submit_Case:
    cases:
      - name: high priority escalates and opens a case
        inputs:
          subject: Printer is on fire
          priority: High
        expect:
          result:
            - path: $[0].escalated
              equals: true
          debug:
            - contains: "subject=Printer is on fire"
          db:
            - soql: SELECT Id FROM Case WHERE Subject = 'Printer is on fire'
              count: 1
          governor:
            maxSoql: 2
            maxDml: 1

  # A refusal is not a failure. Pinning the code makes it a regression test.
  Mismatched_Action:
    cases:
      - name: an input the request wrapper does not carry
        expect:
          outcome: refused
          refusal: apex-input-not-on-request-wrapper

nimbus agent test --fixtures                     # every **/*.agenttest.yaml
nimbus agent test --fixtures ./agent-tests      # one directory
nimbus agent test --fixtures --case "Submit_Case/high priority escalates"
nimbus agent test --fixtures --results-xml results.xml --coverage-report cov.json

Every case runs in its own transaction and is rolled back — nothing a fixture does is ever committed. Failures print first, each naming every assertion that did not hold and the exact command that reruns that one case.

What a case can assert

result paths are a deliberately small JSONPath subset — $, $.field, $.a.b, $[0], $[0].field. Wildcards, recursive descent, filters and slices are refused by name: each matches a setrather than a value, and an assertion whose subject is "some element, possibly none" passes for reasons you did not write down.

Governor limits are ceilings, not equalities. An assertion that a method issues exactly three queries breaks on every unrelated refactor; one that it issues no more than three catches the loop that turned into an N+1.

Database assertions have to run inside the action's own transaction, because the writes are never committed — a query issued anywhere else would see an empty database and every one of them would pass by reporting zero. Your SOQL is run verbatim, never rewritten: a rewritten query is a different assertion from the one in the file.

Importing a Salesforce test-spec

If you already maintain a sf agent generate test-spec YAML, a fixture can read it. Nimbus maps the one thing in it that can be checked locally — the actions the planner is expected to reach — and refuses the rest by name, printed on every run.

schema: nimbus.agenttest/v1
import: ./support-agent-test-spec.yaml

Each named action becomes a case that checks it against local source without running it: the target still exists, and its declared inputs are still fields on the request wrapper. That second check is the one no other tool in the ecosystem makes — the org validates that invocationTarget names something in the org; it cannot tell you whether the action's inputs still match the Apex in this working copy. The spec carries no input values, so nimbus does not invent any: a fabricated input set produces a green case that tested a value nobody chose.

Those rows are the boundary above, applied key by key: every planner-side expectation is refused by name and printed on the run, never approximated into a local verdict.

CI

A fixture run emits the same JUnit XML and coverage reports a test run does, through the same writers — so anything that already consumes a nimbus report consumes this unchanged. The GitHub Action picks fixtures up automatically and adds one section to the same PR comment, failures first. A repository with no fixtures pays nothing and the comment says nothing about agents.

- uses: nimbus-solution/nimbus/.github/actions/nimbus-test@v1
  with:
    license-key: ${{ secrets.NIMBUS_LICENSE_KEY }}
    agent-fixtures: auto        # or a path, or false

Flags

nimbus org diff

Show where this project and the org disagree — what exists only in the org, only here, and what both have with different bodies.

nimbus org diff                              # the default target org
nimbus org diff -o my-sandbox                # a specific org
nimbus org diff --type ApexClass,ApexTrigger # narrow it
nimbus org diff --all                        # list the matching components too
nimbus org diff --json                       # the whole tree, structured

Five states, not three

Every component comes back as one of five states. The fifth is what makes the other four worth trusting.

A row is undetermined when the org will not hand over a body in the same call that listed the name — a static resource's binary, an Aura or LWC bundle's files, source a managed package hides from a subscriber — or when this project defines the same API name in two package directories, in which case there is no single local copy to compare. Nimbus says so rather than guessing. A wrong "differs" costs you a diff; a wrong "in sync" is how a stale class ships.

What is compared, and how

Bodies are compared after trailing whitespace is removed from each line and from the end of the file, and after nothing else — the two differences a round trip creates on its own. No other normalization is applied, deliberately: every additional rule makes an "in sync" verdict easier to produce and less true.

Managed-package members are excluded. A subscriber org cannot hold their source, so every one of them would report as org-only forever.

What it does not cover

Objects, fields, layouts, flows, permission sets, profiles, record types, validation rules and the rest of the long tail are not looked at. Those cannot be listed over the Tooling API at all — they need the Metadata API's listMetadata call, which this build does not make. The command prints them by name on every run, and the JSON carries them in pendingTypes, so a clean report is never mistaken for a complete one.

A type the org refuses to list is reported undetermined with the org's own error, never as empty. "The org has none of these" and "the org would not tell me" are different answers, and the second one must not silently turn this project's components into local-only rows.

Bounded output

An org with a few packages installed answers a listing with four figures, so the tree lists at most 200 components per type and counts the rest. The cut is stated on the row that replaces them. Components are ordered drift first, so the cap can only ever hide rows nobody needed to see; the listing behind it is never truncated, because a component dropped before the comparison would come back as a local-only verdict rather than as a missing row.

Matching components are counted but not listed unless you pass --all. The answer to "is my project current" is the rows that are not.

JSON

The payload is pinned by a schema field and carries its own caveats: supportedTypes is every type this build can list, pendingTypes is every type it cannot, and limits states what the run could not establish. Every array is present even when empty.

nimbus org diff --json | jq '.types[].entities[] | select(.status == "bothDiffer") | .name'

{
  "schema": "nimbus.orgdiff/v1",
  "org": "my-sandbox",
  "summary": { "orgOnly": 1, "localOnly": 0, "bothSame": 142, "bothDiffer": 2, "undetermined": 4 },
  "types": [
    {
      "type": "ApexClass",
      "status": "listed",
      "counts": { "orgOnly": 1, "localOnly": 0, "bothSame": 142, "bothDiffer": 2, "undetermined": 0 },
      "total": 145, "shown": 3, "hidden": 142, "hiddenInSync": 142, "hiddenCapped": 0,
      "entities": [
        {
          "name": "AccountService",
          "status": "bothDiffer",
          "localPath": "/projects/acme/force-app/main/default/classes/AccountService.cls",
          "orgId": "01p000000000001AAA",
          "localHash": "27ff45bbc204",
          "orgHash": "154c010ef21f",
          "actions": ["retrieve", "deploy", "open"]
        }
      ]
    }
  ],
  "pendingTypes": [
    { "type": "CustomObject", "reason": "typeNeedsListMetadata", "detail": "..." }
  ],
  "limits": ["Managed-package members are excluded. ..."]
}

actions names only the operations Nimbus judged unambiguous for that row — retrieve when the org has it, deploy and open when exactly one local file backs it. A name defined in two package directories gets neither, because "which file" has no answer.

In the IDE

The IntelliJ plugin renders the same tree on the Drift tab beside the Org browser, with Retrieve and Deploy on the rows that support them. Both hand off to the same paths the editor's right-click menu uses, so the git overwrite guard and the local Apex check before a deploy behave exactly as they do elsewhere.

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

Machine-readable schema

--json skips the TUI and writes the full schema to stdout: every table with its columns (name, dataType, isNullable, isPrimary, isReference), its inferred foreign keys in both directions (references and referencedBy), and its rowCount. Tables are sorted by name so two dumps of the same database diff cleanly.

# The whole schema
nimbus schema --json

# Which tables point at Account?
nimbus schema --json | jq -r '.tables[] | select(.references[]?.toTable == "account") | .name'

# Row counts, largest first
nimbus schema --json | jq -r '.tables[] | "\(.rowCount)\t\(.name)"' | sort -rn

The document is built through a runner rather than read straight off the connection, so the tables your project's metadata implies exist before they are described — the same document the editor plugins read from the daemon, so a script and an IDE see one schema.

Piping without --json is unchanged: it still prints the plain table list, because nimbus schema | grep Account is a table-name search and answering it with JSON would break every script that does it.

Flags

nimbus soql

Run a SOQL query and print the rows. By default it queries this project's local database — the same one your tests run against, seeded the same way — so you can check what a test will actually see before you write the assertion.

# Query the local database
nimbus soql "SELECT Id, Name FROM Account WHERE Name LIKE 'Acme%'"

# Show the PostgreSQL it translates to, without running it
nimbus soql --preview "SELECT Id, Account.Name FROM Contact WHERE CreatedDate = LAST_N_DAYS:7"

# Ask a real org the same question
nimbus soql -o my-org "SELECT Id, Name FROM Account LIMIT 5"

# Structured output for scripts and editors
nimbus soql --json "SELECT Id, Name FROM Account" | jq '.rows[].Name'

The local mode runs through the same runner configuration nimbus exec builds — seeded rows, org defaults and managed-package stub namespaces included. A console that answered differently from an @isTest method would be worse than no console at all.

Three modes, one query

• Local (default) — executes against the embedded Postgres and prints an aligned grid with a row count and timing. No box drawing and no colour: the output is meant to survive a pipe into grep or awk.
• --preview — translates the query to PostgreSQL and prints the SQL without running it. The fastest way to understand why a query returned what it did: you see the joins a relationship field produced and the window a date literal resolved to. It describes the local translation, so it cannot be combined with an org.
• -o <alias> — forwards the query to that org instead, so the same command answers "and what does the org say?". It goes straight to the org's REST API (see nimbus org doctor) and is bounded by a two-minute timeout, so an expired session fails with an error rather than blocking forever on a login prompt.

Flags

--json carries columns, rows, count, the generated sql, the resolved object and the elapsed time. A failed query emits the document with an error field and exits non-zero — one thing to parse, and the verdict on the exit code rather than on whether output appeared.

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

This is the destructive one. If you only want the rows gone — schema, daemon and synced metadata intact — use nimbus data reset instead and skip the nimbus sync that this makes necessary.

nimbus data

Operate on the rows in the local database, as opposed to the database itself (nimbus db) or the whole project state (nimbus reset).

# Empty every table; keep the schema, the daemon and the database
nimbus data reset

# No prompt (required when stdin is not a terminal)
nimbus data reset --yes

The prompt needs somebody to answer it, so a script, a cron job or a CI step has to pass --yes. Without it the command refuses and says so — including under < /dev/null, which looks like a terminal to the usual check and used to fail as though someone had declined.

nimbus data reset vs nimbus reset

The distinction is the point of the command, and reaching for the wrong one costs a nimbus sync.

Seed rows (profiles, users, ApexClass records) are cleared along with everything else, but every run re-creates them before it executes anything — so the next nimbus test starts from a clean standard org rather than a broken one. Use it when scratch data has accumulated into a state you no longer trust.

Flags

Rows are deleted, so it asks first — the same rule the release commands apply to a production deploy: a non-interactive caller must have said so on the command line, because there is nobody there to ask.

nimbus data branch

Keep more than one state of the local org at once. A data branch is a copy of this project's local database, made with a PostgreSQL CREATE DATABASE … TEMPLATE inside the cluster Nimbus already runs for the project. At the size a local org reaches that is a file copy — tens to a few hundred milliseconds — and switching between branches changes one word in a connection string.

# Copy the current data into a new branch and switch to it
nimbus data branch experiment

# Copy a specific branch rather than the current one
nimbus data branch --from default hotfix

# What exists, what it costs, which one is in use
nimbus data branches

# Move between them
nimbus data switch default
nimbus data switch experiment

# Remove one (refuses the branch in use)
nimbus data branch --delete experiment

What comes along

Everything in the database: tables, rows, the seed records a run creates, and any per-worker schemas the test runner built. There is no re-seed, no re-sync and no org round trip — the copy is of the database as it stands.

What this is not

This is local dev data, not a migration tool and not a backup. Branches live inside .nimbus/db with everything else, so nimbus reset deletes them along with the rest of the local database, and so does a daemon shutdown that tears the database down. Nothing here versions your schema, moves data between orgs, or survives a machine. It exists so you can run the destructive test and still have the state you had before it.

Branch names

Lowercase letters, digits, - and _, starting with a letter or digit, up to 40 characters. default is the project's original database: it is where nimbus data switch default goes back to, and it is not a branch you create or delete.

The daemon

PostgreSQL will not copy or drop a database while a session is connected to it, and the daemon holds one for its whole life. So a branch or a switch asks the daemon to move: it closes its pool, performs the operation and reopens on the result, in one round trip.

If a separate Nimbus process is mid-run against the branch being copied or deleted, the command refuses rather than severing it. If the daemon cannot be moved for some other reason, the switch still takes effect for everything started afterwards and Nimbus says so — a test run detects the mismatch and connects to the right branch itself rather than silently reading the previous one.

Flags

Following the git branch

Off by default. Turn it on and Nimbus creates and switches to a data branch matching the checked-out git branch whenever it changes, printing one line to say what it did:

# nimbus.properties
nimbus.data.branch.follow-git=true

The git branch name is lowercased and anything outside the allowed characters becomes a hyphen, so feature/NIM-42 becomes feature-nim-42. It is evaluated when a test run starts and when the daemon starts — the two moments that genuinely are opening the project. A detached HEAD names a commit rather than a branch and is left alone, and deleting a git branch never deletes its data.

It is off by default deliberately: a checkout silently moving your local org is a surprise nobody asked for, and every branch you touch costs another copy of the database on disk. nimbus data branches shows what that adds up to.

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 metadata

Move metadata between the org and this project: pull what a run could not resolve, push files, a directory or a manifest back.

# Retrieve everything the last run reported missing
nimbus metadata retrieve -o my-org

# Machine-readable summary
nimbus metadata retrieve -o my-org --json

# Push a class, a directory, or a manifest
nimbus metadata deploy AccountService -o my-sandbox
nimbus metadata deploy force-app/main/default/permissionsets -o my-sandbox
nimbus metadata deploy --manifest manifest/package.xml -o my-sandbox

How it travels

Both directions go through Nimbus's own Salesforce APIs where they can, and hand the identical sf invocation to the Salesforce CLI where they cannot. What decides which is one question: does source format keep the type in a single file?

The split is per call, not per component: a manifest naming even one type from the third row goes to the Salesforce CLI whole. Two retrieves are two snapshots of an org that changed in between, and two deploys are two transactions — which makes rollback-on-error a promise a pair of them cannot keep.

nimbus org doctor prints the exact boundary for your org, and org.native=false in nimbus.properties sends everything through the Salesforce CLI as before.

nimbus metadata retrieve

Every run that hits a class, object, field, custom metadata type or label Nimbus has no source for reports it and writes the whole list to manifest/nimbus-missing.xml. This command reads that manifest and retrieves the items — and then stops. Not re-running the tests is the difference between it and nimbus test --fetch-missing.

Transport follows the table above. An Apex-only manifest comes back over the Tooling API and lands in the same files at the same paths, each with its -meta.xml companion. A manifest naming the single-file types comes back over the Metadata API as a package and is converted to source format on the way to disk. A manifest naming an object, a field or a single label goes through a single sf project retrieve start --manifest call instead.

Object and field schemas are separate again: they come back as REST describes written to .nimbus/schemas/, because that is what the runtime actually reads.

An org is required and must be explicit — -o <alias> or a default target-org. Run the tests again afterwards: retrieving one class often reveals the next missing reference behind it, so a project with deep unresolved chains takes a few rounds.

Flags

Progress goes to stderr, so --json owns stdout and a plain run still shows what is happening during a retrieve that can take a minute. Any failed item exits non-zero.

nimbus metadata deploy

Push files, directories or a manifest into an org. An argument is a file path, a directory, or a bare Apex name resolved against the project's package directories.

nimbus metadata deploy AccountService -o my-sandbox
nimbus metadata deploy force-app/main/default/classes/AccountService.cls -o my-sandbox
nimbus metadata deploy AccountService AccountServiceTest -o my-sandbox
nimbus metadata deploy force-app/main/default/permissionsets -o my-sandbox
nimbus metadata deploy --manifest manifest/package.xml -o my-sandbox
nimbus metadata deploy AccountService -o my-sandbox --check-only

A handful of .cls or .trigger files keeps the Tooling API's metadata-container flow — the same one the Salesforce IDE plugins use to save a file — because that is the path that reports the Apex compiler's own errors with line and column:

Deploy failed: 1 component error.

  AccountService (line 7, column 13): Variable does not exist: bogus

Anything wider goes over the Metadata API as a package, and anything the third row of the table above names goes to the Salesforce CLI with the identical invocation. Only a bare name is Apex-specific: other types' member names are not unique across types — an "Account" is a layout, a tab and a profile — so pass a path for those.

A deploy rolls back as a unit, so one component's error means none of them landed. Any component error exits non-zero.

This command is the inner loop, not the release: it is for the twenty seconds between changing a file and wanting it in a sandbox. For the full assurance cycle — staged release, validation, tests, receipt — use nimbus deploy instead.

Conflict detection

A deploy replaces the org's copy, and the org does not ask whether yours was derived from theirs. So before anything is pushed, Nimbus asks the org one question: has this class changed since this working copy last took it?

It can answer that because every time Nimbus writes a file from an org — a retrieve — or pushes one to it, it records the org's LastModifiedDate, who saved it, and a hash of the bytes involved. That record is the sync base, and it lives in .nimbus/org-base.json, keyed by org id. It describes this working copy, so it belongs outside version control — committing it would hand a teammate a claim about their files that was never true of them.

There are four outcomes, and only one of them stops anything:

Refusing to deploy: the org's copy is newer than yours.

  AccountService changed in the org on 2026-08-26 11:02 by Dana Ruiz, after your last retrieve.

Deploy anyway with --force, or take the org's copy with:
  nimbus sf project retrieve start -m ApexClass:AccountService -o my-sandbox

Brownfield projects start with no bases at all, which is why a missing one warns rather than refuses:

No sync base for AccountService — nimbus can't tell whether the org copy changed. Deploying anyway.

That warning is self-limiting: a successful deploy records a base, so from the first one onward the file is checked. Warnings and notices go to stderr, so --json still owns stdout — under --json a refusal is a single document with "status": "Refused" and the same sentence in message.

Three deliberate limits. --check-only is never refused — it saves nothing, so it reports the conflict and compiles anyway. A check that cannot run (unreachable org, no login, org.native=false) prints one line and lets the deploy through; conflict detection is never a reason a deploy fails. And a class the org does not have yet is a create, so it is silent. Use nimbus org status to read the bases without deploying anything.

Flags

nimbus rename

Rename a custom field or a custom object and update every place this project refers to it — Apex, SOQL, metadata XML, LWC, Aura and Visualforce — with a preview you approve before anything is written.

# Preview. Nothing is written.
nimbus rename field Account.Legacy_Code__c Account_Code__c

# Write the changes
nimbus rename field Invoice__c.Amt__c Amount__c --apply

# Rename an object: its references, its directory, and every file named after it
nimbus rename object Invoice__c Bill__c --apply

# The plan as JSON, for an editor to drive
nimbus rename field Account.Legacy_Code__c Account_Code__c --json

The preview is the product. It lists every file, every line, old above new, and the reason that line was believed to mean your field. Nothing is written without--apply, and an apply is all-or-nothing: every file is re-hashed against the plan first, and one file that changed underneath aborts the whole thing before a byte is written.

What gets updated, and why each one is safe

What it will not decide for you

A field and the object it looks up routinely share an API name —ServiceDelivery__c.ProgramEngagement__c pointing atProgramEngagement__c. So a field rename never touches a slot only a type can occupy, and an object rename never touches a slot only a field can occupy. Everything else that mentions the name and cannot be attributed is listed as an unresolved candidate for you to check by hand — never silently skipped, and never silently edited. A query assembled by string concatenation is the common case:'SELECT ' + fields + ' FROM Account' names no field this reading can attribute, so the fragment is reported.

Every plan also carries what it cannot see: Apex comments are ignored entirely, receiver types are resolved from declarations in the same file only,stubs/ is skipped because those API names belong to an installed package, and the whole thing covers your source — the org-side rename that moves the data and preserves history is still Setup → Object Manager.

nimbus rename field

The field is named with its object, because a bare field name is not a field: two objects can both declare Status__c, and which one you mean decides which mentions in your source are yours. The new name may be given bare or with the same object prefix.

nimbus rename object

Renames a custom object, custom setting or custom metadata type, along with the directory its metadata lives in and every file whose name leads with the API name — its layouts, its tab, its quick actions, its workflow, its object translations.

nimbus record

Set up managed-package record/replay in one command: pull the packages' stubs from an org, then run the matching tests with recording on. After it finishes, plain nimbus test replays the recorded answers offline — no org, no flag.

nimbus record -o my-org                # pull stubs, then record the whole suite
nimbus record -o my-org MyTestClass    # pull stubs, then record one class
nimbus test                            # from now on: replays offline

It is exactly nimbus stub pull followed by nimbus test --record, which both remain available individually — stub pull when you want the package's shape without running anything, test --record to re-record once stubs exist. The pull is additive (project metadata and existing stub files are left alone), so re-running after a package upgrade is safe; recording re-records each matched test method wholesale.

Recordings land in .nimbus/recordings/, one JSON file per test method, and are meant to be committed — the team and CI then run against the same answers with no org access. Details of the record/replay mechanics are in the stub documentation.

nimbus stub

Scaffold and inspect stubs/ — the directory Nimbus loads before the main source tree so tests can reference managed-package classes, custom objects and fields, and custom labels 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.

Scaffold a custom label

nimbus stub label writes a label into stubs/labels/ so Apex that reads it resolves to a real value instead of an empty string. Unnamespaced labels land in CustomLabels.labels-meta.xml; a managed-package label lands in <ns>.labels-meta.xml, where the file name is what declares the namespace — the metadata format has nowhere to record another package's namespace, and Label.<ns>.<Name> is the only legal Apex spelling for one.

# Unnamespaced → stubs/labels/CustomLabels.labels-meta.xml
nimbus stub label Welcome_Message --value "Hello there"

# Either form is accepted for a managed-package label
nimbus stub label npe03.RecurringDonationStageName --value Pledged
nimbus stub label RecurringDonationStageName --namespace npe03 --value Pledged

# Several at once (value defaults to the label name)
nimbus stub label Alpha Beta Gamma --namespace npe01

Re-running is safe: a label that already exists in the file has its value updated in place instead of being duplicated. Apex then reads Label.npe03.RecurringDonationStageName or System.Label.Welcome_Message as usual.

Pull labels, fields, and classes from an org

nimbus stub pull reads an org that has the managed packages installed and writes the parts your project is missing into stubs/. Labels come from the Tooling API's ExternalString entity — the only place another package's labels are readable — fields come from SObject describes, and classes come from ApexClass.SymbolTable, which exposes the exact global surface of an installed package: every method overload, constructor, property, inner class, and enum. It needs the Salesforce CLI (sf) on PATH and an authenticated org.

# Everything the org has that the project doesn't
nimbus stub pull --org dev

# Just the packages you care about
nimbus stub pull --org dev --namespaces npe01,npe03,npo02

# See what it would do first (prints every sf command it runs)
nimbus stub pull --org dev --namespaces npe03 --dry-run

# Class stubs for one package, without running anonymous Apex
nimbus stub pull --org dev --namespaces Nebula --classes-only --no-exec

# Narrow the describes to specific objects
nimbus stub pull --org dev --objects Contact,Opportunity --fields-only

What gets written. stubs/labels/<ns>.labels-meta.xml for labels, stubs/objects/<Obj>/fields/<ns__Field__c>.field-meta.xml for namespaced fields on objects your project references, stubs/objects/<ns__Obj__c>/<ns__Obj__c>.object-meta.xml plus its fields for namespaced objects the project uses but does not define, and stubs/<ns>/<Class>.cls for every global class of the pulled namespaces.

Class stubs record the org's behavior, not a guess. Signatures are the org's own, so the overloads your tests call resolve the way the package declared them. Bodies are stubbed with usable defaults: builder methods hand back a constructed object instead of null, collection returns come back empty instead of null, and enums keep their declaration order so ordinals survive. Global constants have no value in a SymbolTable, so their values are read by running one short anonymous Apex script per class against the org — pass --no-exec to skip that. A recorded constant keeps its final modifier; an unrecorded one loses it so your tests can assign it. Two fidelity limits are inherent to the source: the SymbolTable erases generics (a List<Contact> parameter arrives as List, rendered as List<Object>, and overloads that collapse under erasure are deduplicated and reported), and a @Deprecated class is invisible to anonymous Apex, so its constants stay null.

--data records the package's data, opt-in. Custom-metadata records become ordinary stubs/customMetadata/<Type>.<Record>.md-meta.xml files, so SOQL against the type and getInstance(name) return what the org returns. Custom-setting rows become seed lines in a fenced, regeneratable block of nimbus.properties: the org-wide default of a hierarchy setting as nimbus.seed.org-default.<Object>, list-setting rows as nimbus.seed.record.<Object>.<Name>. Nothing outside the fence is ever touched, and a value the property format cannot carry (commas, equals signs, line breaks) is skipped by name rather than written wrong. After a pull that adds schema, run nimbus sync so the next test run sees it — the pull reminds you.

Which objects get described. The objects your project ships objects/ metadata for, the standard objects packages usually extend (Account, Campaign, Contact, Lead, Opportunity), any namespaced object name your Apex mentions, and the lookup targets of the fields it pulls.

What it never touches. Anything the project already defines, and anything already under stubs/ unless --force is passed — so re-running after a package upgrade adds what's new and leaves your hand edits alone. Every file written and every skip is printed, and the summary line counts both.

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.

Recording per-call behavior

A stub carries a package class's shape; its method bodies return type-defaults. When a test depends on what the real package actually returns, record it once against an org and replay it offline from then on:

nimbus record -o my-org MyTest          # one command: pulls stubs, then records against the org
nimbus test MyTest                      # replays from .nimbus/recordings/ - no org connection
nimbus test MyTest --no-replay          # ignores the recordings, runs the stub bodies
nimbus test MyTest --record -o my-org   # re-records without re-pulling stubs

Recordings are plain JSON, one file per test method, written as each method finishes so an interrupted run keeps what it captured. They are meant to be committed: the rest of the team and CI then run against the same answers with no org access. Re-recording a method replaces its file wholesale; other methods are untouched.

Fallback is always the stub body. A call that was never recorded, an argument with no JSON form, an org that refuses the forwarded call because the installed package version drifted — each prints one line and runs the stub body. Adding recordings to a suite cannot break it, and --record is never harder to complete than an ordinary run.

Scope. Static methods only — a local stub instance has no org counterpart to forward to, so instance methods keep their stub bodies. Callouts are deliberately out: the platform refuses a callout in a test without Test.setMock, so a deployable test already ships its own mocks. Forwarding is capped at 200 org round trips per run.

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, IntelliJ, Neovim DAP — can launch this command to step through Apex tests with real breakpoints, a call stack view, and expandable local-variable inspection. This is the debug transport both first-party editors use automatically: the VSCode extension launches it as a DebugAdapterExecutable, and the IntelliJ plugin drives it through LSP4IJ's DAP integration. You don't need to configure either editor to get it — it's the default.

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

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

Beyond stepping and inspection, the server supports: conditional, hit-count, and log-point breakpoints (evaluated in the paused frame); caught/uncaught exception breakpoints, each optionally filtered to a comma-separated list of Apex exception types; expression evaluation for the debug console, watch expressions, and hovers; and editing a variable's value in place from the Variables pane (live sessions only — a replay session has nothing to write to).

Launch arguments (set in .vscode/launch.json, an IntelliJ run configuration, or equivalent) select one of four session kinds via mode:

Calling one method directly, without a wrapping test:

{
  "type": "nimbus-apex",
  "request": "launch",
  "name": "Debug Method",
  "mode": "method",
  "method": "Calculator.add",
  "isStatic": true,
  "returnType": "Integer",
  "parameters": [
    { "name": "a", "type": "Integer", "value": "2" },
    { "name": "b", "type": "Integer", "value": "3" }
  ]
}

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.

Flow debugging Pro

Breakpoints work in .flow-meta.xml files: a flow element is defined at a concrete place in its XML, and a breakpoint set on — or anywhere inside — an element's block stops the session before that element executes. While paused, the stack shows a flow frame (flow name · current element), and its scopes expose $Record (plus $Record__Prior on updates), the flow's variables, and the current element's metadata. next advances to the next element — a decision's taken branch is the element you land on — stepIn on an Apex-action element enters the method, and stepOut runs the flow to completion.

This works in the default launch mode — a test whose DML fires a record-triggered flow stops at flow breakpoints mid-DML — and in the dedicated flow mode, which runs one record-triggered flow against a single in-memory record in a rolled-back database context, no Apex test required:

{
  "type": "nimbus-apex",
  "request": "launch",
  "name": "Debug Flow",
  "mode": "flow",
  "flow": "Account_Set_Rating",
  "record": { "Name": "Acme", "Industry": "Tech" },
  "triggerType": "beforeInsert"
}

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 fuzz Pro

Property-based testing for trigger paths. Nimbus generates records that are valid per your project's schema - required fields populated, picklist values from the real value set, string lengths within bounds, required lookups satisfied by a generated parent record - and runs each one through the DML pipeline with your triggers firing. Alongside typical values it generates the adversarial ones your triggers actually meet in production: null in every nillable field, empty strings, boundary numbers and dates, unicode.

This is the QuickCheck/Hypothesis technique, applied to triggers. It has never been practical for Apex because an org grants 150 DML statements per transaction and each round-trip costs seconds. Locally, every run executes in its own rolled-back transaction with fresh static state, in milliseconds - hundreds of generated records take seconds.

A validation-rule rejection or an addError is not a failure - that is the object doing its job, and it is tallied separately. A failure is the pipeline surfacing a defect: an unhandled exception inside a trigger, a non-DML exception escaping the DML, or an engine-level error. On the first failure the input is shrunk - fields toward null, strings shorter, numbers toward zero, re-running the pipeline at every step - until only what triggers the bug remains, and reported as a paste-ready Apex snippet for nimbus exec.

# 200 generated inserts through the Account trigger pipeline
nimbus fuzz Account

# More runs - same milliseconds each
nimbus fuzz Account --runs 1000

# Also update each record after a clean insert (before/after update paths)
nimbus fuzz Account --update

# Replay a reported run exactly
nimbus fuzz Account --seed 741253

# Machine-readable report
nimbus fuzz Case --json

A found failure reports the minimal reproducing input:

FAILURE on run 8 of 200 (seed 741253), insert phase
  UNKNOWN_EXCEPTION: Insert failed. First exception on row 0; first error:
  UNKNOWN_EXCEPTION, Attempt to de-reference a null object: []

Minimal failing record:
  Name = 'a'
  Rating = 'Hot'

Repro (paste into `nimbus exec`):
  Account rec = new Account(Name = 'a', Rating = 'Hot');
  insert rec;

Shrunk in 26 steps (32 executions). Replay this run: --seed 741253

Flags

Exit code is non-zero when a failure is found, so nimbus fuzz can gate CI. Deliberate rejections are tallied by DML status code in the report - a large REQUIRED_FIELD_MISSING count means generated records are missing a constraint, not that your triggers are healthy.

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
        AccountServiceTest.testCreate
          replay: nimbus trace AccountServiceTest.testCreate --run 2026-08-26T02-08-59_5ba1f24e

    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

Each failure carries the command that reopens its recorded trace, the same as nimbus test — see replay on failure. Pass --no-trace-on-failure to skip recording.

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

nimbus history get <run-id>

The list carries per-run totals only. Every per-test result — its status, duration and failure message — lives in the stored record, and history get prints it. show is an accepted alias.

# Everything recorded for one run
nimbus history get 1756060500123456789

# The timestamp matches too, and is easier to type
nimbus history get 20260824T1015

# Just the failures
nimbus history get 20260824T1015 --json | jq '.results[] | select(.passed == false)'

The run ID is the id field from nimbus history — a nanosecond timestamp. The store matches it as a substring of the record's file name, <timestamp>_<id>.json, so a leading chunk of the ID works and so does the human-readable timestamp. The output leads with the run's pattern, timing, totals and the environment it ran under (Nimbus version, worker count, isolation mode, whether it was a full run), then one line per test with its failure message.

JSON is the default when stdout is not a terminal, matching the run list — so piping into jq needs no flag. --json forces it when it is.

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 Label.Order_Error   # which classes read one custom label
nimbus graph Handler_Config__mdt # who queries one custom metadata type
nimbus graph SObject.Account     # who reads it, who writes it, what fires
nimbus graph Permission.Can_Approve_Orders  # what is gated on one custom permission
nimbus graph Resource.Test_Accounts         # what loads one static resource
nimbus graph Flow.Order_Automation          # what fires one flow, and what it calls
nimbus graph AccountService --json

Bare nimbus graph prints the orientation view: how many classes, triggers and edges, the cycle count, the custom-label count with how many of them nothing in Apex reads, the number of custom metadata types, how many SObjects the code touches, the custom permissions with how many nothing in Apex checks, the static resources with how many nothing in Apex loads, the flows with how many of them are inactive but still wired to something, 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.

Custom labels

Custom labels are nodes in the graph, and Label.<Name> is a root selector: nimbus graph Label.Order_Error reports the label's value and the classes that read it. Reads spelled out in source — Label.Order_Error, or System.Label.get with a constant name — are found by reading the code. Reads through a computed name are not visible to any syntactic reading; those come from the last coverage run, where the interpreter resolved the name as the read happened, and are listed separately as observed.

Label edges cover Apex only. References from Flows, LWC, Aura and formulas are not read, so unreferenced in the overview line means unreferenced from Apex — it is not a delete list. Dynamic reads carry the freshness caveat that applies to every observed edge: a read on a path the coverage run did not execute is not there, and one recorded before the code changed may no longer happen.

Custom metadata types

Custom metadata types are nodes too, and the API name is the root selector — no prefix to learn, since __mdt is reserved:

$ nimbus graph Handler_Config__mdt
Handler_Config__mdt — custom metadata type
    4 record(s)

  Queried by
    1 directly, 12 transitively
      TDTM_TriggerHandler

  Dispatches to (4) — classes named by record field values
      ACCT_IndividualAccounts_TDTM
      ...

  Tests reached syntactically (1)
      TDTM_TriggerHandler_TEST

  Classes a coverage run observed being dispatched to (4)
      ACCT_IndividualAccounts_TDTM
      ...

Three readings, kept apart. Queried by is read from source: SOQL against the type, getAll, getInstance. Dispatches to is a heuristic — a record's field values are matched against the class registry, and a value that names a class becomes an edge — so it can over-claim (a text field that happens to read like a class name) and under-claim (a handler named by a value the records do not carry). The third is measurement: after a coverage run, Type.forName(...).newInstance() resolved an exact class name while the code ran, and that dispatch is recorded as observed.

This closes the gap the limits above only apologised for. A trigger dispatching through custom metadata used to reach its handler with no reference to follow; AccountTrigger → TDTM_TriggerHandler → Handler_Config__mdt → ACCT_IndividualAccounts_TDTM is now a chain you can walk. The caveat travels with it — the handler side is a guess until a coverage run confirms it.

SObjects

Objects the code queries or writes are nodes as well, and SObject.<Name> is the root selector — the prefix exists because a class may legitimately be called Account:

$ nimbus graph SObject.Account
Account — SObject

  Queried by (19)
      AccountService
      ...

  Written by (19) — these fire its triggers
      AccountService
      ...

  Triggers on this object (1)
      AccountTrigger

  Record-triggered flows on this object (1)
      Probe_Account_Flow

  Tests reached syntactically (20)
      AccountServiceTest
      ...

  Classes a coverage run observed querying it (1)
      DynamicSelectorTest

Read and write are separated because they are different questions. Written by is the one that carries consequences: a write reaches every trigger the project declares on that object, so the object-to-trigger edges are certain rather than inferred — this is where a trigger finally gets inbound edges, and the caveat that they "come from DML, which this reading cannot derive" no longer applies.

Objects named in source — a SOQL FROM clause, a typed variable under insert, X__c.getInstance() — are found by reading the code. Dynamic access is not visible to any syntactic reading: Database.query with a computed string, DML on a generic SObject or a List<SObject>. Those come from the last coverage run, where the SOQL translator and the DML executor knew the concrete object, and are listed separately as observed — which is how an fflib-style selector layer becomes visible at all. The usual freshness caveat applies: access on a path the run did not execute is not there. Readers and writers cover Apex only; Flows, LWC, Aura and integrations touch objects without appearing here.

A bare argument is still resolved as a class first, since that is what it has always meant. When no class answers, __c and __e names resolve to the object silently — the platform reserves those suffixes for schema — and any other bare name gets an error that suggests the SObject. form when an object of that name exists. Nodes exist only for objects this code touches or a trigger runs on; this is not the org's schema.

Custom permissions and static resources

Both are nodes too, both are leaves, and both have their own root selector — Permission.<Name> lists the classes gating on a custom permission, Resource.<Name> the classes loading a static resource:

$ nimbus graph Permission.Can_Approve_Orders
Can_Approve_Orders — custom permission
    "Approve Orders"
    force-app/main/default/customPermissions/Can_Approve_Orders.customPermission-meta.xml

  Checked by
    1 directly, 2 transitively
      ApprovalGate

  Tests reached syntactically (1)
      ApprovalGateTest

  Classes a coverage run observed checking it (1)
      ApprovalGate

$ nimbus graph Resource.Test_Accounts
Test_Accounts — static resource
    text/csv
    force-app/main/default/staticresources/Test_Accounts.resource-meta.xml

  Loaded by
    1 directly, 1 transitively
      ApprovalGateTest

  Classes a coverage run observed loading it (2)
      ApprovalGateTest
      FixtureLoader

  Observed but named nowhere in source (1) — loaded through a computed name
      FixtureLoader

Checks and loads spelled out in source — FeatureManagement.checkPermission with a constant name, Test.loadData or a PageReference('/resource/…') — are found by reading the code. A name assembled at runtime is not visible to any syntactic reading; those come from the last coverage run, where the permission or resource resolved to an exact name as the check or load happened, and are listed separately — with the observed-only ones called out as named nowhere in source.

Only Apex is read, which matters more here than for any other kind. A permission granted through a permission set or a profile, or enforced in a Flow, a formula or a validation rule, is invisible to this view; so is a resource referenced from LWC, Aura, Visualforce or markup. Unchecked and unread in the overview therefore mean from Apex — neither is a delete list. The usual freshness caveat applies to the observed side: a check on a path the coverage run did not execute is not there.

Flows

Nimbus runs record-triggered flows itself, so they are nodes too, and Flow.<Name> is the root selector:

$ nimbus graph Flow.Order_Automation
Order_Automation — flow
    Draft
    force-app/main/default/flows/Order_Automation.flow-meta.xml

  Fired by DML on ParentObj__c
    1 class(es) write that object
      OrderIntakeService

  Calls Apex (1)
      AccountService

  Calls subflows (1)
      Probe_Account_Flow

  Writes objects (1) — these fire their own automation
      ChildObj__c

  Tests reached syntactically (1)
      OrderIntakeServiceTest

A flow is not a leaf. It has edges in both directions: inbound from the object it triggers on, outbound to the Apex actions it invokes, the subflows it runs and the objects its record elements read and write. That completes the DML edge — a write to an object now reaches both its triggers and its record-triggered flows, so SObject.Account lists the flows next to the triggers and the blast radius of an insert includes the automation a flow starts. Flows are also the first non-class nodes that can sit inside a cycle, through a subflow loop or a flow calling a class that writes the flow's own trigger object; --cycles reports such a loop as nodes rather than classes.

Status travels with the node and changes what its edges mean. A Draft, Obsolete or invalid flow still owns every edge above, but it does not run on record changes — those edges describe what it would reach if it were activated. The overview counts inactive-but-connected flows separately for that reason, and the detail view says it outright rather than letting a full-looking graph imply the automation is live.

Edges are read from the flow's own metadata: the object it is triggered on, the Apex actions and subflows it names, and the objects its record elements touch. An action invoked through a name assembled at runtime is not read, and neither is anything a flow reaches through a screen component. Nor is the launch path of a screen flow started from a page, a button, a quick action or a process — such a flow appears with no inbound edge. Being fired by DML is derived rather than referenced (nothing in an org names a record-triggered flow), and whether a particular write meets a given flow's entry conditions is not evaluated here.

Agentforce agents

Where a project ships Agentforce metadata, its agents, topics and actions are nodes too, and each action's edge lands on the Apex class or Flow its invocationTarget names. A class or flow reached that way says so — Reached by agent actions (1) · Support_Agent › Submit Case — which is a caller no reading of Apex can find, because nothing in Apex references an agent back. For an autolaunched flow it is the only inbound edge there is. Which action a planner selects for a given utterance is Salesforce's stochastic runtime and is not modelled at all. An action whose target this project does not ship, or whose target type nimbus does not run, carries no edge and is counted separately — nimbus agent list names which. A project with no agent metadata sees none of this and pays nothing for it.

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. Non-class nodes — custom labels, custom metadata types, SObjects, custom permissions, static resources and flows — stay out of the dot and mermaid exports unless --include-metadata is passed (--include-labels adds the labels alone), so that ceiling keeps measuring the class graph; the JSON always carries them. Pointing the command at a metadata root overrides the default, since stripping the node you asked about would draw its neighbourhood with the subject missing.

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. Names appear on hubs first and fade in as you zoom. In VS Code, double-clicking a node opens the file.

The resting view is classes and triggers only. Custom labels are added from the display panel — drawn as squares, with the label's value and its reader count in the tooltip; a second checkbox adds the labels nothing reads. Searching does not wait for either: a query that matches a label reveals it while the query is active, so a label that exists in source never comes back as no match. A label: prefix restricts the search to labels.

show custom metadata adds the custom metadata types the same way, drawn as diamonds; the tooltip gives the record count, how many classes query the type, and how many classes its records dispatch to. Their outbound edges are the heuristic ones, and the legend says so. Search reaches them while the toggle is off too, and an mdt: prefix restricts the search to types.

show sobjects adds the objects, drawn as triangles; the tooltip gives the reader count, the writer count and how many triggers a write fires, and an object reached only through dynamic access is drawn in the same orange as every other runtime-observed node. Search reaches them with the toggle off, and an obj: prefix restricts the search to objects.

show permissions & resources is one toggle for the two smallest kinds: custom permissions are drawn as pentagons, static resources as tall boxes. The permission tooltip gives the permission's label and how many classes check it, the resource tooltip its content type and how many classes load it, and either is drawn in the runtime-observed orange when nothing in source names it. Both have their own search prefix — perm: and res: — and search reaches them while the toggle is off, like every other kind. These two are also the first metadata nodes that open: they carry a file, so double-clicking one opens its -meta.xml, where double-clicking a label, a type or an object frames its neighbourhood instead.

show flows is a toggle of its own — an org runs hundreds of flows and "which flows are there" is a question worth its own switch. They are drawn as an outline hexagon: the trigger's shape in the trigger's amber, unfilled and a size step smaller, because a flow is automation rather than data and belongs next to triggers rather than next to the squares and triangles. A flow that is not Active is drawn with a dashed outline — its edges exist but it does not run — and the tooltip gives the status, what fires it, how many classes and subflows it calls, and how many objects it writes. A flow: prefix restricts the search to flows, search reaches them while the toggle is off, and double-clicking one opens its .flow-meta.xml.

Flags

nimbus flow

Inspect the Flows in a project without opening an org. nimbus already parses every .flow-meta.xml to fire record-triggered flows during tests; this command family exposes that same parse as something you can read. Free.

nimbus flow list                       # every flow: name, type, trigger, status
nimbus flow graph Order_Automation     # one flow's elements and connectors
nimbus flow graph Order_Automation --json
nimbus flow graph Order_Automation --mermaid
nimbus flow graph Order_Automation --out order.html   # self-contained interactive viewer
nimbus flow graph force-app/main/default/flows/Order_Automation.flow-meta.xml

List

nimbus flow list tables every flow in the package directories — name, label, type, trigger object, status. Draft and Obsolete flows are listed like Active ones: they are still source, and the flow that no longer runs but still names an Apex class is exactly the one worth finding before that class is deleted.

Graph one flow

nimbus flow graph <name> prints the flow's identity — process type, trigger, entry-condition count, status, API version, resource counts — then every element with its source line and every connector. The argument can also be a .flow-meta.xml path, which works outside a Salesforce project too.

$ nimbus flow graph Order_Path

Order_Path — flow
    "Order Path"
    AutoLaunchedFlow · Active · API 59.0
    RecordAfterSave on Order__c (CreateAndUpdate)

  Elements (5)
           start                Start  — RecordAfterSave on Order__c (CreateAndUpdate)
       20  decision             Check Amount  — 1 rule
       37  recordUpdate         Save Order  — update Order__c
       ...

  Connectors (6)
    Start → Check_Amount
    Start → Notify  [scheduled: Reminder (+3 Days)]
    Check_Amount → Save_Order  [rule: Large order]
    Save_Order → Notify  [fault]

Every edge is typed rather than merely drawn: decision rules carry their rule label, the loop's next-value and no-more-values connectors are split, scheduled paths carry their offset, and fault connectors are marked — so a renderer can dash the error path without re-deriving flow semantics. Element line numbers come from the same index the flow debugger keys breakpoints by.

Exports

--json emits the nimbus.flowgraph/v1 document; --mermaid and --dot export diagrams with fault edges dashed and rule edges labeled. With --out, a .html path writes a self-contained interactive viewer — pan, zoom, hover to light a step's neighbourhood, click to pin its facts — with no server and no external assets, and a .md path wraps the Mermaid diagram so VS Code, GitHub and Obsidian render it.

In the IDE

IntelliJ has the same viewer as View Flow: in the editor and Project-view right-click menus of any .flow-meta.xml, and on the flow's editor capsule, which also shows the flow's identity facts (label, type, trigger object, status, API version). Double-clicking a node opens the flow file at that element's exact line. The renderer is the same file every other host uses, so all surfaces draw one definition.

Flags (flow graph)

nimbus bisect

Find the commit that broke a test, using git bisect — made practical for Apex because each step is a local, sub-second test run instead of an org deploy. Free.

# AccountTest.testDiscount used to pass at v1.40.0 and fails now
nimbus bisect "AccountTest.testDiscount" --good v1.40.0

# Bad ref other than HEAD
nimbus bisect "AccountTest.testDiscount" --bad abc1234 --good v1.40.0

# Machine-readable result for CI
nimbus bisect "AccountTest.testDiscount" --good v1.40.0 --json

How it works

The search runs inside a temporary git worktree of the project's own repository — never your actual checkout. git bisect moves HEAD as it walks history, which would be destructive against a checkout other sessions or tools might be using, so nimbus bisect creates a disposable worktree, drives the whole bisection there, and removes it before exiting — including on Ctrl-C. Each worktree gets its own embedded database automatically (the port and database name are derived from the worktree's path), so a bisect run never collides with the database from your regular checkout.

At each candidate commit, a probe step runs nimbus test "<pattern>" --no-daemon in the worktree and reports one of three verdicts back to git bisect run: good (the test passed), bad (the test actually failed), or skip when the class or method doesn't exist yet at that commit. Skipping a missing test rather than calling it "bad" matters — otherwise bisect would blame whichever commit happens to introduce the test for a failure that is really somewhere later in history. A build, parse, or config error that never got to evaluate the test is also treated as a skip rather than a guess.

Output

Progress streams as the bisection narrows the range. On convergence, a verdict block reports the culprit commit (hash, author, date, subject), how many steps it took and how long, and a copy-pasteable command that reproduces the failure in its own disposable worktree. --json emits a nimbus.bisect/v1 payload on stdout instead — progress moves to stderr so a CI run watching stdout still gets clean JSON, while someone watching the terminal still sees steps happen in real time.

Flags

nimbus bisect runs against the project's own git history — the Salesforce project under test, found the same way every other nimbus command finds it. If that directory isn't a git repository, or --bad/--good don't resolve to commits, nimbus bisect fails with a clear error before creating a worktree.

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.

Traces & Analytics

A test run with --trace records every span of its execution — methods, SOQL, DML, triggers, and (at --trace-level verbose) every statement — into .nimbus/traces/<run>/trace.jsonl. The trace is what powers replay debugging, the trace viewer, and the field ledger below.

Execution Traces

A trace is the record of what a test actually did: which methods it entered, which SOQL it issued, which DML it ran, and in what order. Nimbus does not collect one unless you ask, because collecting it costs time on every statement.

# Run a test with tracing on
nimbus test AccountServiceTest.testCreate --trace

# Open the trace in the viewer
nimbus trace AccountServiceTest.testCreate

# Most recent trace, whatever test produced it
nimbus trace --last

nimbus test --trace writes traces to .nimbus/traces/. nimbus trace opens the interactive TUI viewer on the newest trace file there and roots the flow at the test you name; with no argument, or with --last, it roots at whatever ran.

If you collected somewhere other than .nimbus/traces/, point the viewer at the same place with --trace-output, or set nimbus.trace.output in nimbus.properties so both sides read it and neither needs the flag.

Verbosity

Two flags share one ladder. --trace-level on the test run decides how much gets recorded; --level on the viewer decides how much of a recording is shown, hiding spans below the level you ask for.

Filtering only ever subtracts. Recording at minimal and then viewing at debug shows you nothing extra, because the detail was never written down — so the level that matters most is the one you collect at.

Flags

nimbus test:

nimbus trace:

The viewer needs an interactive terminal. Piped or run under CI it prints the directory the traces are in and exits successfully, so a CI step that reaches it by accident does not fail the build. The same traces are rendered inline by the VS Code trace viewer.

nimbus trace Pro

nimbus trace opens the interactive trace viewer for a test's most recent recorded run:

nimbus test "AccountServiceTest.*" --trace   # record
nimbus trace AccountServiceTest.testCreate   # inspect
nimbus trace --last                          # newest trace, any test

nimbus trace timeline — the run on one axis

Where nimbus trace shows one transaction's call tree, nimbus trace timeline puts a whole recorded run on a single time axis: test methods, Apex calls, SOQL, DML, triggers, flows and the rest of the save pipeline as lanes of bars, with every field write as a tick and every span's governor delta as a reading. Statement-level spans are left off by default and the header reports how many; --detail places them.

nimbus trace timeline                            # newest traced run
nimbus trace timeline 20260824T101530_a1b2c3d4
nimbus trace timeline --json                     # the nimbus.timeline/v1 document
nimbus trace timeline --out run.html             # self-contained interactive viewer
nimbus trace timeline --detail                   # with the statement-level spans
nimbus trace timeline --diff 20260823T090000_9f8e7d6c

--detail is off by default because a verbose recording holds orders of magnitude more statement spans than lanes of bars. They are not a lane of their own: each is drawn inside the bar that ran it, once the axis is magnified far enough for a statement to be worth a pixel. The document reports detail_available either way, so you can tell whether asking would show anything.

--diff takes a second run id and aligns the two by test method name — never by a run identifier, since trace run ids and test-history ids are separate id spaces. The two runs are not laid on one axis: they do not share a clock, so what is compared is how long each method took, not where it fell. The viewer draws one row per method with the current run's bar over the baseline's; the terminal prints the same ordering as a delta table.

The lanes, the span bars and the governor readings are free — they are span data, and spans are the trace. The field-write ticks are a ledger surface and need Pro Pro; a timeline built without it says so rather than showing an empty track.

The HTML export and the IDE panel share one renderer, so the page you write and the panel JetBrains opens are the same viewer. In the IDE (Nimbus → View Run Timeline, or the Run Timeline button on the debugger toolbar during a replay session) clicking a bar seeks the replay to that instant — landing on the last recorded step at or before the click. With no replay session open the position is copied to the clipboard and the panel says so.

nimbus trace ledger — the field ledger Pro

Every traced run also records the causal field ledger: each SObject field write, with the old value, the new value, and the frame that performed it — your Apex line, a trigger line, or the engine itself (a formula resolve, a roll-up recompute, a platform default). nimbus trace ledger queries a run's ledger; it answers "why is this field this value?" without re-running anything.

nimbus trace ledger                              # newest traced run, every write
nimbus trace ledger --field Account.Name         # one field's history
nimbus trace ledger --record 001Kj00000AbCdEfGH1 # one record's history
nimbus trace ledger 20260824T101530_a1b2c3d4 --json

Each row reports the test, sequence number, timestamp, object, record, field, old -> new, the writer kind (apex, trigger, flow, default, rollup, formula, platform), and the writing location — Class.method:line for code, or the pipeline phase / roll-up definition for engine writes, which have no source line to point at.

The run-id argument is a directory name under .nimbus/traces (any unambiguous suffix works); omitted, the newest traced run is used. The raw apex.field.write events are in every trace at any tier — the indexed, queryable ledger is Pro.

The same ledger drives Find Where This Was Set in the IDE: during a replay debug session, right-click a field in the Variables view and Nimbus runs the recording backwards to the write that set it, via standard DAP data breakpoints.

Test Analytics

Every nimbus test run is recorded under .nimbus/history/ whether or not you asked for it. nimbus analytics reads that history back as trends: pass rate and duration over time, rather than the state of the last run.

# Trends over the last 30 days
nimbus analytics

# Narrow the window
nimbus analytics --days 7

Flags

The dashboard is a TUI. Piped or under CI it emits JSON instead — the requested days alongside the raw runs the trends are computed from, so a build step can chart or threshold them itself.

# Pass rate of the most recent run
nimbus analytics | jq '.runs[0] | .passedTests / .totalTests'

The JSON dump reads up to 1000 runs regardless of --days; the flag scopes the interactive view. Trends need history to exist — a fresh project shows nothing until it has runs behind it, and nimbus reset deletes them along with the rest of .nimbus/.

Flaky Detection

A flaky test is one that changes its answer while nothing that could legitimately change it moved. nimbus history --flaky reports them out of the same run history the analytics view uses.

nimbus history --flaky

What counts as a flip

Not every pass-then-fail is flakiness, and treating it as such is how a flaky-test report becomes noise nobody reads. Nimbus records the conditions of every run alongside its results, and compares only runs whose conditions match:

An outcome flip is evidence of non-determinism only when all of that held still. Records written before this environment data existed carry none of it and are not comparable.

Reading the report

The report is part of the history TUI and needs a terminal: --flaky selects the flaky view over the run list. A piped nimbus history always emits the run list as JSON — the flag does not change that, so scripting a flakiness gate means consuming .results[] across runs yourself.

Flakiness is a property of a history, not of a run, so the report is only as good as the history behind it. A test that has run twice cannot be called flaky; one that flips under -p 8 and never under -p 1 is telling you about contention, which is a real bug and not a measurement artifact.

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.

MultiCurrency changes the shape of your schema, not just what UserInfo reports. On a single-currency orgCurrencyIsoCode does not exist at all — the describe omits it and SOQL rejects it by name — so Nimbus leaves it out by default. Toggling the feature re-syncs the schema cache automatically; you do not need to clear anything.

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.

On GitHub, the Nimbus action is the shortest path: one file and one secret gets the suite running on every pull request, with failures, reproduction commands, and a coverage delta posted back to the PR.

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 Pro

The Nimbus action runs your Apex suite on the pull request itself. No Salesforce org is involved — no JWT certificate, no DevHub, no scratch org pool to exhaust, no queue behind another team's deploy. The runner installs a binary and executes the tests locally, on the runner.

One file, one secret:

name: Apex Tests

on:
  pull_request:
  push:
    branches: [main]     # publishes the coverage baseline PRs compare against

permissions:
  contents: read
  actions: read          # read the base branch's coverage baseline
  pull-requests: write   # write the report comment

jobs:
  apex-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: nimbus-solution/nimbus-test-action@v1
        with:
          license-key: ${{ secrets.NIMBUS_LICENSE_KEY }}

What lands on the pull request

One comment, updated in place on every push rather than appended. Failures come first, because that is what a reader on a red build came for:

• Each failure with its exception type, message, and the assertion's expected and actual values.
• The exact commands to reproduce it locally — nimbus test "Class.method" and, when a trace reproduced the failure, the nimbus trace replay one-liner for it.
• A coverage delta table against the base branch, showing only the classes that moved.
• A link to the failure traces, downloadable as a job artifact.
• A parity receipt: the Nimbus version, and the corpus totals from the published parity record.