Skip to main content
The explain --json command returns a structured trace of command analysis. This page defines the JSON shape for scripts and other tools. It also explains what a trace can reveal before you share it. For flags and exit behavior, see CLI commands. For help with an unexpected block, see Troubleshooting.
A trace is not automatically safe to share. Read Before you share a trace first.

​
ExplainResult

The top-level object returned by explain --json. The four configuration fields — effectiveLevel, selectedPreset, effectiveCapabilities, and destructiveCommandRuleOverrides — are built once and included in every return path, so they are present even when you explain an empty command.

​
effectiveCapabilities

effectiveCapabilities is a record keyed by fail_closed, paranoid_rm, and paranoid_interpreters. Each value contains: See Modes for what each capability changes.

​
ruleActivation

ruleActivation is present only when the relevant rule declares an activation capability. The relevant rule is either the matched rule or a mode-gated candidate. A mode-gated candidate is a rule that would match if its required level or capability were active. In human output this renders as a single line: Rule activation: <id> — on|off via <source>.

​
ExplainTrace

The trace is passive: recording it never changes a decision, and ordinary guard evaluation never builds one. It exists only for explain. Bounds. The recorder caps what it keeps: at most 512 events, 2,048 characters per text value, 128 items per list, 128 properties per object, and 16 levels of nesting. Events beyond the cap are counted rather than stored, and every recorded value is deep-frozen. The count of dropped events is not exposed in ExplainTrace — only steps and segments are.

​
TraceStep variants

Use type to select the variant before you read its other fields.

​
recurse reasons

recurse.reason has one of eight values: shell-wrapper, interpreter, busybox, shell-eval, shell-trap, shell-stdin, shell-heredoc, or heredoc-file. heredoc-file is recorded when a command runs a script file whose content the analysis already knows — a quoted heredoc body written to that path earlier in the same command via cat > or tee — and the stored body is re-analyzed as the script; see Heredoc analysis.

​
transparent-wrapper steps

transparent-wrapper is a segment-scoped step recorded when a command you registered with rule wrapper add is seen through. One step is emitted per candidate child — the primary child plus each alternative — each carrying: The step is recorded immediately before recursing into those tokens, so it always precedes the analysis of the wrapped command. Human output renders it as a numbered Transparent wrapper step showing Wrapper: and Tokens:. Manage wrappers with the rule wrapper add, rule wrapper remove, and rule wrapper list commands. See rule wrapper.

​
Trace order

A typical trace flows from parse → per-segment env-strip / leading-tokens-stripped → detection (shell-wrapper / interpreter / busybox / transparent-wrapper) → rule-check or custom-rules-check → a decision. Recursion appears as recurse steps with increasing depth — except busybox dispatch, which records a recurse step but does not consume recursion depth, so a chain of busybox wrappers repeats the same depth value. When you only need the verdict, read result (plus reason, segment, and ruleId) at the top level instead of walking the trace. Three protections short-circuit before the evaluator runs: policy-file protection, Git-metadata protection, and secret protection. When one of those blocks a command, the trace contains a single synthetic rule-check step and no parse step, with ruleId set to policy-protection, git-metadata-protection, or the id of the matched secret rule. Tooling that assumes every trace opens with a parse step needs to handle this case.

​
Before you share a trace

An explain trace is not inherently safe to share. The parse step records the raw command string you supplied and every token it parsed out of it. Many other steps carry raw text too — fallback-scan.tokensScanned, dangerous-text.token, shell-wrapper.innerCommand, interpreter.codeArg, recurse.innerCommand, strict-unparseable.rawCommand, transparent-wrapper.output, worktree-relaxation.gitCwd, and cwd-change.segment. configSource is an absolute path, normally inside your home directory.Redaction removes recognized credential shapes only — the same bounded pattern list the audit log uses. It makes no claim about file paths, hostnames, IP addresses, usernames, project or client names, or any secret whose format is not on the list, and it cannot redact what it does not recognize.Before sharing a trace: reproduce the case with placeholder credentials and placeholder paths, then read the output end to end and remove anything you would not post publicly.
For example, explaining a command that contains a --token=… assignment redacts the token, but a path like /srv/acme-prod/customer-dump.sql in the same command is returned in full, along with any hostname, IP address, or account name in the command text. You can include explain output in a vulnerability report. Redaction is a best-effort control, not a guarantee. A redaction bypass is a reportable vulnerability. Review the complete output before you paste it.
  • CLI commands — explain flags, examples, and exit behavior.
  • Audit log — the redaction pattern list, and the same bound applied to logged records.
  • Analysis engine — the behavior each trace step corresponds to.
  • Troubleshooting — using explain to diagnose an unexpected block.
Last modified on August 11, 2026