Command line interface

Notesium is, at its core, a Command Line Interface (CLI) tool. It provides several key functions, including indexing, querying, an interactive finder, and an optional web server with a REST API.

You can use the CLI directly or in scripts, or let the Web interface and Vim plugin call it behind the scenes. In all cases, the CLI is required and does the heavy lifting.

If you’re just getting started, follow the Quickstart guide.

Usage

$ notesium help
Usage: notesium COMMAND [OPTIONS]

Commands:
  home              Print path to notes directory
  new               Print path for a new note
    --verbose       Output key:value pairs of related info
    --ctime=        Use specified ctime instead of now (YYYY-MM-DDThh:mm:ss)
  list              Print list of notes
    --color         Color code prefix using ansi escape sequences
    --labels        Limit list to only label notes (ie. one word title)
    --orphans       Limit list to notes without outgoing or incoming links
    --sort=WORD     Sort list by date or alphabetically (ctime|mtime|alpha)
    --prefix=WORD   Prefix title with date or linked label (ctime|mtime|label)
    --date=FORMAT   Date format for ctime/mtime prefix (default: 2006-01-02)
  links [filename]  Print list of links
    --color         Color code using ansi escape sequences
    --outgoing      Limit list to outgoing links related to filename
    --incoming      Limit list to incoming links related to filename
    --dangling      Limit list to broken links
  lines             Print all lines of notes (ie. fulltext search)
    --color         Color code prefix using ansi escape sequences
    --prefix=title  Prefix each line with note title
    --filter=QUERY  Filter lines by query: AND (space), OR (|), NOT (!)
  stats             Print statistics
    --color         Color code using ansi escape sequences
    --table         Format as table with whitespace delimited columns
  finder            Start finder (interactive filter selection TUI)
    --preview       Display note preview (toggle with ctrl-/)
    --prompt=STR    Set custom prompt text
    -- CMD [OPTS]   Input (default: list --color --prefix=label --sort=alpha)
  web               Start web server
    --webroot=PATH  Path to web root to serve (default: embedded webroot)
    --mount=DIR:URI Additional directory to serve under webroot (experimental)
    --open-browser  Launch default web browser with web server URL
    --stop-on-idle  Automatically stop when no activity is detected
    --port=INT      Port for web server to listen on (default: random)
    --no-check      Disable daily new version checks
    --writable      Allow writing of notes in NOTESIUM_DIR via API
  extract [path]    Print list of embedded files or contents of file path
  version           Print version
    --verbose       Output key:value pairs of related info
    --check         Check if a newer version is available

Environment:
  NOTESIUM_DIR      Path to notes directory (default: $HOME/notes)

Shell completion

Bash completion is available for all notesium commands and option flags. Add the following line to your $HOME/.bashrc or similar location.

command -v notesium >/dev/null && source <(notesium extract completion.bash)

Commands

home

The home command will print the path of the notes directory, which is controlled by the NOTESIUM_DIR environment variable (default: $HOME/notes).

Usage

home              Print path to notes directory

Examples

$ notesium home
/Users/user/notes

$ git clone https://github.com/alonswartz/notesium.git /tmp/notesium
$ export NOTESIUM_DIR="/tmp/notesium/tests/fixtures"
$ notesium home
/private/tmp/notesium/tests/fixtures

new

The new command prints the full path for a new note, but does not create it.

Notesium filenames are derived from the note’s creation time (ctime). This ensures each note has a unique and deterministic filename. The current time is used by default, but can be specified using the --ctime flag when needed (e.g. when backfilling past notes, or following a convention such as periodic notes).

Usage

new               Print path for a new note
  --verbose       Output key:value pairs of related info
  --ctime=        Use specified ctime instead of now (YYYY-MM-DDThh:mm:ss)

Examples

$ notesium new
/private/tmp/notesium/tests/fixtures/68f74e14.md

$ notesium new --verbose
path:/private/tmp/notesium/tests/fixtures/68f74e20.md
filename:68f74e20.md
epoch:1761037856
ctime:2025-10-21T12:10:56+03:00
exists:false

list

The list command will print a list of notes, depending on the supplied option flags.

Usage

list              Print list of notes
  --color         Color code prefix using ansi escape sequences
  --labels        Limit list to only label notes (ie. one word title)
  --orphans       Limit list to notes without outgoing or incoming links
  --sort=WORD     Sort list by date or alphabetically (ctime|mtime|alpha)
  --prefix=WORD   Prefix title with date or linked label (ctime|mtime|label)
  --date=FORMAT   Date format for ctime/mtime prefix (default: 2006-01-02)

Examples

$ notesium list --prefix=label --sort=alpha --color
64218087.md:1: «book» surely you're joking mr. feynman
64218088.md:1: «physicist» albert einstein
64214a1d.md:1: «physicist» richard feynman
6421460b.md:1: book
64217712.md:1: empty note
642176a6.md:1: lorem ipsum
642146c7.md:1: physicist
64214930.md:1: quantum mechanics

$ notesium list --prefix=ctime --sort=ctime --date=15:04 --color
64218088.md:1: «14:39» albert einstein
64218087.md:1: «14:39» surely you're joking mr. feynman
64217712.md:1: «13:59» empty note
642176a6.md:1: «13:57» lorem ipsum
64214a1d.md:1: «10:47» richard feynman
64214930.md:1: «10:43» quantum mechanics
642146c7.md:1: «10:33» physicist
6421460b.md:1: «10:30» book

Date Format

Notesium uses the Golang time.Format, and a few experimental extras:

Format string	Description	Example output
`2006-01-02`	Year-Month-Day (ISO style)	`2025-10-23`
`2006/01/02`	Slashed date	`2025/10/23`
`2006-01`	Year-Month	`2025-10`
`02 Jan 2006`	Day + short month + year	`23 Oct 2025`
`January 2, 2006`	Long month, Day, Year	`October 23, 2025`
`Mon Jan 2`	Weekday, short month, day	`Thu Oct 23`
`15:04`	24h time (HH:MM)	`12:34`
`03:04 PM`	12h time with AM/PM	`12:34 PM`
`15:04:05`	24h time with seconds	`12:34:56`
`2006-01-02 15:04`	Date + time	`2025-10-23 12:34`
`2006-01-02T15:04:05-07:00`	ISO-8601 style	`2025-10-23T12:34:56+03:00`
`Mon, 02 Jan 2006`	RFC-1123 style	`Thu, 23 Oct 2025`
`2006-01-02 15:04:05.000`	Milliseconds	`2025-10-23 12:34:56.789`
`2006/Week%V` (experimental)	ISO week number (Mon = first day)	`2025/Week43`
`2006/Week%U` (experimental)	Week number (Sun = first day)	`2025/Week43`

links

The links command will print a list of links, depending on the supplied option flags. The output includes the line number where the link was defined.

Usage

links [filename]  Print list of links
  --color         Color code using ansi escape sequences
  --outgoing      Limit list to outgoing links related to filename
  --incoming      Limit list to incoming links related to filename
  --dangling      Limit list to broken links

Examples

$ notesium links --color
64218088.md:3: «albert einstein» → physicist
64218088.md:7: «albert einstein» → quantum mechanics
64214a1d.md:3: «richard feynman» → physicist
64214a1d.md:5: «richard feynman» → quantum mechanics
64218087.md:3: «surely you're joking mr. feynman» → book
64218087.md:3: «surely you're joking mr. feynman» → richard feynman
64218087.md:3: «surely you're joking mr. feynman» → 12345678.md

$ notesium links 64214a1d.md --color
642146c7.md:1: «outgoing» physicist
64214930.md:1: «outgoing» quantum mechanics
64218087.md:3: «incoming» surely you're joking mr. feynman

$ notesium links --dangling --color
64218087.md:3: «surely you're joking mr. feynman» → 12345678.md

lines

The lines command will print all lines of all notes, unless a filter query is specified. This is what the Vim Plugin and Web interface use when performing a full-text search.

Usage

lines             Print all lines of notes (ie. fulltext search)
  --color         Color code prefix using ansi escape sequences
  --prefix=title  Prefix each line with note title
  --filter=QUERY  Filter lines by query: AND (space), OR (|), NOT (!)

Examples

$ notesium lines | grep 64218088.md: | head -4
64218088.md:1: # albert einstein
64218088.md:3: albert einstein was a german-born theoretical [physicist](642146c7.md),
64218088.md:4: widely acknowledged to be one of the greatest and most influential
64218088.md:5: physicists of all time. einstein is best known for developing the

$ notesium lines --prefix=title --color --filter="german|quantum"
64214930.md:1: «quantum mechanics» # quantum mechanics
64214a1d.md:5: «richard feynman» [quantum mechanics](64214930.md), the theory of quantum electrodynamics,
64218088.md:3: «albert einstein» albert einstein was a german-born theoretical [physicist](642146c7.md),
64218088.md:7: «albert einstein» to the development of the theory of [quantum mechanics](64214930.md).

stats

The stats command will print counts of notes, labels, orphans, links, lines, words, etc.

Usage

stats             Print statistics
  --color         Color code using ansi escape sequences
  --table         Format as table with whitespace delimited columns

Examples

$ notesium stats --table --color
«notes    » 8
«labels   » 2
«orphans  » 2
«links    » 7
«dangling » 1
«lines    » 28
«words    » 213
«chars    » 1396

finder

The finder command starts the built-in interactive filtering and selection tool powered by the fzf engine. It enhances the CLI with flexible input handling and syntax-highlighted previews, making it easier to search and navigate notes efficiently.

The Vim plugin integrates with the Finder for a seamless workflow. Other tools can leverage it as well.

It was introduced in Notesium v0-6-4.

Usage

finder            Start finder (interactive filter selection TUI)
  --preview       Display note preview (toggle with ctrl-/)
  --prompt=STR    Set custom prompt text
  -- CMD [OPTS]   Input (default: list --color --prefix=label --sort=alpha)

Examples

$ notesium finder

$ notesium finder --preview --prompt=NotesiumLinks -- links --color

Supported Input CMDs

Command	Comment
list	Print list of notes
links	Print list of links
lines	Print all lines of notes (ie. fulltext search)

Keybindings

Binding	Comment
`C-j` `↓`	Select next entry (down)
`C-k` `↑`	Select previous entry (up)
`C-/`	Toggle preview
`Enter`	Submit selected entry
`Esc`	Dismiss finder

Search syntax

Token	Match Type	Comment
`word`	exact-match	Items that include `word`
`^word`	prefix exact-match	Items that start with `word`
`word$`	suffix exact-match	Items that end with `word`
`!word`	inverse exact-match	Items that do not include `word`
`!^word`	inverse prefix exact-match	Items that do not start with `word`
`!word$`	inverse suffix exact-match	Items that do not end with `word`
`foo bar`	multiple exact match (AND)	Items that include both `foo` AND `bar`
`foo \| bar`	multiple exact match (OR)	Items that include either `foo` OR `bar`
`'sbtrkt`	fuzzy-match	Items that fuzzy match `sbtrkt`

Themes

The NOTESIUM_FINDER_THEME environment variable controls the Finder theme. Supported values are dark (default) and light. The Vim plugin sets this automatically based on Vim’s &background setting when launching the Finder.

web

The web command starts a local web server, serving a web frontend (webroot) and the REST API.

The embedded webroot (default) is documented in Web interface.

Usage

web               Start web server
  --webroot=PATH  Path to web root to serve (default: embedded webroot)
  --mount=DIR:URI Additional directory to serve under webroot (experimental)
  --open-browser  Launch default web browser with web server URL
  --stop-on-idle  Automatically stop when no activity is detected
  --port=INT      Port for web server to listen on (default: random)
  --no-check      Disable daily new version checks
  --writable      Allow writing of notes in NOTESIUM_DIR via API

Examples

$ notesium web --writable --open-browser --port=8080
Serving on http://localhost:8080 (bind address 127.0.0.1)
Press Ctrl+C to stop

# https://github.com/alonswartz/notesium/tree/master/web/graph
$ notesium web --webroot="/tmp/notesium/web/graph" --stop-on-idle --open-browser

# https://github.com/alonswartz/notesium-gpt
# mounted along side the embedded webroot (http://localhost:8080/gpt/)
$ notesium web --mount="/tmp/notesium-gpt:/gpt/" --port=8080

extract

The extract command lists embedded files or prints the contents of a specified embedded file.

Usage

extract [path]    Print list of embedded files or contents of file path

Examples

$ notesium extract | head -3
completion.bash
web/app/alert.js
web/app/app.js

$ notesium extract completion.bash | head -3
__notesium_cmds() {
    notesium help 2>&1 | awk '/^  [a-z\-]/ {print $1}'
}

version

The version command will print the current Notesium version. It can also display detailed build information and optionally check whether a newer version is available.

Usage

version           Print version
  --verbose       Output key:value pairs of related info
  --check         Check if a newer version is available

Examples

$ notesium version
0.6.5

$ notesium version --check --verbose
Notesium 0.6.5 (darwin/arm64)
You are using the latest version

comparison:0
version:0.6.5
gitversion:v0.6.5-0-g200b05c
buildtime:2025-07-20T11:20:03Z
platform:darwin/arm64
latest.version:0.6.5
latest.published:2025-07-20T11:26:27Z
latest.release:https://github.com/alonswartz/notesium/releases/tag/v0.6.5

Environment

NOTESIUM_DIR

The NOTESIUM_DIR environment variable specifies the notes directory to use. By default, Notesium uses $HOME/notes. The home command prints the effective path in use.

Usage

NOTESIUM_DIR      Path to notes directory (default: $HOME/notes)

Examples

$ notesium home
/Users/user/notes

$ git clone https://github.com/alonswartz/notesium.git /tmp/notesium
$ export NOTESIUM_DIR="/tmp/notesium/tests/fixtures"
$ notesium home
/private/tmp/notesium/tests/fixtures

# Bash/Zsh
export NOTESIUM_DIR="$HOME/journal"

# Fish
set -x NOTESIUM_DIR "$HOME/journal"

# Powershell
$env:NOTESIUM_DIR = "$HOME\journal"

# Cmd.exe
set NOTESIUM_DIR=%USERPROFILE%\journal