CLI reference

Reference

The threemd CLI

threemd is the command-line tool for 3md, built in Swift and shipped with the canonical ThreeMD parser. It validates documents, prints their metadata, inspects cross-plane links, and renders to HTML. It self-documents: run threemd --help.

A file path of - reads from standard input, so you can pipe documents in.

Install

brew install CorvidLabs/tap/threemd

You can also build it from the repository with Swift Package Manager. In that case the commands below are invoked as swift run threemd <subcommand> <file>.

Subcommands

validate, info, links, and check-links also accept --json for CI, editor integrations, and other tooling. (html does not take --json; it always prints HTML.)

Examples

Validate a file:

$ threemd validate week.3md
ok

On a parse error, validate exits non-zero and writes the message to stderr. The --json form gives a stable, machine-readable error with a code, message, and (when available) the 1-based source line:

$ threemd validate broken.3md --json
{
  "error" : {
    "code" : "missingVersion",
    "line" : 2,
    "message" : "..."
  },
  "ok" : false
}

Inspect document metadata and planes:

$ threemd info week.3md
version: 1.0
axis:    time
title:   My Week
planes:  3
  z=0 label=Monday
  z=1 label=Tuesday
  z=2 label=Wednesday

List cross-plane links and spot dangling ones:

$ threemd links dungeon.3md
links: 4
dangling: 1
  source=0 target=1 status=ok text=north
  source=1 target=9 status=dangling text=secret door

Gate a build on link integrity (exits non-zero if anything dangles):

$ threemd check-links dungeon.3md
dangling links: 1
  source=1 target=9 status=dangling text=secret door
$ echo $?
1

Render to HTML, piping from stdin:

$ cat week.3md | threemd html - > week.html

See also

• The format - what the CLI validates against.
• Parsers - the library behind the CLI, plus the TypeScript and Rust ports.