> For the complete documentation index, see [llms.txt](https://docs.interlynk.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.interlynk.io/lynkctl/database.md).

# OSS-Index Database

`lynkctl db` manages the OSS-index database that `generate` uses to identify vendored open-source projects. The database is a local cache; `db` keeps it current and lets you inspect it.

***

## Cache Locations

By default, lynkctl stores the database in the operating system cache directory:

```
macOS:   ~/Library/Caches/lynkctl/oss-index/oss-index.db
Linux:   $XDG_CACHE_HOME/lynkctl/oss-index/oss-index.db
         (or ~/.cache/lynkctl/oss-index/oss-index.db)
```

Override the location with `--cache-dir DIR`. The file inside is always named `oss-index.db`.

## Common Flags

All `db` subcommands accept:

| Flag              | Default | Description                                                                 |
| ----------------- | ------- | --------------------------------------------------------------------------- |
| `--cache-dir`     |         | Directory holding `oss-index.db`; empty uses the OS default cache location. |
| `--oss-index-url` |         | Override the OSS-index download URL (staging or mirror).                    |

## Subcommands

### `db download`

Fetch or refresh the cache from the published URL — roughly 300 MB. The command is idempotent: it skips the transfer when the cached file already matches the published manifest. On success it prints the resolved cache path to stdout.

```bash
lynkctl db download              # first install or routine refresh
lynkctl db download --force      # re-download even when current
```

| Flag      | Description                                                           |
| --------- | --------------------------------------------------------------------- |
| `--force` | Re-download even when the local cache matches the published manifest. |

### `db check`

Compare the cached database against the published manifest. It does **not** modify the cache, which makes it suitable as a CI gate signal.

```bash
lynkctl db check || lynkctl db download   # refresh only when needed
lynkctl db check --format json            # machine-readable
```

The exit code is `0` when the cache is up to date, and `1` when it is stale, missing, format-incompatible, or a network error occurred.

| Flag       | Default | Description                                           |
| ---------- | ------- | ----------------------------------------------------- |
| `--format` | `text`  | `text` (human-readable) or `json` (machine-readable). |

### `db info`

Inspect the cached database without touching the network: format version, build date, sha256, file size, and self-described index statistics (project, version, and file counts) when the database is present.

```bash
lynkctl db info
lynkctl db info --format json
```

| Flag       | Default | Description       |
| ---------- | ------- | ----------------- |
| `--format` | `text`  | `text` or `json`. |

### `db path`

Print the absolute path lynkctl uses for the OSS-index cache, resolved against `--cache-dir` or the OS default. Useful in scripts.

```bash
DB=$(lynkctl db path)
cp "$DB" /backup/
```

### `db clear`

Delete the cached database and its manifest sidecar. The command is idempotent — it exits `0` if nothing is cached — and removes a partial cache too. It prompts for confirmation unless `--yes` is given.

```bash
lynkctl db clear
lynkctl db clear --yes
```

| Flag    | Default | Description                               |
| ------- | ------- | ----------------------------------------- |
| `--yes` | `false` | Skip the interactive confirmation prompt. |

## Related

* [Air-Gapped Environments](/lynkctl/how-to-guides/air-gapped.md) — pre-fetch the database and run lynkctl offline