Get started →

    CLI Commands

    All commands are run from your repo root where ciderpress.config.ts lives.

    ciderpress <command> [flags]

    The ten registered commands are: setup, dev, build, serve, sync, check, diff, draft, clean, dump.

    Common flags

    Several commands share the same option set. Where a per-command table omits a flag, it isn't supported.

    FlagTypeDefaultCommandsDescription
    --quietbooleanfalsesync, dev, buildSuppress non-error output
    --cleanbooleanfalsedev, buildRemove build artifacts before running
    --portnumber—dev (6174), serve (8080)Preferred port — falls back to the next free port in a 5-port range
    --themestring—dev, serveOverride theme.name for this run without touching ciderpress.config
    --colorMode'dark' | 'light'—dev, serveOverride theme.variant for this run
    --vscodebooleanfalsedev, serveEmit the VS Code extension's chrome trimmings (no topbar, panel layout)

    setup

    Initialize a ciderpress config file in the current project.

    ciderpress setup

    Derives the project title from git remote get-url origin (falling back to the directory name), writes a starter ciderpress.config.ts, ensures .ciderpress/ is gitignored, and generates initial branded SVG assets in .ciderpress/public/. Skips with a warning if ciderpress.config.ts already exists.

    sync

    Sync documentation sources into .ciderpress/.

    ciderpress sync [--quiet]
    FlagTypeDefaultDescription
    --quietbooleanfalseSuppress non-error output

    Resolves all entries in the config, copies source files into .ciderpress/content/, merges frontmatter, and writes _meta.json and _nav.json files alongside each section.

    dev

    Start the dev server with live reload.

    ciderpress dev [--quiet] [--clean] [--port <n>] [--theme <name>] [--colorMode <dark|light>] [--vscode] [--headless]
    FlagTypeDefaultDescription
    --quietbooleanfalseSuppress non-error output
    --cleanbooleanfalseRemove build artifacts before starting
    --portnumber6174Preferred port (falls back to the next free port in a 5-port range)
    --themestring—Override theme.name for this run
    --colorMode'dark' | 'light'—Override theme.variant for this run
    --vscodebooleanfalseEmit the VS Code extension's chrome trimmings
    --headlessbooleanfalseRun without the Ink TUI — plain log output

    Runs sync first, starts a file watcher on all source files, and launches the Rspress dev server. Changes to source markdown files are detected and re-synced automatically.

    --headless is required when invoking dev from a non-TTY shell (CI, Docker, nodemon, background tasks) — the default Ink TUI needs raw-mode stdin and will error otherwise.

    build

    Build the static site for production.

    ciderpress build [--quiet] [--clean] [--check | --no-check] [--verbose]
    FlagTypeDefaultDescription
    --quietbooleanfalseSuppress non-error output
    --cleanbooleanfalseRemove build artifacts before building
    --check / --no-checkbooleantrueValidate config and check for broken links during the build
    --verbosebooleanfalseSurface raw Rspress output during the check pass (otherwise suppressed)

    Runs sync first, then builds the Rspress site. Output is written to .ciderpress/dist/. Branded SVG assets (banner, logo, icon) are regenerated as a side effect when title is configured.

    When --check is enabled (the default), config validation and deadlink detection run as part of the build. Use --no-check to skip checks and build with standard Rspress output. Use --verbose to see raw Rspress diagnostics during the check pass.

    serve

    Preview the production build locally.

    ciderpress serve [--no-open] [--port <n>] [--theme <name>] [--colorMode <dark|light>] [--vscode]
    FlagTypeDefaultDescription
    --no-openbooleanfalseDon't open the browser automatically
    --portnumber8080Preferred port (falls back to the next free port in a 5-port range)
    --themestring—Override theme.name for this run
    --colorMode'dark' | 'light'—Override theme.variant for this run
    --vscodebooleanfalseEmit the VS Code extension's chrome trimmings

    Starts a local static file server pointed at .ciderpress/dist/. Requires a prior ciderpress build.

    clean

    Remove build artifacts, synced content, and build cache.

    ciderpress clean

    Deletes the following directories:

    DirectoryContents
    .ciderpress/cache/Build cache
    .ciderpress/content/Synced pages
    .ciderpress/dist/Build output

    Safe to run at any time — all directories are regenerated by sync and build.

    diff

    Show changed files in configured source directories.

    ciderpress diff [--pretty] [--ref <ref>]
    FlagTypeDefaultDescription
    --prettybooleanfalseHuman-readable output with headers (default: space-separated list)
    --refstring—Git ref to compare against HEAD (e.g. HEAD^, main)

    Loads the config and extracts every source directory from include fields, plus their top-level roots and the config files themselves.

    Default mode (no --ref) runs git status --short scoped to those paths and prints a space-separated file list to stdout — suitable for piping into lefthook, scripts, or git hooks.

    Ref mode (--ref <ref>) runs git diff --name-only <ref> HEAD and exits with code 1 when changes are detected. This matches the Vercel ignoreCommand convention — exit 1 means "proceed with build", exit 0 means "skip build":

    # vercel.json
{ "ignoreCommand": "ciderpress diff --ref HEAD^" }

    Use --pretty for labeled, human-readable output instead of the machine-friendly list.

    dump

    Resolve and print the full site structure as JSON.

    ciderpress dump

    Loads the config, resolves all entries (including glob patterns and recursive discovery), and outputs the resolved navigation tree to stdout. Useful for debugging your site structure.

    Output includes text, link, collapsible, hidden, standalone, and nested items for each entry.

    check

    Validate config and check for broken links.

    ciderpress check

    Validates the config file, syncs content, then runs a build to detect deadlinks. Reports results for both config validation and link checking. Exits with code 1 if any check fails. Useful for CI pipelines.

    draft

    Scaffold a new documentation file from a template.

    ciderpress draft [--type <type>] [--title <title>] [--out <dir>]
    FlagTypeDefaultDescription
    --typestring—Template type (prompts if omitted)
    --titlestring—Document title (prompts if omitted)
    --outstring"."Output directory for the new file

    When --type or --title are omitted, an interactive prompt lets you select from the available templates and enter a title. The output filename is derived from the title slug (e.g. "Authentication" → authentication.md).

    References

    Resources