> 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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.interlynk.io/lynkctl/database.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.