@creator-notes/cli

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

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

Quick Start

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

npx @creator-notes/cli@latest init

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

After init:

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

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

Commands

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

Authentication

# Browser-based OAuth (recommended)
cn auth login

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

# Check session
cn auth status

Notes

cn 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)
cn notes create --notes '{"key":"A","type":"Insight","markdown":"# Quick idea","tags":["ux","onboarding"]}'

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

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

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

# Update metadata
cn 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:

cn 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
cn 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.
cn 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
cn 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
cn 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.
cn canvas activity <canvasId> [--limit 50]

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

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

# Create from template
cn 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 cn 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.

cn canvas agent-run wrap \
  --canvas <canvasId> \
  --prompt "Reorganize roadmap into Q1/Q2 clusters" \
  -- bash -c '
    cn canvas add-text "$CANVAS" --text "Q1" --x 100 --y 100
    cn 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 (cn canvas place)

Most of the time you shouldn't be computing pixel coordinates by hand — agents and humans alike are bad at it. cn 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" }
        ] }
    ]
  }
}

cn 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/cn/SKILL.md for the full DSL reference and more examples.

AI Integration

Claude Code (recommended)

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

After that, Claude will use cn 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:

cn init

2. Generate the MCP config:

cn 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": {
    "cn": {
      "command": "node",
      "args": ["/path/to/dist/mcp-server.js"],
      "env": {
        "CN_SERVER": "https://creatornotes.app",
        "CN_TOKEN": "<your-token>",
        "CN_WORKSPACE": "<your-workspace-id>"
      }
    }
  }
}

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

Manual Skill Install

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

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

Scripting

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

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

# Several interlinked notes with @key placeholders
cn 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