NoteCove NoteCove

Command Line Interface (CLI)

NoteCove includes a powerful command-line interface for power users, developers, and AI/LLM integrations.

Overview

The NoteCove CLI is bundled with the desktop app and provides shell integration for quick access from your terminal. Primary use cases include:

  • Power users: Quickly add notes, search, and manage tasks without leaving the terminal
  • AI/LLM integration: Enable AI assistants like Claude Code to interact with your NoteCove data
  • Automation: Script note creation and task management workflows

Installation

The CLI is bundled with the NoteCove desktop app. To enable the notecove command in your terminal:

Using the Desktop App

Menu: Tools > CLI > Install CLI…

This opens a dialog where you can:

  1. See which shells are available (bash, zsh, fish, PowerShell)
  2. Select which shells to install for
  3. Preview the shell configuration that will be added
  4. Install with one click

A backup of your shell config is created before any modifications.

Manual Installation

If you prefer to add the CLI configuration manually, the desktop app can show you the exact code to add:

Menu: Tools > CLI > CLI Status…

Click on any shell to preview the configuration, then copy it to your shell config file.

Verifying Installation

After installation, open a new terminal window and run:

notecove --version

You should see the version number matching your NoteCove desktop app.

Authentication & Access Control

The CLI uses a per-directory authentication model. Before using commands, you must initialize access for each directory where you want to use the CLI.

Initializing Access

# Basic: single project access (tasks only)
notecove init --profile <profile-id> --tasks-project MYPROJ

# Multiple projects
notecove init --profile <profile-id> --tasks-project PROJ1 --tasks-project PROJ2

# All projects
notecove init --profile <profile-id> --all-tasks

# With notes access (SD-scoped to your project)
notecove init --profile <profile-id> --tasks-project MYPROJ --notes

# With folder-scoped notes access (by path or ID)
notecove init --profile <profile-id> --tasks-project MYPROJ --notes --folder "Documents"
notecove init --profile <profile-id> --tasks-project MYPROJ --notes --folder "Work/Projects"

# Disambiguate when folder exists in multiple SDs (prefix with /sdname/)
notecove init --profile <profile-id> --tasks-project MYPROJ --notes --folder "/My SD/Documents"

# Full access to all notes across all SDs
notecove init --profile <profile-id> --all-tasks --all-notes

# With event stream access
notecove init --profile <profile-id> --tasks-project MYPROJ --events

# Events only (no task or notes access)
notecove init --profile <profile-id> --events

When you run init, the desktop app will show an approval dialog describing exactly what access is being requested. Access is only granted after approval.

Access Scoping

The CLI enforces server-side access scoping. You only see and can modify resources within your authorized scope:

ScopeWhat It Controls
ProjectsWhich task projects you can access
NotesWhether you can access notes at all (off by default)
SDsWhich storage directories your notes access covers
FoldersOptionally restrict notes to specific folders

Multi-Project Usage

When authorized for multiple projects, task commands require the --project flag:

# Single-project auth: --project is optional
notecove task list

# Multi-project auth: --project is required
notecove task list --project MYPROJ
notecove task create "New task" --project MYPROJ
notecove task show MYPROJ-42 --project MYPROJ

Checking Your Configuration

notecove debug

This shows your current scope, connection status, and authentication details.

Managing CLI Keys

You can review and revoke CLI authorization keys from the desktop app:

Settings > CLI Keys

This tab shows all issued CLI keys with their:

  • Working directory path
  • Creation date
  • Project and notes access scope
  • Shared secret (masked, click to reveal)

You can revoke individual keys or all keys at once. See the Settings guide for details.

Available Commands

Notes

Create a new note:

notecove note create "My Note Title"
notecove note create "Shopping List" --folder "Personal"

List notes:

notecove note list
notecove note list --folder "Work"
notecove note list --limit 10

Search notes:

notecove note search "project ideas"

Find similar notes (semantic search required — enable in Settings > Search):

notecove note similar <note-id>
notecove note similar <note-id> --limit 5

View a note:

notecove note view <note-id>

Tasks

Create a task:

notecove task create "Fix login bug"
notecove task create "Write documentation" --priority 3
notecove task create "Bug report" --project BACKEND

List tasks:

notecove task list
notecove task list --state "In Progress"
notecove task list --project BACKEND --limit 10

Show task details:

notecove task show PROJ-42
notecove task show PROJ-42 --json

Update a task:

notecove task change PROJ-42 --state "Done"
notecove task change PROJ-42 --priority 5 --title "Updated title"
notecove task change PROJ-42 --block PROJ-10  # add blocker

Find ready tasks (not blocked, not completed):

notecove task ready
notecove task ready --priority 3

Search tasks:

notecove task search "authentication"

Find similar tasks (semantic search required — enable in Settings > Search):

notecove task similar PROJ-42
notecove task similar PROJ-42 --limit 5

Delete a task:

notecove task delete PROJ-42
notecove task delete PROJ-42 --force  # skip confirmation

Comments:

notecove task comments list PROJ-42
notecove task comments add PROJ-42 "Looks good to me"
notecove task comments reply PROJ-42 <thread-id> "Thanks!"

Full-text search across notes and tasks:

notecove search "query"
notecove search "query" --type notes
notecove search "query" --type tasks

Semantic search (enable in Settings > Search):

notecove search "distributed systems" --semantic
notecove search "project management" --semantic --limit 10

Filter by date:

notecove search "query" --modified-after 2025-01-01
notecove search "query" --created-after 2024-06-01 --created-before 2024-12-31

Filter by tags:

notecove search "query" --tag work --tag urgent
notecove search "query" --exclude-tag archive

Task filters:

notecove search "query" --terminal           # completed tasks only
notecove search "query" --active             # active tasks only
notecove search "query" --project PROJ --state "In Progress"
notecove search "query" --min-priority 3
notecove search "query" --has-blockers

Folders

List folders:

notecove folder list

Create a folder:

notecove folder create "New Folder"
notecove folder create "Subfolder" --parent "Parent Folder"

Remote Access

Project your local profile to a remote machine so the CLI works there as if NoteCove were running locally:

notecove serve --ssh user@remotehost

See Remote CLI Access for the full walkthrough.

Projects

List projects:

notecove project list

Event Stream

Subscribe to live events from the NoteCove desktop app. Useful for automation, reactive scripts, and AI agents that need to observe what’s changing.

Requires --events permission. When running notecove init, include --events to request event stream access:

notecove init --profile <profile-id> --tasks-project MYPROJ --events

Without this flag your token will receive Token does not have events:subscribe permission.

Subscribe to all events (live SSE stream):

notecove events
notecove events --types "task.*,note.created"
notecove events --json   # raw JSON per line

Resume after disconnection (replay missed events):

notecove events --last-event-id 42   # replay events since seq 42

Poll for recent events (non-streaming, for scripts and MCP):

notecove events recent --json
notecove events recent --since 42 --json   # only events after seq 42
notecove events recent --types "task.*" --json
notecove events recent --limit 20 --json

Event types include: task.created, task.modified, task.deleted, note.created, note.modified, note.deleted, folder.updated, project.created, smart_folder.item_matched, sync.completed, and more.

The seq field in each event is a monotonically increasing cursor. Use it with --last-event-id (streaming) or --since (polling) to receive only events that arrived after your last known position.

Quick Add

Add content quickly:

notecove add "Quick thought to capture"
echo "Piped content" | notecove add

Configuration

The CLI communicates with the running NoteCove desktop app. Ensure the desktop app is running when using CLI commands.

A .notecove config file is created in the directory where you run init. This file contains your access credentials and scope — treat it like a secret and don’t commit it to version control.

Environment Variables

VariableDescription
NOTECOVE_DEBUGEnable debug logging

Shell Integration Details

How It Works

The CLI installation adds a shell function that:

  1. Locates the bundled CLI in the NoteCove app resources
  2. Executes the CLI with your arguments

Shell Config Locations

ShellConfig File
Bash~/.bashrc
Zsh~/.zshrc
Fish~/.config/fish/config.fish
PowerShell$PROFILE

Markers

The CLI configuration is wrapped in markers for safe uninstall:

# >>> notecove cli >>>
# NoteCove CLI configuration here
# <<< notecove cli <<<

Uninstalling

Menu: Tools > CLI > Uninstall CLI…

Select which shells to remove the CLI from. A backup is created before removal.

Troubleshooting

”NoteCove CLI not found”

The desktop app may not be installed in the expected location:

  • macOS: /Applications/NoteCove.app
  • Linux: /opt/NoteCove
  • Windows: %LOCALAPPDATA%\Programs\NoteCove

If you installed NoteCove elsewhere, the CLI won’t find it automatically.

”Cannot connect to NoteCove”

The desktop app must be running for CLI commands to work. Start NoteCove and try again.

Command Not Found

After installing, you may need to:

  1. Open a new terminal window (to reload shell config)
  2. Run source ~/.bashrc (or equivalent for your shell)

AI/LLM Integration

The CLI is designed for integration with AI assistants. When using Claude Code or similar tools:

  1. Install the CLI using the desktop app menu
  2. Initialize access in your project directory: notecove init --profile <id> --tasks-project MYPROJ --notes --events
  3. Approve the access request in the desktop app
  4. The AI can now use notecove commands within the authorized scope

Example: Claude Code Integration

# Search for context in notes
notecove note search "project requirements"

# Create notes from discussions
notecove note create "Meeting Notes - $(date +%Y-%m-%d)"

# Manage tasks
notecove task create "Follow up on API design"
notecove task ready  # see what needs work
notecove task search "authentication"

Requirements

  • NoteCove desktop app installed
  • Node.js 18 or later (only required for notecove serve remote access)
  • Supported shell (bash, zsh, fish, or PowerShell)

MCP Server

NoteCove ships a built-in Model Context Protocol (MCP) server. This lets any MCP-compatible AI client — Claude Desktop, Claude Code, or any other agent — interact with your NoteCove data directly: creating notes, managing tasks, reading comments, and running searches.

How It Works

The MCP server exposes a single notecove_cli tool that accepts any notecove CLI arguments and returns the output. Agents that already understand the CLI get the same surface over MCP with zero extra configuration.

MCP clients can use events recent to poll for recent changes without a long-lived connection:

["events", "recent", "--since", "42", "--json"]

Stdio Mode (local processes)

The simplest setup for local use. The AI client spawns notecove mcp as a subprocess and communicates over stdin/stdout. No separate auth needed — the subprocess inherits the working directory and finds your .notecove config the same way the CLI does.

Authentication: The MCP subprocess uses the same directory-walk lookup as the CLI: current directory → parent directories → ~/.config/notecove/.notecove → ~/.notecove. For clients like Claude Desktop that don’t launch from a specific project directory, use notecove init --global to write a config to ~/.config/notecove/ that’s always found.

Get your config snippet:

notecove mcp --print-config

This prints the JSON to paste into your Claude Desktop config file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "notecove": {
      "command": "/path/to/notecove",
      "args": ["mcp"]
    }
  }
}

Port Mode (HTTP + bearer token)

For headless servers, remote machines, SSH tunnels, or any MCP client that connects over HTTP. Binds to 127.0.0.1 by default; use --host 0.0.0.0 to expose on all interfaces.

# Start server on localhost:3456 (generates a bearer token on first run)
notecove mcp --port 3456

# Expose on all interfaces (for SSH tunneling)
notecove mcp --port 3456 --host 0.0.0.0

# Get the config snippet including the bearer token
notecove mcp --print-config --port 3456

The config snippet looks like:

{
  "mcpServers": {
    "notecove": {
      "type": "http",
      "url": "http://127.0.0.1:3456/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

The bearer token is stored in your .notecove config file and is separate from your CLI shared secret.

Claude Desktop limitation: Claude Desktop’s remote server UI requires HTTPS on a public hostname and will reject http:// or localhost URLs. Port mode works with Claude Code (claude mcp add --transport http notecove http://127.0.0.1:3456/mcp --header "Authorization: Bearer <token>"), Claude Code’s .mcp.json, and any other HTTP MCP client. For Claude Desktop specifically, use stdio mode or the .mcpb bundle below.

SSH tunnel example: Run port mode on a remote machine and forward it locally:

# On the remote machine
notecove mcp --port 3456

# Locally — tunnel the port
ssh -L 3456:localhost:3456 user@remotehost

# Then connect your local MCP client to http://127.0.0.1:3456/mcp

One-Click Install (.mcpb)

Generate a Claude Desktop Extension bundle for easy sharing:

notecove mcp --package

This emits notecove-mcp.mcpb — a ZIP archive you can double-click in Claude Desktop to install in one step (uses stdio mode under the hood).

For a complete end-to-end walkthrough of getting Claude Desktop connected to NoteCove, see Using NoteCove with Claude Desktop.

Note: The .mcpb / Desktop Extension spec is evolving.