Command Reference

This page lists every notes command, generated from the same registry that powers notes help.

`notes root`

Print the notes vault root

notes root [--projects]

Options

Option	Description
`--projects`	Print the projects directory

Examples

notes root
notes root --projects

`notes context`

Print project-note context for integration plugins

notes context --command <name> [--json]

Resolve the current project, its notes directory, and relevant existing notes. The —json form is intended for OpenCode plugins that render their own prompt context.

Options

Option	Description
`--command` `<name>`	Integration command name requesting context
`--json`	Emit structured context JSON

Examples

notes context --command notes-list
notes context --command note-reference --json

`notes list`

List repository notes

notes list [--all] [--tag <tag>] [--format labels|json]

Options

Option	Description
`--all`	Show notes from every projects directory
`--tag` `<tag>`	Only include notes with this tag
`--format` `<labels\|json>`	Output format (one of: `labels`, `json`)

Examples

notes list
notes list --all
notes list --tag handoff
notes list --format json

`notes read`

Print a note file

notes read --path <path> [--json]

Options

Option	Description
`--path` `<path>`	Absolute path to a note file inside the notes vault
`--json`	Emit content and revision hash as JSON

Examples

notes read --path ~/Documents/notes/projects/owner/repo/topic.md

`notes write`

Write stdin to a note file, then commit and push it

notes write --path <path> --stdin [--expected-hash <sha256>] [--json]

Options

Option	Description
`--path` `<path>`	Absolute path to a note file inside the notes vault
`--stdin`	Read note content from stdin
`--expected-hash` `<sha256>`	Fail if the existing note no longer has this SHA-256 hash
`--json`	Emit the complete mutation result as JSON

Examples

notes write --path ~/Documents/notes/projects/owner/repo/topic.md --stdin

`notes delete`

Delete a note file, then commit and push it

notes delete --path <path> [--json]

Options

Option	Description
`--path` `<path>`	Absolute path to a note file inside the notes vault
`--json`	Emit the complete mutation result as JSON

Examples

notes delete --path ~/Documents/notes/projects/owner/repo/topic.md

`notes handoffs`

Browse handoff-tagged notes

notes handoffs [--all] [--list] [--format labels|json]

Handoffs are normal notes tagged handoff. Priority metadata is shared with notes. With no flags this opens the interactive notes TUI filtered to handoffs.

Options

Option	Description
`--all`	Show notes from every projects directory
`--list`	List handoffs to stdout instead of opening the TUI
`--format` `<labels\|json>`	Output format (one of: `labels`, `json`)

Examples

notes handoffs
notes handoffs --all
notes handoffs --list
notes handoff

`notes mcp`

Run the notes MCP server over stdio

notes mcp

Start a Model Context Protocol server exposing note read, list, write, and delete tools.

Examples

notes mcp

`notes daemon`

Process captured notes through local OpenCode

notes daemon --config <path> [--once]

Poll a configured GitHub issue queue, claim work through custom Git refs, and post local OpenCode results. The OpenCode server password is read from OPENCODE_SERVER_PASSWORD.

Options

Option	Description
`--config` `<path>`	Daemon YAML configuration path
`--once`	Process one queue snapshot and exit

Examples

notes daemon --config ~/.config/notes/daemon.yml
notes daemon --config ~/.config/notes/daemon.yml --once

`notes completions`

Generate shell completions

notes completions [bash|fish|zsh]

Generate shell completions for notes.

Arguments

Argument	Description
`<shell>`	One of: `bash`, `fish`, `zsh`.

Examples

notes completions zsh
notes completions bash
notes completions fish

`notes help`

Show notes help

notes help [command]

Arguments

Argument	Description
`<command>`	Optional command to show help for. One of: `root`, `context`, `list`, `read`, `write`, `delete`, `handoffs`, `mcp`, `daemon`, `completions`.

Examples

notes help
notes help list