Notezbeta
Back to blog

Getting Started With the Notez CLI

terminalDenis Povarov

The Notez CLI is a 3 MB native binary that captures notes from your shell. No Node runtime, no daemon, no configuration file to write by hand — you install it, authorize the terminal once, and from then on notez "your thought" lands the thought in your workspace. It runs on macOS, Linux, and Windows.

This guide walks through installation, first-time setup, and the handful of flags worth knowing.

Installing

On macOS or Linux:

sh 
curl -fsSL https://notez.dev/install.sh | sh

The script downloads the latest binary for your platform, verifies its SHA256 checksum, and places notez in /usr/local/bin (falling back to ~/.local/bin if that is not writable).

On Windows, in PowerShell:

powershell 
iwr -useb https://notez.dev/install.ps1 | iex

This installs into %LOCALAPPDATA%\Programs\notez and adds it to your user PATH.

If you would rather not pipe a script into your shell — a reasonable instinct — the binaries are served directly from https://notez.dev/downloads/cli/ for macOS (arm64 and x64), Linux (x64 and arm64), and Windows, each with a sibling .sha256 file for manual verification. Extract the archive and put notez anywhere on your $PATH.

One macOS note: if you download the tarball through a browser instead of curl, Gatekeeper quarantines it. Clear the attribute once with xattr -d com.apple.quarantine /path/to/notez.

Authorizing your terminal

Bash 
notez login

This opens your browser to notez.dev/cli-auth, where you pick a workspace you own and approve the terminal; only a workspace's owner can set up the CLI for it. A long-lived API key, scoped to that one workspace and limited to creating notes and uploading files, is generated and stored locally:

  • macOS: ~/Library/Application Support/notez/config.toml

  • Linux: ~/.config/notez/config.toml

  • Windows: %APPDATA%\notez\config.toml

You can revoke the key at any time in Settings → Integrations → Notez CLI — useful if a laptop is lost or a shared machine should no longer have access. notez logout forgets the key locally.

Capturing notes

The dominant path is one command:

Bash 
notez "retry storm happens when the circuit breaker resets too early"

The text becomes a note in your workspace, searchable immediately. A few variations cover the rest of daily use:

Bash 
# Pipe output into a note
grep -c ERROR app.log | notez

# Give the note an explicit title (otherwise the text is used)
notez --title "Incident 2026-08-30" "db failover took 40s, alarms fired late"

# Capture a URL — auto-detected and stored as a bookmark
notez "https://docs.anthropic.com/quickstart"

# Upload a file — a path that exists is detected and uploaded
notez ./architecture-diagram.png

The pipe form deserves emphasis. Anything your shell can produce — a failing test's output, a stack trace, the flag combination that finally worked — can be captured at the moment it is on screen, without selecting text or switching windows.

Scripting with --json

notez --json "..." prints the created note as JSON, which makes the CLI composable. A couple of practical patterns:

Bash 
# Capture and keep the note id for later reference
NOTE_ID=$(notez --json "deploy checklist for v2.3" | jq -r .id)

# A git hook that logs every release
notez "released $(git describe --tags) to production"

Because it is a single fast binary, the CLI is comfortable in places heavier tools are not: inside CI jobs, on remote servers over SSH, in a tmux pane you keep open next to your editor.

Where the notes go

Everything the CLI captures lands in the same vault as your other Notez surfaces — the web dashboard, the notez.dev/your thought URL-bar capture, and any AI tools connected over MCP. In the web app you can browse and search the captures, add tags, link them to other notes, or promote a raw capture into a structured document with the full editor.

Notez's search works by meaning, not just keywords, so a terse capture like notez "cursor pagination beats offset for big tables" is findable later by searching "pagination performance" — even though you never tagged or filed it.

A workflow that sticks

The habit that makes the CLI pay off is lowering your bar for what deserves a note. With a notes app that takes twenty seconds to reach, only important thoughts clear the bar, and most of the small ones — the workaround, the flag, the half-formed idea — evaporate. With capture at two seconds, everything clears it.

A few habits worth stealing:

  • Capture the fix, not just the bug. The moment something finally works, notez "..." the reason. Future you, facing the same error, will search for it.

  • Log decisions as they happen. One line about why you chose approach A over B beats reconstructing it in a design doc review later.

  • Pipe, don't paste. If it is already in your terminal, | notez is faster and more accurate than copy-paste into a GUI.

Troubleshooting

If notez login reports that it could not reach the CLI on your machine, the authorization handshake likely timed out — run notez login again. If a key stops working, check Settings → Integrations → Notez CLI: revoking a terminal there disables it immediately, and re-running notez login on that machine issues a fresh key.

That is the whole tool. notez --help lists everything, notez update installs the latest version in place, but the honest summary is: one command, your thought, done.

Continue reading