Installation

Installing Unrag is a one-command operation. You run the initializer, answer a few questions (or skip them with flags), and the CLI writes the necessary files into your project.

Running the initializer

The simplest invocation is interactive:

bunx unrag@latest init

This will prompt you for:

1. Install directory — where to put the vendored module code. The default is lib/unrag, but you can choose any project-relative path that makes sense for your codebase structure.

2. Store adapter — which database adapter to use. Your options are Drizzle (a typed schema with Drizzle ORM), Prisma (using raw SQL through Prisma's client), or Raw SQL (using the pg driver directly).

3. Import alias base — the TypeScript path alias for importing Unrag. The default is @unrag, which means you'll import from @unrag/core, @unrag/config, etc. If you already have an @unrag alias or prefer something else, you can change it.

4. Rich media ingestion — whether to enable multimodal capabilities for PDFs, images, audio, video, and other files. If you say yes, the CLI presents a list of extractors to install (with sensible defaults pre-selected) and configures everything for you. This is optional—you can always enable it later by re-running init --rich-media or editing unrag.config.ts directly.

If you want to skip the prompts—useful in CI or when scripting—pass the --yes flag along with your choices:

bunx unrag@latest init --yes --store drizzle --dir lib/unrag --alias @unrag

To enable rich media non-interactively, add --rich-media (uses default extractors) or --extractors (with a comma-separated list):

bunx unrag@latest init --yes --store drizzle --rich-media
bunx unrag@latest init --yes --store drizzle --extractors pdf-text-layer,file-text

If you want the legacy full scaffold (all embedding providers + shared utilities), add --full. To generate the optional setup doc, add --with-docs.

What the CLI creates

After initialization completes, your project will have several new files:

If you enabled rich media during setup, you'll also see additional extractor modules under the extractors/ folder for the specific extractors you selected (e.g., pdf-text-layer/, image-ocr/). The shared extractor utilities (media.ts, text.ts) are only installed when rich media is enabled (or if you opt into a full scaffold).

unrag.config.ts is where you configure the embedding provider, database connection, and default settings. The CLI generates this file with working code for your chosen adapter—you can use it immediately or customize it. If you enabled rich media, this file already has the extractors registered and the relevant assetProcessing flags enabled.

lib/unrag/ contains the vendored module code including the core engine (with ingest, retrieve, delete, and rerank operations), your chosen store adapter, the selected embedding provider implementation, and shared utilities. These files are yours to read and modify. If you want all provider implementations vendored for easy switching later, run unrag init --full. Some providers require embedding/_shared.ts; it’s only installed when needed.

lib/unrag/unrag.md is optional. If you want a generated setup doc with schema and adapter notes, re-run with unrag init --with-docs.

unrag.json records your installation choices (including which extractors you installed) for future unrag@latest init runs.

Changes to existing files

The CLI may also modify your existing configuration:

Dependencies. Unrag adds the packages needed for your chosen adapter to your package.json. For Drizzle, that includes drizzle-orm and pg. For Prisma, it adds @prisma/client. For Raw SQL, just pg. All adapters need the ai package for embedding. If these dependencies already exist, Unrag won't overwrite their versions.

TypeScript paths. If Unrag detects you're in a Next.js project, it patches your tsconfig.json (or jsconfig.json) to add path aliases:

{
  "compilerOptions": {
    "paths": {
      "@unrag/*": ["./lib/unrag/*"],
      "@unrag/config": ["./unrag.config.ts"]
    }
  }
}

This lets you import Unrag modules cleanly without relative paths threading through your codebase.

Automatic dependency installation

The CLI automatically runs your package manager to install dependencies after adding them to package.json. It detects which package manager you're using based on your lockfile (bun.lock, pnpm-lock.yaml, yarn.lock, or package-lock.json).

If you need to skip automatic installation (for example, in CI pipelines where you manage installs separately), pass the --no-install flag:

bunx unrag@latest init --yes --store drizzle --no-install

Updating Unrag

Because Unrag vendors code into your project, updating requires more care than a typical dependency bump. You've likely customized files, and a naive overwrite would destroy your changes.

The unrag upgrade command handles this intelligently using a three-way merge—the same algorithm Git uses for combining branches. It compares your current files against both the version you originally installed and the new version, automatically merging changes when possible and marking conflicts for manual resolution when automatic merging isn't feasible.

bunx unrag@latest upgrade

The upgrade command:

• Preserves your customizations while bringing in upstream improvements
• Shows you exactly what will change before making any modifications
• Handles dependency updates alongside file changes
• Warns you about uncommitted changes to prevent accidental data loss

For a complete guide to the upgrade process, see the Upgrading documentation.