Notesia CLI

Local CLI for reading, searching, tagging, and bulk-importing notes in Notesia through the desktop app bridge. Includes AI knowledge base queries, quick capture to Inbox, and deep link navigation.

Requirements

• Node.js 20+
• Notesia desktop app running (macOS/Linux)
• Logged into Notesia in the desktop app

Install

npm install -g @clarionstack/notesia

Commands

Notes

• notesia get --id <id>|--supabase-id <uuid>|--title "<title>" [--json] [--with-meta]
• notesia list [--limit <count>] [--format table|json]
• notesia store --title "<title>" [--tag <tag>]... [--folder-id <id>] [--content <text>]
• notesia update --id <id>|... [--content <text>] [--title "<new title>"]
• notesia append --id <id>|... [--content <text>]
• notesia prepend --id <id>|... [--content <text>]
• notesia move --id <id>|... --folder-id <id> (use 0 for root)
• notesia trash --id <id>|...
• notesia capture --title "<title>" [--content <text>] [--tag <tag>]...
• notesia open --id <id>|--title "<title>"
• notesia sync
• notesia auth status [--format text|json]

Search

• notesia search <query> [--limit <n>] [--format text|json]

Alias for notesia kb search. Full-text search across all notes by title and content.

Tags

• notesia tags [--format text|json] — List all tags with note counts
• notesia tag add --id <id>|... --tag <tag> [--tag <tag>]... — Add tags to a note
• notesia tag remove --id <id>|... --tag <tag> [--tag <tag>]... — Remove tags from a note

Bulk Import

notesia import <path> [options]

Recursively discovers files in a directory and imports them as notes into Notesia.

| Option | Description | Default | |---|---|---| | <path> | Source directory or file (required) | — | | --ext <list> | Comma-separated file extensions | md,txt,pdf,docx,json | | --folder <name> | Target folder name (created if absent) | — | | --tags <list> | Comma-separated tags for all imported notes | — | | --conflict <mode> | skip or overwrite existing notes by title | skip | | --dry-run | Preview what would be imported without writing | — | | --format <fmt> | Output format: text or json | text | | --quiet | Suppress stdout output | — | | --verbose | Print per-file progress to stderr | — |

Supported file types: .md, .txt, .html, .pdf, .docx, .json.

JSON imports are transformed into flattened key-path text (with truncation guards for very large arrays/strings) to improve embedding quality.

Notes exceeding 100,000 characters are automatically split into multiple parts.

AI Knowledge Base (kb)

• notesia kb search --query "<text>" [--limit <n>] [--threshold <0-1>] [--format text|json]
• notesia kb ask --query "<text>" [--limit <n>] [--threshold <0-1>] [--conversation-id <uuid>] [--format text|json]
• notesia kb folders [--format text|json]
• notesia kb context --query "<text>" [--limit <n>] [--threshold <0-1>] (always JSON)

kb ask automatically reuses the same conversation in the same terminal session. Use --conversation-id only when you want to override/reset the session.

Deep Links

Open a note in the desktop app via URL scheme:

• com.notesia.app://open?id=<id> — Open by local ID
• com.notesia.app://open?title=<title> — Open by title

Examples

Basic note operations

notesia get --id 42 > note.md
notesia get --id 42 --with-meta          # prepends YAML frontmatter
notesia list --format json > notes.json
cat patch.md | notesia update --id 42
echo "- new item" | notesia append --id 42
notesia trash --id 42
notesia sync
notesia auth status

Search, move, open, and capture

# Full-text search
notesia search "meeting notes"
notesia search "meeting" --json | jq '.notes[].title'

# Move a note to a different folder
notesia move --id 12 --folder-id 3

# Open a note in the desktop app
notesia open --title "My Note"

# Quick capture to Inbox
notesia capture --title "Quick idea" --content "Look into this later"

Prepend and pipe examples

# Prepend content before existing note body
echo "Important: " | notesia prepend --id 5

# Capture from clipboard (macOS)
pbpaste | notesia capture --title "Clipboard"

Tags

# List all tags with usage counts
notesia tags
notesia tags --format json

# Add tags to a note
notesia tag add --id 42 --tag project --tag important

# Remove tags from a note
notesia tag remove --id 42 --tag draft

Bulk import

# Import all markdown and text files from a directory
notesia import ~/Documents/notes

# Import into a specific folder with tags
notesia import ./project-docs --folder "Work" --tags "project,2026"

# Import HTML, PDF, DOCX and JSON files too
notesia import ./archive --ext md,txt,html,pdf,docx,json

# Overwrite existing notes with the same title
notesia import ./updated-notes --conflict overwrite

# Preview what would be imported
notesia import ~/notes --dry-run --verbose

# JSON output for scripting
notesia import ./docs --format json --quiet 2>/dev/null | jq '.created'

AI Knowledge Base

# Check auth
notesia auth status --json

# Discover knowledge structure
notesia kb folders --json

# Find relevant notes
notesia kb search --query "project plan" --limit 10

# Ask KB directly (searches notes and todos)
notesia kb ask --query "what are my pending tasks?"

# Load full context for AI prompt (returns JSON with full content)
notesia kb context --query "Q1 roadmap" --limit 5

# Continue a KB conversation across calls
notesia kb ask --query "what did I change yesterday?"
notesia kb ask --query "and what about folder sync?"

# Create a tagged note
echo "## Summary\n..." | notesia store --title "AI Summary" --tag ai --tag generated

# Get a note with frontmatter for context injection
notesia get --id 42 --with-meta

Exit Codes

| Code | Meaning | |---|---| | 0 | Success (including skipped items) | | 1 | Runtime error (bridge unavailable, failed items, renderer error) | | 2 | Invalid arguments |

Security Notes

• Secure notes (encrypted vault notes) are never exposed through the CLI
• The bridge token is stored in $TMPDIR/notesia-cli-<user>.json (mode 600)
• Content via --content or stdin is limited to 512 KB