CLI reference

Every Aardvark command — new, build, dev, link-check, and ai-enrich — and the options each takes.

Aardvark — a Mantine-powered static site generator.

Author your content in Markdown and build it into a fast, fully static site: Mantine-powered interactive components, built-in client-side search, automatic Open Graph cards, and optional build-time AI enrichment. Scaffold a project with vark new, preview it live with vark dev, and produce the deployable site with vark build.

On interactive terminals, vark quietly checks for newer releases in the background while real subcommands run, and prints an upgrade reminder only when an update is available. Run vark update any time for an explicit check.

Run with no command to open the interactive TUI (agentic authoring + launchers).

Run vark <command> (or aardvark <command>) from your project root.

Examples:

vark new my-docs        # scaffold a new site in ./my-docs
cd my-docs && vark dev  # preview at http://localhost:8000, live-reload
vark build              # build the static site into ./build

The islands toolchain (react, @mantine/*, esbuild) ships inside Aardvark: a project with no node_modules gets it staged automatically on the first build — no npm install, nothing downloaded (Node itself is the one prerequisite). npm runs only when your package.json needs packages Aardvark doesn’t ship (opt out with AARDVARK_NO_AUTO_NPM); a node_modules you install yourself always wins.

Commands

vark new PATH

Scaffold a new site in PATH.

Creates PATH and fills it with starter content, a sample data file, the editable default theme under themes/vark/, an example snippet, and a package.json for the Mantine islands toolchain. Next: cd into PATH and run vark dev — the first build stages the islands toolchain shipped with Aardvark (no npm install, nothing downloaded; npm only runs for packages Aardvark doesn’t ship, and a node_modules you install yourself always wins). Node is the one prerequisite; without it the site builds without the islands bundle.

Examples:

vark new my-docs   # scaffold ./my-docs, then `cd my-docs`

vark build

Build the site to the output directory.

Every build prints a per-phase timing summary — how many pages and components were produced, and how long each phase (discovery, render, island bundling, …) took. The summary goes to stdout and the live --verbose progress to stderr, so vark build > summary.txt keeps the digest while progress still streams to the terminal. Conditional phases (translation, AI, OpenAPI, island bundling) appear only when they actually run.

A link to a missing page or a missing local image — in any language — always fails the build (the same check vark link-check runs without producing output). A link to a missing #anchor on a page that DOES exist is warn-only by default (it still lands on the right page); set links: {strictAnchors: true} in config to make those fail too. Unknown component references never fail the build: each renders as an HTML comment and is reported as a warning on stderr — usually a typo, a missing npm install, or a snippet you haven’t created yet.

--log-file PATH also appends this build’s summary, warnings, and any failure to a plain-text file — what vark build > summary.txt captures, plus the warnings and the error (-v’s per-phase streaming stays on stderr and is not written to the file). It exists mainly for symmetry with vark dev --log-file, where a pipe isn’t an option because it turns the dashboard off. Runs are appended under a === vark build … started … === banner.

Examples:

vark build               # build ./ into ./build
vark build --no-bundle   # skip the islands JS bundle (no Node needed)
vark build -v            # stream per-phase progress to stderr

vark deploy

Build the site and publish it to Aardvark cloud managed hosting.

Runs the same full production build as vark build, then uploads the output directory to your Aardvark cloud site and makes it live, printing the site’s URL. Pass --no-build to upload an already-built output directory as-is (it errors if none exists).

This publishes only to a CLI-created site. A site connected to a GitHub repository keeps deploying from that repository, so vark deploy refuses it — before running the build, not after.

Authenticates with your Aardvark secret key in AARDVARK_SECRET_KEY — the same possession-based CLI credential the AI features use, read from the environment or your project’s .env. On the first deploy of an account with no site, the site is created for you (pass --slug to choose its name); an account already hosting a CLI site deploys to that one. If a previous deploy was interrupted, the upload resumes it, and re-uploading an unchanged file is always safe.

Examples:

vark deploy                     # build, then upload ./build to Aardvark cloud
vark deploy --no-build          # upload the existing ./build as-is
vark deploy --slug my-docs      # deploy to (or create) the site my-docs

vark dev

Serve the site locally and rebuild on change.

Builds once, serves the result, watches your sources, and live-reloads the browser on every change. Your browser opens to the site automatically when the server starts (pass --no-open to skip that). The per-phase timing summary prints on the first build and on every rebuild, so you can see exactly what each change cost. Generation scripts run on every rebuild; pass --no-generators for a fully offline loop when a generator’s network call is slow or its cache is cold.

When the site prerenders islands (islands.ssr), each page’s baked markup is cached and reused until that page — or the islands toolchain — actually changes, so a rebuild only re-renders what you edited. Pass --no-ssr to skip the prerender altogether for the fastest loop, accepting that dev pages then mount client-side and no longer match what vark build publishes.

The live dashboard paints on the terminal’s alternate screen, so its log vanishes when you quit and can’t be piped anywhere (piping vark dev turns the dashboard off entirely). Drag-select copies what the pane still shows (2,000 wrapped lines); s saves from a separate, larger record of 5,000 unwrapped lines, so it keeps output the pane has already scrolled past. Both are still capped. Pass --log-file dev.log to also write the same events — every build summary, warning, broken-link report, and traceback — to a plain-text file you can paste from, with no cap at all. Runs are appended, each under a === vark dev … started … === banner, so restarting never discards the output you were trying to keep.

Examples:

vark dev               # serve ./ at http://localhost:8000, live-reload
vark dev --port 3000   # serve on a different port
vark dev --no-open     # don't open a browser when the server starts
vark dev --log-file dev.log   # also append the log to a file you can paste from

vark link-check

Check internal links, anchors, and images across the site (a build smoke test).

Renders every page in memory and verifies that internal links, #anchors, and local images resolve, without writing HTML output — the same check vark build runs. Use it for a fast pass/fail in CI or a pre-commit hook. A link to a missing page or a missing local image is printed to stderr and fails (exit non-zero). A link to a missing #anchor on a page that DOES exist is a warning by default (still exits 0) — set links: {strictAnchors: true} in config to make those fail too. Generation scripts run first so generated pages are checked too; pass --no-generators to skip them (e.g. an offline check of a site whose generators call the network).

Image checking covers Markdown images, raw <img> / srcset / <video poster> references, CSS background images, and built-in image-bearing islands. It validates only local files the site would publish from static/, public/, and theme assets; external and data-URI images are skipped.

Examples:

vark link-check   # verify internal links and images without writing output

vark convert PLATFORM INPUT_PATH OUTPUT_PATH

Import a docs site built for another platform into an Aardvark site.

Reads the source docs at INPUT_PATH (a project built for PLATFORM), translates its navigation, pages, components, and assets into Aardvark’s format, and writes a buildable site to OUTPUT_PATH — an aardvark.config.yaml, content/*.md, and static/ you can immediately vark build or vark dev. Where the source declares them, its look carries over too: brand colors become a project-owned themes/vark/theme.scss, and its custom stylesheets land at the output root (where the build auto-links them). Conversion is best-effort: the summary reports how many pages and assets were converted and flags any construct that didn’t map cleanly, so you know exactly what to review by hand.

A converted page is TRUSTED CONTENT, exactly like one you wrote. Aardvark passes raw HTML in a Markdown page through to the built site, so anything a source page carries inline — an event handler such as onerror=, a javascript: or data: URL, a <script> or <iframe> embed — is carried too, and is live once built. That is deliberate: a converted page keeps the third-party embeds its author put there, and the converter does not decide which of them you meant. Link targets from the source’s CONFIG are the exception — a javascript: tab, footer or logo link is refused and reported, because those become chrome on every page rather than one page’s markup. So convert only sources you trust, and read the diff before you publish: a conversion is exactly as trustworthy as the site it read.

The supported PLATFORM values are named in the epilog below (and running with an unknown one lists them). OUTPUT_PATH must be empty unless --force is given.

Supported platforms: docusaurus, fern, gitbook, hugo, mintlify, mkdocs, readme.

Examples:

vark convert mkdocs ./my-mkdocs-site ./my-docs   # import a MkDocs site
vark convert mkdocs ./mkdocs.yml ./my-docs        # point at the config directly
vark convert gitbook ./my-gitbook-repo ./my-docs # import a GitBook repo
vark convert mkdocs ./src ./out --force -v        # overwrite a non-empty ./out

vark ai-enrich

Run opt-in build-time enrichment (frontmatter, examples, skills).

Writes generated description/keywords back into your Markdown frontmatter and, when ai.skills is enabled, (re)generates a SKILL.md for each planned skill under skills/ in your project root. This is the only command that touches skills — vark build leaves them alone. Runs through Aardvark’s metered gateway: the only thing you need to set is your AARDVARK_SECRET_KEY.

Examples:

vark ai-enrich   # enrich frontmatter and (re)generate planned skills

vark author

Run agentic authoring tasks on your docs — interactively or headless.

With no --action, opens a menu of AI-assisted actions — regenerate keywords, refresh a page’s description, check and replace dead outbound links, apply a style-guide pass, or chat with a writing agent — that edit your Markdown in place (each change previewed as a diff you confirm before it’s written). The same menu is reachable by running bare vark.

With --action <id> it runs ONE action non-interactively (for CI / automation), previewing diffs unless --yes is given to write. Scope it with --path <file-or-dir> (repeatable), --diff <ref> (only pages changed vs a git ref), or --page for one; with none of those it runs on every page. This is the mode the gateway’s GitHub integration drives on a runner. The styleguide action additionally REQUIRES --rulesets — the style ruleset ids to apply, comma-separated in precedence order (list order, first wins conflicts); no other action accepts the flag.

Running an action (or the interactive menu) requires your Aardvark secret key in AARDVARK_SECRET_KEY — the possession-based CLI credential; every call goes through Aardvark’s metered gateway, never a model provider directly. (--list-actions only prints the headless action ids and needs no key.)

Examples:

vark author                              # open the agentic authoring menu
vark author --page guide/intro.md        # act on one page directly
vark author --list-actions               # list actions runnable headless
vark author --action styleguide --rulesets microsoft,google
                                         # preview a style pass on every page
vark author --action keywords --path guide/ --yes
                                         # apply to just the guide/ subtree (CI)
vark author --action keywords --diff main --yes
                                         # apply to only the pages this branch changed

vark serve

Serve a built site (and a live MCP server) for production.

The hardened, headless counterpart to vark dev: a single uvicorn/Starlette process that serves the already-built ./build — honoring the build’s own _headers / _redirects so content types, redirects, and the ai-config.json no-store rule match a CDN host — and, unless --no-mcp, exposes a stateless MCP server at /mcp that wraps the site’s docs as read-only tools (search, fetch, list, full corpus).

It does NOT build, watch, or live-reload — run vark build first. Designed to sit behind a CDN, which terminates TLS and absorbs the static volume; the per-IP /mcp rate limit is a single-process backstop, not a DDoS shield. For full-text MCP search on a site without the on-page search box, set mcp: true in aardvark.config.yaml before building.

The serve stack (starlette/uvicorn/mcp) ships with every Aardvark install — pip, the standalone binary, and the Docker image — so there is nothing extra to install.

Examples:

vark serve                       # serve ./build on 0.0.0.0:8080, with /mcp
vark serve --port 80 --no-mcp    # static only, no MCP endpoint
vark serve --trusted-proxy 173.245.48.0/20  # trust a CDN's forwarded IPs

vark update

Check whether a newer version of Aardvark is available.

Queries the public Homebrew tap for the latest published release. If you’re behind, it prints how to upgrade — brew upgrade aardvark, or a direct binary download for your Mac (for people who don’t use Homebrew). It only checks and reports; it never touches your installation, and degrades gracefully when offline.

Examples:

vark update   # check for a newer release and how to upgrade

vark version COMMAND [ARGS]...

Manage documentation versions (snapshot-in-tree docs versioning).

Declare which subtrees are versioned in your config first (versions.paths, e.g. [/guide]), then vark version cut <id> freezes a copy of those subtrees under versions/<id>/ and serves it under /<id>/. The latest docs stay in content/ and are served at the site root. See the versioning guide.

Examples:

vark version cut v1        # freeze the current docs as version v1
vark version list          # show configured versions
vark version remove v1     # delete the v1 snapshot + config entry

vark web-bot-auth-keygen

Generate an Ed25519 keypair for Web Bot Auth.

Prints the public key to add under webBotAuth.keys in aardvark.config.yaml (so vark build publishes it at /.well-known/http-message-signatures-directory) and the private key to store as a secret for whatever agent signs requests on your site’s behalf. Aardvark only ever publishes the public directory — it never stores the private key, so save it now; it is not recoverable.

Examples:

vark web-bot-auth-keygen          # print a keypair + a paste-ready config snippet
vark web-bot-auth-keygen --json   # machine-readable {privateKey, x, kid}