napkin

name	napkin
description	Read, create, search, and manage notes in Obsidian vaults using the napkin CLI. Works directly on markdown files and canvas files — no Obsidian app required. Use when the user asks to interact with their Obsidian vault, manage notes, search vault content, work with tasks, tags, properties, daily notes, templates, bases, bookmarks, aliases, or canvas files from the command line.

napkin

CLI for Obsidian vaults. Operates directly on markdown files — no Obsidian app, no Electron, no Catalyst license.

Install: npm install -g napkin-ai

IMPORTANT: Always pass --vault $NAPKIN_VAULT to every napkin command. The vault lives in the knowledge/ subdirectory, not the workspace root.

Reading this vault's memory notes

This vault is maintained by an automatic distillation loop. Entity notes (under people/, projects/, references/) follow a temporal convention — read them this way:

• NAPKIN.md is the map of the vault. Start here for a quick overview of who and what is remembered.
• Frontmatter + ## Current View hold the authoritative present value of every fact. When the user asks "what is X now?", answer from here.
• ## History is append-only past context. A bullet ending with *(superseded YYYY-MM-DD — reason)* is an old value that has been replaced — never quote it as current. Use History only to answer "what did X used to think / when did this change?".

One file per entity, one directory per category — a person is always a file inside people/, never a section in a flat people.md.

Episodes (episodes/)

Episodes are time-bounded events or topics — distinct from entity files which capture permanent knowledge. An episode tracks a developing situation (a market event, a personal search, a conflict) that starts, heats up, and eventually resolves or fades.

• Episodes may appear in your context as <active_episodes> XML — these are automatically injected when the user's message is relevant.
• You can create episodes during conversation using the write tool: write episodes/car-search.md with the episode frontmatter format (type, status, started, last_mentioned, mentions, keywords, summary).
• You can resolve episodes when the user indicates closure: set status: resolved in the frontmatter.
• Episode status values: active (current), cooling (not mentioned recently — set by consolidation, not by you), resolved (explicitly closed), faded (long-dormant — set by consolidation).
• ## History in episodes is append-only, same as entity files.

Memory suggestions (.memory-suggestions.md)

If the file knowledge/.memory-suggestions.md exists, it contains recommendations from the weekly/monthly consolidation about topics worth adding to MEMORY.md. Read it, decide whether the suggestions are relevant, update MEMORY.md if appropriate, then delete the file.

Syntax

napkin uses standard CLI flags. Quote values with spaces:

napkin --vault $NAPKIN_VAULT create --name "My Note" --content "Hello world"

Global flags

Flag	Description
--json	Output as JSON (use this for programmatic access)
-q, --quiet	Suppress output
--vault <path>	Vault path (default: auto-detect by walking up from cwd looking for .obsidian/)
--copy	Copy output to clipboard

File targeting

• --file <name> — resolves like a wikilink (name only, no path or extension needed)
• --path <path> — exact path from vault root, e.g. Projects/note.md

Commands

Vault

napkin --vault $NAPKIN_VAULT vault                                # Vault info (name, path, files, folders, size)
napkin --vault $NAPKIN_VAULT version                              # CLI version

Files & folders — napkin file

napkin --vault $NAPKIN_VAULT file info <name>                     # File info (path, size, dates)
napkin --vault $NAPKIN_VAULT file list                            # List all files
napkin --vault $NAPKIN_VAULT file list --ext md                   # Filter by extension
napkin --vault $NAPKIN_VAULT file list --folder Projects          # Filter by folder
napkin --vault $NAPKIN_VAULT file list --total                    # Count files
napkin --vault $NAPKIN_VAULT file folder <path>                   # Folder info (files, folders, size)
napkin --vault $NAPKIN_VAULT file folder <path> --info files      # Just the file count
napkin --vault $NAPKIN_VAULT file folders                         # List all folders
napkin --vault $NAPKIN_VAULT file folders --total                 # Count folders

Read & write

napkin --vault $NAPKIN_VAULT read <file>                          # Read file contents
napkin --vault $NAPKIN_VAULT create --name "Note" --content "# Hello"
napkin --vault $NAPKIN_VAULT create --name "Note" --path "Projects" --template "Meeting Note"
napkin --vault $NAPKIN_VAULT append --file "Note" --content "New line at end"
napkin --vault $NAPKIN_VAULT prepend --file "Note" --content "New line after frontmatter"
napkin --vault $NAPKIN_VAULT move --file "Note" --to Archive
napkin --vault $NAPKIN_VAULT rename --file "Note" --name "Renamed Note"
napkin --vault $NAPKIN_VAULT delete --file "Note"                 # Move to .trash
napkin --vault $NAPKIN_VAULT delete --file "Note" --permanent     # Delete permanently

Daily notes — napkin daily

Reads config from .obsidian/daily-notes.json (folder, format, template).

napkin --vault $NAPKIN_VAULT daily today                          # Create today's daily note (from template if configured)
napkin --vault $NAPKIN_VAULT daily path                           # Print daily note path
napkin --vault $NAPKIN_VAULT daily read                           # Print daily note contents
napkin --vault $NAPKIN_VAULT daily append --content "- [ ] Buy groceries"
napkin --vault $NAPKIN_VAULT daily prepend --content "## Morning"

Search

Full-text search with relevance ranking (fuzzy matching, prefix search, filename boosting).

napkin --vault $NAPKIN_VAULT search "meeting"                     # Find files matching text
napkin --vault $NAPKIN_VAULT search --query "meeting"             # Same, using flag
napkin --vault $NAPKIN_VAULT search "TODO" --path Projects        # Limit to folder
napkin --vault $NAPKIN_VAULT search "bug" --total                 # Count matches
napkin --vault $NAPKIN_VAULT search "deploy" --limit 5            # Top 5 results
napkin --vault $NAPKIN_VAULT search "TODO" --context              # Grep-style file:line:text output

Tasks — napkin task

napkin --vault $NAPKIN_VAULT task list                            # List all tasks
napkin --vault $NAPKIN_VAULT task list --todo                     # Incomplete only
napkin --vault $NAPKIN_VAULT task list --done                     # Completed only
napkin --vault $NAPKIN_VAULT task list --daily                    # Today's daily note tasks
napkin --vault $NAPKIN_VAULT task list --file "Project A"         # Tasks in specific file
napkin --vault $NAPKIN_VAULT task list --verbose                  # Group by file with line numbers
napkin --vault $NAPKIN_VAULT task list --total                    # Count tasks
napkin --vault $NAPKIN_VAULT task show --file "note" --line 3     # Show task info
napkin --vault $NAPKIN_VAULT task show --file "note" --line 3 --toggle  # Toggle ✓/○
napkin --vault $NAPKIN_VAULT task show --file "note" --line 3 --done    # Mark done
napkin --vault $NAPKIN_VAULT task show --ref "note.md:3" --todo         # Mark todo (file:line shorthand)

Tags — napkin tag

napkin --vault $NAPKIN_VAULT tag list                             # List all tags
napkin --vault $NAPKIN_VAULT tag list --counts                    # With occurrence counts
napkin --vault $NAPKIN_VAULT tag list --sort count                # Sort by frequency
napkin --vault $NAPKIN_VAULT tag info --name "project"            # Tag info (count)
napkin --vault $NAPKIN_VAULT tag info --name "project" --verbose  # With file list
napkin --vault $NAPKIN_VAULT tag aliases                          # List all aliases in vault
napkin --vault $NAPKIN_VAULT tag aliases --file "note"            # Aliases for a file
napkin --vault $NAPKIN_VAULT tag aliases --total                  # Count aliases

Properties — napkin property

napkin --vault $NAPKIN_VAULT property list                        # List all property names in vault
napkin --vault $NAPKIN_VAULT property list --file "note"          # Properties for a specific file
napkin --vault $NAPKIN_VAULT property list --counts               # With occurrence counts
napkin --vault $NAPKIN_VAULT property read --file "note" --name title
napkin --vault $NAPKIN_VAULT property set --file "note" --name status --value done
napkin --vault $NAPKIN_VAULT property remove --file "note" --name status

Links — napkin link

napkin --vault $NAPKIN_VAULT link back --file "note"              # Files linking TO this file
napkin --vault $NAPKIN_VAULT link out --file "note"               # Outgoing links FROM this file
napkin --vault $NAPKIN_VAULT link unresolved                      # Broken links (target doesn't exist)
napkin --vault $NAPKIN_VAULT link orphans                         # Files with no incoming links
napkin --vault $NAPKIN_VAULT link deadends                        # Files with no outgoing links

Outline

napkin --vault $NAPKIN_VAULT outline --file "note"                # Heading tree
napkin --vault $NAPKIN_VAULT outline --file "note" --format md    # Markdown list
napkin --vault $NAPKIN_VAULT outline --file "note" --format json  # JSON array

Templates — napkin template

napkin --vault $NAPKIN_VAULT template list                        # List templates
napkin --vault $NAPKIN_VAULT template read --name "Daily Note"    # Read template content
napkin --vault $NAPKIN_VAULT template read --name "Meeting" --resolve --title "Standup"  # Resolve variables
napkin --vault $NAPKIN_VAULT template insert --file "note" --name "Template"  # Insert template into file

Bookmarks — napkin bookmark

napkin --vault $NAPKIN_VAULT bookmark list                        # List bookmarks
napkin --vault $NAPKIN_VAULT bookmark list --total                # Count bookmarks
napkin --vault $NAPKIN_VAULT bookmark add --file "note"           # Bookmark a file
napkin --vault $NAPKIN_VAULT bookmark add --folder "Projects"     # Bookmark a folder
napkin --vault $NAPKIN_VAULT bookmark add --search "TODO"         # Bookmark a search
napkin --vault $NAPKIN_VAULT bookmark add --url "https://example.com" --title "Example"

Bases — napkin base

Query vault files using Obsidian Bases .base files (YAML-defined filters over frontmatter properties, powered by SQLite in-memory).

napkin --vault $NAPKIN_VAULT base list                            # List .base files
napkin --vault $NAPKIN_VAULT base views --file "projects"         # List views in a base
napkin --vault $NAPKIN_VAULT base query --file "projects"         # Query default view
napkin --vault $NAPKIN_VAULT base query --file "projects" --view "Active"  # Query named view
napkin --vault $NAPKIN_VAULT base query --file "projects" --format paths   # Just file paths
napkin --vault $NAPKIN_VAULT base query --file "projects" --format csv     # CSV output
napkin --vault $NAPKIN_VAULT base create --file "projects" --name "New Item"  # Create item in base

Canvas — napkin canvas

Read and write JSON Canvas files (.canvas) — nodes, edges, groups.

napkin --vault $NAPKIN_VAULT canvas list                          # List .canvas files
napkin --vault $NAPKIN_VAULT canvas list --total                  # Count canvases
napkin --vault $NAPKIN_VAULT canvas read --file "Board"           # Dump canvas (nodes + edges)
napkin --vault $NAPKIN_VAULT canvas nodes --file "Board"          # List all nodes
napkin --vault $NAPKIN_VAULT canvas nodes --file "Board" --type text  # Filter by type
napkin --vault $NAPKIN_VAULT canvas create --file "Board"         # Create empty canvas
napkin --vault $NAPKIN_VAULT canvas create --file "Board" --path "Projects"
napkin --vault $NAPKIN_VAULT canvas add-node --file "Board" --type text --text "# Hello"
napkin --vault $NAPKIN_VAULT canvas add-node --file "Board" --type file --note-file "Notes/note.md"
napkin --vault $NAPKIN_VAULT canvas add-node --file "Board" --type link --url "https://example.com"
napkin --vault $NAPKIN_VAULT canvas add-node --file "Board" --type group --label "My Group"
napkin --vault $NAPKIN_VAULT canvas add-node --file "Board" --type text --text "Positioned" --x 100 --y 200
napkin --vault $NAPKIN_VAULT canvas add-edge --file  --from abc1 --to def2 --label 
napkin --vault  canvas remove-node --file  -- abc1  

Node IDs are 16-char hex. --from/--to/--id accept ID prefixes for convenience. Node types: text, file, link, group. Colors: 1-6 or hex. New nodes auto-position to the right of existing content.

Word count

napkin --vault $NAPKIN_VAULT wordcount --file "note"              # Words + characters
napkin --vault $NAPKIN_VAULT wordcount --file "note" --words      # Words only
napkin --vault $NAPKIN_VAULT wordcount --file "note" --characters # Characters only

Agent onboarding

napkin --vault $NAPKIN_VAULT onboard                              # Print instructions for CLAUDE.md/AGENTS.md

JSON output

Every command supports --json. Always use --json for programmatic access:

napkin --vault $NAPKIN_VAULT task list --todo --json
# {"tasks": [{"text": "Buy groceries", "done": false, "file": "Daily/2024-01-15.md", "line": 5}, ...]}

napkin --vault $NAPKIN_VAULT search "deploy" --json
# {"files": ["Projects/Deploy Guide.md", "Notes/CI-CD.md"]}

napkin --vault $NAPKIN_VAULT property read --file "note" --name status --json
# {"value": "done"}

Common workflows

Morning standup prep

napkin --vault $NAPKIN_VAULT daily read --json                    # What did I write yesterday?
napkin --vault $NAPKIN_VAULT task list --todo --json              # What's pending?
napkin --vault $NAPKIN_VAULT search "blocker" --json              # Any blockers?

Project overview

napkin --vault $NAPKIN_VAULT file list --folder Projects --json   # List project files
napkin --vault $NAPKIN_VAULT tag list --counts --json             # Tag distribution
napkin --vault $NAPKIN_VAULT link orphans --json                  # Forgotten files
napkin --vault $NAPKIN_VAULT link unresolved --json               # Broken links to fix

Note management

napkin --vault $NAPKIN_VAULT create --name "Meeting Notes" --template "Meeting Note" --path "Meetings"
napkin --vault $NAPKIN_VAULT property set --file "Meeting Notes" --name attendees --value "Alice, Bob"
napkin --vault $NAPKIN_VAULT append --file "Meeting Notes" --content "- [ ] Follow up on deployment"

---

Obsidian Markdown Reference

napkin operates on Obsidian Flavored Markdown files. This section covers the syntax for creating valid content.

Properties (frontmatter)

YAML frontmatter at the start of a note:

---
title: My Note
date: 2024-01-15
tags:
  - project
  - important
aliases:
  - My Note
  - Alternative Name
cssclasses:
  - custom-class
status: in-progress
rating: 4.5
completed: false
---

Property types

Type	Example
Text	title: My Title
Number	rating: 4.5
Checkbox	completed: true
Date	date: 2024-01-15
Date & Time	due: 2024-01-15T14:30:00
List	tags: [one, two] or YAML list
Links	related: "[[Other Note]]"

Default properties: tags, aliases, cssclasses

Internal links (wikilinks)

[[Note Name]]                    Link to note
[[Note Name|Display Text]]       Custom display text
[[Note Name#Heading]]            Link to heading
[[Note Name#^block-id]]          Link to block
[[#Heading in same note]]        Same-file heading link

Embeds

![[Note Name]]                   Embed entire note
![[Note Name#Heading]]           Embed section
![[image.png]]                   Embed image
![[image.png|300]]               Image with width
![[document.pdf]]                Embed PDF
![[document.pdf#page=3]]         PDF at page

Tags

#tag
#nested/tag
#tag-with-dashes

# In frontmatter:
tags:
  - tag1
  - nested/tag2

Tags can contain letters, numbers (not first), underscores, hyphens, forward slashes.

Task lists

- [ ] Incomplete task
- [x] Completed task
- [ ] Parent task
  - [ ] Subtask
  - [x] Done subtask

Callouts

> [!note]
> This is a note callout.

> [!warning] Custom Title
> Warning with custom title.

> [!faq]- Collapsed by default
> Hidden until expanded.

> [!tip]+ Expanded by default
> Visible but collapsible.

Callout types: note, abstract/summary/tldr, info, todo, tip/hint/important, success/check/done, question/help/faq, warning/caution/attention, failure/fail/missing, danger/error, bug, example, quote/cite

Text formatting

Style	Syntax
Bold	**text**
Italic	*text*
Bold + Italic	***text***
Strikethrough	~~text~~
Highlight	==text==
Inline code	`code`

Code blocks

```javascript
function hello() {
  console.log("Hello");
}
```

Math (LaTeX)

Inline: $e^{i\pi} + 1 = 0$

Block:
$$
\sum_{i=1}^{n} x_i
$$

Block references

This paragraph can be linked to. ^my-block-id

Link to it: [[Note#^my-block-id]]
Embed it: ![[Note#^my-block-id]]

Comments

This is visible %%but this is hidden%% text.

%%
This entire block is hidden.
%%

---

Bases Reference

Bases are YAML-defined views that query vault files using their frontmatter properties. Saved as .base files.

Structure

filters:
  and:
    - file.hasTag("project")
    - 'status != "done"'
formulas:
  days_left: '(date(due) - today()).days'
properties:
  status:
    displayName: Status
views:
  - type: table
    name: "Active"
    order:
      - file.name
      - status
    limit: 20

Filters

# Single filter
filters:
  file.hasTag("project")

# AND
filters:
  and:
    - file.hasTag("project")
    - 'status != "done"'

# OR
filters:
  or:
    - file.hasTag("book")
    - file.hasTag("article")

# NOT
filters:
  not:
    - file.hasTag("archived")

# Nested
filters:
  or:
    - file.hasTag("urgent")
    - and:
        - file.hasTag("project")
        - 'priority >= 3'

Filter operators

Operator	Description
==	equals
!=	not equal
>	greater than
<	less than
>=	greater than or equal
<=	less than or equal

File functions for filters

Function	Description
file.hasTag("tag1", "tag2")	Has any of the tags (includes nested)
file.hasLink("Note")	Has link to note
file.hasProperty("name")	Has frontmatter property
file.inFolder("Projects")	In folder or subfolder

File properties

Property	Type	Description
file.name	String	File name
file.basename	String	Name without extension
file.path	String	Full path from vault root
file.folder	String	Parent folder path
file.ext	String	File extension
file.size	Number	Size in bytes
file.ctime	Date	Created time
file.mtime	Date	Modified time
file.tags	List	All tags
file.links	List	Internal links

Note properties

Frontmatter properties accessed as note.property or just property:

filters:
  and:
    - 'status == "active"'        # shorthand
    - 'note.priority >= 3'        # explicit

Formulas

formulas:
  total: "price * quantity"
  status_icon: 'if(done, "✅", "⏳")'
  formatted_price: 'if(price, price.toFixed(2) + " dollars")'
  created: 'file.ctime.format("YYYY-MM-DD")'
  days_old: '(now() - file.ctime).days'
  days_until_due: 'if(due_date, (date(due_date) - today()).days, "")'

Global functions

Function	Description
date(string)	Parse date (YYYY-MM-DD HH:mm:ss)
now()	Current datetime
today()	Current date (time = 00:00:00)
if(cond, true, false?)	Conditional
min(n1, n2, ...)	Smallest number
max(n1, n2, ...)	Largest number
number(any)	Convert to number
link(path, display?)	Create link
list(element)	Wrap in list

Date arithmetic

"date + \"1M\""              # Add 1 month
"now() + \"1 day\""          # Tomorrow
"today() + \"7d\""           # Week from today
"(now() - file.ctime).days"  # Days since created

Duration units: y/year/years, M/month/months, d/day/days, w/week/weeks, h/hour/hours, m/minute/minutes, s/second/seconds

String functions

contains(), startsWith(), endsWith(), lower(), trim(), replace(), split(), slice(), isEmpty(), .length

Number functions

abs(), ceil(), floor(), round(digits?), toFixed(precision)

List functions

contains(), filter(), map(), join(), sort(), unique(), flat(), isEmpty(), .length

Views

views:
  - type: table           # table, list, cards, map
    name: "My View"
    limit: 10
    order:
      - file.name
      - status
      - due_date
    filters:              # View-level filters (AND'd with global)
      'status != "done"'
    groupBy:
      property: status
      direction: ASC      # or DESC
    summaries:
      price: Sum
      count: Average

Summary functions

Name	Input	Description
Average	Number	Mean
Min	Number	Smallest
Max	Number	Largest
Sum	Number	Sum
Range	Number	Max - Min
Median	Number	Median
Earliest	Date	Earliest date
Latest	Date	Latest date
Empty	Any	Count of empty values
Filled	Any	Count of non-empty values
Unique	Any	Count of unique values

Example: Task tracker

filters:
  and:
    - file.hasTag("task")
    - 'file.ext == "md"'
formulas:
  days_until_due: 'if(due, (date(due) - today()).days, "")'
  priority_label: 'if(priority == 1, "🔴 High", if(priority == 2, "🟡 Medium", "🟢 Low"))'
views:
  - type: table
    name: "Active Tasks"
    filters:
      and:
        - 'status != "done"'
    order:
      - file.name
      - status
      - formula.priority_label
      - due
      - formula.days_until_due
    groupBy:
      property: status
      direction: ASC

---

JSON Canvas Reference

Canvas files (.canvas) are JSON following the JSON Canvas Spec 1.0.

{
  "nodes": [
    {"id": "aabb11223344", "type": "text", "x": 0, "y": 0, "width": 300, "height": 150, "text": "# Hello\nMarkdown content"},
    {"id": "ccdd55667788", "type": "file", "x": 400, "y": 0, "width": 300, "height": 200, "file": 
                 
                   
  
   
               
  

Node types

Type	Required fields	Description
text	text	Markdown content
file	file, optional subpath	Reference to vault file
link	url	External URL
group	optional label, background, backgroundStyle	Visual container

Common fields

All nodes: id (16-char hex), type, x, y, width, height, optional color (1-6 or hex). Edges: id, fromNode, toNode, optional fromSide/toSide (top/right/bottom/left), fromEnd/toEnd (none/arrow), label, color.

---

Example: Project notes

filters:
  and:
    - file.inFolder("Projects")
    - 'file.ext == "md"'
formulas:
  last_updated: 'file.mtime.relative()'
  link_count: 'file.links.length'
views:
  - type: table
    name: "All Projects"
    order:
      - file.name
      - status
      - formula.last_updated
      - formula.link_count
    groupBy:
      property: status
      direction: ASC