> ## Documentation Index
> Fetch the complete documentation index at: https://engramviz.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI reference

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

Install the CLI as a development dependency:

```bash theme={"dark"}
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`.

```bash theme={"dark"}
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:

```bash theme={"dark"}
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:

```bash theme={"dark"}
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:

```bash theme={"dark"}
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.

<Warning>
  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.
</Warning>

## `engram env`

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

```bash theme={"dark"}
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:

```bash theme={"dark"}
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:

```bash theme={"dark"}
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:

```bash theme={"dark"}
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.