CLI reference
Every command and flag. Run netherite <command> --help for the same text. Exit codes: 0 success, 1 the request was understood but there are problems (lint findings, a refused write), 2 it could not run at all (no workspace, bad config).
Every command takes --help, --version, --log-level <level> and --completions <shell>. With no command, netherite runs serve.
netherite
text
DESCRIPTION
Typed, linked knowledge in your git repository. Documentation: https://vicentelyrio.github.io/netherite/
USAGE
netherite <subcommand> [flags]
FLAGS
--dir, -C string Folder to work in (default: the current one). The workspace is found by walking up from it.
--port integer Port to listen on (default 4747, or the next free one).
--no-open Do not open the browser.
--app string Serve this built app folder instead of the bundled one.
--no-watch Do not watch for changes made outside the server.netherite serve
text
DESCRIPTION
Start the app, the API and MCP over HTTP on this machine (127.0.0.1 only). This is what `netherite` does with no command.
USAGE
netherite serve [flags]
FLAGS
--dir, -C string Folder to work in (default: the current one). The workspace is found by walking up from it.
--port integer Port to listen on (default 4747, or the next free one).
--no-open Do not open the browser.
--app string Serve this built app folder instead of the bundled one.
--no-watch Do not watch for changes made outside the server.netherite init
text
DESCRIPTION
Set up Netherite in a repository: config, folders, .gitignore and agent skills.
USAGE
netherite init [flags]
FLAGS
--dir, -C string Folder to work in (default: the current one). The workspace is found by walking up from it.
--content string Folder for the items.
--update Refresh the installed agent skills and AGENTS.md section. Skills you edited are kept.
--no-skills Do not install agent skills, the AGENTS.md section or the agent ruleset.
--json Print machine-readable JSON instead of text.netherite new
text
DESCRIPTION
Create an item with the next free ID.
USAGE
netherite new [flags] <type> <title...>
ARGUMENTS
type string goal, project, task, adr, doc, context or runbook
title... string The title; several words are joined.
FLAGS
--dir, -C string Folder to work in (default: the current one). The workspace is found by walking up from it.
--set key=value Set a field: --set project=PRJ-00001 (repeatable; values are YAML).
--body string Text for after the title.
--body-file string Read the text from a file.
--created-by string @handle to record. Default: from git config.
--template Start from the type's template, with its sections. --body and --body-file replace it.
--json Print machine-readable JSON instead of text.netherite templates
text
DESCRIPTION
List the starter templates, or print one to copy. A file in templates/ in the content folder replaces the built-in one.
USAGE
netherite templates [flags] [<type>]
ARGUMENTS
type string goal, project, task, adr, doc, context or runbook. Without it, list them. (optional)
FLAGS
--dir, -C string Folder to work in (default: the current one). The workspace is found by walking up from it.
--json Print machine-readable JSON instead of text.netherite scan
text
DESCRIPTION
Look through the repository for docs, runbooks, decision records and agent files, and write a draft batch for `netherite import`. It only reads, and writes nothing but the draft.
USAGE
netherite scan [flags]
FLAGS
--dir, -C string Folder to work in (default: the current one). The workspace is found by walking up from it.
--out string Where to write the draft batch, from the workspace root. Default: .netherite/local/scan.json.
--nested-agent-files Include the AGENTS.md and CLAUDE.md files deep in the tree. They are left out by default: agents read them in place, and they would fill the context budget.
--force Replace a draft that is already there.
--json Print machine-readable JSON instead of text.netherite import
text
DESCRIPTION
Bring existing docs, runbooks, context files and ADRs in from a reviewed batch file. Records where each came from, skips what is already imported, and never commits.
USAGE
netherite import [flags] <batch>
ARGUMENTS
batch string A JSON file: a list of entries, or { "mode": "copy", "entries": [...] }. Each entry has source, type (doc, runbook, context or adr) and optionally title, id, fields, body and mode. `netherite scan` writes a draft of one.
FLAGS
--dir, -C string Folder to work in (default: the current one). The workspace is found by walking up from it.
--update Bring items that were already imported up to date with their source.
--dry-run Say what would happen and write nothing.
--stub With mode "move", leave a one-line note where the original was.
--created-by string @handle to record. Default: from git config.
--json Print machine-readable JSON instead of text.netherite lint
text
DESCRIPTION
Check the workspace. Exit 0 when clean, 1 when problems remain, 2 when it cannot run.
USAGE
netherite lint [flags] [<path...>]
ARGUMENTS
path... string Only report on these files or folders. (optional)
FLAGS
--dir, -C string Folder to work in (default: the current one). The workspace is found by walking up from it.
--json Print machine-readable JSON instead of text.
--fix Apply the fixes lint offers (never commits).
--dry-run With --fix: show the diff and change nothing.
--fail-on string Exit 1 when a problem at least this serious is left: error, warning, info or never.
--no-git Skip checks that need git history (freshness).netherite renumber
text
DESCRIPTION
Give an item a new ID and update links to it. Resolves ID collisions after a merge.
USAGE
netherite renumber [flags] <item>
ARGUMENTS
item string Path or ID of an item.
FLAGS
--dir, -C string Folder to work in (default: the current one). The workspace is found by walking up from it.
--to string Use this ID instead of the next free one.
--rewrite-in string A file whose links to the old ID should follow it (repeatable).
--exact Renumber exactly this item, not the newest one that shares its ID.
--json Print machine-readable JSON instead of text.netherite mcp
text
DESCRIPTION
Serve this workspace to an AI agent over MCP (stdio). Add it to your agent's MCP config.
USAGE
netherite mcp [flags]
FLAGS
--dir, -C string Folder to work in (default: the current one). The workspace is found by walking up from it.
--no-watch Do not watch for changes made outside the server.netherite context sync
text
DESCRIPTION
Write the context items into CLAUDE.md and AGENTS.md, between markers. Never commits.
USAGE
netherite context sync [flags]
FLAGS
--dir, -C string Folder to work in (default: the current one). The workspace is found by walking up from it.
--check Change nothing; exit 1 if CLAUDE.md or AGENTS.md is out of date.
--json Print machine-readable JSON instead of text.netherite timeline
text
DESCRIPTION
Goals, projects, tasks and decisions on one time axis, read from git history. Needs git.
USAGE
netherite timeline [flags]
FLAGS
--dir, -C string Folder to work in (default: the current one). The workspace is found by walking up from it.
--from string First day, such as 2026-01-01. Default: the earliest date.
--to string Last day. Default: today, or the latest due date.
--json Print machine-readable JSON instead of text.netherite stats
text
DESCRIPTION
Tasks created and done, cycle time, goal areas and knowledge health for a period, against the one before. Needs git.
USAGE
netherite stats [flags]
FLAGS
--dir, -C string Folder to work in (default: the current one). The workspace is found by walking up from it.
--period string 30d, quarter or year.
--json Print machine-readable JSON instead of text.