nod

nod is a small Go CLI for managing .nod files inside a local vault.

A .nod file is Markdown with YAML front matter. The YAML front matter is the source of truth for node metadata and graph links.

Status

This repository is still a proof of concept. The goal is a small, readable, Unix-friendly tool rather than a feature-complete system.

nod is intended to be the minimal core of a wider ecosystem. Richer tools can be built on top of the .nod file format and on top of nod's machine-friendly output, instead of turning nod itself into a monolith.

For this POC, nod is not trying to be the strict guardian of graph integrity.

• .nod files are the source of truth
• manual editing is a first-class workflow
• diagnostics are advisory
• users remain responsible for maintaining their own vaults

In practice, nod helps inspect and manipulate a vault, but it does not try to turn the vault into a hidden database with strong global guarantees.

What nod Is For

nod helps manage a local graph of Markdown-backed nodes.

Each node has:

• an immutable id
• a human-facing slug
• a title
• graph links
• optional tags
• optional custom front matter fields such as author, status, or priority

Typical uses:

• personal knowledge notes with explicit graph links
• project maps and ADR-like notes
• local inventories of tasks, ideas, or documents
• metadata-rich note files that can be queried from shell scripts

Why Other CLIs Can Build On It

nod is useful on its own, but it is also designed as a stable substrate for other command-line tools.

Other CLI applications can rely on three things:

• the vault layout is simple and local
• the .nod file format is plain Markdown plus YAML front matter
• existing nod commands already expose machine-friendly output such as --json, --raw, and stable check diagnostic codes

That means another tool can choose one of two approaches:

1. Read .nod files directly from disk.
2. Shell out to nod for common operations and consume its output.

The intended ecosystem stance is pragmatic rather than strict:

• companion tools may report inconsistencies
• companion tools should tolerate imperfect vaults where practical
• companion tools should avoid silently taking ownership of the vault away from the user

Examples of possible companion CLIs:

• map: render the active graph or adjacency views and export a vault to Graphviz
• dot: a task management tool with custom fields (author, priority, status etc.)
• pik: fuzzy-find nodes by tag or metadata
• kym: music library

Current Commands

• nod init
• nod create
• nod archive
• nod restore
• nod rename
• nod delete as an alias of archive
• nod list
• nod link
• nod unlink
• nod header
• nod print
• nod check

Vault Layout

nod works inside a local vault rooted by a .nod/ directory.

vault/
  .nod/
    archive/
  alpha.nod
  beta.nod

Archived nods live in .nod/archive/ and are excluded from the active graph until restored.

.nod Format

Minimal example:

---
id: 01JTB3A1M7Y6D2M4R8W9KQ7S5V
slug: project-x
title: Project X
links: []
tags: []
files: []
---

Reserved front matter fields for v0:

• id
• slug
• title
• links
• tags
• files

Unknown YAML fields are preserved when nod rewrites a file.

tags is a standard field used by nod list, but it is not required on older or manually created files. Missing tags behaves like an empty list.

The format is intentionally meant to stay readable and editable by humans. nod may standardize some metadata fields, but the vault should still make sense as ordinary files on disk.

Design Rules For Companion Tools

If you want to build another CLI on top of .nod files and nod, these rules are the safest working assumptions:

• treat the YAML front matter as the source of truth
• treat id as canonical identity
• treat slug as human-facing and mutable
• store graph relationships by id, not by slug
• assume archived nods live under .nod/archive/ and are outside the active graph
• preserve unknown YAML fields if your tool rewrites files
• do not parse semantic links from the Markdown body in v0
• treat diagnostics as advisory, not as proof that a vault is fully correct
• prefer explicit local edits over hidden global repair behavior

Practical guidance:

• if your tool only needs metadata, read the front matter and ignore the body
• if your tool needs stable automation, prefer nod check --json, nod header --json, nod print --json, and nod list --json
• if your tool introduces custom metadata, use your own front matter keys and let nod preserve them
• if your tool depends on diagnostics, key off code, not message
• if your tool rewrites files, optimize for preserving readability and user-owned structure

Case Study

One concrete use case is a lightweight editorial or project-tracking vault.

Example nodes:

• one node per project
• one node per article or feature idea
• one node per person or team

Custom metadata can be added directly in front matter, for example:

---
id: 01JTB3A1M7Y6D2M4R8W9KQ7S5V
slug: article-api-design
title: Article API Design
links: []
tags:
  - writing
  - draft
files: []
author: jack
status: drafting
---

With the features already implemented, you can:

• list all draft notes tagged writing
• rename a node without changing its identity
• archive inactive work
• validate the vault before another tool consumes it

Quick Start

go build ./...
./nod init
./nod create --tag work --tag urgent "Project X"
./nod create --slug inbox --title "Inbox"
./nod list --tag work
./nod list --where title="Project X"
./nod link project-x inbox
./nod rename project-x active-project
./nod header --json active-project inbox
./nod print --raw title active-project
./nod check active-project
./nod check --json

Full Workflow

This workflow uses the features implemented today and is intended to be easy to test and show.

1. Initialize a vault

mkdir demo-vault
cd demo-vault
../nod init

2. Create a few nodes

../nod create --tag work --tag urgent "Project X"
../nod create --tag work "Inbox"
../nod create --tag people "Alice"

3. Add custom metadata manually when needed

Because .nod files are plain Markdown plus YAML, you can edit them directly.

For example, update inbox.nod and add:

author: jack
status: open

4. Explore the vault

../nod list
../nod list --tag work
../nod list --where author=jack
../nod list --tag work --where status=open

5. Create graph relationships

../nod link project-x inbox
../nod link project-x alice

6. Inspect metadata in machine-friendly form

../nod header --json project-x inbox alice
../nod print --json tags project-x
../nod print --raw title project-x

7. Rename a node without changing identity

../nod rename project-x active-project
../nod list
../nod header --json active-project

The node keeps the same id, but its slug and filename change.

8. Archive and restore

../nod archive inbox
../nod list
../nod list --archived
../nod restore inbox

9. Validate the vault

../nod check
../nod check --json
../nod check active-project
../nod check --archived inbox

This is the step another CLI can use before reading the vault in bulk.

nod check SLUG keeps the same output and exit-code conventions as nod check, but limits validation to the targeted file. It is useful when you want a quick local diagnosis without surfacing unrelated vault-wide issues.

check is a diagnostic report, not a guarantee that the vault is globally sound. It exists to help humans and companion tools inspect a vault, not to take control of the vault away from the user.

rename

nod rename OLD-SLUG NEW-SLUG changes the human-facing slug of an active nod.

• the nod keeps the same immutable id
• the file is renamed to NEW-SLUG.nod
• the command rejects invalid slugs
• the command rejects conflicts with both active and archived nods

list

nod list shows active nods by default and prints one line per nod:

project-x	Project X
inbox	Inbox

Useful options:

• --json prints a JSON array of front matter objects
• --archived lists archived nods instead of active ones
• --tag TAG filters by exact tag and can be repeated
• --where KEY=VALUE filters by exact scalar string field match and can be repeated

All filters use AND semantics. tags is filtered only through --tag, not through --where.

Examples:

./nod list
./nod list --tag work
./nod list --tag work --tag urgent
./nod list --where author=jack
./nod list --tag work --where status=open
./nod list --json --archived

Machine-Friendly Output

Several commands are already usable as building blocks for other tools:

• nod list --json
• nod header --json
• nod print --json
• nod print --raw
• nod check --json

Examples:

./nod list --json --tag work
./nod header --json active-project inbox
./nod print --raw title active-project
./nod print --json tags active-project

check --json

nod check can run in two scopes:

• nod check checks the whole vault
• nod check SLUG checks one nod only
• nod check --archived SLUG checks one archived nod only

Single-node check is intentionally local. It validates the targeted file and the coherence of its stored links, but it does not report vault-wide issues such as duplicate slug, duplicate id, or missing backlinks.

As elsewhere in nod, these diagnostics are advisory. They are meant to help users and tools understand the current state of the vault, not to promise that the graph is perfectly robust.

nod check --json returns a JSON report shaped like this:

{
  "issues": [
    {
      "code": "broken_link",
      "path": "/path/to/alpha.nod",
      "message": "broken link to missing id \"01ABC...\""
    }
  ]
}

The public API contract for check --json is:

• The top-level shape is always {"issues":[...]}.
• Success is reported as {"issues":[]}.
• Each issue currently guarantees code, path, and message.
• code values are stable lowercase ASCII snake_case identifiers.
• path is an absolute filesystem path.
• message is for humans and may be reworded over time.
• Existing codes and field meanings are stable.
• New codes and optional fields may be added later.
• Consumers should ignore unknown future fields.
• Issue ordering is stable: path, then code, then message.
• Duplicate issues are removed using code + path + message.
• JSON formatting is not part of the API contract.
• The JSON schema is currently unversioned.

nod check --json still exits non-zero when issues are found:

• 0: no issues
• 1: check completed and found issues
• 2: operational failure, so no trustworthy report was produced

The message is for humans. The code is the stable machine-facing handle for scripts and future tools.

Current diagnostic codes include:

• missing_archive_dir
• invalid_front_matter
• missing_required_field
• invalid_slug
• filename_slug_mismatch
• duplicate_id
• duplicate_slug
• duplicate_link
• self_link
• broken_link
• link_to_archived
• missing_backlink

Additional rules that are part of the current API:

• missing_required_field is shared across all missing reserved fields.
• invalid_slug is distinct from missing_required_field.
• invalid_front_matter covers front matter parse failures, including malformed delimiters and YAML parse errors.
• missing_archive_dir covers both a missing archive directory and a malformed non-directory archive path.
• duplicate_id and duplicate_slug are checked across the whole vault, including archived nods.
• For duplicate id and slug conflicts, the issue is reported on the later conflicting file, and the earlier conflicting path only appears in message.
• Archived nods are still checked as documents for parse, validation, filename, and uniqueness problems.
• Archived nods are outside the active graph for backlink consistency.
• Consumers should not parse path to infer metadata such as whether a nod is archived.

Development

Common commands:

gofmt -w main.go main_test.go internal/nod/*.go
go test ./...

More Detail

See SPEC.md for the current v0 mini-spec.