CLI

QVAC CLI provides tools and an HTTP server exposing the QVAC API, with an optional OpenAI-compatible extension.

Overview

QVAC CLI is provided through the @qvac/cli npm package. The CLI is installed globally so the qvac command is available on your PATH. At the moment, it provides the following functionality:

OpenAI-compatible HTTP server
System requirements check
Interactive qvac.config.json generator
SDK bundling

Usage

Install the CLI globally so the qvac command is available on your PATH:

npm install -g @qvac/cli

Create a qvac.config.* file in the root of your project and add the configuration required for the functionality you want to use. See Configuration to learn how to do this.

Tip: you can use the CLI to help with part of the configuration. See Interactive config generator.

Run a command:

qvac --help

Tip: if you cannot install the CLI globally, you can run it with npx instead:

npx --package "@qvac/cli" qvac --help

QVAC CLI provides an HTTP server that internally translates HTTP requests into SDK calls, with an optional extension compatible with the OpenAI REST API, enabling broad integration with the AI ecosystem. Run it with qvac serve --openai and any system compatible with the OpenAI REST API can point to http://localhost:11434/v1/ and work without changes.

HTTP server

Learn how to run a local HTTP server and mount the API surfaces you need.

Interactive config generator

The qvac configure command assembles a valid qvac.config.json for you — search the models the SDK provides, pick by capability, and inject entries with sensible defaults, without hand-writing serve.models or memorizing model constant names. Runs interactively by default; also has a non-interactive mode (--yes / --modality) for scripting.

qvac configure

See the reference for options, behavior notes, and examples.

SDK bundling

The qvac bundle sdk command allows you to select only the plugins you need in your project and reduce your application's final bundle size. See Plugin system to learn how to use it.

System requirements check

The qvac doctor command validates that the current host can run @qvac/sdk and @qvac/cli before you hit runtime errors. It prints a human-readable report by default and exits 1 when any required check fails.

System requirements

Full host matrix, deploy targets, optional tools, exit codes, and JSON schema.

Reference

Run qvac --help to see all available commands and qvac <command> --help for command-specific options.

`qvac bundle sdk`

Generate a tree-shaken Bare worker bundle with selected plugins.

Option	Description
`-c, --config <path>`	Config file path (default: auto-detect `qvac.config.*`)
`--sdk-path <path>`	Path to SDK package (default: auto-detect in node_modules)
`--host <target>`	Target host (repeatable)
`--defer <module>`	Defer a module (repeatable)
`-q, --quiet`	Minimal output
`-v, --verbose`	Detailed output

`qvac serve`

Start the HTTP server. qvac serve openai is a deprecated alias for qvac serve --openai --no-default.

Option	Description
`--openai`	Mount the OpenAI-compatible REST API
`--no-default`	Do not mount the QVAC surface
`-c, --config <path>`	Config file path (default: auto-detect `qvac.config.*`)
`-p, --port <number>`	Port to listen on (default: `11434`)
`-H, --host <address>`	Host to bind to (default: `127.0.0.1`)
`--model <alias>`	Model alias to preload (repeatable, must be in config)
`--api-key <key>`	Require Bearer token authentication
`--api-key-file <path>`	Read the Bearer token from a file instead of argv
`--allow-unauthenticated`	Permit binding to a non-loopback host without a key
`--cors`	Compatibility validation switch; fails unless `--cors-origin` or `serve.cors.origins` supplies an explicit origin
`--cors-origin <origin>`	Trust an exact HTTP(S) CORS origin (repeatable; wildcard is not allowed)
`--public-base-url <url>`	Externally reachable origin (required for image `response_format=url`)
`--docs`	Mount the Swagger UI at `/docs`. Off by default; adds same-port loopback origins to CORS, so it requires a fixed `--port`.
`-v, --verbose`	Detailed output

A non-loopback --host requires --api-key or --api-key-file; the server refuses to start otherwise. Use --allow-unauthenticated to override that and start with a warning instead.

--cors does not enable CORS by itself. It only validates that at least one explicit origin was supplied by CLI or config; --cors --docs also fails without one because the docs defaults are not explicit origins. Independently, --docs trusts same-port localhost, 127.0.0.1, and [::1], plus the bound host when that host is itself loopback. Since those origins come from the configured port, --docs --port 0 is rejected at startup instead of producing unusable http://localhost:0 origins.

Scripts that previously relied on wildcard CORS must name every trusted browser origin. They may keep --cors as a validation guard or drop it:

# Before: allowed every browser origin
qvac serve --openai --cors

# After: optionally retain validation and repeat once per trusted origin
qvac serve --openai --cors \
  --cors-origin https://app.example.com \
  --cors-origin http://localhost:3000

`qvac configure`

Interactively build a qvac.config.json with a starter serve.models, so you can go straight to qvac serve --openai. It searches the models the SDK provides — by name or by capability (role, addon, quantization) — and on a wide terminal previews, for the highlighted result, the exact serve.models entry it would produce. Pick a model, rename its alias, set config parameters (guided by the SDK's config schema — each field shows its type and description and is validated on entry, for model types the SDK exposes a schema for; currently llama.cpp chat + embedding), and (with $EDITOR) tweak the entry and review the result before adding it. Press Esc (or choose Back) to step back one menu; Ctrl+C aborts without writing. Existing entries are preserved; re-running is idempotent per model.

qvac configure                 # interactive
qvac configure --yes           # non-interactive: write a chat + transcription starter
qvac configure --modality chat --modality image

Option	Description
`-c, --config <path>`	Config file to write (default: `./qvac.config.json`). JSON only.
`-y, --yes`	Non-interactive: write a sensible default starter (chat + transcription).
`--modality <name>`	Non-interactive: add a modality (repeatable) — `chat` / `embedding` / `transcription` / `speech` / `image`.
`--force`	Re-add a model that is already configured (overwrites its existing entry in place).
`-q, --quiet`	Suppress output.

Single-artifact modalities (chat, embedding, transcription, image) are runnable as written. Text-to-speech is emitted as a best-effort example with a referenceAudioSrc placeholder — set it to a real .wav and see the linked TTS docs to finish. Runs in a terminal; for non-TTY use --yes / --modality.

See HTTP server — Configuration for the shape of the serve.models entries this command writes.

`qvac openai spec`

Emit the OpenAPI 3.1.0 spec for the OpenAI-compatible HTTP server to stdout or a file, without starting the server. Useful for piping into offline doc generators (Redocly, Widdershins, etc.) or wiring API clients.

Option	Description
`--yaml`	Emit YAML instead of JSON (default: JSON).
`-o, --output <path>`	Write the spec to a file instead of stdout.

Examples:

qvac openai spec                       # JSON → stdout (pipe-safe)
qvac openai spec -o spec.json          # write JSON to file
qvac openai spec --yaml                # YAML → stdout
qvac openai spec --yaml -o spec.yaml   # write YAML to file

`qvac doctor`

Run a preflight check of host system requirements.

Option	Description
`--json`	Emit a machine-readable `DoctorReport` JSON.
`-q, --quiet`	Set the exit code only; suppress human-readable output.

HTTP server

qvac configure

System requirements

On this page