@creator-notes/cnotes

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

The npm package is @creator-notes/cnotes. The unscoped package cnotes belongs to someone else. Do not install it.

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

On a terminal 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. With no terminal, cnotes init does not open a browser: it prints a sign-in URL and exits 2. cnotes init --help shows the heredoc to run with the key.

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

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, rubrics? }; read created notes from .results (not notes/ok). Each result carries displayId, title, type, and rubric.
• 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 sign-in
cnotes auth login

# API key. The key stays on stdin, off `ps` and out of shell history.
cnotes auth login --token-stdin <<'EOF'
cn_...
EOF

# Who is signed in. Exit 0 when a token is stored, exit 2 when signed out.
cnotes auth status
cnotes whoami

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

# The note plus every note it links to (outgoing rows and [[rel::ID]] / [[ID]])
cnotes notes get DECISION-6KN --expand
cnotes notes get DECISION-6KN --expand --depth 2 --rel assumes,depends-on --summary

# Partial reads set truncated and notice: 40 output notes, 40 candidates per
# direction/inline body per note, and 512 candidates across the whole walk.

# 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. First line is the timeline headline
# (verb-first, at most 110 characters). A blank line, then the body. The
# platform may rewrite an agent headline. The body is kept.
cnotes versions create MEETING-42 --description "Added the action items from the review" --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]

# Save a milestone. First line is the timeline headline: it must start with a
# past-tense verb and name a specific object ("Shipped the public comic canvas",
# never "V1"), at most 110 characters; anything else is rejected. A blank line,
# then the body. The platform may tidy an agent headline. The body is kept.
# An active operations run is stamped on.
cnotes canvas milestone create <canvasId> --message "Opened pricing question: charge for agents or the workspace?"
cnotes canvas milestone list <canvasId>
cnotes canvas milestone show <milestoneId>
cnotes canvas milestone rename <milestoneId> -m "Shipped the public comic canvas"

# 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" --content "# 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, richtext (the Text element — a markdown heading with no tint IS a heading), list, canvas (link), or section (frame)

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.

Or install everything as a Claude Code plugin: the cnotes skill, the optional skills below, and the remote MCP server, updated when a new version ships. Run /mcp once afterwards to sign the connection in.

claude plugin marketplace add https://cnotes.dev/marketplace.json
claude plugin install creator-notes-cli@cnotes

Optional skills (not auto-installed):

cnotes skills list
cnotes skills install fat-marker-flows     # Shape Up sketch journeys
cnotes skills install howto-filmstrips     # live UI screenshot how-tos
cnotes skills install wayfind              # decision maps for multi-session work
cnotes skills install shaping              # requirements, shapes, fit check, slices
cnotes skills install attention-planner    # one answerable card a day, loop closed by the agent
cnotes skills install transcript-timeline  # one interview, themes as rows, quotes on a timeline
cnotes skills install teach-workspace      # a course taught from the notes, one cited lesson a session

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:

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

Query the local copy (cnotes query)

cnotes query keeps a SQLite copy of the workspace's note metadata (titles, types, tags, canvases, who made each note, judged answers; never a note body) under ~/.cnotes/local-db/, syncs what changed since the last call, and answers from the copy. The query itself runs in milliseconds; each call first reads the workspace head and what changed, a second or two on a 5,000-note workspace, and the first copy takes about a minute at that size. The web app's Query panel uses the same copy format, so the two never disagree.

A copy on disk is the person's decision, as it is in the web app: it is off until cnotes config set-local-db on (or CNOTES_LOCAL_DB=on in the environment), which copies the current workspace right away. Until then cnotes query, and the cnotes_query MCP tool, refuse and say so. set-local-db off deletes every copy; cnotes query --forget deletes one workspace's.

With the copy on, cnotes notes list and the cnotes_notes_list MCP tool answer type, tag, title-text, pin and no-canvas lists from it as well, in the same row shape, counting every note. A list within 30 seconds of a sync, with no write from this machine since, reads only the file; otherwise it syncs first, so a note you just wrote is always there. Dimension filters ask the server, and so does any list when the copy cannot answer (no copy of that workspace yet, a copy from another cnotes version). One stderr line says which answered: From the local copy, synced 12 s ago. or From the server: <why>.

cnotes query pricing --type Decision,Insight      # words in the title, AND across fields
cnotes query --canvas CANVAS-12 --group-by tag    # notes on one canvas, grouped by tag
cnotes query --made-by api --group-by month       # what agents wrote through a cn_ key, by month
cnotes query --sql "SELECT type, COUNT(*) AS n FROM notes GROUP BY type ORDER BY n DESC"
cnotes query --rebuild                            # drop this workspace's copy and copy it again

--group-by takes type, canvas, tag, month, person, made-by, none, or <Type>:<dimension> for a judged dimension. --sql runs one read-only SELECT (--sql tables prints the tables). Needs Node.js 22.13 or newer.

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