---
title: "CLI"
canonical: https://docs.qvac.tether.io/cli/v0.17/
collection: "CLI"
package: "@qvac/cli"
line: v0.17
current_line: false
---
# CLI (/cli/v0.17)
## 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`:
```bash
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](/sdk/configuration) to learn how to do this.
**Tip:** you can use the CLI to help with part of the configuration. See [Interactive config generator](#interactive-config-generator).
Run a command:
```bash
qvac --help
```
**Tip:** if you cannot install the CLI globally, you can run it with `npx` instead:
```bash
npx --package "@qvac/cli" qvac --help
```
## HTTP server
QVAC CLI provides an HTTP server that internally translates HTTP requests into
SDK calls, with an optional extension compatible with the
[OpenAI REST API](https://developers.openai.com/api/reference/overview), 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.
This is what makes QVAC usable as a local model provider: any tool that already speaks that API can point at it and run against models on your own machine, with no code change.
Run a local HTTP server that exposes an OpenAI-compatible API.
Use the HTTP server as a local model provider for AI tools that support OpenAI-compatible API.
Use the npm package @qvac/ai-sdk-provider to create a client for the HTTP server.
## 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.
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](/sdk/configuration/plugins) 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.
Full host matrix, deploy targets, optional tools, exit codes, and JSON schema.
## Reference
Run `qvac --help` to see all available commands and `qvac --help` for command-specific options.
### `qvac bundle sdk`
Generate a tree-shaken Bare worker bundle with selected plugins.
| Option | Description |
| --------------------- | ----------------------------------------------------------- |
| `-c, --config ` | Config file path (default: auto-detect `qvac.config.*`) |
| `--sdk-path ` | Path to SDK package (default: auto-detect in node\_modules) |
| `--host ` | Target host (repeatable) |
| `--defer ` | 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 ` | Config file path (default: auto-detect `qvac.config.*`) |
| `-p, --port ` | Port to listen on (default: `11434`) |
| `-H, --host ` | Host to bind to (default: `127.0.0.1`) |
| `--model ` | Model alias to preload (repeatable, must be in config) |
| `--api-key ` | Require Bearer token authentication |
| `--api-key-file ` | 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 ` | Trust an exact HTTP(S) CORS origin (repeatable; wildcard is not allowed) |
| `--allowed-host ` | Accept this `Host` header besides loopback names, IP addresses and the bind host; `.example.com` also covers subdomains (repeatable) |
| `--allow-any-host` | Accept any `Host` header, turning off DNS-rebinding protection |
| `--public-base-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.
Every request, including `/openapi.json`, must carry a `Host` header naming a loopback host, an IP address, the bind host, the `--public-base-url` host or an `--allowed-host` entry; anything else gets `403 host_not_allowed`. This stops a web page that rebinds its own domain to `127.0.0.1` from calling the server. Behind a reverse proxy or under a LAN hostname, list that name with `--allowed-host` or `serve.allowedHosts`.
`--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:
```bash
# 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`](#qvac-serve). It searches the models the SDK provides by name or by capability, including role, addon, and quantization. On a wide terminal, it previews the exact `serve.models` entry for the highlighted result. Pick a model, rename its alias, and set config parameters. The parameter editor shows types and descriptions and validates entries against the SDK's config schema, currently for llama.cpp chat, embedding, and decision models. Use `$EDITOR` to tweak the entry and review it 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.
```bash
qvac configure # interactive
qvac configure --yes # non-interactive: write a chat + transcription starter
qvac configure --modality chat --modality image
qvac configure --modality decision
```
| Option | Description |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `-c, --config ` | Config file to write (default: `./qvac.config.json`). JSON only. |
| `-y, --yes` | Non-interactive: write a sensible default starter (chat + transcription). |
| `--modality ` | Non-interactive: add a modality, repeatable. `chat` / `embedding` / `transcription` / `speech` / `image` / `decision`. |
| `--force` | Re-add a model that is already configured (overwrites its existing entry in place). |
| `-q, --quiet` | Suppress output. |
The picker includes MOSS-SoundEffect and MOSS-Speech starters. MOSS-SoundEffect uses the model source URL with `ttsEngine: "moss-sfx"`; MOSS-Speech includes its codec source. Their conversation and sound-effect controls are available through the [SDK Text-to-Speech API](/sdk/ai-capabilities/text-to-speech); the OpenAI speech endpoint does not represent those controls.
Single-artifact modalities, including chat, embedding, transcription, image, and decision, 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`.
The Decision starter selects `LAYA_MULTILINGUAL_322M_Q8_0`. Start it with `qvac serve --openai` and use the [Decisions endpoint](/cli/v0.17/http-server#decisions) to answer predicate, choice, and score questions about text.
See [HTTP server — Configuration](/cli/v0.17/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 ` | Write the spec to a file instead of stdout. |
Examples:
```bash
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. |