@creator-notes/cnotes

CLI for CreatorNotes — create notes, build canvases, search knowledge, and manage workspaces from the terminal.

Works as a standalone CLI (cnotes) and as an MCP server (cnotes-mcp) for AI assistants like Claude.

Quick Start

One command sets everything up — auth, workspace, Claude Code skill, and (optionally) a global cnotes shortcut:

npx @creator-notes/cnotes@latest init

The wizard opens your browser to sign in (the only manual step), then offers to install the Claude Code skill and cnotes globally so future calls are instant.

After init:

cnotes notes list            # Browse your notes
cnotes notes create --notes '{"key":"A","type":"Meeting","markdown":"# Standup\nAgenda…"}'
cnotes search semantic "onboarding flow"

Prefer to install globally up front? npm install -g @creator-notes/cnotes && cnotes init works too.

Commands

| Command | Alias | Description | |---------|-------|-------------| | cnotes init | | Interactive setup wizard | | cnotes auth login | | Authenticate via browser or API token | | cnotes notes list\|get\|create\|update\|delete | cnotes n | Manage notes (create accepts one or many items) | | cnotes notes bulk-retype | | Retype multiple notes to a new type | | cnotes notes move | | Move a note to another workspace (copies content, archives source, cross-links) | | cnotes versions list\|create | cnotes v | Note version history | | cnotes canvas list\|get\|create\|delete | cnotes c | Manage canvases | | cnotes canvas place | | Declarative layout — server packs items with no overlap | | cnotes canvas add-node\|add-text\|add-richtext\|add-list\|add-link | | Add a single node at explicit --x/--y | | cnotes canvas bulk-add\|bulk-move\|bulk-remove | | Bulk canvas operations — requires explicit coordinates | | cnotes canvas from-template | | Create canvas from template | | cnotes search semantic | cnotes s | Semantic search across notes | | cnotes timeline | cnotes tl | Recent activity feed | | cnotes relationships list | cnotes rel | Note relationships | | cnotes types list\|create\|update | cnotes t | Manage note types (supertags) | | cnotes memory query\|facts\|entities | cnotes mem | Query workspace knowledge | | cnotes workspace list\|select\|current | | Workspace management | | cnotes config get-server\|set-server | | CLI configuration | | cnotes mcp setup | | Print MCP server config for Claude |

Global Flags

--json              Output raw JSON (for piping / scripting)
-q, --quiet         Minimal output (IDs only)
-w, --workspace <id>   Override active workspace
--server <url>         Override server URL

Output Contract

One contract across every command:

• Success is the exit code, not a body field. Exit 0 is success; never look for an ok key. Failures use a typed table: 2 auth, 3 validation, 4 not found, 5 conflict, 6 rate limit, 7 permission, 8 subscription required, 9 network (the request never reached the server — DNS/TCP/TLS failed; the JSON carries the low-level cause, e.g. ENOTFOUND). Re-running a write because a key looked empty will duplicate it.
• Reads return a bare array; writes return an envelope. notes list/get/search --json pipe to jq '.[0]'. notes create --json returns { results, relationshipsCreated, relationshipTypesCreated }; read created notes from .results (not notes/ok).
• Errors teach. A --json failure prints { error, code, exitCode, hint } to stderr, where hint names the command that fixes it (a bad workspace id returns a 404 with resource: "workspace" and a cnotes workspace list hint, not a bare 500).

Authentication

# Browser-based OAuth (recommended)
cnotes auth login

# API token (CI / non-interactive)
cnotes auth login --token <key>

# Check session
cnotes auth status

Notes

cnotes notes create accepts one item or many — pass --notes either as a single JSON object or an array of objects. Use [@key: Title](relationship:references) inside markdown to cross-reference another item in the same batch — @key is replaced with the new note's display ID after creation.

# Single note (object form)
cnotes notes create --notes '{"key":"A","type":"Insight","markdown":"# Quick idea","tags":["ux","onboarding"]}'

# Multiple interlinked notes (array form)
cnotes notes create --notes '[
  {"key":"A","type":"PainPoint","markdownFile":"./problem.md"},
  {"key":"B","type":"Insight","markdown":"# Solution\nFixes [@A: Problem](relationship:references)."}
]'

# List with filters
cnotes notes list --type Meeting --pinned --limit 10

# Get one or many by display ID (single round-trip, always returns array in input order)
cnotes notes get MEETING-42
cnotes notes get MEETING-42 PRD-3 IDEA-7

# Update metadata
cnotes notes update MEETING-42 --pin --tags "important,q2"

If any item is malformed, the command exits non-zero and lists every bad item together — item <index> (<key>): <field>: <reason> — so you can fix the whole batch in one shot. With --json, the same per-item errors come back under details.items for programmatic parsing.

Bulk Retype

Change the type of multiple notes at once:

cnotes notes bulk-retype --ids '["NOTE-1","NOTE-3","NOTE-5"]' --type Insight --json

Content Updates

Content and metadata are separate operations:

# Update content -> create a new version
cnotes versions create MEETING-42 --description "Added action items" --markdown-file ./updated.md

# Update metadata (type, tags, pin, archive). Title is read-only —
# change it by creating a new version with a different # h1 heading.
cnotes notes update MEETING-42 --type Insight --tags "auth,security" --pin

Canvas

Values in <angle-brackets> are placeholders — replace them with real IDs from your workspace.

# Create a canvas
cnotes canvas create "Sprint Review"

# Read every note on a canvas as one concatenated markdown document, in
# display order — for thinking across a canvas in a single round-trip
cnotes canvas read <canvasId>

# Recent activity on a canvas: edits, agent runs, gestures, restores —
# newest first. Use this to see what changed (and who changed it) before
# editing, or to confirm a previous agent run actually applied.
cnotes canvas activity <canvasId> [--limit 50]

# Place items with a declarative layout (preferred — no x/y math)
cnotes canvas place <canvasId> --spec ./layout.json

# Add nodes with explicit coordinates (escape hatch — pixel-perfect templates only)
cnotes canvas bulk-add <canvasId> --notes '[{"noteId":"NOTE-1","x":100,"y":100},{"noteId":"NOTE-2","x":500,"y":100}]'
cnotes canvas add-edge <canvasId> --source <nodeId> --target <nodeId> --label "blocks"

# Create from template
cnotes canvas from-template sprint-retrospective --populate

Available templates: sprint-retrospective, swot-analysis, kanban-board, feature-prioritization, meeting-notes, product-roadmap

Agent-run lifecycle

When an AI agent makes multiple canvas changes for a single user request, wrap the whole sequence in cnotes canvas agent-run wrap. The server captures auto-checkpoints around the work, clusters every mutation into a single revertable operation, and attaches the prompt as intent metadata.

cnotes canvas agent-run wrap \
  --canvas <canvasId> \
  --prompt "Reorganize roadmap into Q1/Q2 clusters" \
  -- bash -c '
    cnotes canvas add-text "$CANVAS" --text "Q1" --x 100 --y 100
    cnotes canvas add-edge "$CANVAS" --source <id1> --target <id2>
  '

The wrap form does begin → run-your-command → end automatically, even if your command fails. For details on the underlying agent-run begin / end pattern (used when shell-wrapping isn't possible) see SKILL.md.

Declarative layout (cnotes canvas place)

Most of the time you shouldn't be computing pixel coordinates by hand — agents and humans alike are bad at it. cnotes canvas place takes a layout document that describes structure (rows, columns, what's anchored to what) and the server measures every item, packs them with no overlaps, and inserts them in a single batch. The call is best-effort: per-item failures are reported in the response (HTTP 207) but successful items stay on the canvas.

Four building blocks:

• stack — items flow along one axis (vertical or horizontal), like CSS flexbox
• grid — N columns, items wrap to new rows, like CSS grid auto-flow
• anchor — place a sub-tree relative to an existing canvas node
• item — a leaf: note, text, richtext, list, or canvas (link)

Example — a richtext header above a 3-column grid of notes:

{
  "root": {
    "kind": "stack", "axis": "vertical", "gap": "medium",
    "items": [
      { "kind": "item", "type": "richtext",
        "content": "# Goals\nQ2 commitments.", "size": "medium" },
      { "kind": "grid", "columns": 3, "gap": "tight",
        "items": [
          { "kind": "item", "type": "note", "noteId": "GOAL-1" },
          { "kind": "item", "type": "note", "noteId": "GOAL-2" },
          { "kind": "item", "type": "note", "noteId": "GOAL-3" }
        ] }
    ]
  }
}

cnotes canvas place <canvasId> --spec ./goals.json --json

gap accepts "tight", "medium", "spacious", or a raw pixel number. Edges between items can be added with a top-level "edges" array referencing item key fields. See skills/cnotes/SKILL.md for the full DSL reference and more examples.

AI Integration

Claude Code (recommended)

The simplest path: run npx @creator-notes/cnotes@latest init and accept the "Install the Claude Code skill?" prompt. The wizard copies the skill into ~/.claude/skills/cnotes/SKILL.md so every Claude Code session learns the full cnotes command reference automatically.

After that, Claude will use cnotes whenever you ask about notes, canvases, or workspace tasks — no further setup.

Claude Desktop (MCP Server)

Add CreatorNotes as a tool server so Claude Desktop can read and write your notes directly.

1. Authenticate and select a workspace:

cnotes init

2. Generate the MCP config:

cnotes mcp setup --json

3. Copy the output into your Claude Desktop config file:

| OS | Config path | |----|-------------| | macOS | ~/Library/Application Support/Claude/claude_desktop_config.json | | Windows | %APPDATA%\Claude\claude_desktop_config.json | | Linux | ~/.config/Claude/claude_desktop_config.json |

The output looks like this — merge it into your existing config:

{
  "mcpServers": {
    "cnotes": {
      "command": "node",
      "args": ["/path/to/dist/mcp-server.js"],
      "env": {
        "CNOTES_SERVER": "https://creatornotes.app",
        "CNOTES_TOKEN": "<your-token>",
        "CNOTES_WORKSPACE": "<your-workspace-id>"
      }
    }
  }
}

4. Restart Claude Desktop. The CreatorNotes MCP tools will appear in the tool picker.

Manual Skill Install

cnotes init installs the user-level skill (~/.claude/skills/cnotes/SKILL.md) for you. If you want to scope the skill to a single project instead:

mkdir -p .claude/skills/cnotes
cp $(npm root -g)/@creator-notes/cnotes/skills/cnotes/SKILL.md .claude/skills/cnotes/SKILL.md

Scripting

# Chain commands with quiet mode (--quiet emits one display ID per line)
NOTE_ID=$(cnotes notes create --notes '{"key":"A","type":"Note","markdown":"# Quick note"}' -q)
cnotes canvas add-node <canvasId> --note "$NOTE_ID"

# JSON output for parsing
cnotes notes list --json | jq '.[0].displayId'

# Several interlinked notes with @key placeholders
cnotes notes create --json --notes '[
  {"key":"A","type":"PainPoint","markdownFile":"./problem.md"},
  {"key":"B","type":"Insight","markdown":"# Solution\nFixes [@A: Problem](relationship:references)."}
]'

Requirements

• Node.js >= 18
• A CreatorNotes account

License

MIT