Command line

xtxt <command> <file>... [options]

Use - as the filename to read from standard input.

Commands

Command	What it does
`validate`	Check syntax and report problems
`lint`	Validate, plus style warnings
`render`	Render to the terminal
`export`	Convert to another format
`import`	Convert Markdown to XTXT
`ast`	Print the parse tree as JSON
`extract`	Print the machine-facing view as JSON
`paste`	Append the clipboard image to a document

validate and lint

xtxt validate notes.xtxt
xtxt lint notes.xtxt
xtxt validate *.xtxt

validate reports errors and warnings. lint adds style warnings on top — things that parse and mean what you wanted but are worth reconsidering.

Exit status is non-zero only when there is an error. Warnings never fail a build, because an unknown directive is a warning and a document from the future must not break a pipeline built today.

render

xtxt render notes.xtxt
xtxt render notes.xtxt -w 100
xtxt render notes.xtxt --no-color

export

xtxt export notes.xtxt html -o notes.html
xtxt export notes.xtxt md
xtxt export notes.xtxt text -w 72

Format	Output
`html`	Standalone document with styling
`body`	HTML fragment, no `<head>`, for embedding
`md`	CommonMark
`text`	Plain text, wrapped
`json`	Parse tree

import

xtxt import notes.md -o notes.xtxt

Converts CommonMark to XTXT: headings, emphasis, lists, links, tables and code fences all map across. Tables become @table, fenced code becomes @code with its language preserved.

ast and extract

xtxt ast notes.xtxt          # the parse tree
xtxt extract notes.xtxt      # the machine-facing view

ast is the tree every implementation must produce, and what the conformance suite pins. extract is the interpreted view: outline, tasks, records, links, media and code, each with a line number.

paste

xtxt paste notes.xtxt
xtxt paste notes.xtxt --folder media
xtxt paste notes.xtxt --folder ""
xtxt paste notes.xtxt --embed
xtxt paste notes.xtxt --caption "Whiteboard" --width 600

Reads an image from the system clipboard, writes it into assets beside the document and appends the @image directive. --folder chooses a different subfolder; an empty one writes beside the document. Uses whatever the platform provides — osascript on macOS, PowerShell on Windows, wl-paste or xclip on Linux.

Options

Flag	Effect
`--resolve`	Expand `@include` and `@embed` first
`--interactive`	In HTML, inline the chart runtime; without it, output has no script
`--mermaid`	In HTML, load the diagram renderer from a CDN
`--folder <path>`	Where `paste` saves an image, relative to the document (default `assets`)
`--plugins <path>`	Load a plugin manifest for unknown directives
`-o <path>`	Write to a file instead of stdout
`-w <n>`	Wrap column for text output, default 80
`--no-color`	Disable ANSI colour

Diagnostics

notes.xtxt:14: error: unclosed @code block: no matching @endcode
notes.xtxt:22: warning: unknown directive @youtube (preserved, but this reader cannot render it)

Level	Meaning
error	The file cannot be interpreted unambiguously
warning	It parses, but something is suspect

In CI

xtxt validate docs/**/*.xtxt || exit 1

Because warnings do not affect exit status, this fails only on genuine breakage. To be stricter, read the JSON and decide for yourself:

xtxt ast notes.xtxt | jq -e '.issues | length == 0'