Envidence
Docs
Documentation menu

Start here

Getting started

This guide takes you from a global install to your first recorded command failure. You do not need to configure a server or create an account.

Requirements

  • Node.js 24 or newer.
  • Windows 10 or 11 for the full collector set. macOS and Linux work with a smaller POSIX collector set.
  • A terminal that can run the command you want to investigate. PowerShell, Windows Terminal, bash, and zsh are all fine.

Why Node 24?

The local store uses node:sqlite. Older Node versions fail before the CLI starts.

Install

Install the CLI
npm install -g envidence

envidence --version
evd --version

The package installs two equivalent commands: envidence and evd. The documentation uses evd because it is shorter.

If you do not want a global install, use npx envidence in place of evd.

Initialize a project

Move into the project you want to investigate, then create the local store and take the first full snapshot. Run this while the project is in a state you trust.

Create a known-good snapshot
cd /path/to/project
evd init --label "Known good"

evd init creates the store, captures a full snapshot, and marks that snapshot as the active baseline. You can use --fast for a quicker snapshot with fewer collectors, or --no-baseline if you only want the snapshot.

Keep the store inside the project

To avoid writing to the default data directory, pass a store path:
Project-local store
evd init --store ./.envidence --label "Known good"
The same --store ./.envidence flag can be used with later commands, or you can set ENVIDENCE_HOME. See Configuration.

Run a command under watch

Wrap the command that represents the behavior you care about. Envidence takes a fast snapshot, runs the command, takes another snapshot, and compares the two.

Run and record
evd watch -- npm test

The command runs normally. Its exit code is preserved, so scripts and terminals see the same result they would without Envidence. If the command fails, Envidence opens a case and prints the strongest machine changes it found.

Use --full when the failure may involve a collector that is not in the fast profile, and --timeout 300 when a command may hang.

Review the failure

Open the case
evd why

evd case list
evd case show CASE-...

evd why explains the newest open case, a specific case or run, or a command. It shows the reference state, observed changes, ranked hypotheses, and the reasons behind each score.

A finding is a lead, not a verdict. Read the before and after values and the origin label. A change marked pre-existing was already present relative to the reference. A change marked observed-during happened inside the command window.

Already failing?

Envidence cannot reconstruct a machine state it never recorded. If a failure is already happening and you have no known-good snapshot, take one now and use evd watch for future commands. You can still compare new changes against the snapshot you take today.

Share the evidence

Create a single HTML file that another developer can open without your store:

Create a report
evd report --case CASE-... --out envidence-case.html

The default standard redaction removes your home directory, project path prefixes, hostname, username, and public-looking IPs. Use --redact strict to remove more identifiers. Review the file before attaching it to a public issue.

Preview a fix

If the evidence points to a reversible change, generate a plan without changing anything:

Preview only
evd rollback --case CASE-... --dry-run --script rollback.ps1

Apply is a separate, confirmed step. Read Rollback before using --apply.

Try the demo

To see the full case flow without reading your machine, run the fixture demo:

Optional demo
evd demo --reset

# Optional: create a report or open the dashboard
evd demo --report --out ./.envidence/demo-report.html
evd demo --ui --no-open

The fixture data is seeded under <store>/demo. The demo does not scan live system state while seeding.

Next steps