--- title: Notes description: Complete reference for creating, reading, editing, organizing, and inspecting notes with the Octarine CLI. --- `octarine note` works on Markdown files inside the selected workspace. All write operations use atomic replacement and workspace locking. ## `note create` Create a Markdown note. Supply content directly, from standard input, or from a file. ```text octarine note create [--content | --stdin | --file ] [--property ]... [--tag ]... [--if-missing] [--unique] ``` ```bash octarine note create Projects/Launch.md \ --content "# Launch plan" \ --property status=active \ --tag project --tag launch cat draft.md | octarine note create Projects/Draft.md --stdin octarine note create Projects/Brief.md --file ./brief.md ``` ```text # Created with inline content ╭──────────┬──────────────────────────────────────────────────────────────────────────╮ │ Field ┆ Value │ ╞══════════╪══════════════════════════════════════════════════════════════════════════╡ │ content ┆ ---\nstatus: active\ntags:\n- project\n- launch\n---\n# Launch plan │ │ path ┆ Projects/Launch.md │ │ revision ┆ sha256:4f1c… │ ╰──────────┴──────────────────────────────────────────────────────────────────────────╯ # Created from standard input or a file ╭──────────┬───────────────────╮ │ Field ┆ Value │ ╞══════════╪═══════════════════╡ │ content ┆ # Project brief │ │ path ┆ Projects/Brief.md │ │ revision ┆ sha256:91ae… │ ╰──────────┴───────────────────╯ ``` `--if-missing` returns the existing note instead of failing. `--unique` chooses an available filename when the requested path exists. Properties and tags are merged into YAML frontmatter. ## `note read` Read a note and return its content plus a revision for guarded writes. ```text octarine note read [--from-line ] [--to-line ] [--lines ] [--section ] [--max-bytes ] [--max-chars ] [--body-only | --frontmatter-only] ``` ```bash octarine note read Projects/Launch.md octarine note read Projects/Launch.md --lines 10:30 octarine note read Projects/Launch.md --section "Open questions" octarine note read Projects/Launch.md --frontmatter-only --json octarine note read Projects/Launch.md --body-only --max-chars 4000 ``` ```text # Full, ranged, section, or body-only read (table) ╭──────────┬───────────────────────╮ │ Field ┆ Value │ ╞══════════╪═══════════════════════╡ │ content ┆ # Launch plan\n… │ │ path ┆ Projects/Launch.md │ │ revision ┆ sha256:4f1c… │ ╰──────────┴───────────────────────╯ # Frontmatter-only read (JSON) {"schemaVersion":1,"ok":true,"data":{"path":"Projects/Launch.md","content":"---\nstatus: active\ntags:\n- project\n- launch\n---","revision":"sha256:4f1c…"},"meta":{"truncated":false}} ``` Line bounds are one-based. Open ranges such as `20:` and `:40` are valid. Use byte or character limits when placing note content into an agent context. ## `note context` Read a note together with the information needed to edit it safely: its content and revision, outline with line numbers, properties, tags, task counts, outgoing links, and backlinks. ```text octarine note context [--max-bytes ] [--no-content] [--backlinks-limit ] ``` ```bash octarine note context Projects/Launch.md --json octarine note context Projects/Launch.md --no-content --backlinks-limit 10 --json ``` ```text {"schemaVersion":1,"ok":true,"data":{"path":"Projects/Launch.md","revision":"sha256:67730d5c…","content":"---\nstatus: active\n…","contentTruncated":false,"sizeBytes":114,"created":1767225600000,"modified":1767312000000,"outline":[{"level":1,"line":6,"text":"Launch plan"},{"level":2,"line":8,"text":"Goals"},{"level":2,"line":12,"text":"Open questions"}],"properties":{"status":"active","tags":"[project]"},"tags":["#project"],"tasks":{"open":0,"done":0},"links":[],"backlinkCount":2,"backlinks":[{"source":"Home.md","line":3,"text":"See [[Projects/Launch#Goals|launch goals]]."},{"source":"Roadmap.md","line":3,"text":"Next: [Launch](Projects/Launch.md)"}]},"meta":{"truncated":false}} ``` Content is limited to 20,000 bytes by default; `contentTruncated` reports when the limit applied. Each outgoing link includes a `resolved` path, or `null` when the target does not exist. Backlinks are limited to 50 by default, and `backlinkCount` always reports the full total. ## `note info` Show file metadata without reading the full note body. ```bash octarine note info Projects/Launch.md octarine note info Projects/Launch.md --json ``` ```text # Table output ╭───────────┬────────────────────╮ │ Field ┆ Value │ ╞═══════════╪════════════════════╡ │ created ┆ 1767225600000 │ │ extension ┆ md │ │ modified ┆ 1767312000000 │ │ name ┆ Launch │ │ path ┆ Projects/Launch.md │ │ sizeBytes ┆ 428 │ ╰───────────┴────────────────────╯ # JSON output {"schemaVersion":1,"ok":true,"data":{"path":"Projects/Launch.md","name":"Launch","extension":"md","sizeBytes":428,"created":1767225600000,"modified":1767312000000},"meta":{"truncated":false}} ``` ## `note random` Read a random note from the workspace or one folder. ```bash octarine note random octarine note random --folder Projects ``` ```text ╭──────────┬──────────────────────╮ │ Field ┆ Value │ ╞══════════╪══════════════════════╡ │ content ┆ # Launch plan\n… │ │ path ┆ Projects/Launch.md │ │ revision ┆ sha256:4f1c… │ ╰──────────┴──────────────────────╯ ``` ## `note wordcount` Count words and characters in one note. ```bash octarine note wordcount Projects/Launch.md ``` ```text ╭────────────┬────────────────────╮ │ Field ┆ Value │ ╞════════════╪════════════════════╡ │ characters ┆ 428 │ │ path ┆ Projects/Launch.md │ │ words ┆ 67 │ ╰────────────┴────────────────────╯ ``` ## `note update` Replace the complete note body. Add `--revision` to reject the write if another process changed the note after it was read. ```text octarine note update [--content | --stdin] [--revision ] ``` ```bash octarine note update Projects/Launch.md --content "# Revised launch plan" cat revised.md | octarine note update Projects/Launch.md --stdin \ --revision 'sha256:' ``` ```text ╭──────────┬────────────────────────╮ │ Field ┆ Value │ ╞══════════╪════════════════════════╡ │ content ┆ # Revised launch plan │ │ path ┆ Projects/Launch.md │ │ revision ┆ sha256:bc20… │ ╰──────────┴────────────────────────╯ ``` ## `note append` Append content while optionally guarding the current revision. ```bash octarine note append Projects/Launch.md --content $'\n## Update\n\nReady to ship.' printf '\n- [ ] Announce release\n' | \ octarine note append Projects/Launch.md --stdin --revision 'sha256:' ``` ```text ╭──────────┬────────────────────────────────────────────╮ │ Field ┆ Value │ ╞══════════╪════════════════════════════════════════════╡ │ content ┆ # Launch plan\n…\n- [ ] Announce release │ │ path ┆ Projects/Launch.md │ │ revision ┆ sha256:d7a2… │ ╰──────────┴────────────────────────────────────────────╯ ``` ## `note prepend` Insert content at the very beginning of a note, above any frontmatter. For a note with frontmatter, use [`note insert --at start`](#note-insert) instead, which places text below the frontmatter so the properties stay valid. ```bash octarine note prepend Projects/Launch.md --content $'> Status: active\n\n' printf '%s\n\n' '# Important' | octarine note prepend Projects/Launch.md --stdin ``` ```text ╭──────────┬────────────────────────────────────╮ │ Field ┆ Value │ ╞══════════╪════════════════════════════════════╡ │ content ┆ # Important\n\n> Status: active\n… │ │ path ┆ Projects/Launch.md │ │ revision ┆ sha256:03ef… │ ╰──────────┴────────────────────────────────────╯ ``` `update`, `append`, and `prepend` accept the same `--content`, `--stdin`, and `--revision` options. ## Targeted Edits These commands change part of a note instead of replacing the whole file. Each one accepts `--revision` and returns the note's previous and new revisions, so you can chain edits without re-reading the note: ```text ╭──────────────────┬─────────────────────╮ │ Field ┆ Value │ ╞══════════════════╪═════════════════════╡ │ changes ┆ 1 │ │ path ┆ Projects/Launch.md │ │ previousRevision ┆ sha256:67730d5c… │ │ revision ┆ sha256:baa6e604… │ ╰──────────────────┴─────────────────────╯ ``` `changes` is the number of replacements or insertions made. Pass the returned `revision` to the next edit of the same note. ### `note edit` Replace exact text. The text must match exactly once unless you add `--all`. ```text octarine note edit --find [--replace | --stdin] [--all] [--revision ] ``` ```bash octarine note edit Projects/Launch.md \ --find "Ship v2" \ --replace "Ship v2 in November" \ --revision 'sha256:' octarine note edit Projects/Launch.md --find "TODO" --replace "DONE" --all ``` If the text appears more than once, the command fails with `AMBIGUOUS_MATCH` and changes nothing; if it does not appear, it fails with `NOT_FOUND`. Include more surrounding text to make the match unique. An empty `--replace` deletes the matched text. ### `note replace-section` Replace the body under a heading. The heading itself is kept, and the section ends at the next heading of the same or higher level. ```text octarine note replace-section [--content | --stdin] [--revision ] ``` ```bash octarine note replace-section Projects/Launch.md "Open questions" \ --content "Support is owned by the platform team." cat goals.md | octarine note replace-section Projects/Launch.md "## Goals" --stdin ``` The heading can be written with or without its leading `#` characters. ### `note insert` Insert text at the start or end of a section, before a specific line, or at the start or end of the note. ```text octarine note insert [--content | --stdin] [--heading ] [--line ] [--at ] [--revision ] ``` ```bash octarine note insert Projects/Launch.md --heading Goals --at end --content='- Update the docs' octarine note insert Projects/Launch.md --line 6 --content '> Draft' octarine note insert Projects/Launch.md --at start --content 'Status: draft' ``` `--at` defaults to `end`. With `--heading`, it places the text at the start or end of that section; without one, at the start or end of the note. Inserting at the start of a note keeps the text below any frontmatter. `--line` inserts before that one-based line. When the inserted text starts with `-`, such as a list item, attach it with `=` (`--content='- item'`) so it is not read as another option. ### `note patch` Apply a unified diff to a note. Use it for changes that touch several places at once. ```text octarine note patch [--diff | --file ] [--revision ] ``` ```bash diff -u Launch.md Launch-edited.md | octarine note patch Projects/Launch.md --file - octarine note patch Projects/Launch.md --file change.diff --revision 'sha256:' ``` ```diff --- a/Projects/Launch.md +++ b/Projects/Launch.md @@ -8,1 +8,2 @@ - Ship v2 +- Publish the changelog ``` If any hunk does not match the note, the command fails with `PATCH_FAILED` and changes nothing. ## `note move` Move a note to an exact destination path and update links to it across the workspace. ```text octarine note move [--dry-run] [--no-update-links] ``` ```bash octarine note move Drafts/Launch.md Projects/Launch.md --dry-run octarine note move Drafts/Launch.md Projects/Launch.md ``` ```text ╭──────────────┬─────────────────────╮ │ Field ┆ Value │ ╞══════════════╪═════════════════════╡ │ dryRun ┆ false │ │ from ┆ Drafts/Launch.md │ │ linksUpdated ┆ 2 │ │ to ┆ Projects/Launch.md │ │ updated ┆ Home.md, Roadmap.md │ ╰──────────────┴─────────────────────╯ ``` `linksUpdated` counts the rewritten links, and `updated` lists the notes that contained them. ## `note rename` Rename a note and update links to it across the workspace. ```text octarine note rename [--dry-run] [--no-update-links] ``` ```bash octarine note rename Projects/Launch.md Projects/Release.md --dry-run octarine note rename Projects/Launch.md Projects/Release.md octarine note rename Old.md New.md --no-update-links ``` ```text # Dry run ╭──────────────┬─────────────────────╮ │ Field ┆ Value │ ╞══════════════╪═════════════════════╡ │ dryRun ┆ true │ │ from ┆ Projects/Launch.md │ │ linksUpdated ┆ 2 │ │ to ┆ Projects/Release.md │ │ updated ┆ Home.md, Roadmap.md │ ╰──────────────┴─────────────────────╯ # Rename ╭──────────────┬─────────────────────╮ │ Field ┆ Value │ ╞══════════════╪═════════════════════╡ │ dryRun ┆ false │ │ from ┆ Projects/Launch.md │ │ linksUpdated ┆ 2 │ │ to ┆ Projects/Release.md │ │ updated ┆ Home.md, Roadmap.md │ ╰──────────────┴─────────────────────╯ ``` `note move` and `note rename` rewrite every link that resolves to the note, using the same rules as the desktop app when it renames or moves files: - Path wikilinks such as `[[Projects/Launch]]` and unique-name wikilinks such as `[[Launch]]` - Embeds such as `![[Projects/Launch]]` - `#heading` and `|alias` suffixes, which are kept - Links in frontmatter properties - Relative Markdown links such as `[Launch](Projects/Launch.md)` Links inside code blocks and inline code are left alone. Renames that only change letter case are supported. Run `--dry-run` first to preview which notes would change. `--no-update-links` changes only the file path. ## `note duplicate` Copy a note. Omit the destination to use the CLI's copy name; add `--unique` to avoid a collision. ```bash octarine note duplicate Projects/Launch.md Projects/Launch-template.md octarine note duplicate Projects/Launch.md --unique ``` ```text # Exact destination ╭──────────┬─────────────────────────────╮ │ Field ┆ Value │ ╞══════════╪═════════════════════════════╡ │ content ┆ # Launch plan\n… │ │ path ┆ Projects/Launch-template.md │ │ revision ┆ sha256:4f1c… │ ╰──────────┴─────────────────────────────╯ # Generated unique destination ╭──────────┬─────────────────────────╮ │ Field ┆ Value │ ╞══════════╪═════════════════════════╡ │ content ┆ # Launch plan\n… │ │ path ┆ Projects/Launch copy.md │ │ revision ┆ sha256:4f1c… │ ╰──────────┴─────────────────────────╯ ``` ## `note outline` List the Markdown heading hierarchy and source locations. ```bash octarine note outline Projects/Launch.md octarine note outline Projects/Launch.md --json ``` ```text # Table output ╭──────────────────╮ │ Value │ ╞══════════════════╡ │ # Launch plan │ │ ## Open questions│ ╰──────────────────╯ # JSON output {"schemaVersion":1,"ok":true,"data":["# Launch plan","## Open questions"],"meta":{"truncated":false}} ``` ## `note properties` List parsed frontmatter properties for one note. This is the note-scoped equivalent of `property list`. ```bash octarine note properties Projects/Launch.md ``` ```text ╭────────┬───────────────────╮ │ Field ┆ Value │ ╞════════╪═══════════════════╡ │ status ┆ active │ │ tags ┆ [project, launch] │ ╰────────┴───────────────────╯ ``` ## `note task list` List Markdown tasks in one note. Returned task IDs are line-oriented identifiers used by `note task set`. ```bash octarine note task list Projects/Launch.md octarine note task list Projects/Launch.md --json ``` ```text # Table output ╭─────────┬────┬──────┬────────────────────╮ │ checked ┆ id ┆ line ┆ text │ ╞═════════╪════╪══════╪════════════════════╡ │ false ┆ 12 ┆ 12 ┆ Announce release │ │ true ┆ 13 ┆ 13 ┆ Prepare screenshots│ ╰─────────┴────┴──────┴────────────────────╯ # JSON output {"schemaVersion":1,"ok":true,"data":[{"id":12,"line":12,"checked":false,"text":"Announce release"},{"id":13,"line":13,"checked":true,"text":"Prepare screenshots"}],"meta":{"truncated":false}} ``` ## `note task set` Set a task to `open`/`todo` or `done`/`closed`. A revision can guard the edit. ```text octarine note task set [--revision ] ``` ```bash octarine note task set Projects/Launch.md 12 done octarine note task set Projects/Launch.md 12 open --revision 'sha256:' ``` ```text ╭──────────┬────────────────────────────────────────────╮ │ Field ┆ Value │ ╞══════════╪════════════════════════════════════════════╡ │ content ┆ # Launch plan\n…\n- [ ] Announce release │ │ path ┆ Projects/Launch.md │ │ revision ┆ sha256:5b93… │ ╰──────────┴────────────────────────────────────────────╯ ``` ## `note trash` Move a note to the operating system trash instead of deleting it permanently. ```bash octarine note trash Drafts/Abandoned.md ``` ```text ╭─────────┬─────────────────────╮ │ Field ┆ Value │ ╞═════════╪═════════════════════╡ │ trashed ┆ Drafts/Abandoned.md │ ╰─────────┴─────────────────────╯ ``` ## `note list` List all notes, or only notes below a folder. ```text octarine note list [folder] [--sort ] [--reverse] [--limit ] [--long] [--include-internal] ``` ```bash octarine note list octarine note list Projects octarine note list Projects --format jsonl octarine note list --sort modified --limit 2 ``` ```text # All notes ╭─────────────────────────────╮ │ Value │ ╞═════════════════════════════╡ │ Home.md │ │ Projects/Launch.md │ │ Projects/Release-notes.md │ ╰─────────────────────────────╯ # Notes below Projects ╭─────────────────────────────╮ │ Value │ ╞═════════════════════════════╡ │ Projects/Launch.md │ │ Projects/Release-notes.md │ ╰─────────────────────────────╯ # JSONL output "Projects/Launch.md" "Projects/Release-notes.md" # Two most recently modified notes ╭───────────────┬───────────┬───────────────┬────────┬────────────────────┬───────────╮ │ created ┆ extension ┆ modified ┆ name ┆ path ┆ sizeBytes │ ╞═══════════════╪═══════════╪═══════════════╪════════╪════════════════════╪═══════════╡ │ 1767225600000 ┆ md ┆ 1767312000000 ┆ Launch ┆ Projects/Launch.md ┆ 428 │ │ 1767139200000 ┆ md ┆ 1767225600000 ┆ Home ┆ Home.md ┆ 68 │ ╰───────────────┴───────────┴───────────────┴────────┴────────────────────┴───────────╯ ``` `--sort modified` and `--sort created` list the newest notes first; `--reverse` flips any sort order. `--long` adds size and timestamps, and is implied by `--sort`. Octarine's internal notes, such as Inbox items, are hidden unless you pass `--include-internal`.