memhtml session start
1. Synopsis
Open a v2 session on the ref’s tip: a pointer to that version plus an empty overlay log.
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.
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.
The JSON envelope gives the fields both shapes carry. Response types lists every value type takes across the binary.
5. Further reading
No guide block names this command. The 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.