neuron-cli

README

A terminal knowledge manager that doesn't get in your way.

If you like Neuron CLI, please consider giving it a ⭐ to help make it more visible!

neuron is a local-first, Obsidian-compatible note manager for the terminal. It keeps your Markdown vault exactly where it is — no migration, no cloud, no subscription. Just fast, keyboard-driven access to your notes from anywhere in a shell.

---

✨ FEATURES

🗂️ PARA Methodology — Built In

neuron understands the Projects · Areas · Resources · Archive framework out of the box. It scans your vault for PARA folders and surfaces them throughout the UI:

• Folder picker on note creation — After typing a title (n in the TUI or neuron add), an interactive chip list lets you choose the destination folder before the note is saved. No more notes silently landing at the vault root.
• Keyboard navigation: ← → / h l / ↑ ↓ / j k to move between folders, Enter to confirm, Esc to cancel.
• neuron move — Relocate any note to a different PARA folder at any time, from both the CLI and the /move TUI command.
• Vaults without PARA folders skip the picker entirely — zero friction for simple setups.

📂 Live Folder Breadcrumb

The status bar at the bottom of the TUI permanently shows where the currently highlighted note lives — e.g. 📂 1. Projects or 📂 2. Areas/Finance — giving instant spatial context while browsing without opening the note.

📋 Clipboard-to-Note (Paste Workflow)

• ctrl+v on a selected note appends your clipboard contents directly to that note on disk — great for capturing web snippets or code blocks without leaving the terminal.
• Bracketed paste support: paste any amount of text while typing a new note title to pre-fill both the title (first line, up to 40 chars) and the note body in a single gesture.

🔍 Dual Search Engine

• BM25 full-text search — instant keyword search across all notes, available out of the box.
• Semantic / AI search — enable Ollama in your config to get embedding-based similarity search (neuron list -q "your concept").

📝 Template System

Create note templates and render them on demand:

neuron add "2025-06-01 Standup" --template standup
neuron today                                        # uses a "daily" template automatically

🔗 Wikilinks & Knowledge Graph

• Full [[wikilink]] extraction and index — same format as Obsidian.
• Press g in the TUI to get an instant summary of your knowledge graph: nodes (notes) and edges (links).
• Inline #tags are extracted automatically from note bodies.

💅 Interactive CLI Prompts

Missing arguments? neuron will prompt you interactively for anything it needs — title, folder, confirmation — using rich terminal forms (huh).

⚡ Command Palette

Press / in the TUI to fuzzy-search all available commands:

Command	Description
/add <title>	Create a new note (triggers folder picker)
/today	Open or create today's daily note
/edit	Open the selected note in $EDITOR
/move <folder>	Move the selected note to a PARA folder
/rm	Delete the selected note
/sync	Git push (with optional pull)
/stats	Show vault statistics
/open	Reveal vault in Finder
/theme dark|light	Switch the TUI colour scheme live
/quit	Exit neuron

🎨 Splash Screen & Theming

• A premium ASCII splash screen greets you on launch with your vault stats and a quick-start keybinding reference.
• Two built-in themes: dark (Tokyo Night) and light (GitHub). Switch live with /theme dark or persist with neuron config set theme dark.

---

🚀 INSTALLATION

# Homebrew
brew install steevin/tap/neuron

# Go
go install github.com/steevin/neuron-cli@latest

# Source
git clone https://github.com/steevin/neuron-cli && cd neuron-cli && make build

---

💻 USAGE

neuron                                   # open the TUI (default)
neuron init                              # interactive setup wizard (first run)
neuron add                               # prompt for title + PARA folder picker
neuron add "standup notes" --tag work    # create note with tag, then pick folder
neuron add "1. Projects/API redesign"    # skip picker — explicit path prefix
neuron edit "standup notes"             # open in $EDITOR
neuron today                             # daily note for today
neuron list -q "kubernetes"              # full-text / semantic search
neuron move "standup notes" projects    # move note to your Projects folder
neuron sync --pull                       # git pull + push
neuron stats                             # note count, tag count
neuron config set editor nvim            # change default editor
neuron config set theme dark             # set colour theme
neuron mcp                               # start the MCP server

---

🧠 MCP (AI AGENT ACCESS)

neuron exposes your vault as an MCP server. Add it to any compatible client (Claude Desktop, Cursor, Antigravity…):

{
  "mcpServers": {
    "neuron": { "command": "neuron", "args": ["mcp"] }
  }
}

Then you can ask your AI to search, create, summarize, or move notes directly from your vault — without leaving the chat.

---

⌨️ TUI KEYBINDINGS

Key	Action
j / k or ↑ / ↓	Navigate note list
Enter	Select / confirm
Tab / Shift+Tab	Switch pane focus (sidebar ↔ preview)
n	New note (triggers PARA folder picker)
e	Edit selected note in $EDITOR
ctrl+v	Paste clipboard into selected note
/	Command palette (fuzzy search)
s	Git sync
ctrl+g	Knowledge graph summary
?	Help overlay (all keybindings)
q	Quit

During folder selection (📁 SAVE TO mode)

Key	Action
← → / h l / ↑ ↓ / j k	Navigate folder chips
Enter	Confirm folder
Esc	Cancel

---

📂 VAULT FORMAT

Plain Markdown with YAML frontmatter — identical to Obsidian. Point neuron at an existing Obsidian vault and it just works.

---
title: My Note
tags: [ideas, project]
created: 2025-05-30T09:00:00Z
---

Content with [[wikilinks]] and #inline-tags.

Recommended PARA structure (neuron auto-detects any variant):

vault/
├── 1. Projects/
├── 2. Areas/
├── 3. Resources/
└── 4. Archive/

---

🔄 UPDATE

brew upgrade steevin/tap/neuron

---

❤️ SUPPORT THIS PROJECT

If you find Neuron CLI useful, you can help support the development by donating via PayPal: Donate via PayPal ➔

---

📄 LICENSE & ATTRIBUTION

Neuron CLI is open-source software licensed under the GNU GPL v3.

⚖️ What this means

• Copyleft: Any modifications or derivatives of this code must also be open-sourced under the GPL v3.
• Keep Copyright: You must retain all original copyright notices and author info in the source files.
• State Changes: You must prominently state any changes made to the original files.

📢 How to Attribute

If you redistribute, fork, or use parts of this codebase in public projects, please show your support and maintain visibility by adding the following attribution to your repository's README or documentation:

This project uses code/components from Neuron CLI by Daniel Steevin, licensed under the GNU GPL v3.

---

✉️ CONTACT

For support, feedback, business inquiries, or any other questions, please contact: neuron@steevin.com

---

Made by Daniel Steevin
Licensed under the GNU GPL v3 License — Open Source with Copyleft.