Every LATdx command, flag, and stream contract in one place.

Command entrypoint in this repo:

latdx <command>

If latdx is not found, complete install/link steps in cli-quickstart.md.

Top-level commands

Global options

Environment variables

The most relevant env vars for the global flag surface:

For the full list of supported environment variables, see environment-variables.md.

Stream contract

LATdx separates machine-readable output from human diagnostics on the two standard streams:

• stdout carries the command’s result payload only. With --json (where the subcommand supports it), exactly one JSON document; without --json, the human-formatted result. It is never mixed with logger output, spinners, live test renderer frames, or progress events.
• stderr carries every diagnostic stream: logger lines (text by default, NDJSON when --json is passed or LATDX_LOG_FORMAT=json is set), spinner animations, the live test renderer, --progress-events, and interactive prompts.
• Auto-degradation (no flag needed): non-TTY stdout, CI env set, NO_COLOR, or --json all collapse the TTY-only affordances (spinner, live renderer, color) automatically.

Pipes like latdx test --json | jq work without any extra flags.

test run

Core options

Execution behavior options

Experimental anon-apex execution flags

The following flags drive the LATdx anon-apex (latdx-engine) execution path and are gated behind LATDX_EXPERIMENTAL=1. Without the enabler they are not registered and commander rejects them with error: unknown option '<flag>'.

Run-mode knobs

Defaults: --engine sf + --db normal (the supported path). Anything else is experimental and gated behind LATDX_EXPERIMENTAL=1. The --engine and --db flags are not registered without the enabler (commander rejects them as unknown options); the corresponding env-var overrides also error with ExperimentalFeatureError when the enabler is unset.

When any value diverges from the default, the run header echoes the active value (e.g. Engine: latdx, DB: mocked) so it is obvious the run is non-standard.

Test-result cache

Every latdx test run against an org transparently consults a per-org disk cache keyed on (test class source + transitive dep source + org schema rev). The cache layer is governed by ADR 0009 phase rules: Phase 0 (default) is the read-disabled parity floor where writes still happen but every read returns to the miss list, so the engine runs every method; Phase >= 1 unlocks per-rule skip logic. See test-caching.md for the full rationale.

When the cache wraps the engine, the run prints a trailing line on stdout. Phase 0 includes a would have hit telemetry tail; Phase >= 1 includes the active phase and shadow counters when sampled:

Cache: 0 hit / 18 miss / 0 stale (18 written)  [phase 0, would have hit 12]
Cache: 12 hit / 3 miss / 1 stale (4 written)  [phase 2, 1 shadow sample / 0 mismatches]

{
  "status": 0,
  "result": {
    "summary": {
      /* unchanged sf-shape */
    },
    "tests": [
      /* unchanged sf-shape */
    ],
    "cacheReport": {
      "hits": 12,
      "misses": 3,
      "stale": 1,
      "writtenOnExit": 4,
      "phase": 2,
      "killSwitch": false,
      "shadowSamples": 1,
      "shadowMismatches": 0,
    },
  },
  "warnings": [],
}

When the cache is disabled (--no-cache or LATDX_CACHE_DISABLE=1) the line is suppressed; the run header echoes Cache: off to make the opt-out visible. When the active phase is non-zero the header echoes Cache: phase N. Coverage rule for the SF engine: with --no-coverage per-method skip is allowed; with coverage on, any miss inside a class promotes that class’s hits back to misses so the engine can compute aggregate coverage on a single transaction.

Cache env vars are read per CLI invocation and forwarded to the workspace daemon with the test-run request. You do not need to restart the daemon for LATDX_CACHE_PHASE=2 latdx test run ... or a per-rule cache flag to apply to that run.

Validation rules

test list

If --file/--dir is omitted, test list uses org mode and resolves org via --target-org or default org.

Output

Without --json, each discovered method is printed to stdout as a single fully qualified path: ClassName.methodName. A trailing summary line (Total: N file(s), M test method(s)) is also written to stdout. Diagnostics from the logger remain on stderr:

latdx test list -d src/tests > tests.txt        # data + summary captured, logs still on terminal
latdx test list -d src/tests | grep TestsAnti   # filter Class.method paths
latdx test list -d src/tests 2>/dev/null        # silence diagnostics

While the command runs, a progress spinner on stderr reports the current phase, elapsed time, the per-batch fetch / scan counts, and (during the scan phase) the running totals of test methods and test classes discovered so far. Example: [7s] Discovering tests in org my-org (scanned 1200/2500 classes; 837 test(s) across 71 class(es)). The spinner is suppressed in --json mode and in non-TTY contexts (CI=1, --plain, piped stderr) where a single static line is emitted per phase instead.

In org mode, test list queries ApexClass.SymbolTable (the compiler’s precomputed structural metadata) over the Tooling API instead of pulling each class body and parsing it locally. On a 5,000-class org this drops the cold-path runtime from ~2 minutes to ~10 seconds. Classes whose SymbolTable is null (compile errors or hidden managed-package source) are skipped with an aggregate warning; use --dir against the local source tree if you need them included.

With --json, the structured payload is written to stdout instead.

test impact

Show which test methods statically reach a set of changed Apex classes (no execution; uses Phase 4 reach analysis). Spawns its own apex-ls bridge — no daemon required.

--base is one-shot only (incompatible with --watch) and folds together with positional identifiers when both are supplied. Three-dot range matches what GitHub renders for a PR (diff against the merge base). Deletions are dropped because the workspace no longer contains the file for apex-ls to index.

When the resolved delta contains any Apex trigger (*.trigger / *.trigger-meta.xml) the JSON output includes triggerChange: true and human mode prints a stderr warning. Apex triggers fire on DML and have no static call-graph edge from any test method to the trigger that fires, so the affected list is incomplete for trigger-only changes — CI scripts should fall back to running the full suite when the flag is set.

The same applies to Apex Flows (*.flow-meta.xml): record-triggered Flows fire on DML and auto-launched Flows are dispatched by name string at runtime via Flow.Interview.createInterview. When the delta contains any flow, the JSON output includes flowChange: true and human mode prints a stderr warning.

Custom Labels (*.labels-meta.xml) hit the same blast-radius problem: System.Label.X is a static-name reference, but the label VALUE (the only thing that affects test outcomes) lives only in the labels XML and is invisible to the bridge’s call graph. When the delta contains any labels file, the JSON output includes labelChange: true and human mode prints a stderr warning.

Custom Metadata Type records (*.md-meta.xml) follow the same pattern: Apex queries records via SOQL or Type.getInstance('Name') / getAll(), but the record VALUES live only in customMetadata/...md-meta.xml files. When the delta contains any custom-metadata record file, the JSON output includes customMetadataChange: true and human mode prints a stderr warning.

Validation Rules (*.validationRule-meta.xml) live under objects/<X>/validationRules/ and fire on DML; the bridge’s schema scan reads field / object metadata only, not rule bodies. When the delta contains any validation-rule file, the JSON output includes validationRuleChange: true and human mode prints a stderr warning.

Permission Sets (*.permissionset-meta.xml) and Profiles (*.profile-meta.xml) define field-level security and object permissions; tests using runAs(user) see different visibility (and different Schema.SObjectType.X.fields.Y.isAccessible() results) when those XMLs change. When the delta contains either kind, the JSON output includes permissionSetChange: true / profileChange: true (independently) and human mode prints a single combined stderr warning.

Record Types (*.recordType-meta.xml) live under objects/<X>/recordTypes/ and define picklist value sets, default field values, and activation. Tests using [SELECT Id FROM RecordType WHERE DeveloperName='X'] lookups or relying on default field values for specific record types see different behaviour when the XML changes. When the delta contains any record-type file, the JSON output includes recordTypeChange: true and human mode prints a stderr warning.

Sharing Rules (*.sharingRules-meta.xml) live in sharingRules/<ObjectName>.sharingRules-meta.xml (sibling to objects/) and define record-level access beyond the org-wide sharing default. Tests using runAs(user) see different record visibility (and SOQL results) when sharing rules change. When the delta contains any sharing-rules file, the JSON output includes sharingRuleChange: true and human mode prints a stderr warning.

Workflow rules (*.workflow-meta.xml) live in workflows/<ObjectName>.workflow-meta.xml and bundle workflow rules / field updates / outbound messages / tasks that fire on DML — same false-PASS surface as triggers and flows. Workflows are legacy (Salesforce migrates callers to Flows) but still active in many orgs. When the delta contains any workflow file, the JSON output includes workflowChange: true and human mode prints a stderr warning.

All ten flags are independent — any combination can fire on the same diff, and any one of them signals “fall back to the full suite”.

CI wiring (GitHub Actions)

IMPACT=$(latdx test impact --base origin/${{ github.base_ref }} --json)
NONREACH=$(jq -r '(.triggerChange // false) or (.flowChange // false) or (.labelChange // false) or (.customMetadataChange // false) or (.validationRuleChange // false) or (.permissionSetChange // false) or (.profileChange // false) or (.recordTypeChange // false) or (.sharingRuleChange // false) or (.workflowChange // false)' <<<"$IMPACT")
if [ "$NONREACH" = "true" ]; then
  # Trigger / Flow / Label / CustomMetadata / ValidationRule / FLS / RecordType / SharingRule / Workflow blast radius cannot be statically resolved; run everything.
  latdx test run
else
  TESTS=$(jq -r '.affected | join(" ")' <<<"$IMPACT")
  [ -z "$TESTS" ] || latdx test run --tests $TESTS
fi

Experimental command gate

adapt, boost, clean, restore, and uninstall are gated behind LATDX_EXPERIMENTAL=1 (truthy: 1 / true / yes / on, case-insensitive). Without the enabler they are not registered: latdx --help omits them and latdx <cmd> exits non-zero with error: unknown command '<cmd>'. Set the env var to opt in.

LATDX_EXPERIMENTAL=1 latdx adapt -f Foo.cls

adapt

boost

Adapt every .cls under a source directory for test acceleration (standard Salesforce Test API). Heavy lifting runs in BoostService from @latdx/core; the command is a thin wrapper.

The terminal summary line reports transformed, unchanged, and errors counts; per-file error reasons are logged at warn/error level.

restore

Reverse boost-mode adaptations and restore original Apex classes from LATDX_ORIG markers. Operates on local files (dir mode), an org (org mode), or both in one invocation.

config

Manage CLI configuration. Subcommands:

All three accept --json for structured output: {key,value} for set, {key,value,source} for get, {values:[{key,value,source}]} for list (source is user or default).

The only supported config key is channel (values: stable, latest; default: stable).

upgrade

Check for and apply CLI updates.

Both subcommands respect the configured channel (stable or latest) to determine which release stream to compare against. latdx upgrade --json emits {currentVersion,latestVersion,upgraded} after the install script finishes; install-script chatter is routed to stderr in JSON mode so stdout stays a single JSON document. latdx upgrade check --json emits {currentVersion,latestVersion,updateAvailable}.

Automatic pre-test FLS/OLS grant

Fresh scratch orgs and many sandboxes ship standard fields (for example Account.AccountNumber, Account.Rating, Account.Site) with Field-Level-Security unset for every profile including System Administrator. Deployed @IsTest classes bypass FLS on their own field references, so Salesforce’s native test runner succeeds without a grant. LATdx test execution runs through anon Apex, which enforces FLS at compile time, so without a grant test runs fail with Field does not exist on those same references.

To keep latdx test run working out of the box, @latdx/core deploys and assigns a latdx_TestRunnerAccess permission set to the currently authenticated user before dispatching tests. The permset grants full object permissions plus readable=true editable=true FLS on every settable field the Tooling API exposes. The grant is cached two ways:

1. In-memory on the LatdxCore instance: subsequent test runs in the same process return instantly.
2. On disk at ~/.latdx/runner-access/<orgId>.json (one file per org), keyed by an inexpensive schema fingerprint (entity count + Account field count + latest CustomObject.LastModifiedDate). When the fingerprint matches and the user is still assigned, the cold path takes one Tooling query and one SOQL; when the fingerprint changes, LATdx regenerates the permset.

latdx daemon stop
LATDX_SKIP_TEST_RUNNER_ACCESS=1 latdx test run -o my-org

Cache and daemon commands (advanced)

Available unconditionally; intended for debugging and workspace cleanup.

latdx cache status
latdx cache status --all-workspaces
latdx cache clear
latdx cache clear --all
latdx cache clear --temp                 # clear temp files only
latdx cache clear --daemon               # kill the current workspace daemon only
latdx cache clear --all-workspaces
latdx cache clear --legacy
latdx cache clear -q                     # --quiet: suppress per-step output (scripts)
 
latdx daemon status
latdx daemon status --all-workspaces
latdx daemon stop
latdx daemon stop --all-workspaces
latdx daemon restart
latdx daemon restart --all-workspaces

All cache and daemon subcommands accept --json for machine-readable output:

• latdx cache status --json emits {workspaces:[{workspaceId,cacheDir,cacheSize,cacheScanErrors,daemonRunning}]}.
• latdx cache clear --json emits {events:[…]} collecting the per-step messages the text mode prints.
• latdx daemon status --json emits {workspaces:[{workspaceId,running,pid,socketFile,logFile}]}.
• latdx daemon stop --json and latdx daemon restart --json emit {results:[{workspaceId,pid,outcome,error?}]} where outcome is one of stopped, already_stopped, exited, or failed.

latdx cache status walks the workspace cache directory recursively to compute the size on disk. Entries that cannot be read (EACCES on a hardened subdir, ENOENT on a stat after the daemon’s mid-flight cleanup) are listed under a warning: failed to scan ... line on stderr; the reported size in that case is a lower bound, not silently shrunk.

LATDX_DEBUG namespace patterns

In addition to the legacy boolean form (true / 1), LATDX_DEBUG accepts namespace patterns that selectively enable individual trace channels emitted through the debug package. Output goes to stderr in the standard <namespace> <message> +<delta> format.

Patterns without an explicit latdx: prefix are auto-prefixed so callers do not need to repeat the brand. The legacy boolean form continues to drive the existing developer-only commands shown above plus the temp-file retention behavior in LATDX_KEEP_TEMP_FILES; namespace-pattern values do not change those behaviors and are intended for fine-grained trace gating only.

Each git worktree gets its own daemon process and cache namespace under ~/.latdx/workspaces/<id>/, so latdx cache clear and latdx daemon stop operate on the current worktree by default. Use --all-workspaces to reach across every worktree on the machine, and latdx cache clear --legacy to wipe the pre-upgrade ~/.latdx/cache and ~/.latdx/daemon.{sock,pid,log} files in one pass (user-global config.json and update-check.json are left alone).

Mode decision table

Exit behavior

Uninstall exit codes

latdx uninstall exits with code 1 when class restoration fails, matching the behavior of latdx restore.

Non-interactive / CI behavior

latdx test run auto-detects non-interactive environments (CI=true or stdout not attached to a TTY). In those environments the CLI never blocks on a confirmation prompt:

• Debug log storage exceeded: when the scratch org hits its 1 GB ApexLog limit, the CLI automatically deletes all debug logs and retries the run instead of showing the Delete all logs to continue? prompt. Interactive terminals still see the prompt.
• LATDX_AUTO_CONFIRM=true additionally forces auto-confirmation in interactive terminals (useful for local scripts).

See also