Skip to content

CLI

notio init

notio init [--force] [--write-config]

Creates the workspace directories, default templates, and index files.

Options:

  • --force: overwrite default templates
  • --write-config: write a default notio.toml when it does not exist

notio note

notio note TYPE [--owner NAME] [--title TEXT] [--date YYYY-MM-DD] [--timestamp VALUE] [--force]

Creates or updates a note and refreshes indexes.

Examples:

notio note daily
notio note weekly --date 2026-03-09
notio note meeting --title "Design review"

notio toc

notio toc [TYPE] [--all]

Regenerates index files without creating notes. Each type index is rendered as a card feed with metadata chips. Types that define toc_groupby get ordered group headings with counts, and closed groups (done, cancelled, resolved) are collapsed by default. See Maintain Indexes for details on card styling and group ordering.

notio diataxis init

notio diataxis init [--mkdocs]

Scaffolds a Diataxis documentation structure under the configured docs_root (default docs/).

Creates four section directories with index files:

  • tutorials/index.md
  • how-to/index.md
  • explanation/index.md
  • reference/index.md

Also creates a root docs/index.md linking to all sections.

Options:

  • --mkdocs: print a suggested mkdocs.yml nav snippet to stdout

Idempotent — existing files are not overwritten.

notio diataxis add

notio diataxis add SECTION SLUG [--title TEXT]

Creates a new page in a Diataxis section using a section-appropriate template.

Each section type has its own template structure:

  • tutorials: What you will learn, Prerequisites, Steps, Next steps
  • how-to: Problem, Prerequisites, Solution steps, See also
  • explanation: Overview, Discussion, Further reading
  • reference: Synopsis, Details, See also

The section index is automatically updated after adding a page.

Section names accept aliases: tutorial, howto, how_to, ref, explain.

Examples:

notio diataxis add tutorial quickstart --title "Getting Started"
notio diataxis add how-to custom-templates
notio diataxis add ref cli-reference --title "CLI Reference"

notio diataxis toc

notio diataxis toc [SECTION] [--all]

Regenerates Diataxis section index files. Without arguments or with --all, rebuilds all section indexes and the root docs index.

notio mcp

notio mcp

Starts the FastMCP server over stdio. Requires pip install notio[mcp].

Exposes all notio operations as MCP tools for agent consumption:

  • note_list — list recent notes, optionally filtered by type
  • note_latest — content of the most recent note
  • note_read — read a specific note by path
  • note_search — search notes by keyword (title, tags, content)
  • note_update — update frontmatter fields of an existing note
  • note_links — suggest wikilinks to related notes (optional: apply)
  • note_create — create a new note
  • note_types — list configured note types
  • toc_rebuild — regenerate note indexes
  • diataxis_init — scaffold Diataxis docs
  • diataxis_add — add a page to a section
  • diataxis_toc — rebuild section indexes
  • config_show — show current configuration

The server resolves the project root from the --root flag or the NOTIO_ROOT environment variable.

Library API

The following functions are exported from notio for programmatic use:

from notio import list_notes, latest_note, read_note, search_notes, update_note_frontmatter

list_notes(root, *, note_type=None, limit=20)

Returns a list of dicts with note metadata (path, type, frontmatter fields). Sorted by modification time, newest first.

latest_note(root, *, note_type=None)

Returns the most recent note as a dict including full content, or None.

read_note(root, path)

Reads a specific note by its relative path. Returns a dict with content and frontmatter, or None.

search_notes(root, query, *, note_type=None, limit=10)

Searches notes by keyword matching against title, tags, and content. Returns results ranked by relevance (hit count), then by recency.

update_note_frontmatter(root, path, fields)

Merges fields into existing frontmatter of a note. Preserves key order, overwrites existing keys, appends new ones. Returns the updated metadata dict.