Authentication & Org Targeting

LATdx does not own its own auth. It piggy-backs on the Salesforce CLI (sf), reads the same default-org configuration, and adds a small bootstrap step (the latdx_TestRunnerAccess permset) on the first run against a given org.

Minimum Setup

# 1. Authenticate to the org via the Salesforce CLI
sf org login web -a my-org
 
# 2. Make it the default for this workspace (or shell)
sf config set target-org=my-org

After step 2, every latdx command that needs an org will pick up my-org automatically. You can override per-command with -o/--target-org <alias>.

To verify the setup is healthy:

sf org list                    # confirms auth state
latdx --version -o my-org      # also prints managed-package status; non-zero on failure

Default Org Resolution

When -o/--target-org is omitted, LATdx asks the Salesforce CLI’s runtime which org is the default. The resolution order is:

1. The org alias from sf config get target-org (or target-org set per-project in .sf/).
2. The org username, if no alias is set.
3. null if no default has been configured.

If the resolution returns null, the CLI errors out with:

No default org found. Use --target-org, --file, --dir, --class-names, or --tests.

and exits with code 1. Either set a default with sf config set target-org=... or pass -o explicitly.

LATdx does not cache org auth tokens of its own. Refresh tokens, OAuth state, and JWT material are all owned by sf and stored under ~/.sfdx/.

Org Tier and Default Concurrency

LATdx auto-tunes --concurrency based on the org type. Override the default by passing --concurrency <n> explicitly.

The classifier reads Organization once per run; you can see it in -vv logs as loadOrgConfig.

Managed-Package Health Check

latdx --version -o my-org is the canonical “is this org ready?” probe. It queries InstalledSubscriberPackage for the latdx-sf managed package and prints:

• The CLI version.
• Whether the package is installed in the org.
• The installed version vs. the version the CLI expects.

It exits 0 on success, non-zero if the SOQL query fails (org unreachable, no permission, expired auth). Use it as a smoke step in CI.

If the package is missing or outdated, install/upgrade it first. See Configuration & Modes for LATDX_SF_INSTALL_METHOD (managed package vs. source install).

Automatic FLS/OLS Grant (latdx_TestRunnerAccess)

LATdx executes Apex tests through anonymous-Apex pathways, which (unlike the native test runner) enforce Field-Level Security at compile time. Standard fields like Account.AccountNumber, Account.Rating, and Account.Site ship with FLS unset on every profile in fresh scratch orgs and many sandboxes, which would cause Field does not exist failures on otherwise-valid tests.

To keep latdx test run working out of the box, the CLI deploys a permission set named latdx_TestRunnerAccess and assigns it to the currently-authenticated user. The permset grants:

• Full object permissions on every queryable entity the Tooling API exposes.
• readable=true editable=true FLS on every settable field on those entities.

The grant runs once per org per fingerprint (see below), so the warm path is effectively free.

Cache Layout

The grant is cached in two places:

1. In-memory on the LatdxCore instance, so subsequent runs in the same process hit no API at all.

2. On disk at ~/.latdx/runner-access/<orgId>.json, one file per org:

   {
     "schemaVersion": 1,
     "fingerprint": "abcd1234ef567890",
     "permsetName": "latdx_TestRunnerAccess",
     "grantedAt": "2026-04-27T12:34:56.000Z",
     "assignedUserIds": ["005..."]
   }

Fingerprint

The fingerprint is a SHA-256 of three cheap signals, truncated to 16 hex characters:

1. Total queryable EntityDefinition count.
2. FieldDefinition count on Account.
3. Latest CustomObject.LastModifiedDate in the org.

When the fingerprint matches the cached value and the user is still assigned, LATdx skips the deploy entirely (one Tooling COUNT + one SOQL assignment lookup). When it changes (custom object added/edited, schema mutation), the permset is regenerated and re-deployed automatically.

To force a regenerate, delete the org’s cache file:

rm ~/.latdx/runner-access/<orgId>.json

Failure Modes

If the deploy or assignment fails, LATdx logs a single warning like:

Test-runner access grant failed, continuing anyway: ...

and proceeds with the run. The grant is best-effort; tests may then fail with Field does not exist if the running user lacks FLS, in which case fix the underlying permission and retry.

Opting Out: LATDX_SKIP_TEST_RUNNER_ACCESS

Set the env var to 1 or true to skip the deploy entirely. Use this when:

• You manage latdx_TestRunnerAccess (or an equivalent permset) yourself, e.g., via your sandbox bootstrap pipeline.
• The running user lacks deploy/metadata permissions on a tightly governed sandbox.
• You see repeated Test-runner access grant failed warnings and want to silence them after confirming the permset is in place.

The variable is read at process start time. If the daemon is already running, restart it so the new value is picked up:

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

To make the opt-out persistent, export the variable in your shell profile so every daemon spawn inherits it.

Common Auth Issues

For deeper diagnostics see Troubleshooting.