Home CLI Docs
v1.5.0 · Node ≥ 18 · zero deps

NoteFlow CLI

A standalone Node.js command-line companion for the NoteFlow desktop app. Reads and writes the same notes directory as the GUI — use it over SSH, from cron, on a Raspberry Pi, or as a tool for AI agents.

install.sh 
curl -fsSL https://raw.githubusercontent.com/yagoid/noteflow/main/cli/install-cli.sh | sudo bash

Installs noteflow to /usr/local/bin. No GUI needed. Works on Debian, Ubuntu, Raspberry Pi OS.

bash 
sudo apt install ./noteflow_1.5.0_amd64.deb

Installing the .deb from Releases automatically symlinks the CLI to /usr/local/bin/noteflow. No extra steps.

PowerShell 
.\NoteFlow-1.5.0-Setup.exe

The Windows installer adds the CLI directory to your user PATH. Open a new terminal and run noteflow help.

Installation

NoteFlow CLI is a single Node.js script (cli/noteflow.js) with zero npm dependencies. It only requires Node.js 18 or later.

Linux headless / Raspberry Pi

bash 
curl -fsSL https://raw.githubusercontent.com/yagoid/noteflow/main/cli/install-cli.sh | sudo bash

Linux desktop & Windows

The CLI is bundled with the .deb and .exe installers. No extra steps — open a terminal after installing the app and run noteflow help.

Requirement: Node.js ≥ 18. Verify with node --version. The CLI does not bundle a Node runtime; on headless systems, install it with sudo apt install nodejs.

Integration with AI agents

AI Agent Skill

Install the NoteFlow skill directly into your AI agent (Claude Code, Cursor, etc.) with a single command:

bash 
npx skills add yagoid/noteflow/cli/noteflow-cli
Once installed, your agent can read, create, and update notes using natural language — no manual CLI commands needed. The skill definition (cli/noteflow-cli/SKILL.md) is also available in the repository for manual installation.

Typical agent flow

Every read command supports --json for machine-readable output. stdout carries data, stderr carries errors, exit code is 0 on success and 1 on failure — a standard Unix contract that plays well with shell pipelines, cron jobs, and LLM tool-use loops.

typical agent flow 
# 1. Survey what notes exist
noteflow list --json

# 2. Read a full note with all its sections
noteflow get "title" --json

# 3. Append information to a specific section
noteflow add "new content" --title "title" --section "Section"

# 4. Sync
noteflow push

Notes directory

The CLI reads and writes the exact same directory as the desktop app:

PlatformPath
Linux~/.local/share/noteflow-notes/
Windows / macOS~/noteflow-notes/

Changes made from the CLI are picked up live by any running desktop instance — and vice-versa.

Note format

Each note is a plain Markdown file with a YAML frontmatter header:

31-03-2026.md 
---
id: "abc12345"
title: "31-03-2026"
tags: ["urgent", "backend"]
created: "2026-03-31T10:00:00.000Z"
updated: "2026-03-31T10:05:00.000Z"
sections:
  - id: "sec001"
    name: "Note"
    content: "texto aquí"
    isRawMode: true
  - id: "sec002"
    name: "Tasks"
    content: "- [ ] tarea pendiente"
    isRawMode: true
---
texto aquí
  • The body after --- is always the first section's content (for readability outside the app).
  • isRawMode: true = Markdown/raw mode. false = rich text (TipTap HTML).
  • Notes with encryption: in the frontmatter are ignored by the CLI — they can only be decrypted in the desktop app.

Commands

All commands take the form noteflow <command> [args] [flags]. Run noteflow help <command> for detailed per-command help.

add — Append text to a note

Appends text to today's daily note (title DD-MM-YYYY). Creates the note if it doesn't exist.

bash 
noteflow add "Fix: CORS on /api/notes"
noteflow add "Review server logs" --section "Tasks" --tag urgent
noteflow add "Client meeting" --title "Project Alpha" --section "Meetings"
noteflow add "new feature" --group backend
FlagDescription
--title <title>Write to a note with that title instead of today's
--section <name>Target section / tab. Created if missing. Default: Note
--tag <tag>Add this metadata tag to the note
--group <name>Assign the note to a group (only on creation)
--richCreate the new section in rich-text mode

new — Create an empty note

bash 
noteflow new "Project Alpha"
noteflow new "Sprint 14" --group backend --section "Planning"
noteflow new "My note" --json

list — List notes

Shows notes sorted by updated desc. Archived notes are excluded by default.

bash 
noteflow list
noteflow list --group backend
noteflow list --tag urgent --json
noteflow list --archived

get — View a note's content

Title can be partial — if multiple notes match, the CLI lists them and asks you to be more specific.

bash 
noteflow get "Project Alpha"
noteflow get "Project Alpha" --section Tasks
noteflow get "31-03" --json

sections — List sections of a note

bash 
noteflow sections "Project Alpha"
# Sections of "Project Alpha":
#   Note   (3 lines, raw/markdown)
#   Tasks  (5 lines, raw/markdown)

delete — Delete a note

Asks for confirmation unless --yes is passed. If GitHub sync is connected, the note is also removed from the remote repository.

bash 
noteflow delete "Temporary draft" --yes

rename — Rename a note

Updates the title field in the frontmatter. The filename (which contains the note id) is unchanged.

bash 
noteflow rename "Meeting" "Client meeting — Q2"

pin — Pin or unpin

Toggle: if the note is pinned it becomes unpinned, and vice-versa. Pinned notes appear at the top of the sidebar in the desktop app.

bash 
noteflow pin "Project Alpha"

archive — Archive or unarchive

Toggle the archived state. Archived notes are hidden from list unless --archived is passed.

bash 
noteflow archive "Old draft"

Groups

Groups are color-coded categories shown in the desktop app sidebar. Every note can belong to one group.

bash 
noteflow groups                              # list groups
noteflow group create backend --color cyan   # create a group
noteflow group create "Client projects" --color orange
noteflow group delete backend --yes          # delete (notes are kept, just unassigned)

Available colors: accent, accent-2, red, cyan, purple, text, orange, pink.

GitHub sync

The CLI uses the same Device Flow OAuth mechanism as the desktop app — no personal access tokens, no secrets in config files. Because the desktop app encrypts its token with Electron's safeStorage, the CLI needs its own separate login.

login — Connect to GitHub

bash 
noteflow login                        # default repo: noteflow-notes
noteflow login my-private-notes       # custom repo name

Displays a one-time code and a URL. On a headless system, open the URL from another device to complete authorization.

logout / push / pull / status

bash 
noteflow push      # upload all notes to the remote repo
noteflow pull      # download notes (only overwrites if remote is newer)
noteflow update    # alias for pull
noteflow status    # current sync state
noteflow logout    # disconnect

self-update

Downloads the latest cli/noteflow.js from GitHub and replaces the current script in place. Useful on headless Raspberry Pi systems where there's no installer to run. Does not require being logged in to GitHub sync.

bash 
noteflow self-update
# Checking for updates...
# Updated successfully → /usr/local/bin/noteflow

Global flags

FlagApplies toDescription
--jsonlist, get, new, groups, statusMachine-readable JSON output
--yesdelete, group deleteSkip interactive confirmation
--archivedlistInclude archived notes

Troubleshooting

  • "command not found" after .deb install: open a new terminal. The post-install script creates the symlink, but running shells don't reload PATH.
  • CLI can't read the app's GitHub token: expected. The desktop app encrypts its token with Electron safeStorage, which the CLI cannot decrypt. Run noteflow login separately.
  • Encrypted notes don't show up in list: by design. The CLI cannot decrypt them; use the desktop app.
  • Auto-sync conflicts: the desktop app syncs every 5 minutes. If it runs at the same time as CLI operations and both are connected to the same repo, the last writer wins — same as git.