Skip to content

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.

MIT licensed. Nothing is sent anywhere: it runs on your machine.