> ## Documentation Index
> Fetch the complete documentation index at: https://docs.deploybaseline.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Provider versions

> Where each built-in service's provider comes from, how baseline.lock pins it, and how to run without a network.

Each built-in service runs a provider package, such as `@deploybaseline/stripe`, in its own process. The CLI finds that package before it starts the service, pins the exact version in `baseline.lock`, and prints where it came from:

```text theme={null}
  stripe  http://localhost:4009
    Source: stripe
    Provider: @deploybaseline/stripe 0.14.1 (cache)
```

## Where a provider comes from

For each built-in service, the CLI takes the first of these that has a version in range:

| Order | Source | Printed as |
| - | - | - |
| 1 | The project's `node_modules` (`npm install -D @deploybaseline/stripe`) | `project` |
| 2 | The exact version `baseline.lock` pins, from the cache or a pull | `cache`, `pull` |
| 3 | The newest version in range already in the provider cache | `cache` |
| 4 | A pull of the newest version in range from the npm registry | `pull` |
| 5 | In a checkout of the Baseline repository only, the workspace package | `workspace` |

A pull is a plain registry fetch: the CLI reads the package's metadata, downloads its tarball, checks the tarball's SHA-512 integrity, and unpacks it into the cache. No install scripts run and no dependencies are installed, because a provider's entry is a self-contained bundle.

The CLI package itself ships no providers. The first start on a machine downloads each provider it runs and says so once: `Pulled @deploybaseline/github 0.14.0, ... into ~/.cache/baseline. Later starts use the cache.` Every later start runs them from the cache, even with no network.

When the registry cannot be reached and no version in range is cached, start fails for that service and says how to get it: connect once, run `npx @deploybaseline/cli pull`, or install the provider as a dev dependency.

## Pick a version

Each CLI release names a default range for every built-in provider (CLI 0.14.0 runs `^0.14.0` for each), so a CLI picks up compatible releases of its providers without a CLI release. Providers release on their own, so their versions drift apart over time. Set `version` on a service to choose another range:

```json theme={null}
{
  "stripe": {
    "version": "^0.14",
    "customers": [
      {
        "email": "ada@example.com"
      }
    ]
  }
}
```

Or under `services`:

```json theme={null}
{
  "services": {
    "billing": {
      "emulator": "stripe",
      "version": "0.14.1"
    }
  }
}
```

`version` takes an exact version, `^`, `~`, `x` wildcards, comparators such as `>=0.14.0 <0.16`, and `||`. It applies to built-in providers only; a custom emulator is your own code.

## baseline.lock

With a config file, `start` writes `baseline.lock` next to it once every service is running. Commit it: every machine and CI run then starts the same provider versions.

```yaml theme={null}
lockfileVersion: 1
providers:
  stripe:
    package: "@deploybaseline/stripe"
    version: 0.14.1
    integrity: sha512-...
```

* `start` adds a service that is not in the lockfile, and never changes an entry whose version is still in range. A failed start leaves the lockfile alone.
* An entry from the project's `node_modules` has `source: project` and no integrity: npm already checked it. In the Baseline repository itself, the workspace package gives `source: workspace`. A lockfile from an earlier CLI that says `source: bundled` still reads: the next start pulls that pinned version and records its integrity.
* A cached copy that does not match the lockfile's integrity is pulled again. A registry tarball that does not match is refused.
* With no config file there is no lockfile, and the cache and range decide.
* A `provider:` service (a [provider package](/provider-authors.md) that is not built in) has `trusted: true` once you have trusted that version. Trust covers that version and integrity only.

## Commands

| Command | What it does |
| - | - |
| `npx @deploybaseline/cli pull` | Put every configured provider in the cache and pin it in `baseline.lock` |
| `npx @deploybaseline/cli update [services...]` | Move providers to the newest version in their range and rewrite `baseline.lock` |
| `npx @deploybaseline/cli providers` | List cached providers and the projects whose `baseline.lock` uses them (`--json` for scripts) |
| `npx @deploybaseline/cli prune` | Remove cached providers that no known `baseline.lock` uses (`--dry-run` to preview) |
| `npx @deploybaseline/cli trust [services...]` | Trust `provider:` services and pin them in `baseline.lock` with `trusted: true` |

`pull` and `update` take `--config` and `--service` like `start`.

## Offline and CI

`--offline` (or `BASELINE_OFFLINE=1`) never touches the network: providers come from the project or the cache, and a provider that is in neither fails with a message naming it. Run `npx @deploybaseline/cli pull` once (or any start with the network) before going offline.

* **CI:** cache the provider cache directory keyed on `baseline.lock`, run `npx @deploybaseline/cli pull`, then `npx @deploybaseline/cli start --offline`.
* **Docker:** run `pull` during the image build with `BASELINE_CACHE_DIR` inside the image.
* **Vendored dependencies:** install the providers you use as dev dependencies. They resolve from `node_modules` with no cache at all.

## The cache and the registry

The cache lives in `BASELINE_CACHE_DIR`, else `$XDG_CACHE_HOME/baseline`, else `~/.cache/baseline` (`%LOCALAPPDATA%\baseline` on Windows). Registry metadata is reused for an hour, and a registry that could not be reached is left alone for five minutes.

Pulls follow npm's own settings: `registry`, scoped registries (`@acme:registry=`), and auth (`//host/path/:_authToken=`, `_auth`, `username` and `_password`) from the project's `.npmrc`, your user `.npmrc`, and `npm_config_*` environment variables, with `${VAR}` expanded. A token is only ever sent to URLs under the registry it is set for.

## The programmatic API

`createEmulator` resolves its provider the same way, from the current directory, without a lockfile:

```ts theme={null}
import { createEmulator } from "@deploybaseline/cli";

const stripe = await createEmulator({ service: "stripe", version: "^0.14", offline: true });
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.