Nowline

Roadmaps as code. For everyone.

Human readable roadmaps, built for AI.

Plain .nowline text files. Version-controlled. Render to SVG, PNG, PDF, HTML, Mermaid, XLSX, and MS Project XML.

---

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'

The emitted JSON carries a top-level "$nowlineSchema": "1" so downstream tools can detect schema changes. Comments are not preserved across round-trips — see packages/cli/README.md for the canonical printer rules.

Serve (--serve)

Run a live-reload preview in the browser. Great while authoring.

nowline roadmap.nowline --serve                    # http://127.0.0.1:4318

nowline roadmap.nowline --serve -p 4400 -t dark --open nowline roadmap.nowline --serve -o latest.svg # rewrite latest.svg on each rebuild

The server re-parses, re-validates, re-lays-out, and re-renders on every file change; connected clients refresh automatically via Server-Sent Events. Validation errors are displayed as an overlay on top of the most recent successful render.

Init (--init)

Scaffold a new .nowline file in cwd. The positional argument is the project name, not a file path. .nowline is auto-appended.

nowline --init                              # ./roadmap.nowline (default name)

nowline --init my-project # ./my-project.nowline nowline --init my-plan.nowline # ./my-plan.nowline (literal) nowline --init my-project --template=teams # use the teams template

minimal, teams, and product correspond to the files under examples/. Existing files are silently overwritten.

Exit codes

Manual

After any package-manager install (brew install lolay/tap/nowline, npm install -g @nowline/cli, or the .deb from GitHub Releases), man nowline shows the CLI manual and man 5 nowline shows the full DSL reference. Both man pages also ship as standalone assets on every GitHub Release — see packages/cli/man/ for the mdoc sources.

Language at a glance

File structure

nowline v1                        // 1. version directive (optional, must be first)

include "shared/teams.nowline" // 2. includes include "brand.nowline" config:isolate

config // 3. config section (optional) scale name: weeks style enterprise bg: blue fg: navy

roadmap r "My Roadmap" // 4. roadmap section

swimlane platform item x "Work item" duration:1w status:done

Entities

Properties

item auth "Auth refactor"

duration: 2w // duration literal: d, w, m, q, y status: in-progress // builtin or custom from config owner: sam // id reference (person or team) wave: build // barrier the item belongs to (a declared wave) after: kickoff // dependency (single) after: [kickoff, approvals] // dependency (list) remaining: 30% // percentage labels: [security, p0] // list of label ids link: https://… // URL (bare, no quotes)

Roadmap start date

A roadmap may carry an optional start:YYYY-MM-DD that anchors the timeline baseline:

roadmap platform-2026 "Platform 2026" start:2026-01-06

• If the roadmap contains any anchor, or any milestone with a date: property, start: is required.
• Every such date must be on or after start:.
• A pure-relative roadmap (built from duration: and after: only) does not need start:.
• Across includes that don't use roadmap:ignore, the parent and any included roadmap must agree on start: — both absent, or both present with the same value. Mismatches are errors, not silent overrides.

Includes

include "teams.nowline"                     // merge everything (default)

include "snippet.nowline" config:ignore // skip child config include "partner.nowline" roadmap:isolate // render child as a separate region

• merge — default: child content is merged; parent definitions win on collision.