Create and edit your roadmaps in a plain-text format.
io.nowline/nowline MCP Server
The io.nowline/nowline Model Context Protocol (MCP) server creates and edits product and engineering roadmaps using a plain-text format. It is described as a text-first DSL for roadmaps that can be version-controlled and rendered into multiple outputs. The serverβs topics include gemini-cli-extension.
π οΈ Key Features
Create and edit roadmaps in a plain-text format
Uses a plain .nowline text DSL
Version-controlled roadmap files
Renders to: SVG, PNG, PDF, HTML, Mermaid, XLSX, MS Project XML
π Use Cases
Writing human-readable roadmaps that remain machine-readable
Generating roadmap artifacts for different tooling and formats (e.g., Mermaid, XLSX, MS Project XML)
β‘ Developer Benefits
Works with plain text (.nowline) that fits common version-control workflows
Converts roadmap definitions into multiple target formats, including HTML and Mermaid
β οΈ Limitations
Source material does not specify available MCP tools, tool count, or runtime capabilities beyond roadmap creation/editing and rendering.
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.
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.
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.
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.
bash
nowline roadmap.nowline --dry-run
nowline roadmap.nowline -n # short aliascat 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.
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.
bash
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.
bash
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
Code
Meaning
0
Success
1
Validation error (parse failure, invalid reference, any include error such as a missing include, a wave rule across included files)
2
Usage error (missing input, bad flags, unsupported format, file not found, empty stdin, invalid --diagnostic-format, binaryβTTY refusal)
3
Output error (cannot write to destination)
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
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
Keyword
Purpose
roadmap
The top-level roadmap declaration. At most one per file.
swimlane
A horizontal lane of work.
item
A unit of work inside a swimlane.
parallel
A block whose children run concurrently.
group
A logical grouping of items, rendered together.
anchor
A named date on the timeline.
milestone
A point-in-time marker that depends on work.
wave
A barrier across every swimlane: no work in the next wave starts until this one ends.
footnote
A callout anchored to one or more entities.
person, team
Ownership references.
non-working, working
Days that consume no work (weekends, holidays, closures) and the exceptions that give them back. Config entries with date:, start: / end: or every:; a declaration named weekend replaces the business weekend. A dated closure with a title is labelled on the chart (Thanksgiving Β· 2d) and carried into the MS Project and Mermaid exports; a titled working day is labelled with the days it adds (Crunch Saturday Β· +1d).
style, symbol, label, size, status, scale, calendar, default
Config and declaration entries.
Properties
nowline
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:
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
nowline
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.
ignore β child content of that kind is discarded.
isolate β child roadmap is preserved as a self-contained region (requires a roadmap in the child).
Waves never merge. Under roadmap:merge or roadmap:isolate, an included file that declares a roadmap, swimlanes, or waves must declare the same waves as its parent, in the same order with the same start floors (NL.E0202).
examples/long.nowline β stress test: eight swimlanes, ~160 items, parallels, groups, anchors, milestones, footnotes, cross-cutting labels. Used for layout/render perf.
examples/nested.nowline + examples/nested/ β parent Security swimlane plus five isolated per-team roadmap includes (iOS, Android, Web, Platform, Data). Demonstrates roadmap:isolate.
examples/waves.nowline β wave barriers: three waves (Foundations, Build, Launch) across three lanes, a group wave: that assigns its children, unwaved background work, and milestones after: a wave.
examples/waves-program.nowline + examples/waves-program/ β multi-team waves: web and API team files re-declare the same waves (with a start floor), so each renders alone and the program file merges them behind one barrier.
Editor support
A TextMate grammar lives at grammars/nowline.tmLanguage.json. It works in any editor that supports TextMate grammars (VS Code, Sublime Text, Zed, IntelliJ via third-party plugins, etc.). A first-class LSP server and VS Code extension are tracked in packages/lsp/ and packages/vscode-extension/.
Use as a library
@nowline/core is a pure-TypeScript parser, typed AST, and validator built on Langium. Everything the CLI does on top of parsing is itself built against this library. See packages/core/README.md for the API and a usage example.
Status
Nowline is on v0.x β published to Homebrew, npm, the VS Code Marketplace, Open VSX, and GitHub Releases. The parser, validator, layout, renderer, every export format (SVG, PNG, PDF, HTML, Markdown+Mermaid, XLSX, MS Project XML), and the verbless CLI (--dry-run, --init, --serve) are usable today. Breaking changes may land between 0.x minor versions while the embed surface and IDE expansion settle; full SemVer guarantees kick in at 1.0. The release-by-release roadmap lives in specs/milestones.md.
Contributing
Bug reports, feature requests, and pull requests are welcome. Start with CONTRIBUTING.md for setup, build/test commands, and the expected workflow. Before opening an issue, please check the templates under .github/ISSUE_TEMPLATE/. Security issues should follow SECURITY.md. All participation is governed by our CODE_OF_CONDUCT.md.
Design specs for the DSL, renderer, CLI, IDE integrations, and OSS milestones live under specs/ β start there to understand how Nowline is shaped before touching code.