# CLI (/cli)



## 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
* SDK bundling
* System requirements check

## 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](/configuration) to learn how to do this.
  </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>

## OpenAI-compatible HTTP server

QVAC CLI provides an HTTP server that is compatible with the [OpenAI REST API](https://developers.openai.com/api/reference/overview), enabling broad integration with the AI ecosystem. It internally translates HTTP requests into SDK calls. As a result, any system compatible with the OpenAI REST API can point to `http://localhost:11434/v1/` and work without changes.

<Card href="/cli/http-server" title="HTTP server">
  Learn how to run a local HTTP server that exposes an OpenAI-compatible API.
</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](/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="/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 openai`

Start an OpenAI-compatible REST API server.

| Option                    | Description                                                                                                        |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `-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                                                                                |
| `--cors`                  | Enable CORS headers                                                                                                |
| `--docs`                  | Mount the Swagger UI at `/docs` (auto-enables CORS so the UI's "Try it out" works across origins). Off by default. |
| `--public-base-url <url>` | Externally reachable origin (required for image `response_format=url`)                                             |
| `-v, --verbose`           | Detailed output                                                                                                    |

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