Nowline

---

What is Nowline?

Nowline is a text-first DSL for describing product and engineering roadmaps — human readable and machine readable. You write plain .nowline text files — indented, keyword-driven, diff-friendly — and tooling renders them as timelines, validates them, and composes them.

examples/minimal.nowline:

nowline v1

roadmap minimal "Starter" start:2026-01-05 scale:2w author:"Jane Doe"

swimlane engineering "Engineering"
  item research "Research"  duration:3w status:done
  item design   "Design"    duration:2w status:in-progress remaining:5d
  item build    "Build"     duration:3w status:planned

Renders to:

Why Nowline?

• Text, not a Gantt chart. Version-controlled, diffable, reviewable in a PR.
• Indentation, not XML. Roadmaps read like outlines, because that's how people think about them.
• Strict enough to catch mistakes. 30+ validation rules, clear error messages with line and column numbers.
• Composable. include other files with explicit merge / ignore / isolate semantics.

Quick start

Install the CLI from your package manager:

brew trust lolay/tap                                 # macOS / Linux / WSL (one-time)
brew install lolay/tap/nowline

Debian/Ubuntu and Windows users can grab the latest .deb or .exe from GitHub Releases. See packages/cli/README.md for the full install matrix (including man nowline setup).

Toolchain

Two-tier Node policy: Node ≥ 22 to consume @nowline/* packages (engines.node on every published package), Node 26 (.nvmrc) to develop. CI tests both versions on every PR. See Toolchain & Supported Versions for the full policy and bump procedure.

Render your first roadmap:

nowline examples/minimal.nowline                     # writes ./minimal.svg
nowline --version

Or scaffold a brand-new file from a template:

nowline --init my-project                            # ./my-project.nowline
nowline --init my-project -t teams                   # ./my-project.nowline (teams template)

To give an AI agent Nowline tools, install the plugin from this repo's marketplace. In Claude Code:

/plugin install nowline --marketplace lolay/nowline

GitHub Copilot CLI and Codex read the same marketplace; see plugins/nowline/README.md for those and the other ways to add the MCP server.

For the VS Code / Cursor / VSCodium extension, search Nowline on the VS Code Marketplace or Open VSX.

0.x versioning. nowline is on 0.x.y while we settle the embed surface and IDE expansion. Public APIs may change between minor versions; full SemVer guarantees apply once we ship 1.0. See specs/releasing.md for the version contract.

To run from a checkout for local development (pnpm install && pnpm build), see CONTRIBUTING.md.

Use the CLI

nowline is verbless: rendering is the default. Other operations are flags on the same command.

Render (default)

nowline roadmap.nowline                          # writes ./roadmap.svg
nowline roadmap.nowline -f png                   # writes ./roadmap.png
nowline roadmap.nowline -f pdf                   # writes ./roadmap.pdf
nowline roadmap.nowline -f html                  # writes ./roadmap.html
nowline roadmap.nowline -f mermaid               # writes ./roadmap.md
nowline roadmap.nowline -f xlsx                  # writes ./roadmap.xlsx
nowline roadmap.nowline -f msproj                # writes ./roadmap.xml
nowline roadmap.nowline -o roadmap.pdf           # format inferred from extension
nowline roadmap.nowline -o -                     # SVG to stdout
nowline roadmap.nowline --theme dark --now 2026-03-15
nowline roadmap.nowline --now - --asset-root ./brand --no-links --strict
nowline roadmap.nowline -f pdf --page-size a4 --orientation landscape --margin 0.5in
cat roadmap.nowline | nowline -                  # stdin → ./roadmap.svg

The render pipeline is @nowline/core parse → @nowline/layout layout → @nowline/renderer SVG → format-specific exporter. Output is byte-for-byte deterministic for the same input, theme, and --now. A single nowline binary ships every format — see packages/cli/README.md for install details.

Validate (--dry-run)

Run the full pipeline (parse + validate + layout + format) without writing. Exits 0 on success, 1 if any errors are emitted.

nowline roadmap.nowline --dry-run
nowline roadmap.nowline -n                          # short alias
cat roadmap.nowline | nowline - --dry-run           # read stdin
nowline roadmap.nowline -n --diagnostic-format json # machine-readable output
nowline - -n --format=json < roadmap.nowline        # same, json is the default here

--diagnostic-format text|json picks the stderr format; with --dry-run --format=json it defaults to json, otherwise text. JSON mode writes one { "$nowlineDiagnostics": "1", "diagnostics": [...] } document to stderr whenever any diagnostic exists, warnings included, so a warnings-only source exits 0 with the document. Clean sources print nothing.

Convert text ↔ JSON

Convert is just -f json (or -f nowline to go the other way). Input format is inferred from the extension; --input-format overrides for unusual filenames.

nowline roadmap.nowline -f json -o roadmap.json    # text → JSON
nowline roadmap.json -f nowline -o roadmap.nowline # JSON → text (canonical)
nowline roadmap.nowline -f json -o - | jq '.ast.roadmapDecl.name'

This is the beginning of the README. Read the rest at the original. Read the full README ↗