wanote-cli (Command: notes)

A fast, zero-dependency, cross-platform command-line tool for keeping plain .txt notes — one file per note title. Designed for developers, writers, and terminal enthusiasts who want a clean, instant, distraction-free note-taking workflow on Windows, macOS, and Linux.

Table of Contents

• 1. What This Is
• 2. Installing Node.js
• 3. Installing wanote-cli
  • Install from npm
  • Install from Local Source
• 4. Verifying the Installation
• 5. First-Run Walkthrough
• 6. Command Reference & Examples
  • Create a Note (notes -a / notes add)
  • Append to a Note (notes -a <title> --append)
  • Show / View a Note (notes -s / notes show)
  • List Notes (notes -l / notes list)
  • Delete a Note (notes -d / notes delete)
  • Change Notes Storage Folder (notes -p / notes path)
• 7. Where Data Lives
• 8. Uninstalling
• 9. Publishing & Updating on npm
• 10. Troubleshooting

1. What This Is

wanote-cli (command notes) is a minimalist, local-first note-taking tool that saves each note as a standalone .txt file inside a folder of your choice. It requires zero external npm dependencies, relying entirely on Node.js built-ins (fs, path, os), starts instantly, and works seamlessly with terminal redirection, pipes, and interactive prompts.

2. Installing Node.js

wanote-cli requires Node.js (version 16.0.0 or later). If you don't have Node.js installed yet, follow the instructions below for your operating system:

Windows

1. Download the LTS (Long Term Support) installer from nodejs.org.
2. Run the .msi setup wizard and accept the defaults (ensure the "Add to PATH" option is checked).
3. Open a new Command Prompt or PowerShell terminal and verify:

   node --version
   npm --version

macOS

• Using the official installer: Download and run the macOS .pkg installer from nodejs.org.
• Using Homebrew (recommended):

  brew install node

• Verify the installation:

  node -v
  npm -v

Linux

• Ubuntu / Debian:

  sudo apt update
  sudo apt install -y nodejs npm

• Fedora / RHEL:

  sudo dnf install -y nodejs npm

• Arch Linux:

  sudo pacman -S nodejs npm

• Verify:

  node -v
  npm -v

3. Installing wanote-cli

Install from npm (Recommended after publishing)

Once published to the npm registry, install wanote-cli globally:

npm install -g wanote-cli

Install from Local Source

To install and test directly from this project repository:

1. Open your terminal in the project directory:

   cd path/to/notes-cli

2. Install the package globally onto your system:

   npm install -g .

4. Verifying the Installation

After installing, verify that the notes command is accessible from any directory:

notes

You should see the help summary:

notes-cli - A zero-dependency, plain-text notes manager

Usage:
  notes -a <title> [--append]    Write/add a note (Ctrl+D to save)
  notes -s <title>               Print/show a note
  notes -d <title>               Delete/remove a note with confirmation
  notes -l                       List all note titles in the notes folder
  notes -p [folder]              View or change storage folder

Commands & Aliases:
  -a, add <title> [--append]     Write a new note (use --append to add text)
  -s, show <title>               Print a note (aliases: view, read)
  -d, delete <title>             Delete a note (aliases: rm, remove)
  -l, list                       List all notes (alias: ls)
  -p, path [folder]              Change/set the notes storage folder

Options:
  -h, --help                     Show this help message
  -v, --version                  Show version number

5. First-Run Walkthrough

The very first time you execute any action (such as notes list or notes add), notes checks whether a storage folder has been configured.

If it hasn't, it will prompt you interactively:

$ notes list
Where should notes be stored? [C:\Users\Josuan\Notes]: 

• Press Enter to accept the default location (<home>/Notes).
• Or type any custom directory path (e.g. C:\Users\Josuan\Documents\Notes or ~/Dropbox/Notes) and press Enter.

notes creates the folder automatically, saves your preference in ~/.config/notes-cli/config.json, and will never ask you again.

6. Command Reference & Examples

Create a Note: notes -a <title> (or notes add <title>)

Write a new note. You can enter multi-line text and finish with Ctrl+D (on macOS/Linux) or Ctrl+Z followed by Enter (on Windows).

Interactive Example:

$ notes -a shopping-list
Enter note content (Ctrl+D to finish):
- Organic eggs
- Sourdough bread
- Whole milk
- Colombian coffee
^D
Note 'shopping-list' saved.

Overwrite Protection:

If a note already exists and you run notes -a without --append, it prompts before overwriting:

$ notes -a shopping-list
'shopping-list' already exists. Overwrite? [y/N]: n
Cancelled.

Piped / Scripted Input:

You can also pipe content directly into notes -a:

# macOS / Linux / Git Bash
echo "Call doctor at 3pm" | notes -a reminder

# Windows PowerShell
"Call doctor at 3pm" | notes -a reminder

Append to a Note: notes -a <title> --append (or notes add <title> --append)

Adds additional text to the end of an existing note without overwriting previous content. If the note does not exist yet, it creates it.

Example:

$ notes -a shopping-list --append
Enter text to append to 'shopping-list' (Ctrl+D to finish):
- Dark chocolate
^D
Note 'shopping-list' updated.

Show / View a Note: notes -s <title> (or notes show <title>)

Prints the note with an underline matching the title's character length, and indents every line of content by 4 spaces.

Aliases: notes show <title>, notes view <title>, notes read <title>.

Example:

$ notes -s shopping-list
shopping-list
-------------
    - Organic eggs
    - Sourdough bread
    - Whole milk
    - Colombian coffee
    - Dark chocolate

Intelligent Suggestions:

If the exact title is not found, notes -s searches for partial case-insensitive matches and suggests them:

$ notes -s shop
Note 'shop' not found.

Did you mean:
  - shopping-list

List Notes: notes -l (or notes list)

Lists the configured storage folder path and all existing notes formatted as bullets.

Aliases: notes list, notes ls.

Example:

$ notes -l
Notes folder: C:\Users\Josuan\Notes
  - meeting-notes
  - project-ideas
  - shopping-list

If no notes exist yet:

$ notes -l
Notes folder: C:\Users\Josuan\Notes
No notes found.

Delete a Note: notes -d <title> (or notes delete <title>)

Deletes a note file after asking for confirmation ([y/N]).

Aliases: notes delete <title>, notes rm <title>, notes remove <title>.

Declined Example:

$ notes -d shopping-list
Delete note 'shopping-list'? [y/N]: n
Cancelled.

Confirmed Example:

$ notes -d shopping-list
Delete note 'shopping-list'? [y/N]: y
Note 'shopping-list' deleted.

Change Notes Storage Folder: notes -p [folder] (or notes path [folder])

Displays the current folder or switches storage to a new location (creating the target folder if needed). Existing files remain in their old directory, and all future reads/writes use the new location.

View Current Path:

$ notes -p
Current notes folder: C:\Users\Josuan\Notes

Change Path:

$ notes -p C:\Users\Josuan\Documents\MyNotes
Notes folder set to: C:\Users\Josuan\Documents\MyNotes

7. Where Data Lives

notes strictly separates the configuration file from your notes files:

Configuration File (Fixed Location)

The configuration is always stored at <home>/.config/notes-cli/config.json:

• Windows: C:\Users\<username>\.config\notes-cli\config.json
• macOS: /Users/<username>/.config/notes-cli/config.json
• Linux: /home/<username>/.config/notes-cli/config.json

This file contains a single JSON key:

{
  "notes_path": "C:\\Users\\Josuan\\Notes"
}

Notes Folder (Flexible)

• Default: <home>/Notes
• Can be set to any directory on your computer, external drive, or cloud sync folder (e.g. Dropbox, Google Drive, iCloud, OneDrive) using notes path <folder>.

8. Uninstalling

Remove the CLI Command

npm uninstall -g wanote-cli

(Or if installed locally from source: npm uninstall -g . inside the project folder).

Clean Up Data Files (Optional)

If you wish to remove all settings and notes:

• Windows (PowerShell):

  Remove-Item -Recurse -Force "$env:USERPROFILE\.config\notes-cli"
  Remove-Item -Recurse -Force "$env:USERPROFILE\Notes"

• macOS / Linux:

  rm -rf ~/.config/notes-cli
  rm -rf ~/Notes

9. Publishing & Updating on npm

Publishing to npmjs.com

1. Log in to your npm account:

   npm login

2. Verify package files with a dry run:

   npm pack --dry-run

3. Publish to the registry:

   npm publish

Releasing Updates

To publish bug fixes or new features:

# Bump version (e.g., 1.0.0 -> 1.0.1)
npm version patch

# Publish new version
npm publish

Users can update to your latest release anytime via:

npm update -g wanote-cli

10. Troubleshooting

1. notes: command not found after installing

• Cause: npm's global binaries directory is not in your system PATH.
• Fix (Windows): Ensure C:\Users\<username>\AppData\Roaming\npm is listed in your User Path environment variable. Restart your terminal after updating PATH.
• Fix (macOS / Linux): Add npm global bin to your shell profile (~/.zshrc or ~/.bashrc):

  export PATH="$(npm config get prefix)/bin:$PATH"

2. EACCES / Permission errors during global install

• Cause: Global npm directory requires administrator / root privileges.
• Fix: Avoid running sudo npm install -g. Instead, configure npm to use a directory in your home folder:

  mkdir -p ~/.npm-global
  npm config set prefix '~/.npm-global'
  export PATH=~/.npm-global/bin:$PATH

  Or use a Node version manager like nvm or fnm.

3. Resetting Corrupted Configuration

If config.json becomes corrupted or you want to trigger the initial setup prompt again, simply delete the config file:

# Windows PowerShell
Remove-Item "$env:USERPROFILE\.config\notes-cli\config.json"

# macOS / Linux
rm ~/.config/notes-cli/config.json

The next time you run notes, it will prompt for the storage folder.

License

MIT © Josuan