Notes

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.

octarine note create <path> [--content <text> | --stdin | --file <file>]
  [--property <key=value>]... [--tag <tag>]... [--if-missing] [--unique]

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

# 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.

octarine note read <path> [--from-line <n>] [--to-line <n>]
  [--lines <start:end>] [--section <heading>]
  [--max-bytes <n>] [--max-chars <n>]
  [--body-only | --frontmatter-only]

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

# 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.

octarine note context <path> [--max-bytes <n>] [--no-content] [--backlinks-limit <n>]

octarine note context Projects/Launch.md --json
octarine note context Projects/Launch.md --no-content --backlinks-limit 10 --json

{"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.

octarine note info Projects/Launch.md
octarine note info Projects/Launch.md --json

# 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.

octarine note random
octarine note random --folder Projects

╭──────────┬──────────────────────╮
│ Field    ┆ Value                │
╞══════════╪══════════════════════╡
│ content  ┆ # Launch plan\n…    │
│ path     ┆ Projects/Launch.md   │
│ revision ┆ sha256:4f1c…         │
╰──────────┴──────────────────────╯

note wordcount

Count words and characters in one note.

octarine note wordcount Projects/Launch.md

╭────────────┬────────────────────╮
│ 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.

octarine note update <path> [--content <text> | --stdin] [--revision <revision>]

octarine note update Projects/Launch.md --content "# Revised launch plan"
cat revised.md | octarine note update Projects/Launch.md --stdin \
  --revision 'sha256:<revision-from-note-read>'

╭──────────┬────────────────────────╮
│ Field    ┆ Value                  │
╞══════════╪════════════════════════╡
│ content  ┆ # Revised launch plan │
│ path     ┆ Projects/Launch.md     │
│ revision ┆ sha256:bc20…           │
╰──────────┴────────────────────────╯

note append

Append content while optionally guarding the current revision.

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:<revision>'

╭──────────┬────────────────────────────────────────────╮
│ 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 instead, which places text below the frontmatter so the properties stay valid.

octarine note prepend Projects/Launch.md --content $'> Status: active\n\n'
printf '%s\n\n' '# Important' | octarine note prepend Projects/Launch.md --stdin

╭──────────┬────────────────────────────────────╮
│ 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:

╭──────────────────┬─────────────────────╮
│ 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.

octarine note edit <path> --find <text> [--replace <text> | --stdin] [--all] [--revision <revision>]

octarine note edit Projects/Launch.md \
  --find "Ship v2" \
  --replace "Ship v2 in November" \
  --revision 'sha256:<revision>'

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.

octarine note replace-section <path> <heading> [--content <text> | --stdin] [--revision <revision>]

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.

octarine note insert <path> [--content <text> | --stdin]
  [--heading <heading>] [--line <n>] [--at <start|end>] [--revision <revision>]

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.

octarine note patch <path> [--diff <text> | --file <file>] [--revision <revision>]

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:<revision>'

--- 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.

octarine note move <source> <destination> [--dry-run] [--no-update-links]

octarine note move Drafts/Launch.md Projects/Launch.md --dry-run
octarine note move Drafts/Launch.md Projects/Launch.md

╭──────────────┬─────────────────────╮
│ 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.

octarine note rename <source> <destination> [--dry-run] [--no-update-links]

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

# 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.

octarine note duplicate Projects/Launch.md Projects/Launch-template.md
octarine note duplicate Projects/Launch.md --unique

# 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.

octarine note outline Projects/Launch.md
octarine note outline Projects/Launch.md --json

# 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.

octarine note properties Projects/Launch.md

╭────────┬───────────────────╮
│ 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.

octarine note task list Projects/Launch.md
octarine note task list Projects/Launch.md --json

# 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.

octarine note task set <path> <id> <open|todo|done|closed> [--revision <revision>]

octarine note task set Projects/Launch.md 12 done
octarine note task set Projects/Launch.md 12 open --revision 'sha256:<revision>'

╭──────────┬────────────────────────────────────────────╮
│ 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.

octarine note trash Drafts/Abandoned.md

╭─────────┬─────────────────────╮
│ Field   ┆ Value               │
╞═════════╪═════════════════════╡
│ trashed ┆ Drafts/Abandoned.md │
╰─────────┴─────────────────────╯

note list

List all notes, or only notes below a folder.

octarine note list [folder] [--sort <name|modified|created|size>] [--reverse]
  [--limit <n>] [--long] [--include-internal]

octarine note list
octarine note list Projects
octarine note list Projects --format jsonl
octarine note list --sort modified --limit 2

# 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.