@nowline/cli 0.8.6 → 0.9.0

package/man/nowline.1

@@ -22,6 +22,17 @@
 .Fl -init
 .Op Ar name
 .Nm
+.Fl -mcp
+.Op Fl -root Ar dir
+.Nm
+.Fl -mcp-install
+.Op Ar client
+.Op Ar options
+.Nm
+.Fl -mcp-uninstall
+.Op Ar client
+.Op Ar options
+.Nm
 .Fl -dry-run
 .Op Ar options
 .Ar input
@@ -128,6 +139,9 @@ successful render.
 Opt-in
 .Fl o Ar path
 also writes the rendered output to disk on each rebuild.
+It takes the same render options as a plain render (theme, width, links,
+strict mode, and the rest) and draws what a plain render of the file
+draws for the same options.
 .It Fl -init Op Ar name
 Scaffold a starter
 .Pa .nowline
@@ -140,6 +154,35 @@ is auto-appended if missing.
 Default name is
 .Sy roadmap .
 Existing files are silently overwritten.
+.It Fl -mcp
+Start a Model Context Protocol (MCP) server on standard input and
+output, exposing validate, render, export, and file tools to an agent.
+With
+.Fl -port Ar n ,
+it serves local Streamable HTTP instead.
+It is the same server as
+.Ql npx @nowline/mcp .
+.It Fl -mcp-install Op Ar client
+Register the MCP server with an agent harness:
+.Sy claude-code , claude-desktop , cursor , vscode , codex , gemini ,
+.Sy antigravity , muse , opencode , copilot , windsurf , zed , amp , goose ,
+or
+.Sy all .
+Without
+.Ar client ,
+installs into every harness found on this machine.
+JSON configurations are edited in place, keeping comments and other
+entries; Claude Code (user scope) and Codex go through their own
+.Ql mcp add
+command; Goose gets a snippet to paste.
+Re-running is safe.
+With
+.Fl n ,
+prints the change without writing or running anything.
+See
+.Sx MCP OPTIONS .
+.It Fl -mcp-uninstall Op Ar client
+Remove the server from the same configurations.
 .It Fl n , -dry-run
 Run the full pipeline (parse + validate + layout + format) but skip the
 write step.
@@ -180,7 +223,14 @@ Default: inferred from extension; standard input defaults to
 .Sh RENDER OPTIONS
 .Bl -tag -width Fl
 .It Fl t , -theme Ar name
-.Sy light | dark .
+.Sy light | dark | grayscale ;
+.Sy greyscale
+is accepted as an alias.
+Default:
+.Pa .nowlinerc
+.Sy theme ,
+else
+.Sy light .
 .It Fl -now Ar date
 .Sq Now
 anchor for the now-line and date math.
@@ -190,12 +240,15 @@ Accepts a bare
 .Pa 2026-06-04T23:00:00Z
 or
 .Pa 2026-06-05T06:00:00+07:00
-(an embedded Z or \(pmHH:MM offset overrides
+(an embedded Z or \(+-HH:MM offset overrides
 .Fl -timezone ) .
 A bare date or an instant without an offset is floating: the written date
 part is used and
 .Fl -timezone
 is ignored.
+The date part must be a real calendar day:
+.Pa 2026-02-30
+is an input error, not March\~2.
 Default: today's civil date in the host zone (or
 .Fl -timezone
 if given).
@@ -217,7 +270,7 @@ UTC.
 .It Sy Z , +00:00
 Zero-offset shorthand (equivalent to
 .Sy UTC ) .
-.It Sy \(pmHH , \(pmHH:MM , \(pmHHMM
+.It Sy \(+-HH , \(+-HH:MM , \(+-HHMM
 Fixed offset (DST-naive; documented caveat).
 .It Sy America/Los_Angeles
 Any valid IANA timezone name.
@@ -276,10 +329,33 @@ Raster scale factor (PNG only; default 1).
 .It Fl -strict
 Promote asset / sanitizer warnings to errors.
 .It Fl w , -width Ar px
-Canvas width in pixels (default 1280).
+Maximum canvas width in pixels.
+Default:
+.Pa .nowlinerc
+.Sy width ,
+else unset, so the canvas fits its content.
+A wider roadmap shrinks its timeline to fit, down to one pixel per day;
+captions that spill past their bars can still make the canvas wider.
+.It Fl -non-working Ar mode
+How a business calendar's non-working days appear on the chart:
+.Sy hide
+collapses them (the default),
+.Sy show
+draws them as shaded bands.
+Overrides the file's
+.Sy default roadmap non-working:
+key; leave it unset and the key applies, then
+.Sy hide .
+Any other value exits with status 2.
+The schedule is the same in both views, so Mermaid, MS Project, and XLSX output
+does not change.
 .It Fl -asset-root Ar dir
 Directory from which logo / image assets may be loaded
-(default: input file's directory).
+(default: the
+.Sy assetRoot
+key of
+.Pa .nowlinerc ,
+then the input file's directory).
 .El
 .Sh FORMAT-SPECIFIC OPTIONS
 .Bl -tag -width Fl
@@ -317,12 +393,13 @@ Monospace font for PNG/PDF; same resolution chain as
 Skip the platform font probe and force the bundled DejaVu pair.
 Output is byte-stable across machines.
 .It Fl -start Ar date
-MS Project: anchor date
-.Pq Pa YYYY-MM-DD
-for relative-only roadmaps.
-Default:
-.Fl -now ,
-then deterministic fallback.
+MS Project: project start date
+.Pq Pa YYYY-MM-DD .
+Default: the roadmap's
+.Cm start: ,
+else
+.Fl -now
+(today).
 .El
 .Sh SERVE OPTIONS
 .Bl -tag -width Fl
@@ -337,6 +414,36 @@ to expose on the LAN).
 .It Fl -open
 Open the browser on start.
 .El
+.Sh MCP OPTIONS
+.Bl -tag -width Fl
+.It Fl -root Ar dir
+Directory the MCP file tools may read and write (default: the current
+directory).
+With
+.Fl -mcp-install ,
+it is written into the registered command as an absolute path.
+.It Fl -scope Ar scope
+Where
+.Fl -mcp-install
+writes:
+.Sy user
+(default; the harness's per-user configuration) or
+.Sy project
+(the configuration file in the current directory, for committing).
+.It Fl -server Ar kind
+What
+.Fl -mcp-install
+registers:
+.Sy self
+(default; this
+.Nm
+binary with
+.Fl -mcp ,
+so a Homebrew install needs no Node.js) or
+.Sy npx
+.Pq Ql npx -y @nowline/mcp ,
+which follows npm independently of the CLI.
+.El
 .Sh LOGGING OPTIONS
 The logging flags are mutually exclusive.
 .Bl -tag -width Fl
@@ -344,7 +451,9 @@ The logging flags are mutually exclusive.
 Print extra diagnostics to standard error (config path, pipeline
 timings, font resolution, fallback decisions).
 .It Fl q , -quiet
-Suppress non-error standard error.
+Suppress non-error standard error: warnings, notices, and the warnings
+in a failed run's diagnostic report.
+Errors and JSON diagnostics still print, and the exit code is unchanged.
 .El
 .Sh STANDARD OPTIONS
 .Bl -tag -width Fl
@@ -394,24 +503,81 @@ for the resolution matrix.
 .It Pa .nowlinerc
 Optional JSON or YAML configuration file.
 Walked up from the input file's directory; nearest one wins.
-CLI flags override config values.
-Recognized keys:
-.Sy theme , defaultFormat , width , pdfPageSize , pdfOrientation ,
-.Sy pdfMargin , fontSans , fontMono , headlessFonts , locale .
+Each recognized key is the default for one flag: the flag wins when
+given, then the key, then the built-in default.
+.Sy theme
+.Pq Fl t ,
+.Sy defaultFormat
+.Pq Fl f ,
+.Sy width
+.Pq Fl w ,
+.Sy pdfPageSize
+.Pq Fl -page-size ,
+.Sy pdfOrientation
+.Pq Fl -orientation ,
+.Sy pdfMargin
+.Pq Fl -margin ,
+.Sy fontSans
+.Pq Fl -font-sans ,
+.Sy fontMono
+.Pq Fl -font-mono ,
+.Sy headlessFonts
+.Pq Fl -headless ,
+.Sy useSystemFonts
+.Pq Fl -use-system-fonts ,
+.Sy assetRoot
+.Pq Fl -asset-root ,
+.Sy locale
+.Pq Fl -locale .
+.Sy defaultFormat
+applies only when
+.Fl o
+has no recognized extension;
+.Sy locale
+ranks below the locale environment variables.
+A relative
+.Sy assetRoot
+is resolved against the directory of the
+.Pa .nowlinerc
+that holds it, while a relative
+.Fl -asset-root
+is resolved against the working directory.
+.Fl -serve
+reads
+.Sy theme ,
+.Sy width ,
+.Sy assetRoot
+and
+.Sy locale .
+An invalid value is a usage error that names the key.
 Unknown keys are ignored.
+There is no logging key:
+.Sy quiet
+is ignored, and
+.Fl q
+and
+.Fl v
+apply only on the command line.
 .El
 .Sh EXIT STATUS
 .Bl -tag -width Ds
 .It 0
 Success.
 .It 1
-Validation error (parse failure, invalid reference, etc.).
+Validation error (parse failure, invalid reference, etc.), including
+the wave rules checked across included files, such as
+.Sy NL.E0202 .
+Those are reported like validator diagnostics, at the file and line
+they point into.
 .It 2
 Usage error (missing input, bad flags, mutually-exclusive flags,
 unsupported format, file not found, binary output to TTY, unreadable
 input).
 .It 3
-Output error (cannot write to destination, exporter pipeline failure).
+Output error (cannot write to destination, exporter pipeline failure),
+including an include that cannot be resolved (unreadable, circular or
+duplicate include, mismatched
+.Cm start: ) .
 .El
 .Sh EXAMPLES
 Render the default SVG to the current directory:
@@ -448,6 +614,13 @@ nowline --init
 nowline --init my-project
 .Ed
 .Pp
+Serve the MCP tools, or register them with every agent found:
+.Bd -literal -offset indent
+nowline --mcp
+nowline --mcp-install
+nowline --mcp-install cursor --scope project -n
+.Ed
+.Pp
 PDF with explicit page geometry, byte-stable across machines:
 .Bd -literal -offset indent
 nowline roadmap.nowline -f pdf --page-size a4 \\