---
title: "CLI"
canonical: https://docs.qvac.tether.io/cli/v0.12/
collection: "CLI"
package: "@qvac/cli"
line: v0.12
current_line: false
---

# CLI (/cli/v0.12)



## 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

<Steps>
  <Step>
    Install the CLI globally so the `qvac` command is available on your `PATH`:

    ```bash
    npm install -g @qvac/cli
    ```
  </Step>

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

    <Callout type="success">
      **Tip:** you can use the CLI to help with part of the configuration. See [Interactive config generator](#interactive-config-generator).
    </Callout>
  </Step>

  <Step>
    Run a command:

    ```bash
    qvac --help
    ```
  </Step>
</Steps>

<Callout type="success">
  **Tip:** if you cannot install the CLI globally, you can run it with `npx` instead:

  ```bash
  npx --package "@qvac/cli" qvac --help
  ```
</Callout>

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

<Cards>
  <Card href="/cli/v0.12/http-server" title="HTTP server">
    Run a local HTTP server that exposes an OpenAI-compatible API.
  </Card>

  <Card href="/cli/v0.12/http-server/connection" title="Connect AI tools to QVAC">
    Use the HTTP server as a local model provider for AI tools that support OpenAI-compatible API.
  </Card>

  <Card href="/cli/v0.12/http-server/integration" title="Integrate with the OpenAI-compatible server">
    Use the npm package @qvac/ai-sdk-provider to create a client for the HTTP server.
  </Card>
</Cards>

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

<Card href="#qvac-configure" title="qvac configure">
  See the reference for options, behavior notes, and examples.
</Card>

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

<Card href="/sdk/system-requirements" title="System requirements">
  Full host matrix, deploy targets, optional tools, exit codes, and JSON schema.
</Card>

## 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:

```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 (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.

```bash
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](/cli/v0.12/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:

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