• Verification-style scripts (preferred for "test this"): wrap the body in a savepoint + rollback so org state is untouched:
  apex

  Savepoint sp = Database.setSavepoint();
  try {
      // ... code under test ...
  } finally {
      Database.rollback(sp);
  }

• Production org heads-up: if the resolved

  <alias>

  points at a production org (no scratch/sandbox markers in

  sf org display --json

  ), surface a clear warning before running. This is informational only — there is no automated block. Always wait for an explicit "yes, run it" before executing destructive scripts in prod.
• Never run anonymous Apex you did not generate or have not been shown — if the developer pastes a snippet, echo it back and confirm before executing.

sf apex run --file <path> --target-org <alias> --json

• Always pass

  --json

  . Human-format output conflates compile vs runtime errors.
• If

  target-org

  is already configured,

  --target-org

  may be omitted, but log the alias used.
• The command exits non-zero on compile errors. Capture both stdout and the parsed JSON.

• Short logs (< ~200 lines): inline the log body in the report between fenced code blocks.
• Large logs: write the log to

  .sfdx/tmp/anon-<ts>.log

  and report the path. Include the last 30 lines inline as a tail summary.
• Empty / missing log: likely no active TraceFlag. Surface the Step 3 setup hint and proceed with whatever compile/runtime status was returned.

LIMIT_USAGE_FOR_NS

EXCEPTION_THROWN

FATAL_ERROR

SOQL_EXECUTE_BEGIN

platform-apex-logs-debug

DML_BEGIN

platform-apex-logs-debug

"Run

scripts/seed-test-data.apex

against my default org."

1. Resolve

   <alias>

   from

   sf config get target-org --json

   .
2. Confirm the file exists; if not, stop and surface

   file not found

   .
3. Run

   sf apex run --file scripts/seed-test-data.apex --target-org <alias> --json

   .
4. Parse JSON. Report compile/runtime status, log tail, and org mode.
5. Suggest: "If this seeded real data and you'd like to verify without persisting, re-run with the rollback wrapper (snippet mode)."

"Execute

System.debug([SELECT count() FROM Account]);

and tell me the count."

1. Resolve

   <alias>

   .
2. Echo the snippet back; confirm.
3. Write the snippet to

   .sfdx/tmp/anon-<ts>.apex

   (Write tool).
4. Run

   sf apex run --file .sfdx/tmp/anon-<ts>.apex --target-org <alias> --json

   .
5. Parse

   result.logs

   ; extract the

   USER_DEBUG

   line for the count.
6. Report: "Account count = N. Source:

   .sfdx/tmp/anon-<ts>.apex

   (kept for reference)."

"Test that this Apex correctly upserts a Contact, then rollback."

1. Resolve

   <alias>

   . If prod, surface a heads-up before running.
2. Wrap the developer's snippet:
   apex

   Savepoint sp = Database.setSavepoint();
   try {
       // ---- developer snippet begins ----
       Contact c = new Contact(LastName = 'Smoke', Email = 'smoke@example.com');
       upsert c Email;
       System.debug('Upserted: ' + c.Id);
       // ---- developer snippet ends ----
   } finally {
       Database.rollback(sp);
       System.debug('Rolled back savepoint.');
   }

3. Write to

   .sfdx/tmp/anon-<ts>.apex

   , execute, parse JSON.
4. Report compile/runtime status, the upserted Id from the log, and

   Rollback: applied

   .

• Always pass

  --json

  .
• Always resolve

  <alias>

  from configuration or the developer; never hardcode.
• Never use

  --apex-code

  -style inline flags — they are not supported by the current CLI and are escape-hostile. Always go through

  --file

  .
• Always echo a pasted snippet back to the developer for confirmation before executing.
• For verification-style scripts, default to wrapping in

  Database.setSavepoint()

  +

  Database.rollback()

  .
• For prod orgs, surface a heads-up but do not auto-block — the developer is in charge.
• Do not auto-delete temp files under

  .sfdx/tmp/

  .
• This skill executes anonymous Apex; it does not author, deploy, or test

  .cls

  /

  .trigger

  files. For those, hand off to

  platform-apex-generate

  , the deploy skills, or

  platform-apex-test-generate

  .
• For deep log analysis, hand off to

  platform-apex-logs-debug

  .