Skip to content

Command-line tools

This page inventories the public command-line interface (CLI) for document authors and project maintainers. It keeps command names, aliases, safe defaults, write behaviour, and automation semantics visible in one place.

Start with Publish a document to see each command in the task that needs it. Run a command from the project root—the directory containing zensical.toml—unless an option explicitly names another location.

Use the shorter pdk executable when you prefer it; it is an exact alias. bootstrap also answers to boot, and source-bundle to source.

Check the installation

prodockit --version
prodockit --help

The first prints the installed release. The second lists the commands supplied by that release. Ask an individual command for its current options:

prodockit pins --help

If a guide and local help disagree, the local help describes the code you are actually running. Check prodockit --version, then compare it with the version pinned by the project before assuming an option is unavailable.

Choose a command

Command Use it when Safe first run Writes
prodockit bootstrap A machine or checkout is not ready to build and publish prodockit bootstrap Only with --apply; configuration questions use --configure
prodockit init-tools The project needs local Mermaid or MathJax rendering tools prodockit init-tools Tool manifests, scripts, and ignore entries; existing files require --force
prodockit init-mathjax The website needs the installed MathJax bundle copied into its assets prodockit init-mathjax Website JavaScript assets and, unless disabled, .gitignore
prodockit pdf You need one PDF containing the pages in nav prodockit pdf The configured PDF output
prodockit source-bundle A submission needs the Markdown and configuration as a separate PDF prodockit source-bundle The configured source-bundle output
prodockit sync-repo Repository links or badges must match the current remote prodockit sync-repo --check zensical.toml and the managed README badge block without --check
prodockit pins Build-input versions disagree or need a reviewed upgrade prodockit pins --check --offline Matching version declarations when a version is selected
prodockit template-sync A generated project needs later template fixes prodockit template-sync With --apply, template-owned/shared files on a new branch; always appends its ignored log

The prodockit init-mathjax command is the narrower website asset command; use init-tools when preparing both Mermaid and maths for PDF output.

Build and preview

Zensical owns the live website commands:

zensical serve
zensical build --clean --strict

serve watches the source and rebuilds a local preview. The strict build is the final website check: it starts clean and treats broken links, missing anchors, and other validation warnings as failures.

Prodockit builds the additional artifacts:

prodockit pdf
prodockit source-bundle

When building both the complete PDF and site, keep this order:

prodockit pdf
zensical build --clean --strict

Zensical copies the finished PDF into the site directory. Reversing the order can publish the PDF from the previous build while every command exits successfully.

To render one page while developing PDF styles, use:

prodockit pdf --markdown-file extensions/tables.md

That ignores nav and is a quick diagnostic, not a substitute for the final complete build.

Maintain without changing files

Begin with report-only forms:

prodockit sync-repo --check
prodockit pins --check --offline
prodockit template-sync
prodockit bootstrap

These answer four different questions:

  1. Does repository metadata match origin?
  2. Do declared build versions agree across files?
  3. Has the source template changed files it owns?
  4. Is this machine and checkout ready to build?

Do not replace one with another merely because they all use the word “check”.

Apply and verify a maintenance change

  1. Read the report

    Run the non-writing or check form first. A maintenance command should tell you which files or stages are involved before you authorise writes.

  2. Apply only the reported change

    Examples:

    prodockit sync-repo
prodockit pins --set zensical=0.0.55
prodockit template-sync --apply
prodockit bootstrap --apply

    pins --set is unattended and leaves unnamed packages untouched. template-sync --apply stages its work on a branch but does not commit it. bootstrap --apply performs only outstanding stages and verifies each one.

  3. Repeat the check

    prodockit sync-repo --check
prodockit pins --check --offline
prodockit template-sync
prodockit bootstrap

    The second run should be clean or explain any remaining manual work. Do not treat a changed file as proof that the intended state was reached.

  4. Build and inspect

    prodockit pdf
zensical build --clean --strict
git diff --check
git status --short

    Open the website and PDF when the change can affect rendering. Automated checks catch known failures; visual review answers whether the output is the document you intended to publish.

Use commands in automation

Automation must not wait for a prompt. Use explicit non-interactive forms:

prodockit sync-repo --check
prodockit pins --check --offline
prodockit pins --set zensical=0.0.55

Important exit-status behaviour:

Command Exit zero means
sync-repo --check Managed repository metadata is already current
pins --check --offline Every discovered declaration agrees; no network comparison was attempted
pins --check Declarations agree and none of the selected PyPI packages is behind
zensical build --clean --strict The site built without a strict validation error
pytest The selected source or built-output checks passed

The ordinary interactive prodockit pins command is for a terminal, not CI. Likewise, template-sync --push asks before committing, merging, and pushing; it is an assisted maintainer operation rather than an unattended deployment step.

Find the next guide