CLI reference

Commands for local capture, Studio, imports, diagnostics, and memory regressions.

Install the CLI as a development dependency:

npm install --save-dev @engramviz/cli

Command	Description
engram init [--project name] [--framework langgraph]	Create local capture; optionally scaffold replay and CI
engram dev [--port 3100] [--executor module]	Start Studio with the configured replay executor
engram demo stale-location	Start Studio and record the flagship stale-memory incident
engram env [--format shell|json]	Print agent-safe capture environment values
engram run [--expected text] [--port 3100] -- <command>	Capture a process and print its direct incident link
engram doctor [--port 3100]	Check capture, executor, isolation, checkpoint, and Studio
engram import <capture.json>	Import an engram.capture bundle
engram test [artifact] [--executor module]	Run one or all configured regressions through project-owned code
engram test <artifact> --observation <json>	Validate an existing observation

engram init

Creates .engram/config.json and adds .engram/config.json plus .engram/data/ to the repository’s .gitignore.

npx --yes @engramviz/cli init --project support-agent
npx --yes @engramviz/cli init --project support-agent --framework langgraph

Running init again preserves the existing token and project identity.

With --framework langgraph, Engram also creates engram.config.json, a preserved engram.executor.mjs skeleton, regressions/, and a package-manager specific GitHub Actions workflow. Existing files are never overwritten.

The setup scan detects npm, pnpm, yarn, or bun; checks whether the SDK and a matching Mem0 or LangGraph adapter are installed; reports OpenAI Agents when present; and confirms that local capture files are ignored.

engram demo

Run the complete Capture → Diagnose → Replay → Test walkthrough:

npx --yes @engramviz/cli demo stale-location

Use --no-open to keep the browser closed. --no-start seeds an already running Studio, which is useful in automated tests. When the default port belongs to another local service or Engram project, the demo automatically starts on the next available port. Pass --port to require a specific port.

engram dev

Starts Studio at http://localhost:3100/?mode=incidents by default:

npx --yes @engramviz/cli dev
npx --yes @engramviz/cli dev --port 3200

When engram.config.json declares an executor, dev loads it automatically. --executor remains available as an explicit override:

npx --yes @engramviz/cli dev \
  --executor ./engram.executor.mjs \
  --executor-port 3101

The CLI loads the module’s default MemoryReplayExecutor export, starts an authenticated loopback server, and passes its URL and bearer token to Studio as server-only environment variables. The browser never receives the token or imports the executor module.

An executor must construct isolated checkpoint and memory-store runtimes. Never connect a replay executor directly to a mutable production Store or allow live side effects unless its manifest and implementation explicitly support that mode.

engram env

Use this when a process manager needs the capture values without engram run:

npx --yes @engramviz/cli env --format shell
npx --yes @engramviz/cli env --format json

The output contains only ENGRAM_URL, ENGRAM_TOKEN, and ENGRAM_PROJECT_ID.

engram run

Everything after -- is executed as the agent command:

npx --yes @engramviz/cli run -- npm run dev:agent
npx --yes @engramviz/cli run --expected Oakland -- node scripts/reproduce-incident.mjs

The child process inherits its normal environment plus the Engram capture values. After it exits, the CLI finds the newly captured trace and prints a direct Studio URL. --expected also prefills expected answer evidence and opens the incident automatically when Studio loads the URL.

engram doctor

In a scaffolded project, doctor validates the configured framework and executor manifest, rejects an executor whose default side-effect mode is execute, checks replay capabilities and captured checkpoint metadata, and probes both Studio and its local executor bridge. A generated executor still containing the scaffold marker is reported as unfinished.

Regression output

engram test supports human-readable, JSON, and GitHub Actions output:

npx --yes @engramviz/cli test incident.engram-test.json \
  --executor ./engram-regression.mjs \
  --format github \
  --output engram-regression-report.json

Omit the artifact and executor to run every *.engram-test.json under the paths declared in engram.config.json through that project’s configured executor:

npx engram test --format github --output engram-regression-report.json

Failed findings include the expected value and the observed retrieval IDs, context count, or answer. GitHub mode emits error annotations for failed assertions while the JSON report remains available as a build artifact.