Q-Press exposes one primary CLI command with focused subcommands. The CLI is installed as a project-local npm binary, not a global shell command:

pnpm exec qpress api generate
pnpm exec qpress check
pnpm exec qpress ssg

Inside package scripts, you can call qpress directly because npm, pnpm, yarn, and bun add local binaries to the script PATH.

The older qpress-ssg binary remains available as a backwards-compatible alias, but new scripts should prefer qpress ssg so all Q-Press tooling is grouped under one command.

Help Output

Every command supports --help:

pnpm exec qpress --help
pnpm exec qpress api --help
pnpm exec qpress api generate --help
pnpm exec qpress api check --help
pnpm exec qpress check --help
pnpm exec qpress ssg --help

Use these when you need the current option list from the installed package.

How Projects Get The CLI

The CLI is provided by the installed @md-plugins/quasar-app-extension-q-press package through its npm bin entries. It is not copied into your app source by the generated template and is not installed globally.

When you install or update Q-Press, run the app-extension invoke flow so your generated scripts point at the current command names:

quasar ext invoke @md-plugins/q-press

Installed projects also get package scripts for the common workflows:

pnpm check:qpress
pnpm build:ssg
pnpm prerender:ssg
pnpm preview:ssg

Project Validation

Use qpress check before release or CI builds to catch docs-specific problems that normal TypeScript and lint checks do not always see. Run it directly through your package manager:

pnpm exec qpress check

Or use the generated package script:

pnpm check:qpress

The checker scans:

• Markdown route duplicates
• Broken internal Markdown and HTML links
• Broken related frontmatter routes
• Broken siteConfig navigation routes
• Missing MarkdownExample source files
• Missing imported Q-Press API JSON files
• Malformed API JSON files
• Stale generated API JSON when api.entries is configured
• Missing frontmatter title or description warnings
• Common browser-only globals in examples that can surprise SSG builds

Errors fail the command. Warnings, such as missing frontmatter or SSG-risky browser globals, are reported without failing by default.

Use --fail-on-warnings when CI should treat warnings as blockers:

pnpm exec qpress check --fail-on-warnings

Configuration File

Q-Press can load project-local check options from a config file in the project root. This keeps package scripts readable as validation grows.

Supported filenames:

• qpress.config.json
• qpress.config.mjs
• qpress.config.js
• qpress.config.cjs
• .qpressrc.json

Put check options under the check key:

{
  "api": {
    "generatedSuffix": ".generated",
    "entries": [
      {
        "input": "src/utils/timestamp.ts",
        "output": "src/.q-press/api/composables/timestamp.json",
        "group": "functions",
        "docsUrl": "/api/timestamp"
      }
    ]
  },
  "check": {
    "allowedRoutes": ["/theme-builder"],
    "ignoreFiles": ["__*.md"],
    "checkUnreachable": true
  }
}

CLI flags override config values. Repeated list options such as allowedRoutes and ignoreFiles merge with the config values.

Unknown config keys and invalid value types fail fast with a clear error. For example, allowedRoutes must be an array of strings and checkUnreachable must be a boolean.

Use an explicit config file when needed:

pnpm exec qpress check --config docs-qpress.config.mjs

Skip config loading for debugging or one-off CI checks:

pnpm exec qpress check --no-config

API JSON Generation

Use qpress api when you want TypeScript exports and JSDoc to become the source of truth for Q-Press API JSON.

generate writes review files next to your configured API JSON output paths:

pnpm exec qpress api generate

For example, an entry with this output path:

src/.q-press/api/composables/timestamp.json

Generates this review file:

src/.q-press/api/composables/timestamp.generated.json

Review the generated file before publishing it. If the generated descriptions, examples, categories, params, returns, or slot scopes are thin, update the TypeScript/JSDoc and run the generator again. Generated JSON includes a top-level generated_at timestamp; drift checks ignore that field so timestamp churn does not fail CI.

For release and package builds that should write the configured API JSON files directly, add --write-output:

pnpm exec qpress api generate --write-output

Use review files while authoring, then use direct output mode once the source JSDoc is the accepted API contract.

Run check when CI should report stale or missing API JSON without writing files:

pnpm exec qpress api check

qpress check also runs these stale generated API checks automatically when api.entries is configured. This keeps the normal release validator aware of API drift without requiring a second command in most CI scripts.

If you need to run the docs checks without generated API drift checks, use:

pnpm exec qpress check --no-api

The generator extracts exported TypeScript functions, exported const arrow/function expressions, object-style and typed Vue SFC props/emits/slots, and TypeScript defineComponent({ props, emits, slots, setup }) component surfaces. It can follow local prop type aliases, local imported prop declarations, withDefaults(defineProps<T>(), defaults), local imported prop/emit spreads, SlotsType<T> declarations, render-function slot usage, and expose({ ... }) methods when they resolve to local TypeScript source.

It reads JSDoc descriptions plus @param, @returns, @example, @category, @since, and @deprecated tags, then emits the same JSON shape used by MarkdownApi. Repeat @example for multiple examples. For prop categories, repeat @category or separate names with | or ,; props without a category render in MarkdownApi’s default group.

Use explicit metadata tags for fields that should not be guessed from source: @values, @applicable, @default, @required, @type, @ts-type, and @api-exemption. Function, event, and slot-scope params can use @param-values name ..., @param-applicable name ..., @param-example name ..., @param-default name ..., @param-required name false, @param-type name ..., @param-ts-type name ..., and @param-api-exemption name examples. Return metadata can use @returns-values, @returns-applicable, @returns-example, @returns-type, @returns-ts-type, and @returns-api-exemption.

For component-heavy libraries, the generator also supports documented emit arrays, @api method markers, @event functions, @api-follow getRawMouseEvents on helper spreads, and wrapper forwarding tags such as @api-source, @api-props, @api-events, @api-slots, and @api-methods.

See API JSON for full source examples covering exported functions, typed props, runtime props, emits, custom events, slots, exposed methods, return definitions, metadata tags, generated output, and review output.

Configure entries under api.entries:

{
  "api": {
    "entries": [
      {
        "input": "src/utils/timestamp.ts",
        "output": "src/.q-press/api/composables/timestamp.json",
        "group": "functions",
        "docsUrl": "/api/timestamp"
      }
    ]
  }
}

Use group: "functions" for composables and utilities, or group: "methods" when the generated API should appear under the Methods tab.

You can also run a one-off comparison without config:

pnpm exec qpress api generate \
  --input src/utils/timestamp.ts \
  --output src/.q-press/api/composables/timestamp.json \
  --type plugin \
  --group methods \
  --docs-url /api/timestamp

For one-off runs, --type, --group, and --docs-url mirror the matching api.entries fields. Use them when you are probing a new source file and want the generated review file to resemble the final API JSON shape. docsUrl is passed through to MarkdownApi as the Docs button target, so Q-Press docs commonly use a route path.

Custom Routes

If your docs include custom Vue routes that are valid but not generated from Markdown, allow them explicitly:

pnpm exec qpress check --allow-route /theme-builder

You can repeat --allow-route for multiple routes.

The same route set is used for Markdown links, related frontmatter, and siteConfig navigation, so one allowed route covers all three places.

Navigation Checks

Q-Press checks configured siteConfig routes by default, including path, route, to, href, link, and url values that point to absolute internal routes.

External URLs and static assets are ignored. If your siteConfig lives somewhere other than src/siteConfig, point the checker at it:

pnpm exec qpress check --site-config-dir docsConfig

If you need to temporarily skip navigation validation:

pnpm exec qpress check --no-navigation

Unreachable Pages

Hidden pages are sometimes intentional, so unreachable-page warnings are opt-in. Enable them when you want release checks to flag Markdown routes that are not referenced from configured navigation:

pnpm exec qpress check --check-unreachable

This is useful before public releases, but it may be too strict for sites that intentionally keep custom tools, release archives, or private drafts out of the main menu.

Ignored Markdown Files

If your docs folder includes intentional scratch pages, fixtures, or generated drafts that should not participate in release checks, ignore them explicitly:

pnpm exec qpress check --ignore-file "__*.md"

You can repeat --ignore-file for multiple patterns. The checker does not hard-code any filename conventions, so ignored files stay visible and intentional.

Machine-Readable Output

Use JSON output when another script needs to consume diagnostics:

pnpm exec qpress check --json

Use quiet output when CI should only print failures:

pnpm exec qpress check --quiet

Static Site Generation

Use qpress ssg to prerender Q-Press routes into static HTML:

pnpm exec qpress ssg --out-dir dist/spa

The SSG command reads the generated route manifest, uses the Q-Press app factory, renders each route at build time, and writes route-specific HTML into your static output folder.

See Q-Press SSG for renderer modes, output configuration, route crawling, exclusions, redirects, reports, and browser-only content guidance.