Reference

Commands

Every command is available through both envidence and evd. This reference uses evd. Run evd --help or evd <command> --help for the exact options on your version.

Global options

Option	Description
`--store <path>`	Use a specific store directory instead of the default or `ENVIDENCE_HOME`.
`--json`	Print machine-readable JSON where the command supports it.
`--quiet`	Suppress status messages.
`--verbose`	Show extra diagnostics.
`--help`	Show help for the current command.

Command summary

Command	Purpose
`evd init`	Create the store and take the first full snapshot.
`evd snap`	Take a snapshot without running a command.
`evd watch -- <command>`	Snapshot, run a command, snapshot again, and explain a failure.
`evd why`	Rank the likely causes of a run or case.
`evd diff`	Compare two snapshots.
`evd log`	List recent snapshots, runs, or cases.
`evd case list`	List investigation cases.
`evd case show <id>`	Show a case, its findings, and its changes.
`evd case close <id>`	Close a case with a summary.
`evd baseline set`	Mark a snapshot as the known-good reference.
`evd baseline show`	Show the active baseline and current drift.
`evd fingerprint`	Print a stable fingerprint of tracked machine state.
`evd report`	Write a self-contained HTML report.
`evd rollback`	Plan or apply a reversal of machine changes.
`evd undo`	Undo a previously applied rollback.
`evd ui`	Open the local dashboard.
`evd doctor`	Check store health, baselines, warnings, and collector configuration.
`evd config`	Read or update configuration.
`evd prune`	Remove old unprotected snapshots.
`evd demo`	Open the isolated fixture demo.

Snapshots

`evd init`

Creates the store, takes a full snapshot, and marks the snapshot as the active baseline unless you pass --no-baseline.

shell

evd init
evd init --label "Clean install"
evd init --fast
evd init --store ./.envidence

Options: --label <text>, --fast, and --no-baseline.

`evd snap`

Takes a snapshot without running a command. Use it before a risky upgrade, after a manual fix, or when you want a reference for a later diff.

shell

evd snap
evd snap --fast
evd snap --full --label "Before upgrade"
evd snap --pin

A pinned snapshot is protected from pruning. You can also pass --profile fast or --profile full.

Watched runs

`evd watch`

Runs a command between two snapshots and compares the machine state. The command's exit code is preserved. If the command fails, Envidence opens a case unless you pass --no-why.

shell

evd watch -- npm test
evd watch --full -- npm run build
evd watch --timeout 300 -- npm run test:e2e
evd watch --capture-output -- npm install
evd watch --no-why -- npm install

watch uses a fast snapshot by default. --full uses the full collector set on both sides. The default output capture is bounded. --capture-output keeps more of stdout and stderr and may retain sensitive text.

Investigation

`evd why`

Explains a run or case with ranked hypotheses. With no target, it picks the newest open case, then the latest failed run, then the latest run.

shell

evd why
evd why --case CASE-...
evd why --run RUN-...
evd why --since 2h
evd why --since SNAP-...
evd why --all
evd why --fail-on-findings

--all includes volatile changes. --fail-on-findings exits with code 1 when any hypotheses are present, which is useful in scripts.

`evd diff`

Compares two snapshots. With no arguments, it compares the last two snapshots. Snapshot references can be IDs, prefixes, labels, or latest.

shell

evd diff
evd diff SNAP-1 SNAP-2
evd diff --category packages,path
evd diff --search typescript
evd diff --all --limit 100

`evd log`

Lists recent snapshots by default. Use --runs for command runs or --cases for cases.

shell

evd log
evd log --runs
evd log --cases
evd log --limit 50

`evd case`

A case is created when a watched command fails. Cases can be listed, inspected, and closed with a resolution summary.

shell

evd case list
evd case list --open
evd case show CASE-...
evd case close CASE-... --summary "Restored TypeScript 5.9"

`evd baseline`

A baseline is the reference Envidence uses when deciding whether a change is new. Set one after a clean install or a passing test run.

shell

evd baseline set latest --label "Known good"
evd baseline set SNAP-... --label "Clean install"
evd baseline show
evd baseline list
evd baseline accept --label "Accepted current state"

baseline accept marks the selected snapshot, which defaults to the latest, as the accepted baseline. baseline show reports drift from the active baseline.

`evd fingerprint`

Prints a stable digest of tracked machine state for a snapshot. It defaults to the latest snapshot and leaves out volatile facts.

shell

evd fingerprint
evd fingerprint SNAP-...
evd fingerprint --json

Reports and dashboard

`evd report`

Writes a single HTML file for a case or run. With no case or run, it reports the latest case.

shell

evd report --case CASE-... --out envidence-case.html
evd report --case CASE-... --redact strict
evd report --run RUN-... --out run.html
evd report --case CASE-... --open

Redaction levels are standard (default), strict, and none. See Reports.

`evd ui`

Starts the local dashboard on 127.0.0.1 and opens a token-protected URL. The server stays in the foreground until you press Ctrl+C.

shell

evd ui
evd ui --port 4317
evd ui --no-open
evd ui --demo

Do not expose the port through a proxy, tunnel, or port forward. The dashboard is designed for one local user.

Rollback

`evd rollback`

Builds a reversal plan from a case, run, snapshot, or individual change. It is a dry run unless you pass --apply.

shell

# Preview a case and write a script. This changes nothing.
evd rollback --case CASE-... --dry-run --script rollback.ps1

# Restore a specific snapshot.
evd rollback --to SNAP-... --dry-run

# Restrict the plan to selected categories.
evd rollback --case CASE-... --only env,path --dry-run

# Apply after reviewing the plan.
evd rollback --case CASE-... --apply

--apply asks for the literal word rollback and takes a pinned safety snapshot first. --yes skips the prompt. --fail-fast stops at the first failed action. Read Rollback before applying.

`evd undo`

Reverses a previously applied rollback. With no argument, it uses the latest applied rollback.

shell

evd undo
evd undo ROLLBACK-...
evd undo --script undo.ps1
evd undo --yes

Store and configuration

`evd doctor`

Checks the store, latest snapshot age, baseline, open cases, collectors, and redaction settings. It is a quick way to see whether the store is healthy.

shell

evd doctor

`evd config`

Reads or updates the store configuration. Paths are dot paths. Values are parsed as booleans, numbers, arrays, or JSON when possible.

shell

evd config path
evd config list
evd config get profile
evd config get collectors.tasks
evd config set profile fast
evd config set collectors.tasks false

`evd prune`

Removes old snapshots that are not protected by a pin, baseline, run, case, or safety reference. It is a dry run until you pass --yes.

shell

evd prune
evd prune --keep 30 --days 14
evd prune --keep 30 --days 14 --yes

`evd demo`

Seeds the isolated fixture case so you can try the case view, report, dashboard, and rollback preview. The demo does not read live machine state while seeding.

shell

evd demo --reset
evd demo --report --out ./.envidence/demo-report.html
evd demo --ui --no-open

Common workflows

Investigate a failing test

shell

evd watch -- npm test
evd why
evd report --case CASE-... --out envidence-case.html
evd rollback --case CASE-... --dry-run

Compare before and after an upgrade

shell

evd snap --label "Before upgrade"
# Run the upgrade.
evd snap --label "After upgrade"
evd diff "Before upgrade" "After upgrade"
evd baseline accept --label "After upgrade"

Use JSON in a script

shell

evd why --json
evd diff --json
evd doctor --json
evd config list --json

Exit codes

evd watch preserves the child command's exit code. evd why --fail-on-findings exits with code 1 when findings are present. Rollback apply exits with code 1 if any actions fail.