Command-line reference

Run mpress help to print the compact command summary.

Project commands

M-Press searches the current directory and its parents for mpress.yaml, so commands may be run from a nested content directory.

Start an existing project without changing your shell directory:

mpress dev ../product-docs

To begin from a remote repository, use one command. Git authentication comes from your existing credential helper or gh login. M-Press clones the source, creates a non-default work branch, builds the site, and prints the local UI URL:

mpress dev \
  --repo [email protected]:example/product-docs.git \
  --checkout ../product-docs \
  --branch docs/add-french

Open the printed URL and use Translations in the development bar. The editing tools recognise the prepared branch, so they do not ask you to prepare the repository a second time.

Start from a published M-Press page when the site has enabled contributions:

mpress contribute https://docs.example.com/guide/install/

M-Press discovers the repository and matching source file from the page. It uses ~/mpress-contributions/<owner>-<repository> by default, creates a safe contribution branch, selects an available port, and opens the local wizard. Use --checkout to choose another directory or --no-open to keep the browser closed.

Use --goal page or --goal translate to open the matching local workflow directly. Use --draft-file only with a development-only browser draft.

Build modes

Draft pages are excluded unless --drafts is supplied. The development server includes them automatically.

Production builds minify generated CSS and JavaScript with M-Press’s built-in Go minifier. It removes comments and redundant whitespace and shortens safe, non-repeated local JavaScript bindings. It does not need Node or an external minification tool. Production builds also remove clearly unused built-in class and ID rules after scanning every generated page and the runtime script. Responsive at-rules are filtered recursively, while animation, font, and unknown at-rules are retained. Selectors without class or ID tokens are retained because custom HTML and runtime components can activate them later. Pass --no-purge-css when a build must retain every built-in selector. Configured build.customCSS rules are always preserved, including those used by scripts at runtime.

Publication checks

mpress check site --json
mpress check site --output release/site --cloudflare-pages --json
mpress translate check --json
mpress translate check --lang fr --exceptions translation/audit-exceptions.json --json

Both commands are read-only and run locally. They return a non-zero exit status on validation failures. --json writes one report to stdout; the error summary goes to stderr. Paths supplied by these flags are relative to the project root containing mpress.yaml, unless absolute.

mpress check site reads build.outputDir, or the directory selected by --output. It checks:

• Local links and assets, same-host absolute links, and HTML fragments.
• Exact redirects in _redirects, including chains, cycles, and missing targets. The supported rule format is SOURCE TARGET 301 or SOURCE TARGET 302; wildcard rules, rewrites, and other statuses are reported as unsupported. An absent _redirects file is valid. External redirect targets are not fetched.
• Page language and canonical URL against site.baseURL. Canonical checks are skipped when no base URL is configured; the generated 404.html is exempt.
• A page in every configured target language for every default-language route, with no default-language fallback. This is a complete-translation publication gate even when the builder permits missing translations.
• Contribution source metadata pointing to an existing file inside build.contentDir, including checks against symlink escapes.
• D2 source blocks or Markdown fences accidentally displayed as prose.
• Sitemap, robots, and LLM text assets; per-language search indexes when search is enabled; knowledge manifest artifacts when knowledge is enabled, including compressed filenames recorded in the manifest.

--cloudflare-pages additionally enforces a maximum of 20,000 output files and 25 MiB per file. These hosting limits are opt-in. Output symlinks and other non-regular files are rejected. The JSON report contains files, html_pages, languages, redirects, and a sorted errors array.

mpress translate check checks all configured target languages, or just --lang. It discovers Markdown and MPD source pages using the translation engine and checks translated navigation when source navigation exists. Missing, empty, and orphaned translations fail. Local audit warnings also fail this command, unlike translate audit, which fails only for error-level findings.

--exceptions accepts a JSON array using this format:

[
  {
    "language": "fr",
    "file": "guide.md",
    "segment": "title",
    "code": "untranslated",
    "reason": "The reviewed heading is the same term in both languages.",
    "sourceSHA256": "<SHA-256 of the complete source file>",
    "targetSHA256": "<SHA-256 of the complete translated file>"
  }
]

The language, content-relative filename, segment ID, and code must match the finding. The reason must be non-empty and both hashes must still match. Only untranslated and requirement-language findings can be accepted this way; missing content and structural damage cannot be waived by an exception.

--exclude-audit PAGE is an explicit escape hatch for known legacy audit baselines. It excludes all audit findings for that exact source filename, including structural findings, but retains missing, empty, and orphan coverage checks. Repeat the flag for multiple files. No filenames are excluded by default; unknown filenames are errors. The JSON report contains languages, errors, the number of accepted findings, and excluded_audit filenames.

ZIP exports

Run mpress export to create <project-directory>.zip in the project root. The archive contains the production HTML, CSS, JavaScript, search indexes, and static assets at its root, ready for any static host. It does not contain source Markdown, the development bar, or authoring endpoints.

Use an explicit destination when another tool expects a fixed artifact name:

mpress export --strict docs-release.zip

M-Press refuses to replace an existing archive unless --force is supplied. Use --drafts only for private review archives.

Migration

mpress import --from starlight ../old-docs --output ./new-docs

Options may appear before or after the source path. The importer writes a migration-report.md next to the new project configuration.

Version artifacts

mpress versions capture v1.0
mpress versions capture --force v1.0
mpress versions list
mpress versions verify v1.0
mpress versions remove v1.0

Version labels may contain letters, numbers, dots, underscores, and hyphens.

Translation

mpress translate reads its API key from the environment variable named by translation.apiKeyEnv. It never writes the key to project files. Normal runs translate missing and stale segments and preserve manual edits. See Translate documentation for provider, glossary, state, and review details.

Run mpress translate --estimate --lang fr before a paid translation. This command uses the real translation plan but does not initialise or contact the provider. Token totals are approximate because provider tokenisers and target language lengths differ. Add inputPricePerMillion and outputPricePerMillion to the translation configuration to include a USD estimate. Use the current prices published for the configured model.

--harness codex and --harness claudecode override the translation provider for one command without changing mpress.yaml. They invoke the authenticated codex or claude executable already installed on the machine. The harness receives structured translation requests through standard input. M-Press still validates every returned segment before it writes a target page.

--model overrides the configured model for the same command. M-Press passes the value directly to the selected harness. For example:

mpress translate --lang ja --harness codex --model gpt-5.6-terra
mpress translate --lang ja --harness claudecode --model claude-opus-5

mpress translate audit --lang CODE performs a read-only quality check and returns a non-zero exit status when it finds an error. Add --harness and an optional --model to run a second semantic review. The reviewer reports findings only. It cannot rewrite translated pages.

MCP knowledge base

Connect a local MCP client directly to a project:

{
  "mcpServers": {
    "product-docs": {
      "command": "mpress",
      "args": ["knowledge", "/path/to/product-docs"]
    }
  }
}

The command builds the site before it starts. Pass --no-build when CI has already produced and verified the knowledge artifacts.

Use HTTP when the client cannot start a local process:

mpress knowledge --transport http --host 127.0.0.1 --port 3100

The endpoint is http://127.0.0.1:3100/mcp. A non-loopback address requires a bearer token supplied with --token. Keep the endpoint private unless it sits behind a production authentication layer.

External link audit (network opt-in)

Build once, then audit the existing generated HTML:

mpress build --strict
mpress check
mpress check external --json > external-links.json
# Focus a scheduled audit on source/example links:
mpress check external --host github.com --timeout 10s --retries 1 --json

check external is a separate, explicit network operation. check, check site, translation checks and normal builds retain their local validation contracts. Use --output DIRECTORY to select an existing build. The audit scans href and src in every generated HTML page, including translated pages and mounted snapshots. It excludes the configured site’s own host and non-HTTP references. It does not rebuild or edit anything. Run local checks as well.

The JSON report contains every unique destination, its sorted referencing page paths, status, attempts, HTTP status, final redirect URL and diagnostic detail. Repeated URLs share a probe sequence; fragments are removed for HTTP requests and deduplication, while query strings remain distinct. --host HOST is repeatable and matches the initial hostname exactly; redirects may leave that host. Use repeatable --url-prefix https://github.com/owner/repo/tree/ and --url-prefix https://github.com/owner/repo/blob/ to audit source/example links without probing every contributor profile or changelog PR. Prefixes are literal, absolute HTTP(S) URLs without credentials, query strings or fragments; they filter initial URLs only, and combine with the host filter.

Broken results take precedence over inconclusive ones in a mixed report. HTTP 401/403, other unexpected status codes, timeouts, DNS/TLS errors, redirect loops and exhausted retries are inconclusive, never proof of a missing page. A failed audit to load the output/configuration is an operational error (exit 1) and may have no JSON report. Redirects to login/consent pages can return success; HTTP success does not establish correctness.

Each URL uses GET, with a default 10-second timeout per attempt including redirects. Bodies are closed without interpreting content. The audit follows up to ten HTTP(S) redirects; use --max-redirects 0 to disallow them. It makes one additional attempt by default for transport failures, HTTP 408/425/429 and 5xx, waiting one second between attempts. Configure --retries 0..5 and --retry-delay 1s. A Retry-After header on a non-success response stops retries for that destination and defers it to a later audit. 404/410 and ordinary access denials are not retried. URLs with embedded credentials are not requested. Requests use the environment’s normal HTTP proxy/TLS configuration and require network access to the initial and redirected hosts. Only audit trusted builds; their URLs determine where the command sends requests.

This is an availability audit, not a content or security validator. It does not validate remote fragments, JavaScript/CSS-discovered links, srcset, spelling of examples, file-versus-directory semantics, or commands shown inside code blocks. For example, verify a GitHub blob file and tree directory against the actual tag contents before replacing a deleted branch URL. There is no automatic URL substitution or exception refresh.

Run this in a separate scheduled CI job and after branch deletion, retaining the JSON report as an artifact. Failing that job makes broken or inconclusive results visible without blocking ordinary documentation builds or deployment. A pre-release-only audit cannot catch a link that breaks after its branch is deleted. No results or network failures are cached across runs.