DreamLake

Read, edit and search from the CLI

Name a memo

bash
dl memos read --legacy design-doc                     # slug
dl memos read --legacy 6aa948b3fea6e541282b747e       # id
dl memos read --legacy "Design Doc"                   # exact title

# Every example below uses $NOTE_ID. Set it once — any of the three forms:
NOTE_ID=design-doc

A memo you may not read answers exactly as one that does not exist.

Read Memos directly

For normal reads, run the bare command and inspect its output directly:

bash
# Set NOTE_ID to the note ID, slug, or exact title you want to read.
dl memos read "$NOTE_ID"

The default is an annotated reading view. Use the smallest relevant read for inspection; do not write generated address hints back into the Memo. For an editing baseline, retain the complete structured snapshot and its opaque revision:

bash
dl memos read "$NOTE_ID" --json > baseline.json
BASE=$(jq -er .revision baseline.json)
jq -jr .content baseline.json > baseline.md

Keep both files unchanged while preparing a patch. --view source exports exact source bytes without metadata; it alone does not retain the revision required for a guarded edit. See the current CLI read contract.

Python SDK read

Python SDK 0.41.0+ exposes the canonical memos facade. With the SDK installed and the intended account logged in, retain one complete snapshot:

python
import dreamlake as dl

memo = dl.memos("<full-memo-id>")
snapshot = memo.read(view="source")
print(snapshot.content)
# Retain snapshot.revision and snapshot.hash with this original source.
changes = memo.diff(since=snapshot.revision)
print(changes.patch)

The facade's diff(since=...) accepts a retained RTC revision or prior read result, reads that retained source and verifies the resulting net diff. It does not identify the human editor or advance a write baseline. Missing retained source is an error, not an empty diff. With Python 0.43.0+ and matching server support, memo.presence(selections=True) observes human selections; inspect its availability fields before interpreting an empty roster. See agent presence.

Use the actual full ID returned by DreamLake. dl.notes remains an alias for the facade. The lower-level dl.memo/dl.note interfaces below remain available; their read_snapshot and hash-based diff contract differs from the facade's revision-based diff. Do not interchange those inputs. SDK configuration and login are documented in the Python SDK guide.

Read

Prefer the smallest relevant read

For a targeted question or edit, read the relevant section or passage instead of the entire memo. Use toc or find to locate it when needed, then request that section or line range. Read the whole document when reviewing the whole document, establishing a required v2 baseline, or recovering a missing or expired baseline — not on every small edit or verification.

Keep the baseline and its tokens across calls. Once a v2 baseline is available, use incremental reads to refresh the cached source and check edits; inspect only the relevant changed passages. A section read is not a complete v2 baseline. Do not replace the whole body with a partial read, or substitute a legacy ETag for an opaque v2 revision.

With the current CLI, --section, --start-line, --end-line and --numbered require --legacy. V2 supports complete source and --since deltas, not section snapshots. Prefer the scoped compatibility read for inspection; obtain one full v2 baseline only when the planned patch workflow needs it and none is cached.

Attributed reads also affect what collaborators see. A full-body read selects the full source; a scoped read selects its returned passage, and a delta read does not claim a whole-document selection. Match the requested range to the work you are doing. Do not issue repeated full reads just to refresh presence; use a heartbeat for an active session or let recent presence expire.

Read commands

The existing examples below use the explicit --legacy CLI contract (source text and content-hash etag). The v2 interface later in this guide uses content, hash and an opaque RTC revision. Do not mix their tokens.

bash
dl memos read --legacy "$NOTE_ID"                                    # whole body
dl memos read --legacy "$NOTE_ID" --section install                  # one section
dl memos read --legacy "$NOTE_ID" --start-line 40 --end-line 80
dl memos read --legacy "$NOTE_ID" --start-line 40 --end-line 80 --numbered
dl memos read --legacy --note "$NOTE_ID" --json                      # body + revision
dl memos toc --note "$NOTE_ID"                              # the outline
dl memos toc --note "$NOTE_ID" --json

A section is a heading plus everything under it. Anchors are title slugs (setup, setup-2 when repeated); text above the first heading is preamble.

toc gives each heading an anchor, a line range and a character range — enough to edit a part without reading the whole memo.

A ranged read reports the whole memo's revision. Writing a range back as the body deletes everything outside it — use replace instead.

Edit by what it says

Line numbers move when anyone edits above them; text does not. A query matching twice is refused, not applied to the first match.

The examples below are independent recipes, not a script to run in sequence. Before each revision-checked edit, read the memo and capture its revision (the CLI recipe uses jq):

bash
REV=$(dl memos read --legacy "$NOTE_ID" --json | jq -er .etag)

Inspect the returned body before choosing the edit. After a successful write, read again before the next edit; do not reuse the old revision or bypass a conflict with --force.

bash
dl memos find "Draft" --note "$NOTE_ID"
dl memos find --regex '\bTODO\b.*' --flags im --note "$NOTE_ID"

dl memos replace "Draft" --text "Published" --all --note "$NOTE_ID" --if-match "$REV"
dl memos insert --text "New line" --line 10 --note "$NOTE_ID" --if-match "$REV"
dl memos delete "obsolete paragraph" --note "$NOTE_ID"

Replacement text is the first argument; query or regex names what to change. Each edit returns the whole updated source, not just the part it touched.

Exactly one match is expected. --all / all=True takes every match; --count N / count=N requires exactly N. A failed edit changes nothing.

Python edits are local until save(), which writes one patch against the revision read() returned. If the memo moved, the save is refused. doc.revert() throws the local edits away.

Patterns

Regex is explicit — never inferred from the query. JavaScript syntax in both clients: (?<name>…), $1, $<name>, $&, $$ for a literal $. Capture expansion is automatic; there is no flag for it.

bash
dl memos replace --regex '(\w+)=(\d+)' --text '$1: $2' --all --note "$NOTE_ID"
dl memos replace --regex '(?<key>timeout|retries)=(?<value>\d+)' \
  --text '$<key>: $<value>' --all --note "$NOTE_ID" --if-match "$REV" --dry-run

--dry-run prints the result without writing. Every mutation takes --if-match.

By line or character range

When the text is awkward to name, address it by position instead. Positions come from a read or from toc.

bash
dl memos replace --text "Updated line" --line 10 --note "$NOTE_ID" --if-match "$REV"
dl memos replace --text "New block" --line 10:15 --note "$NOTE_ID"
dl memos replace --text "replacement" --ind 120:145 --note "$NOTE_ID"
dl memos insert --text "inserted text" --ind 120 --note "$NOTE_ID"

Lines are 1-based and inclusive. ind is 0-based and end-exclusive, counted in Unicode code points — so an emoji or a CJK character is one unit, not two. toc returns both.

A line edit keeps the line ending; a character edit adds nothing.

HTML

Markdown may contain HTML, and a memo's body can be an HTML document outright. When it does, address an element rather than raw text — the same sentence often appears in several places, and a plain query would refuse the edit as ambiguous.

bash
dl memos select "#contact" --note "$NOTE_ID"          # where it is, and its text
dl memos replace "Contact us" --text "Talk to sales" --selector "#contact" --note "$NOTE_ID"
dl memos insert --text "<li>New</li>" --selector "#list" --position append --note "$NOTE_ID"

A selector must match exactly one element; zero or several is an error. select on its own only reports — the element's source range and its decoded text — and changes nothing.

Only the addressed characters change; entity spelling, attribute quoting and whitespace elsewhere survive.

Write whole parts

Whole-body target writes plan changes against an original source; section replacement remains a separate compatibility operation.

Release status — October 12, 2026: CLI 0.61.0 is publicly published: all nine npm records, downloaded Linux integrity/version, fresh npm installation and native skill packaging are verified. The public binary passed concurrent-gap preservation, strict input and exact-write checks; disposable Memos were removed. Python SDK 0.28.0 is publicly published: wheel/sdist bytes match the retained release workflow, and a fresh public installation passed actual API verified-read/diff/Doc-cache acceptance on a disposable Memo, then removed it. Live docs and public skill propagation are separate release checks.

bash
# CLI 0.61.0: retain the original source used to prepare whole.md.
dl memos read "$NOTE_ID" --json > whole-baseline.json
WHOLE_BASE=$(jq -er '.revision' whole-baseline.json)
jq -jr .content whole-baseline.json > whole.md
# Edit whole.md while keeping whole-baseline.json unchanged.
dl memos write "$NOTE_ID" --file whole.md --base-revision "$WHOLE_BASE" --json > whole-ack.json
WHOLE_ACK=$(jq -er '.revision' whole-ack.json)
dl memos read "$NOTE_ID" --at "$WHOLE_ACK"
# Section write remains on its explicit compatibility API.
dl memos write "$NOTE_ID" --section install --file install.md
# Append uses original-revision patches in CLI 0.59.0 and later. Requires jq.
dl memos read "$NOTE_ID" --json > append-baseline.json
BASE=$(jq -er '.revision' append-baseline.json)
dl memos append "$NOTE_ID" --text "one more line" --base-revision "$BASE" --json > append-ack.json
ACK=$(jq -er '.revision' append-ack.json)
dl memos read "$NOTE_ID" --at "$ACK"
# For a file, use --file more.md with the same saved original baseline.
dl memos add-section "$NOTE_ID" --file trouble.md --after install
dl memos rm-section "$NOTE_ID" troubleshooting

Anyone with the memo open sees an accepted change appear. Modern append merges against the original collaborative identities, preserving unrelated concurrent edits. Add CLI --exact or Python exact=True to require that the original revision is still current. A stale exact request requires review; never replace its baseline with a fresh revision merely to make it pass.

Since server 06fbbe65 (production, 2026-10-27), merge mode refuses, with HTTP 412 stale and no write, any patch that overlaps a change made after its baseline, including text appended at the same end of the memo. Python reports this as NoteChanged. Disjoint edits still merge. The CLI's bundled notes-editing reference ("Overlapping concurrent changes") gives the exact rule and recovery.

Python's default append returns a PatchReceipt; CLI --json returns its revision and hash. Read back that acknowledged revision before claiming the intended result. If a write outcome is unknown, reconcile it before resubmitting. Explicit CLI --legacy / --force and Python legacy=True / force=True retain the older append compatibility path; Python returns a string there.

CLI 0.61.0 whole-body write derives bounded exact disjoint code-point changes from one hash-verified original snapshot, preserving unchanged identities even within a paragraph. Retain --base-revision when a target was prepared earlier; omitting it reads one current snapshot and cannot establish an old file's origin. Modern file/stdin input rejects malformed UTF-8 before transport and preserves literal BOM, Unicode and line endings. Merge no-ops send no write; an unchanged --exact target sends an empty PATCH so a stale original revision still rejects. Alignment or patch limits fail before submission without a coarse rewrite. Explicit --legacy, --force, or --if-match keep the prior body path and cannot mix with modern baseline/exact flags. --section also rejects those modern flags. Keep the original target/baseline after an unknown acknowledgment; never replay or silently refresh the baseline. Without --json, dry-run stdout is the target body; JSON dry-run also reports the planned payload. Neither predicts merged concurrent source.

Python SDK 0.27.0 also defaults whole-body note.read() drafts, note.write() and doc.save() to original-revision edits. Unchanged source spans preserve their collaborative identities, including within one paragraph. A draft keeps its own original snapshot even if other operations use the same Memo object. After saving, it adopts the acknowledged merged source for the next edit. If that readback fails after an acknowledged write, preserve the receipt and draft and reconcile before another save; do not replay the write.

SDK 0.27.0 also fixes native append escaping for tabs. Older native append clients can reject tab-containing edits; upgrading preserves the saved baseline. Explicit Python legacy=True, force=True or write(if_match=...) retain compatibility behavior. A compatibility save keeps subsequent saves in the ETag domain until a new modern draft is read.

CLI whole-body writes through 0.60.0, Python whole-body writes through 0.26.0, and section writes/insertion/deletion still use the ETag compatibility interface. They can reject an intervening content change. Section client migration and Runbook attachment remain pending; no legacy command or server route is retired here.

Changes since a read or edit

Legacy ETag interface: available alongside v2 in CLI 0.26.2 and Python SDK 0.20.0. Select --legacy for these CLI recipes and legacy=True for remote Python patches.

The CLI returns the same ref in read --json and accepts it via --since:

bash
# Requires jq. Keep the snapshot and ref for a later shell session.
NOTE_ID=design-doc
dl memos read --legacy "$NOTE_ID" --json > note-snapshot.json
REV=$(jq -er .etag note-snapshot.json)
dl memos diff --legacy "$NOTE_ID" --since "$REV"
dl memos diff --legacy "$NOTE_ID" --since "$REV" --json
# Apply a diff prepared against that saved body:
dl memos patch --legacy "$NOTE_ID" --file change.patch --if-match "$REV" --json

notes diff requires --since; it does not keep a hidden local baseline. Plain output is the diff on stdout and current ETag on stderr. --json also returns from and to. The CLI help includes this workflow: dl memos diff --legacy --help, notes read --help, and notes patch --help.

Reads return doc.etag, a quoted SHA-256 hash of the complete memo text. Keep that ref to see changes since your own read or successful edit across sessions:

python
note = dl.memo("<note-id>")
doc = note.read(legacy=True)
ref = doc.etag

print(note.diff(since=ref, legacy=True))  # explicit compatibility diff
print(note.diff(legacy=True))             # this handle's cached ETag
result = note.patch(my_diff, if_match=ref, legacy=True)
ref = result.etag                   # reference for the successful edit

Fetching a diff does not advance the cached revision or write precondition. Call read(legacy=True) or refresh(legacy=True) to adopt the latest compatibility state. Identical text has the same hash; the ref identifies content, not an RTC operation index. Unknown refs return an error, including older refs whose snapshots were never retained.

The HTTP endpoint is GET /namespaces/:slug/notes/:noteId/diff?since=<etag>. It returns diff, from, to, and etag (the current ref). Snapshots are scoped to the memo and require current read access. Optional context accepts 0–100 lines, default 3. Partial reads return a ref for the complete body.

For local draft changes, use doc.diff() for all unsaved changes, doc.diff(since="last_edit") for the latest local operation, and doc.patch(unified_diff) to apply a patch before doc.save().

Verified full reads and remote diffs (SDK 0.28.0+)

Default note.refresh(), cache-miss note.text / note.get_text(), and note.read() use verified complete v2 source. Returned Memo identity, content hash and RTC revision must agree; malformed responses or redirects reject without adopting source. Refresh updates the Memo cache, never an existing Doc's saved original snapshot. read_snapshot() remains an independent verified read; at selects retained source, while if_match checks the current RTC revision. They cannot combine. An ETag is not an RTC revision and must not be supplied here.

python
note.refresh()                 # verified complete source, not a partial range
source = note.text             # cached source; refresh explicitly for newer text
original = note.read_snapshot()
remote_diff = note.diff(since=original.hash)  # string, not a write receipt
# Retain original.revision separately for a later original-revision edit.

Default note.diff() returns a unified source-diff string and uses this handle's cached content hash when since is omitted. since accepts sha256:<hex>, quoted ETag-shaped SHA-256, or bare SHA-256; RTC revisions are rejected. The v2 diff's Note/base/format/receipt metadata and acknowledged retained source hash are validated. Inspection does not adopt returned source or advance any cache/draft baseline; a display diff is not a write precondition or proof of peer convergence.

Explicit refresh(legacy=True), get_text(legacy=True) and diff(legacy=True) retain compatibility behavior. diff(context=N) with N != 3 deliberately selects the existing compatibility endpoint before transport; context is an integer from 0 through 100. Default context 3 uses v2, with no fallback after a failure. Section/line reads remain partial compatibility views and cannot serve as complete modern write baselines. Existing Doc-local diff() and patch() continue to operate on the local draft rather than this remote diff endpoint.

Patch

This legacy patch helper validates unified-diff context against current text and rejects mismatched context. Its optional ETag rejects any intervening revision. The v2 merge workflow below instead addresses the saved original native identities and preserves compatible concurrent edits.

bash
diff -u before.md after.md | dl memos patch --legacy "$NOTE_ID" --file -
dl memos patch --legacy "$NOTE_ID" --file change.patch --dry-run

Search

bash
dl memos grep "TODO" -C 2
dl memos grep --regex '\bFIXME\b' --case-sensitive --glob 'spec-*'
dl memos grep "Draft" --json        # revision + character range per hit

Output is slug:line:column, like rg — which memo, and where inside it. Literal and case-insensitive by default, so v1.2 does not match v1x2.

Each hit carries its revision and ind, the character range — enough to edit without re-reading:

python
hit = dl.grep_notes("Draft", namespace="<namespace>").hits[0]
doc = hit.open().read()
doc.replace("Published", ind=hit.ind)
doc.save()

Select an agent passage by matching text

CLI 0.32.0+: notes select --text publishes an agent selection; section selection requires the server update adding hash and range to section reads. Older server responses fail explicitly.

bash
export DREAMLAKE_AGENT_ID="review-session-42"
export DREAMLAKE_AGENT_NAME="Codex"
NOTE_ID="your-note-id"
dl memos select --text "The next step is tested in simulation." --note "$NOTE_ID"
dl memos select --text "simulation" --section next-steps --occurrence 2 --note "$NOTE_ID"
dl memos select --text "simulation" --section next-steps -o -1 --note "$NOTE_ID"

Use a stable task identity and your normal authenticated Memos access. The command matches exact canonical source text, including whitespace and markup. It refuses missing or ambiguous matches. -o aliases --occurrence: 1 selects the first match, -1 the last, and -2 the second-last within the chosen scope. Zero and out-of-range values fail without publishing. Receipts report the resolved positive 1-based occurrence. A section match downloads only that section, not the entire document. A whole-note match reads source internally without printing it. Target resolution suppresses read highlighting until a unique match is found.

It then sends POST /namespaces/:slug/notes/:noteId/presence with {action:"seek", hash, ranges:[{start,end}]}. Ranges are half-open Unicode code-point offsets in the whole canonical source. Section reads now return an additive range in code points and the whole-source hash; legacy start/end stay UTF-16. Old servers without section metadata fail explicitly. The server validates current source and collaboration access. No source write or human-cursor change occurs.

Plain text is the default for selection commands and agent workflows. Omit --json in normal tool calls and examples. The receipt confirms server acceptance and returns the quoted matched text, scope, resolved match number/count, code-point range and separate expiry times. Multiline excerpts escape newlines. Only an explicit machine integration should request --json; that optional receipt includes exact text and scope ({kind:"note"} or {kind:"section",anchor:"next-steps"}), alongside note, hash, range, occurrence, matches, published, selectionExpiresAt and presenceExpiresAt. It does not return the surrounding section or document. Browser rendering still requires an active compatible RTC room and editor. Selection activity lasts eight seconds and presence lasts sixty; a heartbeat renews presence only. Users can navigate to the agent's selected passage through its location control.

Pass a retained --hash "$HASH" (sha256:…) to require the same source. If the source changes before publication, stale_range fails without a guessed retry: read the section again and select its current text. Duplicate/missing matches publish no selection. Legacy notes select "#contact" --note "$NOTE_ID" and notes find remain lookup operations, not explicit visible seek commands.

For address hints while reading Markdown, use read NOTE --view markdown with the addressed-read CLI/server build. It preserves the selected source text and inserts generated address/character/line comments. List-item targets use hierarchical li IDs, such as s1.ul2.li3, including nested items. Containers use ul or ol; every numeric suffix shares paragraph reading order. This reading view is not canonical source and must not be written back as a complete memo.

Proving a patch was not submitted

If preparing the current native body baseline fails before the requested edit starts, the write API keeps HTTP503/rtc_unavailable and adds this current versioned submission status:

json
{"error":"rtc_unavailable","mutation":{"apiVersion":1,"started":false,"phase":"baseline_read"}}

This proves only that this request did not reach its requested native edit; it does not claim that other collaborators or internal room initialization changed nothing. The API logs the request ID, actual preparation stage and the same marker, without patch/source text or capabilities. Read failures do not carry a mutation marker. Once native submission begins, an unavailable or lost ACK does not receive this proof: a503 can still mean that the edit committed.

The CLI recognizes only this exact typed marker and preserves the baseline and draft. Missing, malformed or unsupported marker versions remain unknown; they never trigger automatic mutation retry, revision refresh or API downgrade.

Legacy revision-checked edit helpers

The legacy whole-body/local-document helpers below carry the revision they were based on. A note that changed in between is refused rather than overwritten:

bash
REV=$(dl memos read --legacy "$NOTE_ID" --json | jq -r .etag)
dl memos write "$NOTE_ID" --file new.md --if-match "$REV"
PythonCLI exitMeansDo
NoteChanged3It changed since you read itRe-read, redo. Retrying fails again.
NoteBusy4The realtime outcome is unavailablePreserve the draft and baseline; read and reconcile before resubmitting.
PatchFailed5Your diff no longer appliesRe-read, regenerate it.
NoMatch6Nothing matchedWiden the query.
—7Refused to overwrite a local filePass --overwrite.

--force / force=True skips the check — deliberately, so overwriting a colleague is something you typed rather than something that happened.

Verify a write landed by reading it back against the revision it produced:

python
rev = note.patch(diff, if_match=doc.etag, legacy=True)
check = note.read(if_match=rev.etag)      # refused if anything changed since

Which addressing to reach for

  1. Exact text (query=) — what you can state reliably; ambiguous matches fail.
  2. A section anchor from toc for a heading and its contents.
  3. A line or character range from a current read, TOC or grep hit.
  4. A unified patch for coordinated changes in several places at once.

Next steps

CLI Reference →

Every dl memos command and flag.

API Reference →

The endpoints underneath, if you need them directly.

Proposed incremental insertion and concurrency defaults

Not available in the checked clients. The published TypeScript/CLI package @dreamlake/dreamlake-cli 0.125.3 and Python dreamlake 0.52.2 do not expose the streaming methods and flags below (artifact audit: 15 November 2026). This section records the intended contract; its examples and defaults must not be treated as released client behavior. Continue using the supported editing commands above and inspect each command's installed help for its conflict mode.

The proposed collaborative editing update adds note.streamInsert in TypeScript and note.stream_insert in Python. These accept an original snapshot or revision, a code-point cursor and an iterable of text chunks; TypeScript also accepts an async iterable. CLI memos insert --file - uses the same sequential ACK workflow by default (--no-stream selects a single buffered insertion). Each request contains at most 2048 code points. Batch producer tokens to limit request overhead.

python
import dreamlake as dl
note = dl.memos(memo_id)
original = note.read()
for receipt in note.stream_insert(at=original, cursor=0, chunks=generated_chunks):
    persist_receipt(receipt)
typescript
const note = dl.memos(memoId)
const original = await note.read()
for await (const receipt of note.streamInsert({at: original, cursor: 0, chunks: generatedChunks})) {
  await persistReceipt(receipt)
}

The server returns continuation: {revision, cursor} after a single insertion. The stream uses the returned code-point cursor in that retained ACK revision, so human changes before the insertion point do not misplace the next chunk. A changed target gap or deleted anchor stops the stream. Never follow the human's moving selection, increment an old offset or search for inserted text.

Merge is the default for patch, write, revise and insertion across these clients. Exact remains opt-in (mode="exact", mode: "exact", or CLI --exact) and checks the original revision separately for each chunk. Both modes commit through RTC. CLI revise checkpoints its retained ACK, including merged human contributions, even when the live draft advances afterward.

An older server may acknowledge a chunk without continuation; clients yield the receipt and stop rather than guessing or resending it. SDK interruption errors carry lastReceipt / last_receipt and pending. Reconcile the pending command ID before continuing. Canceling preserves accepted text. CLI JSON output is one receipt per line. Optional stream IDs prefix unique chunk command IDs; do not restart a partially accepted stream from chunk zero.

Built-in insertion tools expose continuation for successive completed calls; they do not execute unfinished model tool arguments. Publish presence intent and save before/after checkpoints for the logical edit, not every chunk. The Python version facade still supports list/read only; do not invent versions.save or revise SDK methods. See the cross-client contract and CLI editing guide for recovery details.