Documentation

CLI commands

The semtext command-line tool reads and renders SemText documents. Every command operates on local files and produces local output — no network, no API key, no cloud.

Author your document as HTML using the SemText vocabulary — any tool that writes HTML can write it. Then load semtext.css and semtext.js, plus an optional theme. That is the whole integration:

<!doctype html>
<html lang="en" data-sem-theme="minimal-tech-light">
<head>
  <meta charset="utf-8" />
  <title>Auth notes</title>
  <link rel="stylesheet" href="https://cdn.semtext.dev/v0/semtext.css" />
  <link rel="stylesheet" href="https://cdn.semtext.dev/v0/semtext-theme-minimal-tech-light.css" />
  <script defer src="https://cdn.semtext.dev/v0/semtext.js"></script>
</head>
<body>
  <sem-enhanced-document>
    <h1 data-kind="title">Auth notes</h1>
    <sem-note variant="tip">Readable as plain text —
    the CDN tier makes it interactive.</sem-note>
    <sem-facts view-as="flashcards">
      <sem-fact id="f-rotate" kind="concept">
        <statement>Refresh tokens rotate per use</statement>
        <conclusion>Each exchange retires the
        previous token.</conclusion>
      </sem-fact>
    </sem-facts>
  </sem-enhanced-document>
</body>
</html>

cdn.semtext.dev is the planned CDN origin; today the same three files ship in the spec repo's dist/ — and in this site's public/semtext/, which the examples on /reference/ render with.

semtext view — read a document

Prints the whole document as plain text in the terminal: every record with its id and attributes, readable from a buffer or a pipe.

$ semtext view auth-notes.sem.html
sem-note (#tip-1): Refresh tokens rotate per use — each exchange retires the previous token.
  variant: tip
sem-facts (#facts-1)
  sem-fact (#f-rotate kind=concept): Refresh tokens rotate per session :: Short-lived access tokens; the refresh grant issues a new pair.
    incorrectStatements: Store the token in localStorage for durability.

semtext outline — the block tree

Prints the document's structure: one line per block with its stable id in brackets. Use --depth N to trim nesting, or --json for machine-readable output.

$ semtext outline auth-notes.sem.html
- [top-h] section: Auth notes (2 nested)
  - [tip-1] sem-note: Refresh tokens rotate per use — each exchange retires the previous token.
  - [facts-1] sem-facts: sem-facts (1 nested)
    - [f-rotate] sem-fact: Refresh tokens rotate per session :: Short-lived access tokens; the refresh grant issues…

semtext filter — select records

Prints matching blocks as normalised HTML. Filter by record type (--type), attribute (--attr), text (--text), id, kind, tag, audience or CSS selector — criteria combine with AND. Add --json for structured output your tools can consume.

$ semtext filter auth-notes.sem.html --type sem-fact
<sem-fact id="f-rotate" kind="concept">
      <statement>Refresh tokens rotate per session</statement>
      <conclusion>Short-lived access tokens; the refresh grant issues a new pair.</conclusion>
      <incorrect-statement>Store the token in localStorage for durability.</incorrect-statement>
    </sem-fact>

semtext expand — one block in full

Loads a single block by the id the outline printed — the on-demand counterpart to a collapsed outline or a filtered result.

$ semtext expand auth-notes.sem.html f-rotate
[f-rotate] sem-fact
sem-fact (#f-rotate kind=concept): Refresh tokens rotate per session :: Short-lived access tokens; the refresh grant issues a new pair.
  incorrectStatements: Store the token in localStorage for durability.

semtext format — normalise a document

Rewrites the document in its normal form — --text prints the plain-text form instead, --json the machine-readable one. Same output shape as view, normalised.

semtext tui — interactive terminal

Opens an interactive terminal UI for browsing the document: arrows or j/k move, Enter expands or collapses a block, / searches, r shows the raw source. No dependencies, runs in your shell.

Usage: semtext tui auth-notes.sem.html

semtext-validate — check a document

Validates documents against the spec schema and reports unknown elements, bad nesting and schema violations per line. Accepts multiple files or globs; exits 0 when everything is clean.

$ semtext-validate auth-notes.sem.html
1 file checked, 0 errors, 0 warnings

The CLI ships in the spec repo (npl-enhanced-content): semtext, semtext-validate and the semtext-agent toolkit (search, write, edit) — installed with npm install npl-enhanced-content.