For AI agents: the complete documentation index is available at https://ciderpress.dev/llms.txt, the full documentation bundle is available at https://ciderpress.dev/llms-full.txt, and this page is available as Markdown at https://ciderpress.dev/reference/cli.md.
Get started →
ciderpress

    CLI Commands

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

    ciderpress <command> [flags]

    The eleven registered commands are: setup, dev, build, serve, sync, check, diff, draft, templates, 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
    --hoststring—devBind interface. Overrides devServer.host (default 'localhost')
    --urlstring—devExternally-visible URL. Overrides devServer.url (e.g. portless host)
    --themestring—dev, serveForce a registered theme name for this run (must appear in theme.themes)
    --colorMode'dark' | 'light'—dev, serveForce the initial variant for this run (overrides theme.defaultVariant)
    --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>] [--host <h>] [--url <u>] [--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). Overrides devServer.port
    --hoststring'localhost'Bind interface. Set '0.0.0.0' to expose on every interface. Overrides devServer.host
    --urlstring—Externally-visible URL surfaced to the ready message + browser auto-open. Overrides devServer.url
    --themestring—Force a registered theme name for this run
    --colorMode'dark' | 'light'—Force the initial 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—Force a registered theme name for this run
    --colorMode'dark' | 'light'—Force the initial 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. Also validates any custom templates declared via the templates config field. Reports results for config, templates, 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>] [--var <id=value>...]
    FlagTypeDefaultDescription
    --typestring—Template type (prompts if omitted)
    --titlestring—Document title (prompts if omitted)
    --outstring"."Output directory for the new file
    --varstring[]—Fill a template variable, id=value (repeatable)

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

    Built-in variables ({{title}}, {{slug}}, {{date}}, {{filename}}) are always substituted. A template's declared vars are filled from --var, then prompted for on an interactive terminal; anything left blank stays as a raw {{ id }} marker and is reported as a checklist. See Variables.

    The available templates are the built-ins plus any declared via the templates config field. A custom template whose filename matches a built-in overrides it, and .mdx templates scaffold to .mdx files. See Templates for the authoring format.

    templates

    List and validate document templates.

    ciderpress templates list    # List built-in and custom templates
ciderpress templates check   # Validate template frontmatter and syntax
    SubcommandDescription
    listPrint built-in and custom templates, grouped by source; overrides marked with *
    checkValidate every template's frontmatter and vars; exits 1 on any issue

    check reports frontmatter errors (missing/unknown fields), invalid types, invalid vars, and duplicate types. {{ }} markers in a template body are always allowed. The same validation runs as part of check and build, which additionally fail on unfilled markers in published docs. See Templates for how to declare and author custom templates.

    References

    Resources