---
title: memhtml session start
description: "Open a v2 session on the ref's tip: a pointer to that version plus an empty overlay log."
---

## 1. Synopsis

Open a v2 session on the ref's tip: a pointer to that version plus an empty overlay log.

```sh
memhtml session start [options]
```

## 2. Arguments

This command takes no positional arguments.

## 3. Flags

| Flag | Type | Default | Values | Description |
| --- | --- | --- | --- | --- |
| `--id` | string | *no default* | *no fixed set* | The session id: one path segment, letters, digits, `.`, `_`, `-`. State lives at .memhtml/sessions/<id>.json (its overlay log); a commit stages through a temporary index of its own and keeps nothing else. Defaults to $MEMHTML_SESSION; with neither, the call is ERR_MISSING_ARGUMENT. |
| `--ref` | string | *no default* | *no fixed set* | The ref commits land on. Defaults to refs/heads/main. A ref that does not exist yet (a curator's refs/heads/curate/<date>) starts from HEAD and is created by the first commit. |
| `--force` | flag | `false` | *no fixed set* | Discard an existing log under this id and start over. Without it, an id that already has a log is refused with ERR_STORAGE (session.exists) so a retried start cannot lose an overlay in progress; `session status --id <id>` reads the existing one. |

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 `session.started`.

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

No guide block names this command. The [guide](/reference/guide/) is the workflow prose the CLI ships beside the command table: which command to reach for, and in what order.

## 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.