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:

See which shells are available (bash, zsh, fish, PowerShell)
Select which shells to install for
Preview the shell configuration that will be added
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> --project MYPROJ

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

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

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

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

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

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

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:

Scope	What It Controls
Projects	Which task projects you can access
Notes	Whether you can access notes at all (off by default)
SDs	Which storage directories your notes access covers
Folders	Optionally 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"

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"

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!"

Folders

List folders:

notecove folder list

Create a folder:

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

Projects

List projects:

notecove project list

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

Variable	Description
`NOTECOVE_DEBUG`	Enable debug logging

Shell Integration Details

How It Works

The CLI installation adds a shell function that:

Checks if Node.js is available (required to run the CLI)
Locates the bundled CLI in the NoteCove app resources
Executes the CLI with your arguments

Shell Config Locations

Shell	Config 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.

”Node.js is required”

The CLI requires Node.js to run. Install Node.js from nodejs.org (version 18 or later recommended).

”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:

Open a new terminal window (to reload shell config)
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:

Install the CLI using the desktop app menu
Initialize access in your project directory: notecove init --profile <id> --project MYPROJ --notes
Approve the access request in the desktop app
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
Supported shell (bash, zsh, fish, or PowerShell)

Developer Tools - Debugging and inspection tools
Tasks & Projects - Task management features