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 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 selector.

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.