DreamLake

Memos CLI streams and outcomes

This is the implementation target, not a claim that the redesigned methods, flags or server guarantees are released. Code tabs compare the same intended action through each interface. Current behavior is called out separately. See the API index for migration boundaries.

Common stream contract

CLI input/output must be predictable in a terminal, shell pipeline or agent subprocess. Mapped reads remain the default regardless of whether stdout is a TTY. --json is a structured result option, not a different edit contract.

stdin

Read stdin only with explicit --file -; do not consume a pipe implicitly. Text mutations accept exactly one input source: --text, --file PATH or --file -. Reject conflicts before a network mutation. Read exact UTF-8 through EOF, preserving CRLF, Unicode and the final-newline state. --text does not interpret literal backslash escapes; callers supply the intended bytes.

Empty source is valid for creation and whole-body targets. Empty patches are rejected. Empty append/no-op behavior still needs a final receipt rule. Commands that do not accept source leave stdin alone. With TTY stdin explicitly requested, any EOF guidance goes to stderr. No editor or hidden interactive question is needed to create an empty Memo.

stdout

Stdout contains command results only. Progress, warnings and debug logs do not belong there. Terminal decoration is selected from stdout's TTY state. Non-TTY human output is plain; machines should use the structured schema rather than parse prose.

  • Default reads: source-mapped content with its identity/provenance; generated addresses are not saved source.
  • --view source: selected exact source bytes only, with no header, color or added LF. For structured provenance use --json.
  • --json: one result object plus one framing LF; source's own trailing newline is inside the JSON string. Never mix ANSI/OSC sequences or prose into structured stdout.
  • Source mutation results: stable Memo ID, canonical URL, accepted revision and necessary original-baseline/mode fields. No-op results must be distinguishable from accepted edits.
  • TTY creation: title, ID and clickable canonical URL, with plain-text URL fallback. A URL does not alter access.
  • Watch: an explicit streaming exception. Human output shows readable net diffs/activity; --json produces NDJSON, one typed event per line.

stderr and exit outcomes

Stderr contains errors, warnings and optional connection/progress information. Do not log credentials, share tokens or source by default. Validate arguments locally first; errors include a stable code, outcome category and actionable next step.

A definitive no-write failure emits no stdout. Unknown mutation outcomes must say unknown and preserve reconciliation information rather than imply retry is safe. With --json, failure objects go to stderr. If a mutation was accepted but link lookup, presence or session association failed, preserve the accepted receipt on stdout and report the ancillary failure separately. Never replay the content edit to repair awareness.

Use outcome categories: success/no-op, invalid usage, definitive no-write conflict/refusal, unknown mutation outcome and operational failure. Numeric exit-code migration must account for existing CLI codes; this design does not silently assign new values. Timeout of a bounded watch is clean completion, not a failed edit. Cancellation or broken output after acceptance does not prove no write occurred.

Same action across interfaces

This example exports complete exact source. The SDK/tool examples request the same view and retain structured metadata; the CLI redirects the exact source payload only.

bash
dl memos read "$NOTE_ID" --view source > note.md

A focused export is allowed when explicitly selected, but it must not be used as a complete replacement baseline. Ordinary mapped reads should contain enough exact source and addressing for targeted edits without another full read.

Per-command input and output

Familystdinstdoutstderr
List/outline/find/diffUnusedOne page, outline, matches or patch; structured provenance with JSONRequest/access/reference errors
CreateOptional explicit sourceIdentity, title/link and initialized-source receiptExplicit partial/unknown outcomes
Read/retained/focusedUnusedMapped by default; exact bytes or structured snapshot when requestedMissing scope/revision or access errors
Replace/insert/removeExplicit replacement/addition where relevantAccepted source receiptSelection/baseline/conflict errors
Append/write/patchExplicit exact source or patchAccepted source receiptConflict/unknown outcomes; no blind retry instruction
Presence/visitUnusedRoster or visit/location receiptAccess/stale-location failures
WatchUnusedSnapshot/events, NDJSON under JSONConnection/shutdown diagnostics
Move/renameUnused, except explicitly named reviewed request fileCompleted/pending/blocked/unknown resource resultAuthority/collision/operation diagnostics
VersionsUnusedSaved metadata/content with explicit provenanceMissing version/retention/access errors

Current CLI help and migration

Installed help and the CLI reference remain the authority for available flags. This guide's mapped default, --lines, --ns, unified move fields and new method names are implementation targets. A companion CLI docs change should link this design from real command help and retain current executable recipes until implementations land.

Human text output changing view can break scripts that parse it. Announce the migration; source-only and structured forms should remain deliberate and stable. Product implementation, source examples, generated help, published docs and installed skills are separate release states.

Related contracts

Use reading to select source, editing to submit an original-baseline change, collaboration for durable catch-up boundaries, and moving for resource identity and ownership changes.