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;
--jsonproduces 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.
dl memos read "$NOTE_ID" --view source > note.mdconst snapshot = await dl.notes(noteId).read({ view: "source" })
// Export snapshot.content using the caller's filesystem adapter.snapshot = dl.notes(note_id).read(view="source")
# Export snapshot.content without changing its final newline.notes_read({ note: noteId, view: "source" })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
| Family | stdin | stdout | stderr |
|---|---|---|---|
| List/outline/find/diff | Unused | One page, outline, matches or patch; structured provenance with JSON | Request/access/reference errors |
| Create | Optional explicit source | Identity, title/link and initialized-source receipt | Explicit partial/unknown outcomes |
| Read/retained/focused | Unused | Mapped by default; exact bytes or structured snapshot when requested | Missing scope/revision or access errors |
| Replace/insert/remove | Explicit replacement/addition where relevant | Accepted source receipt | Selection/baseline/conflict errors |
| Append/write/patch | Explicit exact source or patch | Accepted source receipt | Conflict/unknown outcomes; no blind retry instruction |
| Presence/visit | Unused | Roster or visit/location receipt | Access/stale-location failures |
| Watch | Unused | Snapshot/events, NDJSON under JSON | Connection/shutdown diagnostics |
| Move/rename | Unused, except explicitly named reviewed request file | Completed/pending/blocked/unknown resource result | Authority/collision/operation diagnostics |
| Versions | Unused | Saved metadata/content with explicit provenance | Missing 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.