Reference

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.renmy.net | sh

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

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

# Verify
renmy --version

The installer drops the binary in /usr/local/bin, or ~/.local/bin when that is not writable (macOS/Linux), or %LOCALAPPDATA%\Programs\Nimbus (Windows), and puts that directory on your PATH if it is not already there: one export line in your shell profile on macOS/Linux, the user PATH on Windows. INSTALL_DIR chooses the directory, NIMBUS_VERSION pins a release, and NIMBUS_NO_MODIFY_PATH=1 leaves your dotfiles alone and prints the line to add instead. 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. Go to your SFDX project root
cd path/to/your/sfdx-project

# 2. Set the project up
renmy setup
# or: renmy setup -o my-org

# 3. Run all tests
renmy test

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

# 5. Run with coverage
renmy test --coverage

renmy setup assesses the project and runs only what is missing, so it is safe to run again after a package is installed or the schema moves. renmy init and renmy doctor keep their own sections: setup composes init, and doctor is the standalone check.

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

Project Setup

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

.nimbus/
├── db/          # Embedded PostgreSQL data directory
├── schemas/     # Describes pulled by renmy sync
├── cache/       # Parsed AST cache
├── traces/      # Execution traces (when --trace is used)
├── recordings/  # Managed-package recordings (renmy test --record)
├── evidence/    # Per-line run evidence (renmy test --evidence)
└── history/     # Run history, impact map, test durations

You do not have to ignore this by hand. The first time the runtime starts in a git repository it appends two lines to the project's .gitignore, creating the file if there is none: everything inside .nimbus/ is ignored except .nimbus/recordings/, which is meant to be committed. Nothing else in the file is touched, and a line you wrote is never rewritten. The one exception is renmy's own earlier entry: a .nimbus/ line directly under renmy's comment, which earlier releases wrote, is changed once to the two lines below, with a note. A file git already tracks stays tracked — git ignores nothing it is already following, so a repository that has already committed a .nimbus/ tree has to be untracked deliberately, with git rm -r --cached .nimbus ':(exclude).nimbus/recordings'.

# .gitignore — written on first run
.nimbus/*
!.nimbus/recordings/

A .nimbus/ line you wrote yourself hides the recordings: git does not look inside an ignored directory, so a later !.nimbus/recordings/ has no effect. Change it to .nimbus/* as above. If you would rather commit more of it — traces are worth sharing with a team — add your own negations below. renmy will not widen the entry again.

Disk footprint

A project that has run its suite once carries roughly 60–90 MB in .nimbus/, and almost all of it is db/ — a live PostgreSQL data directory, which is what a real database costs on disk whatever is in it. On the demo project the split measures 59 MB db/, 7 MB schemas/, under 1 MB cache/, and tens of kilobytes of JSON. It is kept between runs on purpose: the next run starts on tables that already exist instead of rebuilding all of them.

The PostgreSQL binaries are not part of that. They are extracted once per machine to ~/.nimbus/pg/ (about 190 MB) and shared by every project, so a second project costs its own data directory and nothing more. renmy keeps its downloaded releases in ~/.nimbus/bin/.

renmy reset deletes the whole per-project .nimbus/ and gives that space back; renmy data reset empties the tables without touching the directory, which is faster but reclaims little — PostgreSQL does not shrink its files when rows go away.

User Stubs / Managed Packages

Sometimes renmy 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 renmy 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. renmy 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, renmy 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

renmy 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, renmy 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 renmy stub label, or pull an entire package's labels out of an org that has it installed with renmy 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. renmy stub add and renmy stub auto (Pro) write the per-class layout; the nested layout is the hand-written convention.

Auto-null fallback behavior

When renmy 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 renmy test --record -o my-org once against a real org; renmy 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 renmy runtime, and they work differently:

• In tests - Salesforce does not allow real callouts inside @isTest methods. Use Test.setMock() with a standard HttpCalloutMock implementation. renmy enforces the same rule as a real org.
• In renmy exec - Apex runs outside of a test context, so Test.setMock() is not available. Use --mocks to provide a config file that renmy 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. renmy enforces the same rule.

The solution is the standard Salesforce pattern: implement HttpCalloutMock and register it with Test.setMock(). renmy 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 renmy runtime. No renmy-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 renmy exec, Test.setMock() is not available. Any Http.send() call needs to be intercepted at the renmy level.

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

Using a mock file

renmy exec -c "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
renmy exec -c "MyClass.run();" --mock "GET:https://api.example.com/v1/users:200:[]"

# multiple --mock flags
renmy exec -c "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

An endpoint with no matching mock entry throws System.CalloutException: Endpoint not mocked: <METHOD> <URL>, naming the request so you can add the entry. Nothing reaches the network: renmy exec makes no real callout, with or without a mock file.

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:

renmy exec -c "MyClass.run();" --mocks mocks/auth.yaml --mocks mocks/orders.yaml

URL Patterns

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.

renmy 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, renmy 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.

One command, from the project root. It registers the server with every AI client already set up on the machine, writing the absolute path of your renmy binary so the client finds it whatever its own PATH looks like. Nothing else in those config files is touched, and running it twice rewrites nothing:

renmy mcp install

renmy mcp status shows which clients are registered. Restart the client afterwards. Recognised clients: Claude Code (~/.claude.json), Cursor (.cursor/mcp.json) and VS Code (.vscode/mcp.json). Each editor is registered once, in the project; pass --client cursor-global or --client vscode-global to write the user-wide file instead.

Any other client — renmy mcp install --print emits the entry to paste. The shapes below are the same thing written by hand. Keep the key nimbus: it is the one renmy mcp install writes, so in a client it recognises, renmy mcp status and renmy mcp uninstall find a hand-written entry too, and a later install updates it instead of adding a second server.

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

{
  "mcpServers": {
    "nimbus": {
      "command": "renmy",
      "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": "renmy",
      "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 (license.plan, license.pro, license.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 renmy 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. renmy 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

renmy 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 renmy 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.

Emails. A run that sent email carries a top-level emails array, added within version 1: one { source, template, to, cc, subject, relatedId, test } per email, oldest first, where source is apex, workflow, approval or flow. The key is absent when the run sent none. The test filter applies to it; kinds and max_spans do not.

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. An identity is unique across the whole run, so --record rec-3 is one record's history. In a recording made before v1.29 identities restarted at rec-1 in every test — read the TEST column to tell those apart. The debugger's Find Where This Was Set and Show Write History scope to the test the replay cursor is inside either way, and name the test they answered from.

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 renmy 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 renmy runtime 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. renmy publishes an ARD catalog so compatible registries and agents can find this server from task intent. ARD handles discovery only: after selecting renmy runtime, the client still installs the local binary and runs renmy mcp over stdio.

Commands

renmy sf

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

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

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

renmy toolchain sf

Report which Salesforce CLI renmy 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 renmy commands never install or replace Salesforce CLI implicitly.

renmy toolchain sf status
renmy toolchain sf status --verbose   # resolved path, reported version line, policy
renmy toolchain sf status --json      # stable shape for CI and editors
renmy toolchain sf install            # official @salesforce/cli stable package
renmy toolchain sf install --version 2.142.7
renmy toolchain sf update --check     # read-only available-version check
renmy 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 renmy's assisted official-package flow:

renmy 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.

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

renmy deploy

The safe one-shot Salesforce deployment. renmy 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 renmy 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 renmy 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.

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

Production targets require an interactive typed confirmation or the explicit --confirm-production flag. renmy 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

renmy 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.

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

Releasing one package

In a project with several packageDirectories, renmy release validate -k core releases one package. The payload is the package's path, which is what sf project deploy start -d ships; its unpackagedMetadata is not deployed. The local gates run in a stage that also holds the other package directories, outside the bundle and its digest, so a class that calls into another package validates and tests as it does in the project. The gates judge only the package's files and run only its tests, including the tests in its unpackagedMetadata, and --min-coverage counts only its files. An active release profile stays in force: -k narrows its source.dirs and keeps its target org, thresholds and test level. With a profile that selects by manifest or metadata, -k is refused: there is no directory to narrow. The receipt records the package names under source.selection.packages; a receipt made without -k has no such key and is byte for byte what it was. A signed receipt that carries the key fails signature verification on a renmy version older than this flag.

renmy release plan -k core reports an org component that this project holds outside the payload as otherPackage, not orgOnly: a component of another package, or of core's own unpackagedMetadata. The human output counts those components as elsewhere in this project without listing them, --json lists them, and they do not trip --fail-on-diff. The Next: line carries the --package.

Exit codes: 0 success, 20 configuration, 21 local gate, 22 Salesforce validation, 23 deploy, 24 production confirmation, 25 release integrity violation (tampered / mismatched / missing bundle), 26 deploy submitted but outcome unconfirmed (run renmy 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, renmy locks, reads, and updates it beside its sibling bundle instead of silently creating a different local copy.

Git is optional. A Salesforce project outside version control releases from its working tree. The receipt records vcs: "none" and no commit, and requireCleanGit has nothing to enforce there, so it does not block the release. A git repository with no commits yet counts the same way. Inside a repository with a commit the receipt records vcs: "git" alongside gitCommit and gitDirty, and an uncommitted worktree passes only with --allow-dirty (or requireCleanGit=false).

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 renmy 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 — renmy 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 renmy 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.

renmy 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. renmy 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 renmy runtime 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.renmy 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 renmy 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.

renmy 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: renmy 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 renmy did not create are never touched. renmy 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, renmy 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 renmy release status but never touched, so requeue can only ever act on a deployment renmy itself validated.

Plan — read-only source ↔ org reconcile

renmy 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 renmy entirely).

Promote — the same bundle through your environments

renmy 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. renmy'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

renmy 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 renmy 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, renmy 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). renmy 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, renmy 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. renmy 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: renmy 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. renmy 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.

renmy release keygen                          # key + roster entry for git config user.email
renmy release keygen --signer you@team.dev    # explicit identity
renmy 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 renmy release validate ...

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

Salesforce test level

Leave salesforceTestLevel unset and renmy resolves it from the target org: RunLocalTests for production, which Salesforce requires, andNoTestRun everywhere else. renmy 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 renmy 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 renmy classifies the rejection conservatively as a likely renmy compatibility gap — every reported problem looks like a compiler diagnostic renmy claims to cover, and no org- or project-dependency pattern matched — renmy 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 renmy defects, and the deploy stays failed regardless of reporting.

A report contains only: the renmy 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, renmy 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 release surface, 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

renmy assurance Team

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: renmy 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 renmy's own licence check on startup — no code, no receipts, no org data — the same as any renmy command.

renmy assurance                      # open the console for this project
renmy 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

renmy 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.

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

renmy 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 renmy runtime 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:

renmy test

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

Pattern matching

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

Path patterns

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

Running renmy 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.

A run that discovers no tests at all is an error for the same reason, and it is the one CI actually hits: a packageDirectories entry pointing at a path that doesn’t exist, a checkout that never fetched the classes, a container missing the source mount. The pipeline would otherwise go green having run nothing. renmy exits 1 and names the two things worth checking. On a project that genuinely has no tests, pass --allow-empty to keep the warning and exit 0.

renmy test "*"                 # no classes found -> exit 1
renmy test "*" --allow-empty   # no classes found -> warning, exit 0

A run that left out a class fails as well. A file that does not parse and a class the compile gate excludes (code the platform would refuse to compile) are not in the run: their tests did not run, and calls into them returned null. The platform could not have run that suite, so renmy exits 1 even when every test that ran passed, and names the files. --allow-compile-errors, or nimbus.test.allow-compile-errors=true in nimbus.properties, lets the tests that ran decide the exit code.

With --json, status agrees with the exit code. It is "failed" when a test failed, when a class was left out, and when nothing matched, and reason says why when the test counts do not ("no tests matched NoSuchTest", "1 file failed to parse and was excluded from the run: Broken.cls"). parse_errors lists each file that did not parse with its parser messages, and compile_excluded lists each class the compile gate excluded as { class, file, error } with its first error. Both are empty lists on a run that left nothing out, and reason is absent.

renmy test --json                          # Broken.cls does not parse -> "status": "failed", exit 1
renmy test --json --allow-compile-errors   # same run -> status and exit code from the tests

Package scope

renmy test -k apex-stream-streams             # Every test in one package
renmy test -k apex-stream-streams "Stream*"   # Its tests that match the pattern
renmy test -k core,billing                    # Two packages
renmy test -k apex-stream-streams --isolate   # Load only it and its dependencies

-k names an entry of packageDirectories in sfdx-project.json: its package name, a packageAliases key, its 0Ho id, or its path. renmy runs the test classes in that directory and in the package’s unpackagedMetadata directory. A package nested inside that directory is a different package and is left out. Every package’s code and schema are still loaded, so a test that passes in a full run passes here.

A positional pattern narrows the package’s tests further. Without one, the run takes every test in the package and does not auto-scope to the current directory. --coverage reports the package’s files only, with totals over those files. History records the run as partial, the impact map and the recorded suite duration are not replaced by it, and --json adds a packages key. With --in-org, renmy sends the org the names of the package’s test classes. -k and -i cannot be combined.

--isolate loads what a package version build of the selected package sees: the package, its local dependencies from sfdx-project.json, stubs/ and .nimbus/retrieved. Before any test runs, renmy checks the package’s files against that set. A name that only a package outside it declares, such as a class in a sibling package the package does not list in dependencies, stops the run with exit 1, reported as renmy validate -k X --isolate reports it and grouped by the package that declares the name. A stopped run still writes --output-file and --results-xml. The header’s Loaded: line lists what the run loads, and a Note: names a pinned dependency that loads from local source, a dependency that is not in the project, or a path-only entry, which has no dependencies. The run uses a database of its own in the project’s local Postgres cluster and keeps its schema cache under .nimbus/isolate. It writes no impact map, durations or failure traces, and history records it as isolated. --impacted runs every selected test. Schemas fetched from an org with renmy sync -o still load, because they describe the org, which holds every package.

Defined in sibling:
  error feature/classes/FeatureService.cls:4  SEMA-TYPE-001 — Invalid type: SiblingHelper. FeatureService uses SiblingHelper (defined in package sibling), which feature does not declare in dependencies

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

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

Coverage

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

Org fallback Pro

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

When renmy 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. A full run (renmy test "*", or no pattern) replaces the file, and removes it when nothing retrievable is missing; a run with a pattern only adds to it, so a narrowed run never drops what a full run found. A comment at the top says which kind of run wrote it, and each member carries <!-- referenced by <file> -->, naming the class whose test met the reference — a name that no retrieve can satisfy, such as one a negative test expects to be missing, is recognisable by its referrer.

A class that is in your project but fails to parse is never listed here, and never lands in the manifest or the unresolved-type summary — retrieving it would overwrite the file you're fixing. renmy reports it as a parse error instead, printed before the tests run: the file is excluded from the run, every call into it returns null, and each failing test that reached it says so under its assertion.

The same applies to a class renmy parses but Salesforce would refuse to compile. renmy prints the org's own message and line before the tests run, excludes the class, and fails the command: a suite cannot report green on code an org would reject. The same check is what renmy validate reports and what the editor squiggles red. What it covers:

• a variable, parameter or field named with one of the platform's reserved words (from, limit, group, string, …)
• a call to a method that does not exist — unqualified, through this., on one of your own classes, or on an SObject (Method does not exist or incorrect signature)
• a static member that does not exist on one of your classes (Variable does not exist)
• an assignment the target type cannot hold, including from a method's declared return type (Illegal assignment from String to Integer)

Unresolved type references. A name your source uses as a receiver that resolves to nothing — no class in your project, no platform type, no SObject, and no managed-package namespace you have declared — is listed in its own block before the tests run, with how often the project writes it and where it first appears. renmy returns null for it at runtime, so a test that passes over one has not proved much. It does not fail the command: auto-stubbing an unresolved reference is how a project runs against packages it has no source for. Declare the namespace in nimbus.properties (nimbus.stubs.namespaces=Hoplog) or drop a stub under stubs/ and the block goes quiet; leave it undeclared and renmy validate and the editor both report it as the compile error the org reports.

Platform members answered by a fallback. A platform method, static member or enum member that renmy has not implemented is answered by a placeholder in a few places (an empty ConnectApi result object, a null from a static get, a class name from getName(), or a type-like value for an unknown static or enum member). Such a test may pass locally and fail in the org. Every hit is counted, and the run ends with ⚠ N platform member(s) answered by a fallback, listing up to twelve entries as kind: Type.member ×count (first at File.cls:line). In renmy test --json the same list appears under platformFallbacks (objects with kind, type, member, count and firstSeen; the key is absent when nothing was hit). renmy exec prints the same block after its output. Set NIMBUS_FALLBACK_TRACE=1 to log every hit to stderr as it happens.

Names the org rejects at compile time. Some calls compile nowhere but in renmy runtime: a method the platform type does not have (Wave.Templates.list()), new on an abstract class, an interface or a type with no public constructor (new ConnectApi.BatchResult()), a constructor with an argument count none of the documented ones takes, and an exception type the platform does not have (new System.TotallyMadeUpException('m')). With nimbus.strictPlatformApi=false in nimbus.properties, renmy still runs them and lists them after the run in a second block, ⚠ N name(s) the org rejects at compile time, with the same line format and kinds invented-member, abstract-new, ctor-arity, invented-exception and carrier-property; renmy test --json carries them in platformFallbacks under those kinds. By default renmy refuses them instead: each throws a catchable System.TypeException with the org's compile message (Method does not exist or incorrect signature: void list() from the type Wave.Templates, Constructor not defined: [ConnectApi.BatchResult].<Constructor>(), Invalid type: System.TotallyMadeUpException), and the compile gate also drops a class over four rules renmy validate reports on its own: an abstract or override method with no access modifier (API 65 and later), listVar instanceof Iterable<String> (API 60 and later), an unknown exception type in catch, new or instanceof, and a List assigned to a variable that is not a collection. The setting is on by default; false is the way back to running them.

Standard objects with no local model. A reference to a standard Salesforce object renmy ships no describe for — AccountContactRelation, TaskRelation, CollaborationGroupRecord and the like, most of them behind an org feature toggle — is reported in its own block rather than as a missing Apex class or custom object. It is deliberately kept out of manifest/nimbus-missing.xml: sf project retrieve start cannot retrieve a standard object under any manifest type. The remedy is a describe, and the report prints it per object: renmy sync -s AccountContactRelation -o <alias>. In renmy test --json the same list appears under unmodelled_standard_objects, apart from the missing-metadata count. --fetch-missing describes them from the org along with everything else.

Tracing / debugging

renmy test --trace                          # Record a replayable trace
renmy test --trace --trace-level normal     # Cheaper, not replayable
renmy 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)
renmy test --org-default "TriggerSettings__c.IsEnabled__c=true"
renmy 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

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

Replay on failure

When a run has failures, renmy 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: renmy 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 by count and by size: the last nimbus.test.trace-on-failure.keep automatic traces are kept, and the oldest are pruned until they fit inside nimbus.test.trace-on-failure.max-total-bytes. Traces you recorded yourself with --trace are never pruned.

One recording is bounded too. A trace stops at nimbus.test.trace.max-bytes; what was written still parses and still replays, up to the point it was cut, and the run says so on the last line. A failure trace divides the bound between the tests it records: each may write max-bytes / (2 × tests) of its own spans and as much again for its @testSetup, so one heavy test cannot use up the recording of the others. The spans that name each test, and the calls still open where a test was cut, are written past the bound; that is a few hundred bytes per test. Set either key to 0 to remove the bound. Traces live in .nimbus/traces, one directory per recorded run; delete the ones you no longer need.

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: renmy test --shard ${{ matrix.shard }}/4 --results-xml results-${{ matrix.shard }}.xml

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.

renmy 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
renmy test -p 8

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

# If you see many sequential re-runs, back off
renmy 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 renmy test processes, each with its own embedded Postgres instance, splitting the suite the same way --shard does. Pass a number, or auto to let renmy 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).

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

Each shard gets a persistent background daemon (visible in renmy 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.

renmy test:watch Pro

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

renmy test:watch              # Watch all tests
renmy test:watch -i           # Select package scope interactively
renmy test:watch -k core      # Re-run only the tests in package "core"
renmy test:watch -k core --isolate   # Each run loads only core and its dependencies
renmy test:watch --pull -o dev       # Also pull what a test run reads when it changes in the org dev

While watching:

r    # Re-run the whole pattern, as the first run does
w    # Show or hide the watched directories
p    # Pause or resume org polling (with --pull)
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. Pressing r always runs the full pattern.

--pull -o <alias> makes the watcher poll that org as well, every 15 seconds unless --pull-interval says otherwise, for Apex classes and triggers changed there. Each one is written into the project where it already lives (a new one into the default package, or the -k package), and the tests it affects run again. A source-tracked org (a scratch org, a sandbox with tracking) is read through the Tooling object SourceMember; any other org through the LastModifiedDate of ApexClass and ApexTrigger. A file edited locally is never overwritten: nimbus compares it with its last sync from that org, or asks git when there is none, keeps your copy and lists a conflict. Metadata no test run reads, such as profiles, layouts and reports, is listed. Polling stops when the org has fewer than 1,000 API calls left for the day, or after three failed polls in a row; p starts it again.

On a source-tracked org the declarative metadata a test run reads is pulled as well: objects, fields, validation rules, record types and field sets, flows, labels, custom metadata records, permission sets, value sets, workflow, assignment, duplicate and matching rules, approval processes, email templates, static resources and Visualforce pages. It comes through sf project retrieve start, which renmy answers itself when it maps every type asked for; without the Salesforce CLI only Apex is pulled. A file edited locally is kept: before the retrieve renmy asks git about every file the member lands in, and one git does not hold unmodified is left out and listed as a conflict. A pull that wrote one of these files runs the whole pattern, because no impact map links a label or a validation rule to the tests it affects.

renmy validate

Check Apex files for syntax errors and the semantic rules the platform enforces at deploy time, without running tests. Fast — no database or runtime needed. Errors come from the parser and the semantic checks; warnings from the metadata checks (CT-META-001/002: a missing *-meta.xml or absentapiVersion) and the SOQL column checks.

One list is opt-in: --api-version-warnings adds CT-API-001, which reads each file’s declared apiVersion and names every referenced symbol whose introduction version is newer. It is advisory, never a deploy finding: the platform does not gate symbol references on a class’s apiVersion — a class pinned at 46.0 deploys and runs calling System.Assert (56.0) andDatabase.Cursor (66.0), verified on a real org — so the list says “newer than your pin”, nothing more. The same switch exists onrenmy test (nimbus.test.api-version-warnings=true makes it a project default), where producing the block also parses every class in the CLI process.

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.

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

Path patterns

Naming a single file is the same command as naming a class: the whole project’s type universe is still built from disk, so an unknown method or a field the SObject doesn’t have is reported forrenmy validate path/to/MyClass.cls exactly as it is forrenmy validate MyClass. The project root is found from the file, not from your shell, so it works from anywhere.

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

Package scope

renmy validate -k feature              # Only feature's files; names resolve project-wide
renmy validate -k feature --isolate    # Resolve against feature and its dependencies only

-k validates the files of one packageDirectories entry, and its unpackagedMetadata directory, and runs the profile and field checks on them. Names still resolve against every package directory and stubs/, so a file that validates in the whole project validates scoped.

--isolate resolves names against what a package version build of the selected package sees: the package, its local dependencies from sfdx-project.json, and stubs/. A class in a sibling package that the package does not declare in dependencies is then an error, and renmy names the package that declares it:

error feature/classes/FeatureService.cls:4  SEMA-TYPE-001 — Invalid type: SiblingHelper. FeatureService uses SiblingHelper (defined in package sibling), which feature does not declare in dependencies

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 renmy 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

renmy 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 renmy 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. renmy 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.

renmy lint                            # every class and trigger
renmy lint AccountService             # files matching "AccountService"
renmy lint *Service*                  # files matching "*Service*"
renmy lint force-app/main/default/classes/   # everything under a path
renmy lint --rules                    # what each rule protects against
renmy 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:  renmy test "*" --evidence

With one, it reports what happened

renmy test "*" --evidence
renmy 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 7 times in
    AccountServiceTest.testOneOwner — the most in any one transaction —
    and 91 times across the run. A transaction may issue 100.

Two numbers, because every governor ceiling is per transaction. The first is what the line did in the single heaviest transaction that reached it — the only number the 100 can be read against — and the second is the total across the whole run, which is the sum over every test that touched the line. When one transaction did all of it, there is one number and the message gives one: issued it 47 times in AccountServiceTest.testBulkInsert.

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 894 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, hardcoded-id anddebug-statement do not judge test code: an empty catch afterAssert.fail() is the success path, a fabricated Id is how a unit test avoids a DML, and a debug in a test is a diagnostic aid in code that never runs in production. The loop rules do judge tests, because a test transaction has the same 100 queries as any other.
• test-without-assertion counts a call to a same-class helper that asserts as asserting, so a suite whose twenty tests all delegate to one exerciseHandler method is judged on what that method does. Anything whose name mentions assert or verifycounts too — ApexMocks states its expectations that way.
• test-class-not-annotated reads the methods, not the class name. A class called …Test that declares no test method has nothing an annotation would make run, and the platform’s ownSystem.Test stub is not a broken suite.

Exit status is 1 when any finding survives the severity threshold, so renmy 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 renmy. 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.

renmy exec

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

# From a file
renmy exec script.apex

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

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

# Ends in a statement, so it runs as written - nothing is wrapped
renmy 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.

Records written by an exec are rolled back when it finishes, so a run is side-effect-free by default. This differs from the org, where executeAnonymous commits. Pass --persist to keep what the snippet writes — the same thing the IDE console's "Keep records" checkbox does, and the way to seed local data from a script.

# Seed data that outlives the run
renmy exec --persist seed.apex

The futures, queueables and batches a snippet enqueues run after it completes, in the order Test.stopTest() drains them, as the org runs them after the block commits. Each is named on an async: line, with its own failure if it throws; the snippet still counts as successful. A scheduled job waits for its cron, and a snippet that throws runs none of them. --persist keeps what the jobs write too.

Running it in the org

--in-org sends the snippet to the Salesforce org named by -o instead of running it locally. The org compiles it, runs it and commits whatever it writes — which is why --persist, --mocks and --mock are refused there rather than ignored.

The run saves the org's debug log under .nimbus/logs/ and converts it into a trace under .nimbus/traces/, so a snippet run in an org can be stepped through afterwards exactly like a local test. Tracing is on by default with --in-org: the log comes back with the response and the org will not produce it again. --trace=false turns it off.

# Run it in the org and record a log you can step through
renmy exec --in-org -o acme-dev script.apex

# Then replay it
renmy log replay .nimbus/logs/anon-20260915-233018.log

# The same thing as a JSON document, for a script
renmy exec --in-org -o acme-dev --json -c "System.debug(Limits.getLimitQueries());"

renmy run-method

Call one method of one class and report what it returned. Where renmy 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
renmy run-method AccountService.createDefault

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

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

# Structured result, including per-line variable snapshots
renmy 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 renmy 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 extension renders as inline annotations — its "Run method" code lens and this command are one implementation.

The method runs against the local database with the same configuration renmy 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 renmy exec: you can call a method that inserts records without leaving them behind.

renmy 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 Pro). For the first two the verdict leads: identical, different, or which side errored, and both stay free. Comparing a whole test run against the org is the Pro form.

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

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

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

# Compare every test class of one sfdx-project.json package
renmy compare --tests "*" -k billing -o my-sandbox

# Machine-readable result
renmy 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 Pro

--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: renmy 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 renmy 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. It runs through the same native Tooling API path renmy test --in-org uses, and reports each method as the org finishes it. Unless you pass --trace, it never touches the org's trace flags or debug levels — a comparison should not reconfigure your debug logging to answer a question about test outcomes. 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 renmy test --coverage uses; the org side is the org's own ApexCodeCoverageAggregate table, one row per class or trigger it tracks. 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.

Comparing governor usage

Every comparison reports what the local side spent on each governor limit — SOQL queries, DML statements, CPU time, heap — per test method, and records a replayable trace under .nimbus/traces/ you can open with renmy trace timeline <run-id>. That costs your machine and nothing else, so it is always on.

--trace asks the org for the same thing. The org's numbers come from a debug log per test method, and recording one means taking the running user's single USER_DEBUG trace flag for the length of the run — so it is opt-in by name. The flag is restored afterwards, on the failure and cancellation paths as well as on the success one. An org that will not provision logging does not fail the comparison: the verdicts are unaffected and the org's governor columns read not recorded.

A side that recorded nothing is never shown as a zero. This test used no queries and nobody measured this test are different findings, and the second printed as the first sends you hunting a difference that was never measured. Governor usage is a column beside the verdicts and never one of them.

--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.

renmy serve Pro

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

renmy serve

renmy app Pro

Feature overview: local app hosting.

Run any App preview target against the local renmy runtime: a Salesforce Multi-Framework UI bundle (React + Vite), an LWC component, or a Visualforce page. 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 app hits renmy's Apex interpreter and embedded Postgres instead of a real org.

The targets you can run are exactly the ones renmy app list prints, named by display name or by the stable id in that listing. LWC and Visualforce previews are deliberately org-free: they run on the local runtime and ignore --org, so starting one never becomes an authenticated describe.

What it does:

1. Discovers React bundles under force-app/**/uiBundles/<name>/ (marker: *.uibundle-meta.xml), LWC components under force-app/**/lwc/<name>/, and Visualforce pages at **/pages/<Name>.page
2. For React and LWC, spawns a dev server (default: npm run dev) — Vite, HMR, source maps, the lot. Visualforce is rendered by renmy itself at /apex/<Name>; no npm involved
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
renmy app

# Pick a specific target by name — React bundle, LWC component or VF page
renmy app reactRecipes
renmy app brewCoffeeCard
renmy app BrewShowcase

# Disambiguate two targets sharing a name, by the id renmy app list prints
renmy app lwc:force-app/main/default/lwc/brewCoffeeCard

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

# Print the URL but leave the browser alone (CI, remote shells)
renmy app brewCoffeeCard --no-open

# List every App preview target — React bundles, LWC components,
# Visualforce pages
renmy app list

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

# Generate a GraphQL SDL from your local SObject metadata (replaces
# "npm run graphql:schema" which requires a real org)
renmy 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)
renmy app build reactRecipes

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

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

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

# The same run as a committable Markdown artifact
renmy 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). renmy 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)

Who a request runs as: every request runs as the seeded System Administrator (005000000RUNNERAQ5), with the access an administrator has in an org: every object, field and record. nimbus.runtime.user and nimbus.mock.user-profile do not apply to these requests.

What's still not covered: 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.

Target selection:

• One target in the project → used automatically
• Name or id passed as argument → that target is used
• Several targets, no argument, terminal → interactive numbered picker listing every kind
• Several targets, no argument, non-TTY (CI) → errors with the target list
• --all → React bundles only: every React 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. LWC and Visualforce targets are served one at a time — name one instead.

If the bundle has no node_modules/, renmy 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 renmy 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: renmy 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 renmy 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 renmy app, it does not stand up the renmy 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 renmy's API surface still means running renmy 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 renmy downloads nothing to produce a number.

--serve boots a local renmy 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 renmy 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-Renmy-Apex-Cacheable, which the preview surfaces as a header badge. If a cacheable method performs DML, something the platform refuses outright, renmy reports the statement count on X-Renmy-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 renmy app itself — the dev server and its Salesforce API surface. list, schema, build, test, preview and scorecard run on the free tier.

renmy mcp

Start a Model Context Protocol server over stdio. AI coding agents (Claude Code, Cursor, and any other MCP-compatible client) call renmy'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, find_dependency_cycles, 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 renmy runtime 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 it with the AI clients on this machine:

renmy mcp install                    # every client detected here
renmy mcp install --client cursor    # just one
renmy mcp install --print            # the entry to paste elsewhere
renmy mcp status                     # which clients are registered
renmy mcp uninstall                  # take it out again

The entry carries the absolute path of your renmy binary, because a GUI client's PATH is rarely the shell's. Symlinks are left alone, so a Homebrew upgrade does not break the registration. Only the nimbus entry, the key renmy registers under, is written: other servers, other projects and every unrelated setting in those files survive, and a second install rewrites nothing.

Each editor is registered once. VS Code keys its servers under servers rather than mcpServers, and renmy writes the shape that editor actually reads.

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:

renmy 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. renmy publishes an ARD catalog so compatible registries and coding agents can discover this MCP server from task intent. ARD only handles discovery: after selecting renmy runtime, the client still installs the local binary and invokes renmy 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 renmy 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 renmy runtime up on a fresh SFDX project, including a CI snippet.
• apex-coverage-uplift — raise coverage by writing targeted tests for uncovered branches.

renmy 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 renmy releases.

Subcommands:

renmy skills list                    # available + which are installed locally
renmy skills install fix-failing-apex-test
renmy skills install all             # install every skill the agent supports
renmy skills remove fix-failing-apex-test
renmy skills path                    # print the install dir for the detected agent
renmy skills list --json             # the same catalog, for editors and scripts

Agent detection. Run from your project root and renmy 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, renmy 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.

renmy sync

Sync your project's schema (SObject definitions, fields, relationships) into the local database. renmy 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 also the only command that reads schema from an org. That reconcile before a test run uses your project's metadata and what a previous sync -o recorded; it never describes objects from an org itself. See Which org a command uses.

sync reads an org only when -o names one. Without -o it reconciles the database with your project's metadata, the bundled describes and what an earlier sync -o recorded; the sf default target-org and nimbus.org are not read. The --include-* flags read from an org, so each of them needs -o, and sync refuses them without it.

Syncing from an org also records the org's profiles and user licences in .nimbus/profiles.json, with each profile's permission flags. Tests then count, look up and run as the org's profiles rather than the eight renmy seeds: SELECT COUNT() FROM Profile answers the org's number, a profile name the org does not have finds nothing, as on the platform, and the running user is the org's System Administrator. A project that never ran sync -o keeps renmy's profiles, including a stand-in row for any name a test asks for.

Syncing from an org (-o) also records the org user the CLI is signed in as — the user the platform runs your tests as — with its TimeZoneSidKey and LocaleSidKey, in .nimbus/org-user.json. Tests then run in that user's zone, which is what Datetime.format(), Date.today() and the date-literal windows answer in the org; nimbus.org.timezone overrides it, and a project that never synced runs in the machine's zone.

It also records which duplicate rules the org has and which of them are active, in .nimbus/duplicate-rules.json. The standard Account, Contact and Lead rules and the rules in your source then run as they do in the org, and a standard rule the org does not have is switched off, unless nimbus.duplicateRules.standard or cumulusci.yml says otherwise. For each active rule the org has that neither a package directory nor stubs/ defines, sync prints one line naming the rule and the command that fetches it, renmy stub pull --org <org> --types DuplicateRule; past ten rules, the rest are counted in one line. The standard rules are built in and never named. Sync writes no rule definition itself: a rule your pipeline deploys belongs in your source, and a rule an admin keeps in Setup goes under stubs/ through renmy stub pull --rules. Until one or the other has it, renmy knows the rule by name only and does not run it. When the org refuses the DuplicateRule query, sync prints a warning, keeps the earlier file and names no rule.

It records the org's validation rules and flows the same way, each with whether it is active, in .nimbus/validation-rules.json and .nimbus/flows.json. A flow is active when it has an active version, and Process Builder processes are listed with the flows. For each active one that neither a package directory nor stubs/ defines, sync prints one line naming it and the command that fetches it, renmy stub pull --org <org> --types ValidationRule or --types Flow; past ten per type, the rest are counted in one line. A managed package's rule is named with its prefix (ns__Obj__c.ns__Rule). Sync writes no definition, and a validation rule or a flow runs as its own file says. One thing a run does read from .nimbus/flows.json: when each flow's active version was last set (activatedAt), which is the order the org runs the record-triggered flows that declare no triggerOrder in. Without the record, or for a flow it does not list, those flows run by API name; renmy flow list says which order a run uses. When the org refuses one of the two queries, sync prints a warning, keeps that type's earlier file and names nothing for it.

  Validation rules: 57 in dev, 54 active
[sync] ValidationRule Invoice__c.Amount_Required is active in org dev and has no definition in this project — fetch it with: renmy stub pull --org dev --types ValidationRule
  Flows: 9 in dev, 5 active
[sync] Flow Invoice_Stamp is active in org dev and has no definition in this project — fetch it with: renmy stub pull --org dev --types Flow

Approval processes and assignment rules are recorded the same way, in .nimbus/approval-processes.json and .nimbus/assignment-rules.json, and each active one your project lacks is named with --types ApprovalProcess or --types AssignmentRule. An approval process is active when its state is Active. Workflow rules go into .nimbus/workflow-rules.json by name and object only: the org does not say in one query which workflow rules are active, so the record carries no activity. Sync names every workflow rule of an object your project has no workflow file for, in a package directory or under stubs/, and says that the fetched file tells whether the rule is active. A rule missing from a workflow file your project has is not named, since the org may keep it inactive. As for validation rules and flows, sync writes no definition and a run does not follow these records.

  Workflow rules: 23 in dev on 6 objects; the org does not list which are active
[sync] WorkflowRule Lead.Volunteer Signup - Lead is in org dev and this project has no workflow file for Lead (whether it is active is read from the file once fetched) — fetch it with: renmy stub pull --org dev --types WorkflowRule
  Approval processes: 1 in dev, 1 active
[sync] ApprovalProcess Invoice__c.Invoice_Approval is active in org dev and has no definition in this project — fetch it with: renmy stub pull --org dev --types ApprovalProcess
  Assignment rules: 2 in dev, 2 active
[sync] AssignmentRule Case.Standard is active in org dev and has no definition in this project — fetch it with: renmy stub pull --org dev --types AssignmentRule

Quick actions, field sets and global value sets are recorded in .nimbus/quick-actions.json, .nimbus/field-sets.json and .nimbus/global-value-sets.json. The org keeps no active flag for them, so sync names every one your project defines nowhere, and the line says the item is in the org rather than active there. The platform's standard quick actions (LogACall, NewTask, Task.Defer and the others every org has) are built in and never named. Sync names each active record type your project lacks too, counting one declared under a CumulusCI unpackaged/ tree, where a run also reads record types. It does not write the record-type list: .nimbus/record-types.json is the snapshot --include-record-types writes, and a run reads that one. A run does not follow any of these lists; a quick action, field set, record type or value set counts as its own file says. Standard value sets have no inventory to read and are not named.

  Quick actions: 53 in dev
[sync] QuickAction New_Campaign is in org dev and has no definition in this project — fetch it with: renmy stub pull --org dev --types QuickAction
  Field sets: 37 in dev
[sync] FieldSet Contact.VolunteersSignupFS is in org dev and has no definition in this project — fetch it with: renmy stub pull --org dev --types FieldSet
  Record types: 31 in dev, 31 active
[sync] RecordType Opportunity.Donation is active in org dev and has no definition in this project — fetch it with: renmy stub pull --org dev --types RecordType
  Global value sets: 3 in dev
[sync] GlobalValueSet LoggingLevel is in org dev and has no definition in this project — fetch it with: renmy stub pull --org dev --types GlobalValueSet

When -s names a custom object that neither the bundle nor your project has, sync -o describes it from the org into .nimbus/schemas, which stays on the machine that synced. For each such object your project still defines nowhere, sync prints the command that records it in the repository, renmy stub pull --org <org> --types CustomObject, which writes the object's file and fields under stubs/.

[sync] Vehicle__c is described from org dev into .nimbus/schemas, which stays on this machine — record it in the project with: renmy stub pull --org dev --types CustomObject

That automatic reconcile regenerates every schema from your metadata each run, then fingerprints each object against the table already in the database. Objects whose shape hasn't moved are skipped without touching the database; the ones that changed are rebuilt whole, so a column type change, a removed field or a newly unique field all land on the next renmy test. On a database that survives between runs that is the difference between rebuilding a few tables and rebuilding all of them.

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, which applies every column type change but also wipes table data. Use -s to scope work to specific objects while iterating.

An incremental sync also checks the columns it already has. A table is created once, so its column types are frozen at whatever the renmy release that created it emitted — and a field whose type has moved since keeps the old column through every upgrade. Where the conversion cannot lose a value the column is converted in place; where it could, the sync says so and leaves it alone:

⚠ account.is_priority__c is text but the schema declares boolean — the column
  keeps its old type. Run `renmy sync --rebuild` to apply the change (it
  recreates the table and wipes its rows).

Left unsaid, that divergence surfaces much later and much further away, as a raw PostgreSQL operator does not exist: text = boolean at query time. Rebuilding the one object — renmy sync -s Account --rebuild — is usually enough.

The other way a describe and a table can disagree is the tables being narrower than the describes: a database built while .nimbus/schemas and .nimbus/org-fields.json were moved aside was rebuilt from repo source alone and lost every org-only column, and putting the two files back does not put the columns back. A run then fails query after query with No such column on fields the describe plainly has. Every run compares the two once and says so before any test starts:

⚠ 126 objects have describe fields with no column in the database (Lead.CurrencyIsoCode, Account.CurrencyIsoCode, Contact.CurrencyIsoCode and 2113 more).
  The database was built from a narrower schema than the describes now claim;
  queries on those fields fail with "No such column". Run: renmy sync -o <org> --rebuild

So: moving the schema cache aside for an experiment needs a renmy sync -o <org> --rebuild afterwards, not just restoring the files.

renmy sync                                        # Incremental sync of all objects, no org
renmy sync -o myorg                               # Also read standard-object describes from myorg
renmy sync -s Account,Contact,Lead                # Sync only these objects
renmy sync --rebuild                              # Full drop-and-recreate of all tables
renmy sync -s My_Object__c --rebuild              # Rebuild just one object
renmy sync -s WorkOrder -o myorg                  # Pull a standard object renmy doesn't ship a describe for
renmy sync -k orders                              # Only the objects one package defines or adds fields to
renmy sync -o myorg --include-setup-data          # Also pull Groups, Queues, Roles, Networks, Sites

-k narrows the sync to one sfdx-project.json package: the objects it defines (custom objects, custom settings, custom metadata types, platform events) and the standard objects it adds fields to. Every package directory is still scanned, so a sibling package's fields on a shared object such as Account are kept, and --rebuild keeps their columns. A sync narrowed with -s or -k does not record the project as fully provisioned, so the next renmy test reconciles the other objects before it runs.

-o reads the org's describe of every standard object renmy bundles and of every catalogue object your Apex or metadata names, such as WorkOrder or NetworkMember, and prints how many of each it read. Fields and child relationships the org has and the catalogue lacks are recorded, and picklist values come from the org, so a later run without an org keeps them.

-s also reaches objects renmy has never heard of. Standard-object describes ship with renmy runtime, 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. The same holds for a standard object renmy does not bundle but provisions from its catalogue when your Apex names it, such as NetworkMember or TaskWhoRelation: that describe comes from the Salesforce documentation or from renmy's own verification org, so renmy sync -s NetworkMember -o <alias> describes it from your org instead, and your org's describe replaces the catalogue's. It is remembered, so later syncs keep it, and a release that adds a bundled describe quietly takes over. The bundled describes list the child relationships an org has with no feature turned on; one a feature adds, such as OpportunityTeams on User with Team Selling, arrives with the object your Apex names (OpportunityTeamMember) or with renmy sync -o.

renmy init

Initialize renmy runtime 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)
renmy init

It also scaffolds what a project wants on day one: a commented nimbus.properties, a stubs/ directory with a README, and .gitignore lines that ignore .nimbus/ except its recordings. Nothing is overwritten: a file that already exists is left alone, and the ignore lines are skipped when .nimbus/ is already covered, which it will be: any run of the runtime, init included, appends them to the .gitignore of a git repository the first time it starts. See Project Setup.

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

renmy setup runs init and the steps that usually follow it, and reports the ones this project already has as done.

renmy setup

Set the project up for renmy runtime. The command assesses the project from what is on disk and then runs only the steps that are still missing, so running it again after a package is installed, after a schema change, or on a fresh clone does the remainder and reports the rest as done. It composes the commands that already do each piece: renmy init, renmy stub pull, renmy sync and renmy test.

# Assess the project, show the plan, ask before running it
renmy setup

# Include the steps that read an org
renmy setup -o my-org

# Print the plan and exit
renmy setup --plan

# Run named steps with no prompt
renmy setup --yes --only packages,schema -o my-org

Without -o, setup uses the org the project or the Salesforce CLI already defaults to, and the plan names which of the two it came from. The steps that read an org report themselves as needs-org when there is none, and everything else still runs.

Steps

Setup runs these in order, and each one can depend on the ones before it: the stubs need nimbus.properties, the sync needs to know which objects the stubs added, recording needs stubs to intercept, and the verifying run needs all of it.

A dotted capitalised reference such as Nebula.Logger is either a managed package or a class the org has, and the difference is not decidable from the source. Setup never declares one of them on its own, because declaring a class as a namespace makes every call into it return null with nothing said. With -o it asks the org which of those names are installed packages and pulls those; a name the org does not know is left to the verify step's --fetch-missing. Without an org it names them and leaves the choice to you.

Statuses

The plan gives every step one of five statuses:

• recommended: the project needs this and renmy can do it now. A plain renmy setup runs exactly these.
• optional: renmy can do this and the project does not need it. record is the step this applies to.
• done: the project already has it. Naming it in --only runs it again.
• needs-org: the step is needed and no org is chosen. Pass -o <org>.
• unavailable: the step cannot run here, and the step's detail says why, such as a missing Salesforce CLI or no stubs to record.

Flags

With a terminal and no --yes, setup prints the plan and asks once (y runs the list, n runs nothing, p asks per step). With no terminal it refuses and names --yes and --plan, so a script says which of the two it meant.

Exit codes

renmy 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.

renmy new apex-class AccountService --test
renmy new apex-trigger AccountTrigger --object Account --events before-insert,after-update
renmy new lwc orderPanel --expose --targets lightning__RecordPage
renmy new lwc typedPanel --ts   # a .ts class module; automatic when lwc/ has a tsconfig.json
renmy new custom-object Storage_Site__c --label "Storage Site"
renmy new custom-field Zone__c --object Storage_Site__c --type Text --length 80
renmy new layout "Storage Site Layout" --object Storage_Site__c --field Name --field Zone__c
renmy new lightning-page Storage_Site_Record_Page --type RecordPage --object Storage_Site__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 renmy test without a sync. renmy rescans the project's own metadata on every run, so a field you created a second ago is already a column. renmy 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 renmy tells you the metadata one rather than writing a field that silently behaves as text.

$ renmy 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.

Which package

Files go into the package marked default in sfdx-project.json. -k names another one, by package name, alias or path, and the layout rules apply inside it. A field, record type, validation rule or other child of an object follows the object into the package that holds it. With -k it goes into that package's own folder for the object instead, created if need be: that is how an unlocked package declares a field on an object another package owns.

renmy new apex-class OrderService -k orders
renmy new custom-field Tier__c --object Account --type Text --length 20 -k orders
# orders/main/default/objects/Account/fields/Tier__c.field-meta.xml

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.

renmy 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.

renmy 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 (renmy ships their describes); custom objects need a sync. Prints to stdout by default.

renmy fixture Account Contact          # print a TestDataFactory to stdout
renmy 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, renmy 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.

$ renmy 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 renmy 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.

renmy coverage diff

Compare two JSON coverage reports (from renmy 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:
renmy test "*" --coverage-report base.json
renmy test "*" --coverage-report pr.json
renmy coverage diff base.json pr.json --fail-on-drop

renmy 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.

renmy test "*" --evidence
renmy coverage lines AccountService
renmy coverage lines force-app/main/default/classes/AccountService.cls --all
renmy 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.

EXEC, SOQL, DML and DB TIME are totals across the whole run — the sum over every test that reached the line. PEAK/TX is the most any single transaction charged the line, and it is the only column a per-transaction governor ceiling may be read against; TEST names the test that peak transaction belonged to.

renmy 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 renmy'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.

renmy budget init            # measure the suite, write nimbus.budgets.json
renmy budget check           # re-measure, exit 1 if any test is over budget
renmy budget check --json    # machine-readable result for CI
renmy budget init -k billing # measure one package, merge it into the file

The budget file

nimbus.budgets.json at the project root. renmy 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 renmy 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

renmy 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.

On a project with several sfdx-project.json packages, renmy budget init -k <package> measures one package's tests and merges them into the existing file instead of replacing it, so it needs no --force. Each measured test's entry is replaced or added. Every other entry is kept: other packages' tests, hand-written patterns, and tests that failed this time. A defaults counter the file already budgets is raised to the package's worst and never lowered, and a counter the file does not budget stays unbudgeted. Running it once per package gives the file an unscoped init would write.

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 renmy 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

renmy budget check flags

renmy budget init flags

renmy 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.

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

Flags

Where the socket lives

On macOS and Linux the daemon listens on a Unix socket in a per-user runtime directory —$XDG_RUNTIME_DIR if set, otherwise ~/.nimbus/run/ — named after a hash of the project path (renmy-<hash>.sock). It is not inside the project: a Unix socket path is capped at 104 bytes on macOS, and a project nested more than ~80 characters deep could not be bound at all. The running daemon writes its endpoint to .nimbus/daemon.endpoint in the project, which is what renmy daemon status and the editor integrations read. Windows uses a named pipe and has no such file.

Override the directory with NIMBUS_RUNTIME_DIR if your environment needs it. A daemon started by an older release listens on .nimbus/daemon.sock; newer clients still find and stop it, so an upgrade does not strand a running daemon.

Runtime coverage and tests-on-idle

Every test run the daemon performs records, per test, the lines it executed. That ledger is kept for the last few runs under .nimbus/history/line-coverage/ and is what answers “who covers this line?” — in the editor gutter, and over these RPCs.

A read walks back to the most recent run that actually touched the file, not simply the most recent run. A run narrowed to three tests says nothing about the files it never reached, and reading its silence as “no test covers this” would blank the gutter after every idle run.

After idleMs (default 1500) with no further watch.touch, the daemon runs the tests that cover the changed lines and streams them through the usual nimbus/test.progress and nimbus/watch.complete notifications. A nimbus/watch.idle notification goes out first, carrying the exact selection and the evidence it came from — or, when nothing could be selected, the reason nothing is running.

Selection unions the line ledger with .nimbus/impact-map.json, under the cold-clone rule: a missing, stale or differently-versioned map is no map, never an empty one. With neither source, it falls back to the file's own test methods if it is a test class, then to the tests that executed any line of it, and then does nothing and says why. It never runs the whole suite unless fullSuite is on — an idle trigger that silently starts a four-minute run is one people disable within the hour.

A newer trigger cancels and supersedes a run still in flight, through the same slot nimbus/test.cancel operates.

Selecting tests over the RPC

Four daemon methods choose which tests to act on, and each accepts exactly the keys below. A request that carries a selector-shaped key the method does not read — className, methodName, testClass, program, suite, packages and the like — is refused with an error naming the keys that do select, and the pattern to send instead. Nothing runs.

An omitted selector still means "everything", which is what a client asking for a full run sends. The refusal is for the other case: a selector that was meant to narrow the run and would otherwise have been dropped by the decoder and silently widened to the whole project.

VS Code integration

The VS Code extension starts the daemon automatically when it detects a Pro license. You do not need to run renmy daemon start manually. The status bar shows a Renmy indicator — if it shows a slash, run Renmy: 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.

renmy login

Activate renmy runtime 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.

renmy login        # Open the browser, sign in, register this machine
renmy logout       # Deactivate this machine and free up a seat
renmy whoami       # Show the current account and license tier
renmy whoami --json  # Structured status for editor and tooling integrations

Licenses are validated online and cached locally: a validation is reused for up to 24 hours, for a stored sign-in and for NIMBUS_LICENSE_KEY alike, and a 7-day offline grace period is built in for outages and travel.

Re-running renmy 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.

renmy whoami --json returns plan, activation state, a shortened machine identifier, capability lists, and account URLs, and keySource: "login" for a stored sign-in, "env" when NIMBUS_LICENSE_KEY is in effect, and envKeyIgnored with envKeyHint when the variable is set but ignored. It never returns a license key or full machine identifier.

In CI or under an AI agent, a key in NIMBUS_LICENSE_KEY takes precedence over a stored sign-in. renmy whoami and renmy doctor then report the plan that key gives and name the environment as its source, without printing the key; checking registers no machine.

Anywhere else NIMBUS_LICENSE_KEY is ignored, so one key cannot be shared across a team through the environment. renmy whoami, renmy doctor and the Pro gates then say that the key is set and ignored. In an automated container or CI job, set CI=true; on a workstation, run renmy login.

Headless / CI: set NIMBUS_LICENSE_KEY in the environment instead of running renmy login. Running in CI is part of the Team plan, which includes a dedicated CI runner license with its own machine pool.

renmy dev

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

renmy dev                            # Launch the Dev UI and open it in the browser
renmy dev --addr 0.0.0.0:8085        # In a container with port 8085 mapped; prints a URL with a token

The Dev UI listens on the loopback interface only and answers only its own pages: a request whose host is not this machine, or that comes from another site, is refused. To reach it from another machine, such as a container with a mapped port, pass --addr. Beyond loopback the API requires a token, generated per start and printed in the URL unless --token names one.

renmy status

Show which database this project will use, what decides that database's connection, and which org the org-facing commands will reach (a local run reaches an org only through -o, see Which org a command uses). For a health check with fixes attached, use renmy doctor instead.

renmy status         # Human-readable summary
renmy 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" }
}

renmy 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.

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

Checks

Exit codes

CI usage

Gate your pipeline on a clean setup before running tests:

renmy doctor && renmy test

renmy orgs

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

renmy orgs

To put one question to every one of them at once, see renmy orgs find and renmy orgs query.

renmy orgs find / renmy orgs query

The same question, every authenticated org, at once. find takes a record Id and reports which orgs hold it; query takes a SOQL query and reports what each org returns. Both list hits first, then the orgs that gave no answer, then the orgs that were not asked, then the misses — an org that could not be checked is not an org where the record is absent.

# A record Id someone handed you, org unknown
renmy orgs find 00Q5g00000AbCdEfAA

# The same, but only these orgs, and give each one ten seconds
renmy orgs find 00Q5g00000AbCdEfAA --orgs prod,uat --timeout 10s

# One query in every org
renmy orgs query "SELECT Id, Name FROM Lead WHERE Email = 'ada@example.com'"

# For a script
renmy orgs find 00Q5g00000AbCdEfAA --json

How an Id finds its object

SOQL needs an object name, and the object behind an Id is only knowable from its three-character key prefix — which is per org: a custom object's prefix is assigned when the object is created and differs from org to org. So each org is asked what the prefix means to it (one light EntityDefinition query), and the record is then selected from that object. A hit shows the record's Id and Name, or Id alone for an object with no Name field. A prefix that names nothing in an org is a miss with the reason stated.

Output

One line per org — org, HIT / miss / error / not connected, row count, time — then a verdict line, then the rows of every org that had any. Orgs are asked six at a time, each under its own timeout, through the same native-first org engine as renmy soql -o. An org the Salesforce CLI reports as not connected is listed but not asked: an expired session would cost a slow failure to learn what sf org list already says. Naming it with --orgs asks it anyway.

renmy   HIT               1 row   1167 ms  Account
deved   not connected         —         —  not connected — run sf org login web -a deved

1 hit in 1 org · 1 not connected in 1167 ms

renmy — Account
  Id                  Name
  001g500000H2GQIAA3  Edge Communications

Flags

Exit codes

The same engine backs the daemon's nimbus/orgs.query RPC, which streams each org's answer as it arrives.

renmy org doctor

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

The native org engine

The org operations renmy 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 renmy 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 renmy 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. renmy 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)
  describe an object         native  (one object's describe; the Tooling describe (-t) still goes through sf)
  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 renmy deploy assurance cycle, org creation, package operations, renmy 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

An answer from the org is not one of those. A query the org rejects and a describe of an object it does not hold come back to you as errors, natively, and the capability keeps its native path. Running sf to be told the same thing costs a second process and learns nothing, and one such answer would otherwise put every later call of that capability on the subprocess for the life of the process — the daemon's life, in the IDE.

renmy 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 renmy 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 — renmy 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. renmy will not send a secret it could not decode.

Reading the report

renmy org doctor                 # the default target org
renmy org doctor -o my-sandbox   # a specific org
renmy org doctor --probe         # also make one live call to prove reachability
renmy 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. That includes the session used to read standard-object describes, which goes back to sf org display. renmy falls back on its own too: a login it cannot read (an encrypted sfdx store with no key available, an alias with no login) is never a failure, only the slower route.

# 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 renmy soql -o my-org "SELECT Id FROM Account LIMIT 1"

renmy org status

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

renmy org status                    # everything tracked for the target org
renmy org status AccountService     # one class
renmy org status -k core            # the files of one sfdx-project.json package
renmy 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 — `renmy metadata deploy` will refuse those.

A project with no rows has simply never retrieved or deployed through renmy — 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.

With -k core the table shows only the entities whose recorded file lies in that package, its unpackagedMetadata included. Records outside the package are not sent to the org. An entity recorded without a file cannot be placed in a package, so it is listed after the package's rows under its own sentence, and an ORG NEWER row there still sets the exit code. A package with nothing recorded says Nothing tracked in package core (...) for this org. --json adds packages and unattributed (the rows without a file); without -k neither key is present.

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

renmy agent (experimental)

Test an Agentforce agent's action surface locally — the actions, never the planner. renmy 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; renmy 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.

renmy 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 renmy agent list's job and executing it is renmy agent test's.

renmy agent list                      # every action, and how each one resolves
renmy agent list --coverage           # ...and what no local test has reached
renmy agent list -k support           # only the agents in one package

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

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

What renmy 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

renmy agent test --fixtures                     # every **/*.agenttest.yaml
renmy agent test --fixtures ./agent-tests      # one directory
renmy agent test --fixtures --case "Submit_Case/high priority escalates"
renmy 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. renmy 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 renmy 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 renmy report consumes this unchanged. On GitHub, run them as one more step after setup-nimbus:

- uses: renmy-solutions/setup-nimbus@v1
# setup-nimbus installs the CLI as nimbus, the same binary as renmy
- name: Run agent fixtures
  run: nimbus agent test --fixtures --results-xml agent-results.xml
  env:
    NIMBUS_LICENSE_KEY: ${{ secrets.NIMBUS_LICENSE_KEY }}

Flags

renmy 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.

renmy org diff                              # the default target org
renmy org diff -o my-sandbox                # a specific org
renmy org diff --type ApexClass,ApexTrigger # narrow it
renmy org diff --all                        # list the matching components too
renmy org diff -k core                      # one sfdx-project.json package
renmy 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. renmy 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.

One package

renmy org diff -k core compares one sfdx-project.json package with the org. The rest of the project is still read. An org component that another package of this project holds is undetermined with the reason otherPackage: it is not org only, and it is not compared. Those rows are counted and listed only with --all, like matching ones, and the summary counts them apart from what was checked. Another package's local-only components are not listed at all. A class that two packages define is compared on the selected package's copy. A nested package directory that was not selected counts as another package.

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.

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

{
  "schema": "nimbus.orgdiff/v1.1",
  "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 renmy 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.

A -k run adds packages to the payload and otherPackage and hiddenOtherPackage to each type node, and its otherPackage rows offer retrieve only. A run without -k has none of these keys. Schema nimbus.orgdiff/v1.1 added them; a reader of v1 reads an unscoped payload unchanged.

renmy 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.

renmy 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
renmy schema --json

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

# Row counts, largest first
renmy 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 renmy schema | grep Account is a table-name search and answering it with JSON would break every script that does it.

Flags

renmy 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
renmy soql "SELECT Id, Name FROM Account WHERE Name LIKE 'Acme%'"

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

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

# Ask the org's Tooling API — class source, logs, test results, coverage
renmy soql -o my-org --tooling "SELECT Id, Name, ApiVersion FROM ApexClass WHERE Status = 'Active'"

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

The local mode runs through the same runner configuration renmy 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 renmy 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. Only -o sends a query to an org; the sf default target-org and nimbus.org do not. An org's answer names the org in the grid's footer.

The Tooling API

--tooling sends the query to the org's Tooling API instead of its data API. That is where a developer's own metadata lives as queryable tables: ApexClass.Body, ApexLog, ApexTestResult, ApexCodeCoverage, MetadataComponentDependency, TraceFlag, Flow. A data query cannot see any of it.

You rarely have to remember the flag. A query whose FROM object only exists in the Tooling API is routed there anyway, and the result says so — in the grid's footer, and as a note field under --json. The subquery in SELECT Id, (SELECT Id FROM ApexClasses) FROM Account does not count: the routing reads the outermost FROM, so an Account query stays an Account query.

Only an org has a Tooling API. Naming one of its objects without an org — renmy soql "SELECT Id FROM ApexLog" — is refused with a sentence rather than run against a local table that does not exist. ApexClass and ApexTrigger are the exceptions: renmy seeds both locally, so they answer either way, and the org query goes through the Tooling API so that asking for Body works.

Flags

--json carries columns, rows, count, the generated sql, the resolved object, the elapsed time, a tooling boolean saying which endpoint answered, and a note when renmy picked that endpoint for you. 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.

renmy cache

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

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

renmy config

Manage renmy configuration via the nimbus.properties file.

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

renmy 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.

renmy reset

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

It is also how you get the disk back. The local database is kept between runs so the next one starts on the tables it already has instead of rebuilding all of them — that is worth a second or two per run and costs 60–90 MB per project, nearly all of it the .nimbus/db/ data directory, which this removes along with the synced schemas, the AST cache and the traces. See Project setup for the full breakdown.

What it does not remove is the shared PostgreSQL installation under ~/.nimbus/pg/. Those binaries are extracted once per machine and used by every project, so resetting one project never makes another one re-download anything.

renmy data

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

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

# No prompt (required when stdin is not a terminal)
renmy 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.

renmy data reset vs renmy reset

The distinction is the point of the command, and reaching for the wrong one costs a renmy 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 renmy 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.

renmy 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 renmy 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
renmy data branch experiment

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

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

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

# Remove one (refuses the branch in use)
renmy 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 renmy reset deletes them along with the rest of the local database. They do survive a daemon shutdown and a machine restart — the database is stopped between runs, not deleted. 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 renmy 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 renmy 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 renmy 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 renmy 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. renmy data branches shows what that adds up to.

renmy data clone

Copy a Salesforce org's data into a local data branch, so tests and anonymous Apex run against the real dataset — without touching the org. Rows land with their org Ids, so a local query returns what the org would return.

# A working set of the default org, into org-<alias>
renmy data clone

# Every row of a sandbox, without personal data
renmy data clone --org uat --thorough --mask default

# Just the objects a bug touches, with their children
renmy data clone --org uat --objects Account,Contact --with-children

# Later, bring it back in step with the org
renmy data switch org-uat
renmy data refresh

Two speeds

Quick (the default) takes the most recently modified rows of each object and then everything they point at, following lookups to a bounded depth. That matters: a truncated dump gives you Opportunities whose Accounts are missing and every lookup resolving to null. Quick is minutes and a few thousand rows, and its lookups resolve.

--thorough takes every row of every object. Longer, and complete.

What a clone asks before it fetches

Both speeds start by asking the org how many rows each object holds — one batched call per 25 objects, so the whole question is a handful of round trips. Three things follow from the answer. An object the org holds no rows for costs no round trip at all. A small object is pulled with one query. Only an object past ten thousand rows gets a Bulk job, which has a fixed cost of about nine seconds whether it carries a million rows or none, and loads through PostgreSQL COPY.

An object the org declines to count — one the running user cannot query, one the local schema has and the org does not — is pulled, never skipped. Both speeds run their org round trips several at a time; --parallel sets how many.

The mirror branch

A clone lands in org-<alias> and does not switch you onto it. Your current branch keeps your data; working against the org's data is a deliberate renmy data switch org-<alias>.

That branch is a mirror, and two rules follow. A test run never clears it — every other branch is emptied and re-seeded at the start of a run, which would destroy the clone. And a clone replaces the data it loads, so it refuses to run on anything that is not an org- branch. To experiment freely, fork it: renmy data branch bug-1234 --from org-uat, and the mirror stays clean for the next refresh.

How much is replaced follows --objects. A clone with no --objects replaces the whole branch. A narrowed one — renmy data clone --objects Account — truncates and reloads only those objects and leaves the rest of the mirror exactly as it was, so you can re-pull one object after a long --thorough run without repeating it.

renmy data refresh

Asks the org what changed since the last clone or refresh and applies only that: records whose SystemModstamp advanced, and records the org deleted. A refresh of a large mirror is seconds where the clone was minutes. It runs on the branch you are on, and refuses a branch whose rows came from a different org.

Masking is a starting point, not a compliance control

--mask default covers the standard personal-data fields — email, phone, the address streets, and the rest — so the common case is one flag. It cannot know your org's own sensitive fields: a custom SSN__c, a salary, a case body. Name those yourself. Cloning production onto a laptop is a decision about data, not only about disk.

Keep the daemon running

A clone or a thorough refresh is a long command, and without renmy daemon running each command owns a short-lived local database cluster. Start the daemon first and the cluster stays up for the whole run.

What this is not

It is one-way. Nothing here writes to the org. Deleted rows arrive as local soft deletes, hidden from ordinary SOQL and visible to ALL ROWS, exactly as in the org. Attachments, files and other blob content are not cloned. To move records the other way — a branch into an org, or one org into another — see renmy data transfer.

renmy data transfer

Move records of one or more objects from a source to a target. Either side is an org alias or a local data branch, so this covers four directions: org to org, org to branch, branch to org, and branch to branch.

# A working set of accounts and their contacts, sandbox to scratch org
renmy data transfer --from uat --to scratch1 --objects Account,Contact \
  --where "Account=Industry = 'Technology'" --dry-run

# The local mirror's rows back into the org they came from, idempotently
renmy data transfer --from branch:org-uat --to uat --objects Account \
  --key Account=Legacy_Id__c

# One org's data into a branch, without switching onto it
renmy data transfer --from uat --to branch:org-uat --objects Account,Contact

Naming the two ends

A bare word is an org: --from uat is the org aliased uat. A data branch says so: --from branch:org-uat. org:uat is accepted too, for a client that would rather be explicit. The word local is refused — it names the runtime in the IDE protocol, not a place records live, and the thing it usually means is branch:default.

The Id is the whole problem

An org mints its own Ids, so a record inserted into a second org is a different record with a different Id. Objects are therefore written parents first, worked out from the source's lookup graph, and every lookup pointing at a record that travelled is rewritten to the Id the target gave it before the child is written.

A lookup pointing at a record that is not being transferred:

OwnerId is not carried into another org: a User Id from one org names nobody in the next, so the org assigns the running user as owner and the plan says so once. Within one org, and into a data branch, the owner travels unchanged.

A transfer into a data branch keeps every Id exactly as the source has it — a mirror whose records have different Ids is a different dataset — and notes the org the rows came from, so renmy data refresh can bring them up to date later.

--dry-run

Reads the source, prints the plan and writes nothing: the order, the rows per object, the key each object is written on, the fields the target will not take and why, and what happens to every lookup. Without --dry-run the command shows the same plan and asks before writing; --yes skips the question.

Re-running a transfer

Without --key the write is an insert, so running the same transfer twice creates a second copy of every record. With --key Account=Legacy_Id__c it is an upsert matching on that field, and a second run updates what the first one created. The field has to be a real external Id in the target org — externalId and idLookup both — and the command refuses anything else by name, listing the fields that would work.

What v1 does not do

• No rehearsal. A transfer does not simulate the write against the local database first. The plan says so.
• No deletes, and no updates without a key. Nothing in the target is removed, and a record the target already has is only updated when --key says which one it is.
• No empty values. A field the source row leaves empty is not written. On an insert that is what empty means anyway; on an upsert that matches an existing record, the field keeps whatever the target already holds.
• No self-referencing lookups. A lookup from a record to another record of the same object — Account.ParentId — is not remapped: both rows are written in the same pass, so the parent's new Id does not exist yet. The lookup is emptied, or the row is held back when it is required.
• No Bulk API on the write. A transfer needs the Id the org minted for every row it created, and only the synchronous sObject Collections path returns those. It sends 200 records per request, up to eight requests at once, which is slower than Bulk on a large object and not slow.
• No blobs. Attachments, files and other base64 content do not travel, and neither do compound fields — their components travel on their own.

Which record became which

Every run writes its old-Id-to-new-Id map to .nimbus/transfers/<target>-<date>-<time>.json, one file per run, so "where did this record end up" has an answer after the command has exited and a second transfer to the same target does not overwrite the first's.

renmy db

Manage the embedded PostgreSQL database directly.

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

renmy db stop stops the postgres process and leaves the cluster on disk, which is also what happens at the end of a run and when the daemon shuts down: the next start reuses the synced tables instead of rebuilding them. To delete the cluster itself, use renmy reset or renmy daemon start --clean.

renmy db start leaves the database running for later commands and marks it as started on purpose. Every renmy command sweeps for databases orphaned in other projects — a postgres left behind by a killed run — and a pre-started database, idle with no daemon and no client on it, would otherwise look exactly like one. The mark protects it from that sweep for 24 hours; renmy db stop ends it early, and running db start again renews it. A database a test run started implicitly carries no mark and is stopped once nothing is using it.

renmy 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
renmy metadata retrieve -o my-org

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

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

How it travels

Both directions go through renmy'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.

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

renmy metadata retrieve

Every run that hits a class, object, field, custom metadata type or label renmy 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 renmy 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.

A component the project does not have yet lands in the default package directory. -k billing sends it to that package instead, under the package's layout (main/default/classes/ and so on). A component the project already has is updated where it is, whichever package holds it. The Salesforce CLI cannot target a package, so when a retrieve goes through it, new files land in its default package directory and the command prints a line on stderr saying so.

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.

renmy 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.

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

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.

-k core scopes a deploy to one sfdx-project.json package. With no other argument it deploys the package's directory, its path entry, as sf project deploy start -d ships it; the package's unpackagedMetadata is not deployed. With names or paths, a bare name is looked up in that package only, so a class two packages define is that package's copy, and a path outside the package is refused. -k cannot be combined with --manifest.

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 renmy 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, renmy asks the org one question: has this class changed since this working copy last took it?

It can answer that because every time renmy 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:
  renmy 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 — renmy 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 renmy org status to read the bases without deploying anything.

A directory deploy, -k included, checks every class and trigger in the directory. The check covers Apex only, so the other types a deploy carries are named once in a stderr line (Can't check PermissionSet for conflicts), and a deploy that carries them is never skipped as already in the org.

Flags

renmy 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.
renmy rename field Account.Legacy_Code__c Account_Code__c

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

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

# The plan as JSON, for an editor to drive
renmy 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.

renmy 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.

renmy 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.

renmy 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 renmy test replays the recorded answers offline — no org, no flag.

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

It is exactly renmy stub pull followed by renmy 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.

renmy stub

Scaffold and inspect stubs/ — the directory renmy 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

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

Scaffold a new stub class

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

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

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

# Replace an existing stub
renmy 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. renmy 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
renmy stub add mp.Logger --method 'info(String):void'
renmy 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

renmy 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
renmy stub label Welcome_Message --value "Hello there"

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

# Several at once (value defaults to the label name)
renmy 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

renmy 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
renmy stub pull --org dev

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

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

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

# Narrow the describes to specific objects
renmy 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 (the package's fields and the custom fields your org added to the object without a prefix), 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 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 renmy sync so the next test run sees it — the pull reminds you.

The block is merged, not regenerated. Every --data rewrite is keyed by object. A run replaces the lines of the objects it recorded or marked in that run, plus every object of a namespace it pulled, and keeps every other line in the block: the project's own unnamespaced settings lines, the objects of namespaces it did not pull, and the # renmy setup: marker lines recording a setting the org was asked about and had nothing to record for. A narrowed pull, with --objects or --namespaces, therefore never drops what an earlier wider pull wrote.

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.

A namespace the org refuses does not sink the pull. A timeout, a transient API failure, or a package whose SymbolTable the org will not project stops that namespace and nothing else: the ones that answered are written, and the run ends by naming each namespace it skipped with the org's own error and the exact command that pulls just those. The exit code is non-zero, and nothing on disk records a skipped namespace as pulled, so the re-run fills precisely the gap. A failure of namespace discovery itself is still fatal — no namespace was established, so there is nothing partial to keep.

Pull duplicate and matching rules from an org

renmy stub pull --types fetches configuration an admin keeps in Setup rather than in your source. For each type it lists the org's active items, leaves out the standard ones renmy has built in and every item a package directory or stubs/ already defines, retrieves the rest with sf project retrieve start, and writes each file under stubs/ in the org's own XML, with a comment naming the org and the date. --rules is --types DuplicateRule,MatchingRule.

# Duplicate rules and the matching rules they name
renmy stub pull --org dev --rules

# See what it would fetch first (prints every sf command it runs)
renmy stub pull --org dev --types DuplicateRule --dry-run

Duplicate rules land in stubs/duplicateRules/<Object>.<Rule>.duplicateRule-meta.xml and matching rules in stubs/matchingRules/<Object>.matchingRule-meta.xml, one file per object, the layout a package directory uses. A matching rule is fetched when a duplicate rule names it. When that duplicate rule arrives in the same pull, a second retrieve follows for its matching rules. The org does not hand out its standard matching rules; renmy has them built in.

A file that exists is never overwritten or edited. A matching-rule file your project already has is left alone even when a duplicate rule names a rule it lacks, and the pull names that rule. To refresh a file, delete it and pull again. Each file written, left alone or failed gets one line, a rule the org cannot hand out is reported with the org's own message, and the pull exits non-zero only when nothing could be retrieved at all. renmy sync -o names the active rules your project is missing; Duplicate rules describes how a run reads them.

Pull validation rules and flows from an org

--types ValidationRule fetches each active validation rule the org has and your project does not define into stubs/objects/<Object>/validationRules/<Rule>.validationRule-meta.xml, the layout a package directory uses. A rule on a custom metadata type lands the same way. The retrieve also returns the object's .object-meta.xml; only the rule is written. A managed package's rule is fetched and written by its prefixed name, ns__Rule. --types Flow fetches each flow that has an active version into stubs/flows/<Flow>.flow-meta.xml, as that version. Process Builder processes are flows and come with them; a flow with no active version is not fetched.

# Validation rules and flows an admin keeps in Setup
renmy stub pull --org dev --types ValidationRule,Flow

# The same, printing every sf command and writing nothing
renmy stub pull --org dev --types ValidationRule,Flow --dry-run

A run reads them after your package directories: a rule or flow a package directory deploys wins over a stub of the same name, and each runs as its own file says. The org will not hand over a rule on a managed package's non-customizable object; the pull prints the org's sentence for that rule (Can't retrieve non-customizable CustomObject named: …) and writes the rest.

Pull workflow rules, approval processes and assignment rules from an org

--types WorkflowRule fetches an object's workflow as one file, stubs/workflows/<Object>.workflow-meta.xml, holding every rule, field update, email alert and task the org has for the object, a managed package's rules among them. The org does not say in one query which workflow rules are active, so the pull fetches every object that has a workflow rule and your project has no workflow file for, and each rule then runs as its <active> in the file says. An object your project already has a workflow file for is left out. --types AssignmentRule fetches the Case and Lead assignment rules the same way, one file per object in stubs/assignmentRules/<Object>.assignmentRules-meta.xml, for each object with an active rule your project lacks. --types ApprovalProcess fetches each active approval process your project does not define into stubs/approvalProcesses/<Object>.<Name>.approvalProcess-meta.xml. The spellings the Metadata API uses, Workflow and AssignmentRules, are accepted too.