CLI Reference

Manage notes, search, and connect AI agents from the terminal with the mnotes CLI.

Installation

bash

npm install -g mnotes-cli

After installation, run mnotes --version to verify the CLI is available.

Configuration

The CLI reads configuration from environment variables or command-line flags. Flags take precedence over environment variables.

Environment Variables

Variable	Description
`MNOTES_API_KEY`	API key for authentication
`MNOTES_URL`	Base URL of your m-notes instance (defaults to `http://localhost:3000`)
`MNOTES_WORKSPACE_ID`	Default workspace ID

Global Options

Flag	Description
`--api-key <key>`	API key (overrides `MNOTES_API_KEY`)
`--url <url>`	Base URL (overrides `MNOTES_URL`, defaults to `http://localhost:3000`)
`--json`	Output as JSON (useful for scripting)
`--version`	Show version number
`--help`	Show help for a command

Commands

All commands support the global --json flag for machine-readable output.

`mnotes list`

List notes in your workspace.

Option	Description
`--workspace-id <id>`	Workspace to list from
`--folder-id <id>`	Filter by folder
`--cursor <cursor>`	Pagination cursor
`--limit <n>`	Max notes to return

bash

mnotes list --workspace-id ws_abc123 --limit 10

`mnotes read <id>`

Read a note by ID, printing its full content to stdout.

bash

mnotes read note_abc123

`mnotes search <query>`

Search notes by keyword or semantic similarity.

Option	Description
`--semantic`	Use vector search instead of full-text
`--workspace-id <id>`	Scope search to workspace

bash

mnotes search "authentication flow" --semantic

`mnotes create`

Create a new note. Content is read from stdin.

Option	Description
`--title <title>`	Note title (required)
`--folder-id <id>`	Target folder
`--workspace-id <id>`	Target workspace

bash

echo "# Meeting Notes" | mnotes create --title "Standup 2026-04-09"

`mnotes update <id>`

Update an existing note. New content is read from stdin.

Option	Description
`--title <title>`	New title for the note

bash

echo "Updated content" | mnotes update note_abc123 --title "New Title"

`mnotes delete <id>`

Delete a note by ID.

Option	Description
`--yes`	Skip the confirmation prompt

bash

mnotes delete note_abc123 --yes

Agent Connect

The mnotes connect command configures AI coding agents to use your m-notes instance as a knowledge base via MCP. It writes the necessary config files to the current directory.

bash

mnotes connect claude-code --api-key sk_xxx --workspace ws_abc123

Options

Option	Description
`--list`	Show available connect targets
`--status`	Show connection status for configured agents
`--url <url>`	m-notes instance URL
`--api-key <key>`	API key for the connection
`--workspace <id>`	Workspace ID to scope the connection
`--config-path <path>`	Custom config directory (openclaw only)

Supported Targets

Target	Description	Files Written
`claude-code`	Writes .mcp.json and CLAUDE.md with m-notes MCP configuration and agent instructions.	`.mcp.json, CLAUDE.md`
`codex`	Writes .mcp.json and AGENTS.md for OpenAI Codex integration.	`.mcp.json, AGENTS.md`
`openclaw`	Writes instructions.md to the OpenClaw workspace config directory.	`instructions.md`

Scripting Examples

The create and update commands read content from stdin, making them composable with pipes. Combine with --json for automation.

bash

# Create note from file
cat notes.md | mnotes create --title "My Notes"

# Get JSON output for scripting
mnotes list --json | jq '.[].title'

# Search and read first result
mnotes search "deploy" --json | jq -r '.[0].id' | xargs mnotes read