---
title: memhtml exec
description: "Run a read-only traversal script over the corpus in a sandbox: multi-hop in ONE execution."
---

## 1. Synopsis

Run a read-only traversal script over the corpus in a sandbox: multi-hop in ONE execution.

```sh
memhtml exec [options]
```

## 2. Arguments

This command takes no positional arguments.

## 3. Flags

| Flag | Type | Default | Values | Description |
| --- | --- | --- | --- | --- |
| `--file` | string | *no default* | *no fixed set* | The script to run, as a path on the HOST. Omit it, pass `--file -`, or pass a positional `-` to read the script from stdin. Mutually exclusive with `--script`. |
| `--script` | string | *no default* | *no fixed set* | The script source, inline. Mutually exclusive with `--file` and with reading stdin. |
| `--timeout-ms` | integer | `30000` | *no fixed set* | Wall-clock bound on the script. Exceeding it is `exitCode` 124 with `timedOut: true`, not an error envelope. Capped at 600000. |
| `--sha` | string | *no default* | *no fixed set* | The commit to mount, materialized as a detached worktree. Defaults to HEAD. Never the live working tree, whose gitignored .memhtml/index.db a worktree omits. |

Every command also accepts the [global flags](/reference/global-flags/).

## 4. Response

On success the command writes one JSON envelope to stdout, and its `type` is `exec.report`.

On failure it writes the failure envelope, whose `code` comes from [error codes](/reference/error-codes/).

[The JSON envelope](/reference/envelope/) gives the fields both shapes carry. [Response types](/reference/response-types/) lists every value `type` takes across the binary.

## 5. Further reading

The guide blocks that name this command:

* [`code-mode`](/reference/guide/code-mode/)

## 6. Provenance

A loader generates this page from `apps/cli/src/commands.ts` while the site builds, so no file in the repository holds it: the `COMMANDS` array there is the one source of argument parsing, of `memhtml manifest`, and of `AGENTS.md`. Change the registry and this page changes with it.