Get started →

    CLI Reference

    Command syntax, flags, and Rspress integration for the ciderpress CLI.

    Overview

    ciderpress uses @kidd-cli/core for command routing. Styled terminal output goes through @clack/prompts. The CLI entry point is packages/cli/src/index.ts, which registers all commands. Each command is a standalone module that orchestrates the engine and Rspress build APIs.

    Commands

    CommandDescription
    setupCreate a starter ciderpress.config.ts
    devSync + Rspress dev server + file watcher
    buildSync + Rspress static build
    servePreview a built site from .ciderpress/dist/
    syncRun the sync engine only — no dev server, no build
    checkValidate config and check for broken links
    diffShow changed files in configured source directories
    draftScaffold a new documentation file from a template
    cleanRemove .ciderpress/cache/, .ciderpress/content/, .ciderpress/dist/
    dumpResolve the full entry tree and print as JSON

    setup

    ciderpress setup

    Creates a starter ciderpress.config.ts in the current directory if one does not already exist.

    dev

    ciderpress dev [--quiet] [--clean] [--port <port>] [--theme <name>] [--colorMode <mode>] [--vscode] [--headless]

    The primary development workflow. Combines initial sync, file watcher, and Rspress dev server on http://localhost:6174. The --clean flag removes cache, content, and dist before starting.

    Use --headless to skip the Ink TUI and emit plain log output. Required when running from a non-TTY shell (tmux without a real PTY, background agent tasks, CI). Note that the headless runner does not construct the shared OpenAPI cache, so OpenAPI dereferencing repeats on every sync — see Dev Mode.

    See Dev Mode for how the watch loop, HMR, and config reload work.

    build

    ciderpress build [--quiet] [--clean] [--check] [--no-check] [--verbose]

    Produces a static site:

    1. Optional clean step
    2. Full sync
    3. Rspress build (generates optimized HTML/CSS/JS in .ciderpress/dist/)
    4. Link check (enabled by default, disable with --no-check)

    serve

    ciderpress serve [--no-open] [--port <port>] [--theme <name>] [--colorMode <mode>] [--vscode]

    Starts a static file server pointing at .ciderpress/dist/ on http://localhost:8080. The browser opens automatically; use --no-open to disable.

    sync

    ciderpress sync [--quiet]

    Runs the sync engine and exits — no dev server, no Rspress build. Loads config, syncs all content into .ciderpress/content/, reports pages written / skipped / removed and elapsed ms. Useful for CI pipelines, benchmarking the sync pipeline in isolation, and pre-warming .ciderpress/ before a separate build step.

    check

    ciderpress check

    Validates the config and runs a build to detect broken links. Reports config errors and deadlinks with a summary table.

    diff

    ciderpress diff [--ref <ref>] [--pretty]

    Shows changed files in configured source directories. Two modes:

    • Without --ref (default): uses git status to detect uncommitted changes in the working tree.
    • With --ref <ref>: uses git diff --name-only <ref> HEAD to compare commits. Exits with code 1 when changes are detected — matching the Vercel ignoreCommand convention (exit 1 = proceed with build, exit 0 = skip).

    By default, output is a space-separated file list on stdout (suitable for scripts and piping). Pass --pretty to emit intro/note/outro formatting via @clack/prompts — not pipeable, but human-readable.

    draft

    ciderpress draft [--type <type>] [--title <title>] [--out <dir>]

    Scaffolds a new documentation file from a template. Prompts for doc type and title when not provided via args, then writes the rendered template to the specified output directory.

    clean

    ciderpress clean

    Removes .ciderpress/cache/, .ciderpress/content/, and .ciderpress/dist/ (all three targets live under .ciderpress/). Safe to run at any time -- all content is regenerated by sync/build.

    dump

    ciderpress dump

    Resolves the full entry tree from the config and prints it as JSON. Useful for debugging config resolution and glob patterns.

    Rspress Integration

    The CLI communicates with Rspress through packages/cli/src/lib/rspress.ts:

    FunctionPurpose
    startDevServer()Launch Rspress dev server on port 6174
    buildSite()Run Rspress static build to .ciderpress/dist/
    buildSiteForCheck()Build with deadlink detection enabled
    serveSite()Start static file server for .ciderpress/dist/
    openBrowser()Cross-platform browser launcher

    All functions receive a Rspress config object built by createRspressConfig() from @ciderpress/ui. Sidebar and nav are loaded by Rspress from _meta.json / _nav.json in the content tree; the UI config additionally loads workspaces.json and scopes.json from .ciderpress/content/.generated/ and wires up the ciderpress theme.

    Error Handling

    CLI errors are handled at the command boundary:

    • Config errors -- loadConfig() returns a Result<T, ConfigError> tuple; commands report errors via @clack/prompts and call process.exit(1)
    • Sync errors -- Result tuples propagate up; the CLI reports them and exits
    • Rspress errors -- Build/dev failures are caught and reported

    All user-facing error formatting is centralized in the CLI layer.

    References