Nikki Mascot Logo Nikki
GitHub npm v1.1.0
Terminal-First Personal Knowledge & Reminder System

Think it. Type it.
Nikki remembers it.

Capture notes instantly from your shell, set natural-language reminders, and receive quiet desktop notifications via a local Linux daemon.

$ npm install -g nikki-cli
nikki-cli demo — zsh
Core Capabilities

Built for Terminal Speed & Frictionless Capture

Designed to stay out of your way while giving you instant memory recall.

Instant Note Capture

No opening heavy GUI apps. Just type nikki "your thought" directly from any directory in your shell.

Natural Language Dates

Set reminders naturally using -r "tomorrow 10am" or --at "in 2 hours" powered by chrono-node.

Background Daemon

Integrates with Linux systemd user services to send non-intrusive desktop notifications via notify-send.

Daily Overview

Run nikki today for a clean dashboard summary of notes written and due reminders for the day.

100% Local & Private

All data stays on your machine inside ~/.note/notes.db powered by high-performance SQLite WAL mode.

Uses Your $EDITOR

Edit notes directly using your favorite editor like Neovim, Vim, nano, or VS Code (export EDITOR=nvim).

Getting Started

Requirements & Installation

System Requirements

  • Node.js 18+ (Node.js 22+ recommended)
  • Linux Desktop Environment with notifications
  • notify-send utility installed
  • systemd with user service support
Verify Desktop Notification System
notify-send "Nikki" "Notification test"

Installation Options

Option 1: Quick Install via npm (Recommended)

npm install -g nikki-cli

Option 2: Install from Source

git clone https://github.com/Nikhil-Gautam-dev/nikki.git
cd nikki
npm install
npm run build
npm link
Documentation

Complete Command Reference

Search or browse every CLI command available in Nikki with executable snippets.

Notes Management 7 commands

nikki <content> | nikki add
Primary
Capture a new note instantly from your shell. Optionally attach a title with -t or a reminder with -r.
$nikki "learn systemd" -t "DevOps"
nikki title <id> [title]
New
Set or update the title of an existing note. Omit the title argument to clear it.
$nikki title 14 "Q3 Planning"
nikki list [-n <limit>]
Query
List recent notes (shows top 20 by default). Displays titles inline next to note ID.
$nikki list -n 50
nikki search <query>
Search
Perform full-text search matching across both note content and titles in SQLite.
$nikki search "DevOps"
nikki show <id>
Inspect
View full details and creation/update timestamps for a specific note ID.
$nikki show 14
nikki edit <id>
Editor
Open note content directly in your system $EDITOR (Neovim, Vim, VS Code, etc.).
$nikki edit 14
nikki delete <id>
Safety
Delete a note permanently with an interactive [y/N] confirmation prompt.
$nikki delete 14

Reminders & Dates 4 commands

nikki "<content>" -r "<time>"
Inline
Create a note and set a natural language reminder in one shot (e.g. "tomorrow 10am").
$nikki "check VPS" -r "tomorrow 10am"
nikki remind <noteId> --at "<time>"
Attach
Attach a reminder to an existing note ID using natural date parsing.
$nikki remind 14 --at "in 2 hours"
nikki reminders
List
List all pending upcoming reminders sorted chronologically by target time.
$nikki reminders
nikki complete-reminder <id>
Done
Mark a pending reminder as completed manually.
$nikki complete-reminder 4

Daily Summary & Date Navigation 4 commands

nikki today
Dashboard
Displays a consolidated daily dashboard overview of notes created and reminders scheduled for today.
$nikki today
nikki yesterday
New
Show yesterday's notes and reminders in the same rich summary dashboard view.
$nikki yesterday
nikki tomorrow
New
Show tomorrow's scheduled notes and upcoming reminders.
$nikki tomorrow
nikki date <when>
NLP
Show notes and reminders for any date using natural language parsing ("last friday", "Aug 25").
$nikki date "last friday"

Systemd Daemon Management 2 commands

nikki daemon install
Setup
Automatically creates a systemd user unit service, enables it, and starts background polling.
$nikki daemon install
nikki daemon status | start | stop
Control
Manage background reminder daemon status and execution cleanly without raw systemctl commands.
$nikki daemon status
System Integration

Background Reminder Daemon

How Nikki delivers lightweight, reliable desktop notifications without battery drag.

SQLite Database (~/.note/notes.db)
Nikki Daemon (note-daemon.service)
Polls every 30 seconds
Due Reminder Triggered
notify-send Desktop Notification with Mascot Icon
Under the Hood

Tech Stack & Project Structure

Technology Stack

Technology Purpose
Node.jsRuntime Environment
TypeScriptStrict Application Language
Commander.jsCommand Line Interface Engine
SQLite & better-sqlite3Embedded Local Database (WAL mode)
chrono-nodeNatural-Language Date Parser
ChalkTerminal Color Styling
tsupTypeScript Bundler (ESM Target)
systemdLinux User Service Manager
notify-sendLinux Desktop Notification Daemon

Project Layout

nikki/
├── src/
│ ├── cli.ts
│ ├── daemon.ts
│ ├── db.ts
│ ├── services/
│ │ ├── daemon.service.ts
│ │ ├── note.service.ts
│ │ ├── notification.service.ts
│ │ └── reminder.service.ts
│ └── utils/
│ ├── date.ts
│ ├── editor.ts
│ ├── paths.ts
│ └── version-manager.ts
├── assets/
│ └── nikki-fox-mascot.png
├── dist/
│ ├── cli.js
│ └── daemon.js
├── package.json
└── LICENSE
Future Vision

Roadmap

Upcoming features planned without compromising simple terminal-first workflow.

Optional Note Titles & Title Search
nikki yesterday / tomorrow / date <nlp>
Full-text SQLite search
Tags & Note Categorization
Note Linking & Backlinks
Recurring Reminders
Snooze Reminders via Notification
Notification Actions (Done / Snooze)
Multiple Mascot Expressions
Markdown note files export
Git-based synchronization
Optional TUI (Bubbletea / Blessed)
Windows / macOS Notification Support