CLI reference

--header-link is repeatable (at most four) and adds a text link to the top bar and the home page introduction, for example --header-link 'Example library=/sheetmill/demo/'. The label is 1 to 40 printable characters (the only space allowed is U+0020) without surrounding whitespace, and labels must be unique (exact, case-sensitive). The value after the first = must be an https:// URL without credentials or a root-relative path starting with a single /. Other schemes (javascript:, data:, http:), //host URLs, spaces, quotes, angle brackets, backslashes, control and non-ASCII characters in the URL fail with REN003 and exit 1 before anything is written. Root-relative values are used as written and are not prefixed with --base-path.

A release build stamps the version with the linker, for example go build -trimpath -ldflags "-X github.com/wstein/sheetmill/internal/cli.Version=v0.1.0" ./cmd/smill; the repository provides no build target. Official release binaries come only from the tag-triggered release workflow (releasing); other distribution builds need separate approval.

Cobra v1.10.2 parses commands and flags. --help works at every command level; top-level help (smill --help, smill help) ends with a notice pointing AI agents to the agent guide and llms.txt published with the manual; import/build flags may precede or follow the positional input. Check/inspect have no content options. There is no recursive or stdin mode. Directories are scanned only one level, in sorted order, for lowercase .md files. Subdirectories and other extensions are ignored; an empty batch selection is an error. Duplicate explicitly selected paths are checked once. Selected files must be regular files. Symlinks in selected paths or .md directory entries are rejected, including ancestor symlinks. On macOS use /private/tmp instead of /tmp for scratch files, or resolve the explicit path yourself first. Input reads are confined with os.Root and limited to 8 MiB plus one byte for oversized-input detection. No implicit filesystem crawling occurs. Source symlinks are unsupported; this is not a sandbox against an adversary concurrently mutating all parent directories.

Stdout contains requested version/JSON/help data and a build export summary. Diagnostics use stderr: path:line:column: CODE: actionable message. Validations across explicit inputs continue after errors. Exit status precedence is IO/usage (2), then invalid source (1), then success (0). Broken stdout also produces exit 2.

Go package tests exercise the same Run entrypoint as the executable, without building a distributable CLI binary (the release workflow builds those). Parser fuzz targets run via:

go test ./internal/frontmatter -run '^$' -fuzz FuzzParse -fuzztime 5s -parallel 2
go test ./internal/markdown -run '^$' -fuzz FuzzParse -fuzztime 5s -parallel 2

The one-sheet E2E harness also invokes a temporary build of this actual entry point, then pinned Hugo and Chromium. It validates both desktop and mobile reader behavior, no-JavaScript navigation and inert source variants. The temporary executable is verification output, never a distribution artifact.

smill serve ./sheets --hugo /absolute/path/to/hugo
smill serve ./sheets/editor.md --open --port 0