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, or --json collapses TTY-only affordances such as spinners and the live renderer automatically. CI text output still uses ANSI color when available; --no-color / NO_COLOR disables it.

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

test run

Startup banner

Non---json runs open with a single intro line carrying the resolved org alias, then stream the test output:

test run  •  my-org

The alias is either the literal --target-org value the user typed, or the local default alias when bare-invoked. The intro emits before workspace discovery or org-metadata fetch, so the header lands first.

Extra bullets appear only for env-driven anomalies the user did not type:

• cache off (LATDX_CACHE_DISABLE=1) when the cache killswitch env is set,
• auto-confirm when the run is non-interactive without an explicit --yes (prompts will auto-yes instead of pausing).

Flags the user typed (--engine, --db, --cache off, --yes) and stable defaults (cache phase, batch mode, anon mode) are omitted from the header. Under --plain and CI providers the same line emits in logfmt form (latdx test run • ...). A context step beneath it carries the resolved engine / db / cache details for log scrapers. --json suppresses the chrome so the stdout payload stays clean.

Phase ladder

On a cold daemon (first invocation after latdx daemon stop), the chrome surfaces each one-time-per-daemon cost as its own phase, so it is attributable rather than hidden under Preparing test run:

▸ test run  •  my-org
◐ Warming engine              ← daemon spawn + apex-ls JVM init
✓ Warming engine        891ms
◐ Pre-hash tests 425/1336   ← workspace-wide Phase 4 prewarm (cold only)
✓ Pre-hash tests      5.52s
◐ Preparing test run
    ✓ Load org context      2ms
    ✓ Resolve tests       305ms
    ✓ Match cache keys      2ms ← in-memory lookup against the precomputed map
✓ Preparing test run      ~310ms

On a warm daemon (subsequent runs), both Warming engine and Pre-hash tests go silent: the JVM cache is warm and the cache-key map is populated. The ladder reduces to:

▸ test run  •  my-org
◐ Preparing test run
    ✓ Resolve tests         5ms
    ✓ Match cache keys      2ms
✓ Preparing test run       ~10ms

File edits invalidate the precomputed entries whose dependencies include the changed types; the next run recomputes only the impacted tests and replays the rest from the fast path. See ADR 0018 for the correctness contract.

The cache-marker legend (a dim-amber ↺ glyph means “served from cache”) lives directly above the Summary block when at least one test row carried the glyph; see End-of-run summary.

End-of-run summary

The trailing block lists result counts and wall clock.

All setup work (org context load, test-runner permission grant, test resolution, mock generation, deploy, and cache-key computation) collapses into one Preparing test run umbrella spinner, resolving to ✓ Preparing test run Ns (or ✗ on failure) when prep finishes. The --verbose (-v) flag expands the umbrella into one indented sub-row per stage so cold-daemon investigations can see which stage dominated; in default mode only the umbrella row renders. The ✓ Ran on org row prints only on failure, above the details, so the failure summary lands before the per-test output scrolls; on success the Summary block’s Passed count and Wall row carry the same facts.

Per-method rows right-align duration to a per-block column sized to the longest method name in that class, so duration sits beside the name rather than at the top-level phase column. A dim-amber ↺ glyph trails any row served from cache; when at least one row carries it, a dim ↺ cached legend line lands above the Summary block.

In an interactive terminal, every class prints its rows one at a time: classes served from cache cascade quickly, classes that ran on the org fill in at the slower pace of their results landing. The Summary block waits for the whole cascade to finish, so it always prints beneath the last row rather than racing ahead of it. Non-interactive runs (piped output, CI, --plain, --json) skip the animation and print each block as soon as it is ready.

Success:

✓ Preparing test run     1.78s
 
 PASS  AccountTest
  ✓ rejectsBadInput  46ms ↺
  ✓ closeWon_uow    1.73s
 
Tests  PASS 2  FAIL 0  SKIP 0
Wall   1.8s
Cache  ↺ 1/2

Under --verbose, the same run renders the umbrella plus its children:

✓ Preparing test run     1.78s
    ✓ Load org context         180ms
    ✓ Ensure test-runner permissions  95ms
    ✓ Resolve tests             62ms
    ✓ Computing cache keys     2/2  1.45s
 PASS  AccountTest
  ✓ rejectsBadInput  46ms ↺
  ✓ closeWon_uow    1.73s

The trailing block collapses passed / failed / skipped counts into a single Tests row with plain foreground-color labels (PASS mint, FAIL red, SKIP amber) rather than inverse-background chips. Each label sits one space from its value (PASS 19); pairs are separated by two spaces (PASS 19 FAIL 0 SKIP 19), matching the row key→value gap. The Cache row collapses to ↺ hits/total with the ↺ glyph in full-intensity amber, matching the dim-amber per-method ↺ markers inline above. When the cache served at least 1s of measured execution this run, the Wall row carries a dim (saved ~Xs) suffix.

The Wall value is measured end-to-end, from process spawn (anchored at Date.now() - process.uptime() * 1000) to the moment the Summary block renders: Bun/Node startup, module imports, Commander dispatch, daemon connect, test execution, and summary build. It tracks time(1) total closely, minus the post-render update-notice fetch and V8 teardown that time keeps counting after the result lands. The Cache row’s (saved ~Xs) suffix uses the same scope, so the saved estimate compares like-for-like against the sf-cli baseline.

The Cache row of the Summary block shows ↺ <hits>/<total>: methods served from cache versus run on the org. The per-method ↺ glyphs inline above carry the per-test detail.

Failure:

 FAIL  AccountTest
  ✓ acceptsValidInput          12ms
  ✗ rejectsBadInput
      System.AssertException: Assertion Failed: expected exception
      Class.AccountTest.rejectsBadInput: line 42, column 1
 
✗ Ran on org                  1 failed of 2  1.8s
 
Summary
  Passed   1
  Failed   1
  Skipped  0
  Wall     1.8s
 

Each ✗ row prints the failure’s error message indented underneath in red, followed by the stack trace in gray. Skipped tests render as ⊘ <method> (skipped) with the reason indented in gray. There is no trailing === Failed/Skipped Test Details section; the data is inline.

A non-zero exit caused by test failures alone does not print the A complete log of this run can be found in: ... footer; it appears only when the CLI itself aborted (org auth, daemon crash, parser error, etc.) and the per-run NDJSON log is the only place to look.

Plain-mode progress

In an interactive terminal under --plain, the command keeps the ten-second stderr heartbeat active with aggregate test progress instead of printing one line per method as soon as it finishes. Progress heartbeat lines are padded with a blank line before and after so completed class blocks stay readable:

 RUNS  OrdersServiceImplTest  2/6  ✓2  40.71s
[35s]  86%  ▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▱▱▱▱▱▱    tests 86/100    suites 7/8    ✓86    36.44s / ETA ~5.93s

Under CI (CI env) or any other non-TTY context (piped stderr), these aggregate snapshots are hidden by default so batch logs are not flooded with a fresh progress block every ten seconds; the periodic heartbeat is disabled entirely and the run prints a single Running tests... liveness line at the start instead. Pass --progress to force the full snapshots on in CI, or --no-progress to suppress them in an interactive terminal (see Execution behavior options). Either way, the per-class jest-style result blocks below still print.

When a class completes, plain mode emits the jest-style result block for that class, separated from surrounding progress by a blank line:

 
PASS  TrialsTest
  ✓ getTrials      147ms ↺
  ✗ terminate
      System.AssertException: 1 != 2
      Class.TrialsTest.terminate: line 42, column 1
  ⊘ unsupportedApi  (skipped)

✓ is a pass (with the test’s reported duration), ✗ is a failure (with error and stack lines indented underneath), ⊘ is a skip, and ↺ marks a cache hit. The lines are indented two cells under their class header. The --json mode suppresses these lines so the stdout payload stays clean; --progress-events takes precedence and emits NDJSON instead of pretty lines for programmatic consumers.

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 consults a per-org disk cache that identifies each result by (test class source + transitive dependency source + org schema revision). The cache layer is governed by ADR 0009 phase rules. Phase 0 is the safe baseline: results are cached but never reused, so the engine runs every method. Phase >= 1 unlocks per-rule skip logic, up to the Phase 4 default. 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:

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]

{
  "status": 0,
  "result": {
    "summary": {
      /* unchanged sf-shape */
    },
    "tests": [
      /* unchanged sf-shape */
    ],
    "cacheReport": {
      "hits": 12,
      "misses": 3,
      "stale": 1,
      "writtenOnExit": 4,
      "phase": 2,
      "killSwitch": false,
    },
  },
  "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: by default (coverage off) per-method skip is allowed; with --coverage on, any miss in a class promotes that class’s hits back to misses so coverage computes in one transaction.

Cache env vars are read per CLI invocation and forwarded to the daemon with the test-run request, so no daemon restart is needed for LATDX_CACHE_PHASE=2 latdx test run ... or a per-rule flag to apply to that run.

When shadow validation samples a hit on a run that already executed tests, cacheReport.shadowSamples and cacheReport.shadowMismatches are included. A non-zero shadowMismatches means a cached result disagreed with a fresh run; the fresh result is used for that method. Tune the sample with LATDX_CACHE_SHADOW_RATE (0 disables it).

Dry run

--dry-run resolves the full test selection a real run would execute (the same workspace discovery and --affected reach analysis) and prints it without running anything, so another tool can consume LATdx’s selection:

# Method-level list, one entry per line
latdx test run --affected --dry-run
 
# Unique class names, e.g. for a RunSpecifiedTests deploy
latdx test run --affected --dry-run --classes-only
 
# Pipe straight into the Salesforce CLI: xargs appends each line after
# --tests, and an empty selection runs nothing (pass -r to GNU xargs)
latdx test run --affected --dry-run | xargs sf apex run test --tests
 
# Command substitution works too: sf accepts space-separated --tests values
sf apex run test --tests $(latdx test run --affected --dry-run)
 
# Or a single comma-joined token (quoted, shellcheck-friendly)
sf apex run test --tests "$(latdx test run --affected --dry-run --delimiter ,)"

Stdout carries only the selection; status lines stay on stderr. Entries are Class.method where methods are known, or a bare class name when only the class is known (for example a --class-names entry that exists only in the org). Both forms are valid sf apex run test --tests values. The list is always the pre-cache selection: an external runner has no access to LATdx’s result cache, so cached-fresh tests are never dropped and --no-cache / --force make no difference. Workspace and --affected dry runs make no org calls; only --org enumeration queries the org. An empty selection prints nothing and exits 0.

With --json, a single document replaces the line output:

{
  "dryRun": true,
  "selection": "affected (origin/main...HEAD)",
  "mode": "org", // "org" or "file", mirroring the run mode
  "tests": ["AccountServiceTest.testHappy", "OrgOnlyClass"],
  "classes": ["AccountServiceTest", "OrgOnlyClass"],
  "summary": { "totalEntries": 2, "totalClasses": 2, "classLevelEntries": 1 },
}

tests may mix Class.method and bare class entries (summary.classLevelEntries counts the latter); classes is always the unique class set. --classes-only and --delimiter change the plain lines only, never the JSON shape.

Validation rules

test list

If --file/--dir is omitted, test list defaults to a workspace scan via apex-ls (no org call). Pass --org to fall back to the org-side ApexClass.SymbolTable scan (requires --target-org or a default org). When apex-ls is not configured on the daemon (Java missing or LATDX_APEX_LS_* jars unset), the command exits non-zero with a hint pointing at --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. With --classes-only, each unique class name is printed once (sorted) instead of Class.method lines, and the summary becomes Total: N test class(es). 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 source the compiler does not expose) 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. When combined with --classes-only, the payload shape is { classes: string[], summary: { totalClasses } } rather than the per-file methods list.

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.

Watch-mode startup prints one progress line per phase (apex-ls bridge spawn, test-method discovery, reach indexing, Phase 4 baselining) on stderr with the wall-clock elapsed for that phase appended as (Ns). The elapsed counter measures from the first start of the phase, not the most recent progress tick, so long-running phases report their full duration.

Per-save flushes use the apex-ls bridge’s incremental refresh(path…) command to reparse only the touched files instead of reopening the workspace, so a single .cls save typically reprints in ~100-300 ms on a medium workspace. Schema, manifest, and deletion events still go through the full reload rebuild because incremental refresh cannot express those.

Class-only flushes skip the apex-ls bridge round-trip entirely when every edited class is non-test AND statically unreached by every indexed test method. The downstream pass still prints the 0 invalidated / 0 affected line; only the workspace rebuild is short-circuited. Schema, manifest, and test-class edits always take the full path because they can mint new reach edges.

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. The affected list is therefore incomplete for trigger-only changes; run 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. When enabled, each appears in the command list with an (experimental) suffix.

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.

validate

Deploy your changes to a sandbox or scratch org and run the tests they affect, in one command. Drop it into the CI job where you previously ran sf project deploy validate followed by a test run.

What it does, in order:

1. Computes the components changed between --base and --head (same git range as latdx test run --affected) and deploys them with sf project deploy start. With --full it deploys every package directory instead.
2. Runs the tests affected by those changes through the standard latdx test run --affected pipeline (cached and accelerated).
3. Optionally checks per-class coverage of the changed Apex classes against --coverage-threshold and fails when any class is below it.

Exit codes: 0 pass · 10 deploy failed · 11 tests failed · 12 coverage below threshold · 64 bad usage.

# CI on a pull request: deploy the PR's changes and run affected tests
latdx validate -o ci-sandbox
 
# Full deploy, affected tests, 75% coverage gate on changed classes
latdx validate -o ci-sandbox --full --coverage-threshold 75

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

Supported config keys:

Telemetry

LATdx sends anonymous usage metrics (which commands run, how many tests a run executed, pass/fail counts, cache hit rate and time saved, plus environment basics like OS, CLI version, and whether the run was in CI) to help prioritize the product. It is on by default and never blocks or slows a command: if the network is down, telemetry is dropped silently.

What is never sent: source code, Apex class or method names, org names or ids, file paths, or email addresses.

Opt out at any time, by precedence:

1. LATDX_TELEMETRY=0 (also accepts false, off, no) for one shell/session.
2. DO_NOT_TRACK=1, the cross-tool standard.
3. latdx config set telemetry off, persisted in ~/.latdx/config.json.

upgrade

Check for and apply CLI updates. latdx update is registered as an alias and accepts the same flags and subcommands.

Both subcommands respect the configured channel to decide which releases are eligible: stable considers published non-prerelease builds only, while latest is a superset that also accepts prereleases (so it is never older than the newest stable). Either way the highest eligible version wins, regardless of the order GitHub published the releases. Pass --latest or --stable to override the configured channel for a single invocation (they are mutually exclusive); the configured channel is left unchanged. To switch channels persistently use latdx config set channel <stable|latest>.

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 without manual setup, @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. Size figures emitted by cache status and cache status --all-workspaces scale through B / KB / MB / GB / TB so multi-gigabyte caches render in their natural unit instead of inflated MB.

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 status --in-flight          # snapshot active phase frames in the current daemon
latdx daemon stop
latdx daemon stop --all-workspaces
latdx daemon restart
latdx daemon restart --all-workspaces

When a new CLI binary is invoked against an already-running daemon, the client asks the daemon to shut down so the next test run boots a process that loaded the freshly-built code. The handover is bounded: the daemon races its in-process shutdown against a 3000ms deadline, and the CLI waits for the daemon PID to disappear before reconnecting. If a stuck step would otherwise strand the old process holding the workspace socket, the CLI escalates to SIGTERM and then SIGKILL on the daemon PID. (The usual culprit is macOS uv__fsevents_close synchronously blocking libuv inside chokidar teardown on huge workspaces.) You should not need latdx cache clear --all to recover after a rebuild; if you do, that is a bug.

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 status --in-flight --json emits {snapshotAtMs,phases:[{name,startedAtMs,elapsedMs,depth}]} listing currently-open PhaseLogger frames in the running daemon (empty phases means the daemon is idle). Only frames opened inside the daemon process itself are visible; if the work runs in a child process the daemon spawned, that process’s stack is not reported.
• 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 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 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 stray ~/.latdx/cache and ~/.latdx/daemon.{sock,pid,log} files from earlier builds 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 (the CI env var set to any value except empty or an opt-out (false, 0, off, no), stdout not attached to a TTY, or --json passed). 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.
• --json mode: confirmation prompts always resolve to their default and emit an Auto-confirmed in non-interactive mode: <prompt> warning on stderr. This guarantees stdout stays a single parseable JSON document, even in an interactive TTY where CI is unset.
• LATDX_AUTO_CONFIRM=true additionally forces auto-confirmation in interactive terminals (useful for local scripts).