note(s)

Two commands for keeping notes in a terminal.

note opens a blank note with the cursor already in it. notes shows what you have written. Notes are plain markdown files in ~/.notes/, so grep, git and rsync all work on them.

Install

cargo install --path .

Puts note and notes in ~/.cargo/bin.

Writing

Key
Ctrl+O	save
Ctrl+X	close, asks (Y/n) if there are unsaved changes
Ctrl+I	stamp the time on its own line
Ctrl+P	set the title
Ctrl+T	add tags
@	link to another note
Ctrl+G	open the link under the cursor
Esc	back to the note you came from
Ctrl+R	read the note rendered, and back again

Otherwise it behaves like any editor: arrows, Home/End, PgUp/PgDn, word wrap, Ctrl+Z to undo. A note you never type in is never written to disk.

Tags are ordinary #hashtags anywhere in the body. # Heading with a space is a heading, #tag without one is a tag.

Reading

Ctrl+R shows the note rendered, Ctrl+R again goes back to editing.

Browsing

↑↓ or jk to move, Enter to open, n for a new note, / to filter, d to delete, q to quit.

CREATED comes from the filename, MODIFIED from when you last saved.

Linking

Type @ and pick a note. It inserts a normal markdown link, and Ctrl+G opens it. Esc walks back, with the bar showing how deep you are.

bob@example.com types normally, since @ only opens the menu at the start of a word.

Filtering

Same syntax in the browser, the @ menu, and the shell. What you type says what you mean:

groc            titles containing "groc"
#shopping       tagged #shopping
#can            any tag starting "can"
#               anything tagged
2026            created in 2026
2026-07         created in July 2026
#shopping 2026  both have to match

From the shell

note 'buy milk'         # start a note with that title
note -f work standup    # start one in a folder
notes list              # numbered, newest first
notes list -n 5         # the five most recent
notes list '#canbus'    # or any filter from above
notes cat 2             # print note 2
notes path 2            # its path
notes mv 2 archive      # file a note into a folder
notes folders           # the folder tree
notes tags              # tags in use, most used first
note 2                  # open note 2

Numbers come from notes list and follow whatever filter you gave it. Colour is only used when stdout is a terminal.

Config

note --init-config

Writes ~/.config/notes/config.toml with every option commented out at its default. Colours, keybindings, where notes live, and the timestamp format. The file is optional and so is every line in it.

NOTES_DIR overrides the notes directory for one run, which is handy for keeping a set of notes per project.

Two terminal things

Ctrl+I and Tab are the same byte, so on most terminals Tab is what stamps the time. The hint line always shows the key that actually works. If your terminal speaks the kitty keyboard protocol they separate, and inside tmux that also needs set -s extended-keys on.

Nothing is bound to Ctrl+B by default, so tmux's prefix stays out of the way.

Building

cargo test
cargo clippy --all-targets -- -D warnings

One test is ignored by default because it needs a real terminal and panics on purpose. It checks that a panic still hands the terminal back:

cargo test --test panic_restore -- --ignored --nocapture

MIT.