CLI Reference

Command entrypoint in this repo:

latdx <command>

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

Top-Level Commands

Global options:

• --no-color: disable ANSI color escape codes. Also honored via the NO_COLOR environment variable (any non-empty value).
• -q, --quiet: errors only. Wins over -v and the env-var level.
• -v (repeatable): increase verbosity. Default is warn. -v = info, -vv = debug-tier, -vvv = trace-tier (loudest). Note: subcommands also accept their own --verbose boolean; the global counter only applies before the subcommand name (e.g. latdx -vv test ...).
• --plain: disable spinners, live updates, and ANSI color output. Useful when running under a wrapper that does not support cursor control. Also honored via the CI env variable (any non-empty value), so CI builds get clean line-buffered output by default.
• --json: machine-readable mode. Log lines on stderr become NDJSON ({"ts","lvl","prefix","msg"} per call) and TTY effects (spinners, live updates, color) are forced off. When the invoked subcommand also accepts --json (for example test run, test list), it additionally emits its result payload on stdout as a single JSON document so latdx ... --json | jq works end to end.

Environment variables:

• LATDX_LOG_LEVEL: explicit log level. One of error|warn|info|debug|trace|off. Used when neither -q nor -v is passed. Set per-shell (export LATDX_LOG_LEVEL=debug) or per-command (LATDX_LOG_LEVEL=trace latdx ...). There is no --log-level flag by design: env-only keeps the global flag surface compact.
• LATDX_LOG_FORMAT: advanced override for the log-line format (text or json). The --json flag is the canonical way to flip this; the env var is for callers that want NDJSON logs without flipping a per-command payload-shape switch.

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

Stream contract

Per ADR 0005:

• 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, TERM=dumb, 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

• -f, --file <path>: run tests for one Apex test class file.
• -d, --dir <path>: run tests discovered recursively in a directory.
• -p, --pattern <glob>: discovery pattern in dir mode (**/*Test.cls default).
• -n, --class-names <names...>: org-mode class execution.
• -t, --tests <tests...>: org-mode method execution with Class.method.
• -m, --method <name>: run a single method (file mode only).
• -o, --target-org <alias>: explicit org alias.

Execution behavior options

• --fullSim: use full mode (default is dbsim).
• --anon-inline: inline the test method body into the ExecuteAnonymous payload (legacy extraction path). Default behavior invokes the target method by name on the already-deployed class, which keeps payloads tiny and lets packed batches fit far more tests per call. Use this flag only when you need the old inline payload for debugging or to work around a test that does not yet behave identically when invoked by name.
• --sequential: disable packed execution.
• --eco: use eco batching (default batch mode is turbo).
• --concurrency <n>: max concurrent batches. Default is auto-picked from the target org type: 20 for Developer Edition / trial / scratch orgs, 25 for production / sandbox orgs (see classifyOrgTier in @latdx/core). Pass an explicit number to override.
• --no-coverage: disable coverage collection.
• --json: emit the test result as a single JSON document on stdout, in the same shape as sf apex test run --json ({status, result: {summary, tests}, warnings}). Drop-in compatible with tools that already parse Salesforce CLI test output: Outcome is Pass/Fail/Skip, tests[].FullName is <ClassName>.<methodName>, time fields are formatted strings (e.g. "1500 ms"). Org-side identifiers latdx cannot produce (Id, QueueItemId, AsyncApexJobId, ApexClass.Id, testRunId) are emitted as empty strings, matching sf’s behavior on local-only runs. result.coverage is not populated yet; tracked as a follow-up. Implies --plain, so the live renderer and spinner stay off and the stdout payload remains a single parseable document.
• --progress-events: emit newline-delimited JSON progress events to stderr (programmatic consumers). Events: {event:"queued"|"start"|"complete", className, methodName, status?}. Failed complete events also include errorMessage? and message? so consumers can surface the failure reason. When a packed batch fails and the runner retries remaining tests, a queued event is re-emitted for each re-enqueued test; consumers should dedupe by className+methodName.
• -v, --verbose: debug-level CLI logging (deprecated; prefer the global -v / -vv / -vvv counter).

Live method-by-method rendering is automatic: enabled when stdout is a TTY, --json is not set, CI is unset, and --plain was not passed. There is no --live / --no-live flag (removed per ADR 0005). Use --plain (or pipe stdout) to force-off; rely on auto-detection otherwise.

Validation rules

• Cannot combine --class-names or --tests with --file or --dir.
• Cannot combine --file with --dir.
• --method cannot be used with --dir or org mode.

test list

• -f, --file <path> or -d, --dir <path> for file mode.
• -p, --pattern <glob> for directory search.
• -o, --target-org <alias> for org mode.
• --json for structured output.
• 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

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

adapt

• -f, --file <path> required.
• -o, --output <path> optional.
• -v, --verbose optional.

Current limitation:

• The current implementation reads and writes original content as a placeholder (transformation pipeline is not yet wired in this command path).

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.

• -d, --dir <path> required: source directory containing .cls files. Walked recursively.
• -o, --output <path> required: output directory for adapted files. Created if missing.
• -v, --verbose optional: debug-level CLI logging.

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

config

Manage CLI configuration. Subcommands:

• latdx config set <key> <value>: set a configuration value.
• latdx config get <key>: read a configuration value.
• latdx config list: print all configuration entries.

Supported config keys include channel (values: stable, latest).

upgrade

Check for and apply CLI updates.

• latdx upgrade check: check whether a newer CLI version is available.
  • --json: machine-readable output.

The upgrade check respects the configured channel (stable or latest) to determine which release stream to compare against.

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.

To bypass the automatic grant (for example in tightly controlled sandboxes where the running user cannot deploy metadata, or when you manage the permset yourself), set LATDX_SKIP_TEST_RUNNER_ACCESS=1 in the environment before launching latdx test run. When the daemon is used, the opt-out is read when the daemon starts, so start a fresh daemon with the env var set:

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

• Exit code 0: successful run/list/adapt path.
• Exit code 1: validation/runtime/test failure path.

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

Uninstall exit codes

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