@notegraph/cli

notegraph reads and writes one NoteGraph graph from the command line. It is built for coding agents — Claude Code, Codex, Cursor, anything that can run a shell command — so a project's context lives in a graph every collaborator's agent shares, instead of being re-explained every session.

npm install -g @notegraph/cli
notegraph guide            # how to store and find context so it is found again — paste into your agent's instructions

Connect to a graph

In the NoteGraph app open a graph card → gear → Agent access, name a token, and save what it shows as .notegraph in your repository (the file is found in the working directory or any directory above):

{ "url": "https://notes.example.com:9020", "token": "ng_1f2e3d4c.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" }

Or notegraph init <url> <token>, or NOTEGRAPH_URL + NOTEGRAPH_TOKEN in the environment. The token is the scope: one graph, no way to reach another.

Commands

notegraph guide                                    how to use the graph well — agent-agnostic, ~10 KB
notegraph index [--compact] [--depth N] [--tag T] [--label L] [--since 2d]
notegraph search <words> [--limit N] [--offset N] [--in <id>] [--tag T] [--label L]
notegraph read <id|root> [--outline] [--section "<heading>"]   "root" is the graph root — its own README
notegraph labels
notegraph create --title T [--parent <id>] [--body B | --body-file F | --stdin] [--label L] [--subgraph]
notegraph append <id> --body B                     atomic on the server
notegraph write <id> [--title T] [--body B] [--if-match <updated>]
notegraph import <file.md> [--parent <id>] [--split h2|h3|none]
notegraph tag <id> <name>  ·  notegraph untag <id> <name>
notegraph delete <id>  ·  notegraph files <id>  ·  notegraph transcribe <id> --file <fileId>  ·  notegraph rewrite <id> --prompt P
notegraph help [--json]                            every command; --json is a machine-readable manifest

--json on any command prints the raw response. Search returns ranked hits with snippets and a path, never bodies — read is the follow-up, --outline and --section for long notes.

Start of an agent session

notegraph read root                    # how this graph is organised and meant to be queried — read it first
notegraph index --compact --depth 1    # the first ring with ids, ~1–2 KB (--depth 2 when the ring is topics)
notegraph index --since 2d             # what changed while you were away
notegraph search "<what you need>"     # then read <id> --section "<heading>"

The root node is the graph's README: whatever its people wrote there about shelves, tags, labels and sections overrides the defaults in notegraph guide.

The server side is the NoteGraph app: https://github.com/kalevski/notegraph — docs/cli.md there documents the agent API this tool talks to.