Notezbeta
Back to blog

How to Take Notes From the Terminal

terminalDenis Povarov

If you spend your day in a terminal, switching to a graphical notes app to write down a thought is a context switch you pay for twice: once to get there, and again to rebuild your focus when you come back. Taking notes directly from the command line removes both costs. This post covers the main approaches, from zero-dependency plain files to dedicated CLI tools, and when each one makes sense.

Why the terminal is a good place for notes

Three properties make the shell an unusually good capture surface:

  • You are already there. Mid-debug, mid-deploy, mid-code-review — the prompt is focused and waiting.

  • Output is text. Error messages, test failures, and command output can be piped straight into a note instead of screenshotted or retyped.

  • It works everywhere. Over SSH, inside tmux, on a CI box — anywhere a shell runs, your capture method runs.

The common failure mode of terminal note-taking is the opposite end: retrieval. Text files accumulate; finding the right line three months later is the hard part. Keep that trade-off in mind as you pick an approach.

Approach 1: a plain append-only file

The simplest system that works:

Bash 
echo "$(date +%F) - use SIGTERM not SIGKILL in the entrypoint" >> ~/notes.md

Wrap it in a shell function and it becomes a two-keystroke habit:

Bash 
note() { echo "$(date +%F) $*" >> ~/notes.md; }

Retrieval is grep -i keyword ~/notes.md. This costs nothing, syncs with whatever syncs your home directory, and never breaks.

Its limits appear with scale: one flat file has no structure, grep only finds exact words, and nothing follows you to a second machine unless you set up syncing yourself.

Approach 2: notes in your editor, launched from the shell

vim ~/notes/$(date +%F).md or a small script that opens today's daily note gives you a real editor and one file per day. Tools in this family (daily-note scripts, nb, journal CLIs) add just enough structure — dated files, sometimes tags — while staying local and scriptable.

This works well when notes are longer than one line. The cost is that opening an editor is no longer a two-second capture; it is a small task of its own, and over SSH your editor config may not be there.

Approach 3: a dedicated capture CLI backed by a synced vault

The third approach separates capture from storage: a small CLI whose only job is to take text from your shell and put it in a note system that handles search, sync, and organization elsewhere.

This is the model the Notez CLI uses. It is a 3 MB binary for macOS, Linux, and Windows; after a one-time notez login, capture is:

Bash 
notez "the flaky test is timezone-dependent — freeze the clock"
echo "worth keeping" | notez
notez --title "Postmortem notes" "timeline starts 14:02 UTC"

The notes land in a workspace you can also reach from a web app, so retrieval does not depend on grep: search works by meaning (searching "flaky tests" finds the timezone note), and captures can later be tagged, linked to other notes, or expanded in a full editor. URLs are auto-detected and saved as bookmarks, and --json output makes the CLI usable in scripts and git hooks.

The trade-off is the mirror image of plain files: you gain search, sync, and structure, and in exchange your notes live in a service rather than a single local file. If that matters to you, check for an exit path — Notez, for instance, exports a whole workspace as a .zip of Markdown files with their attachments, which is a reasonable bar to hold any tool to.

Patterns that work in any system

Whichever approach you choose, a few habits make terminal notes actually useful later:

Pipe, don't retype

The strongest argument for terminal capture is that the material is already text in front of you:

Bash 
./run-tests.sh 2>&1 | tail -20 | notez --title "auth test failure"

A note that contains the actual error output is worth ten that paraphrase it.

Capture resolutions, not just problems

The highest-value note in a developer's vault is "here is what fixed it." When something finally works, write down the cause in one line. Your future self will search for the error message and find the answer.

Timestamp implicitly, title sparingly

Let the tool record when a note was made. Titles are optional for quick captures — a note that took two seconds to write is a win even untitled, and meaning-based search does not need titles to find it.

Keep one inbox

Send all quick captures to one place and triage later (or never). The moment you make yourself choose a destination at capture time, you have reintroduced the friction you were trying to remove.

Choosing between the approaches

  • Plain file: you want zero dependencies and your notes are short-lived working memory.

  • Editor + dated files: your notes are longer-form and you live in one machine.

  • Capture CLI + synced vault: you capture often, from multiple machines, and retrieval matters as much as capture.

These also compose. Plenty of people keep a scratch file for ephemera and a synced vault for anything worth finding again. The only real rule is to make capture cheap enough that you actually do it — a note system you use daily beats an elaborate one you don't.

Continue reading