CLI Reference

Unrag is installed and managed through CLI commands that generate files, validate configuration, and help you maintain your installation over time. This reference covers every command and option.

Basic usage

bunx unrag@latest init

Running without arguments starts an interactive prompt that asks for your preferences. For CI/CD or scripted setups, pass flags to skip the prompts.

Adding a connector

Install a connector into an existing Unrag installation:

bunx unrag@latest add notion

This installs vendored connector source files under your Unrag install directory (e.g. lib/unrag/connectors/notion) and adds connector-specific dependencies to your project.

Adding an extractor

Install an extractor module for processing rich media assets:

bunx unrag@latest add extractor pdf-llm

This installs the extractor source files under lib/unrag/extractors/<name> and adds any required dependencies.

Adding a battery

Install a battery module for extended functionality like reranking:

bunx unrag@latest add battery reranker

This installs the battery source files under your Unrag install directory (e.g. lib/unrag/rerank/) and adds battery-specific dependencies. Batteries are optional modules that add capabilities beyond core ingest/retrieve—see Batteries for available options.

Available extractors

Registering extractors manually

If you installed an extractor with add extractor (rather than during init --rich-media), you need to register it in your unrag.config.ts:

import { createPdfLlmExtractor } from "./lib/unrag/extractors/pdf-llm";

export const unrag = defineUnragConfig({
  // ...
  engine: {
      // ...
    extractors: [createPdfLlmExtractor()],
  },
} as const);

You'll also need to enable the corresponding assetProcessing flag. For example, pdf-llm requires assetProcessing.pdf.llmExtraction.enabled: true.

Validating your installation

The doctor command checks that your Unrag installation is correctly configured:

bunx unrag doctor

This runs static checks that don't require a database connection—verifying that files exist, environment variables are set, and your config is coherent. Add --db to also check database connectivity, schema, and indexes:

bunx unrag doctor --db

For a complete walkthrough of what doctor checks and how to use it in CI, see the Validating Your Installation guide.

Doctor setup

Generate a project-specific config file and add convenience scripts to your package.json:

bunx unrag doctor setup

This creates .unrag/doctor.json with your settings and adds unrag:doctor, unrag:doctor:db, and unrag:doctor:ci scripts. Use --yes to skip interactive prompts.

Doctor flags

--config <path>

Load settings from a doctor config file instead of using defaults. This is typically generated by doctor setup.

bunx unrag doctor --config .unrag/doctor.json

--db

Run database checks in addition to static checks. Requires a valid DATABASE_URL (or the env var specified in your config).

bunx unrag doctor --db

--json

Output results as JSON for programmatic consumption. Useful in CI pipelines.

bunx unrag doctor --json

--strict

Treat warnings as failures. When combined with --db, any missing recommended indexes will cause a non-zero exit code.

bunx unrag doctor --db --strict

--schema <name>

Specify the PostgreSQL schema name if you're not using the default public schema.

bunx unrag doctor --db --schema myapp

--scope <prefix>

Limit dimension consistency checks to embeddings whose source_id starts with the given prefix. Useful when you have content from multiple embedding models.

bunx unrag doctor --db --scope "docs:"

--database-url-env <name>

Specify which environment variable contains your database URL. Defaults to DATABASE_URL.

bunx unrag doctor --db --database-url-env POSTGRES_URL

--env-file <path>

Load environment variables from a specific file before running checks.

bunx unrag doctor --env-file .env.production

Debug command

Launch the debug TUI to connect to a running application with UNRAG_DEBUG=true:

bunx unrag debug

This opens an interactive terminal interface that connects to the debug server running in your app. From the TUI you can watch real-time events, run queries, inspect documents, and diagnose configuration issues.

Debug options

--url <ws://...>

Specify the full WebSocket URL to connect to:

bunx unrag debug --url ws://192.168.1.100:3847

--port <number> or -p <number>

Shorthand for specifying just the port (uses localhost):

bunx unrag debug --port 4000

The default port is 3847.

For full documentation on the debug TUI and its capabilities, see Debugging.

Upgrade command

Update your vendored Unrag installation to a new version while preserving customizations:

bunx unrag@latest upgrade

The upgrade command uses a three-way merge algorithm (the same approach Git uses) to intelligently combine your local changes with upstream updates. It compares your files against both the version you originally installed and the new version, merging changes automatically when possible.

Upgrade options

--from-version <version>

Specify the base version to diff from. This is required if your unrag.json doesn't have installedFrom.unragVersion (common for older installations).

bunx unrag@latest upgrade --from-version 0.3.5

--dry-run

Show the upgrade plan without making any changes. Useful for previewing what would happen:

bunx unrag@latest upgrade --dry-run

--allow-dirty

Allow running with uncommitted git changes. By default, the upgrade command warns about uncommitted changes and (in non-interactive mode) refuses to proceed.

bunx unrag@latest upgrade --allow-dirty

--overwrite <mode>

Control how files without a known base version are handled. Options are:

• skip (default) — Leave the file unchanged
• force — Replace with the new version

bunx unrag@latest upgrade --overwrite force

--no-install

Skip dependency installation during the upgrade. This is handy in CI or when you want to review changes before running your package manager.

bunx unrag@latest upgrade --no-install

--verbose

Show the full init/add snapshot logs while the upgrade command prepares its baseline comparisons. By default, upgrade keeps this quiet and only prints the upgrade plan and summary.

bunx unrag@latest upgrade --verbose

-y, --yes

Non-interactive mode. Skip all prompts and proceed automatically. If conflicts are detected, they're written to the files (with conflict markers) for manual resolution.

bunx unrag@latest upgrade --yes

Upgrade plan actions

When you run upgrade, you'll see a plan with these possible actions:

For comprehensive documentation on upgrading, including conflict resolution strategies, see Upgrading.

Init command flags

These flags control the behavior of unrag init.

--yes or -y

Skip interactive prompts and use defaults (or values from an existing unrag.json file). This is essential for automated pipelines.

bunx unrag@latest init --yes

--store <adapter>

Choose which database adapter to install. Options are:

• drizzle — Drizzle ORM with typed schema
• prisma — Prisma client with raw SQL queries
• raw-sql — Direct pg driver usage

bunx unrag@latest init --store drizzle

--dir <path> or --install-dir <path>

Set where the vendored module code is installed, relative to your project root. The default is lib/unrag.

bunx unrag@latest init --dir src/lib/unrag

--alias <base>

Set the TypeScript path alias prefix. The default is @unrag, which means you'll import from @unrag/core, @unrag/config, etc.

bunx unrag@latest init --alias @myproject/rag

--rich-media

Enable rich media ingestion during setup. This installs selected extractors and enables the corresponding assetProcessing flags in your config. Prompts you to select which extractors to install. Note: this does not enable multimodal embeddings—see Multimodal Embeddings to configure that separately.

bunx unrag@latest init --rich-media

When combined with --yes, the CLI uses a sensible default preset of extractors (pdf-text-layer and file-text) without prompting.

--no-rich-media

Explicitly disable rich media ingestion. This is the default when running non-interactively with --yes, but you can use this flag to be explicit about your intent.

bunx unrag@latest init --yes --no-rich-media

--extractors <list>

Specify exactly which extractors to install, as a comma-separated list. This implies --rich-media.

bunx unrag@latest init --yes --extractors pdf-text-layer,pdf-llm,file-text

Available extractor names: pdf-text-layer, pdf-llm, pdf-ocr, image-ocr, image-caption-llm, audio-transcribe, video-transcribe, video-frames, file-text, file-docx, file-pptx, file-xlsx.

--no-install

Skip automatic dependency installation. By default, the CLI runs your package manager after adding dependencies to package.json. Use this flag in CI pipelines or when you want to manage installs separately.

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

--full

Install the full scaffold (all embedding provider implementations + rich-media shared utilities), matching legacy behavior.

bunx unrag@latest init --yes --full

--with-docs

Generate lib/unrag/unrag.md (schema + env var notes).

bunx unrag@latest init --yes --with-docs

Full examples

A complete non-interactive invocation with text-only setup:

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

Enable rich media with default extractors:

bunx unrag@latest init --yes --store drizzle --rich-media

Enable rich media with specific extractors:

bunx unrag@latest init --yes --store drizzle --extractors pdf-text-layer,pdf-llm,image-ocr

Files created

After initialization, your project will contain:

unrag.config.ts — The configuration file at your project root. This is where you wire together the database client, embedding provider, and default settings. Edit this file to customize behavior.

lib/unrag/ (or your chosen directory) — The vendored module code:

• core/ — ContextEngine, ingest, retrieve, types, chunking
• store/ — Your chosen adapter (Drizzle, Prisma, or raw SQL)
• embedding/ — The selected embedding provider + dispatcher

lib/unrag/unrag.md — Optional setup notes including the database schema, environment variables, and adapter-specific tips (generate with --with-docs).

unrag.json — Records your installation choices. When you re-run unrag@latest init, it reads this file and uses your previous selections as defaults.

Files modified

package.json — Unrag adds dependencies for your chosen adapter:

• Drizzle: drizzle-orm, pg, @types/pg
• Prisma: @prisma/client, prisma
• Raw SQL: pg, @types/pg
• All adapters: ai

If dependencies already exist, their versions are not overwritten.

tsconfig.json or jsconfig.json (Next.js only) — Path aliases are added:

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

Overwriting existing files

If target files already exist, the CLI prompts before overwriting. In non-interactive mode (--yes), existing files are not overwritten—you'll need to delete them manually first if you want fresh copies.

Re-running safely

It's safe to re-run unrag@latest init to update your installation. The CLI reads unrag.json for your previous choices and prompts only for files that would be overwritten. This lets you update vendored code when new versions are available while keeping your customizations.

A typical update workflow:

1. Run bunx unrag@latest init
2. Review each file the CLI wants to overwrite
3. Accept updates for files you haven't customized
4. Reject updates for files with intentional local changes

Troubleshooting

"Could not find a project root" — The CLI couldn't find a package.json. Run from your project directory.

"Alias should start with @" — TypeScript path aliases conventionally start with @. Choose something like @unrag or @myproject/rag.

Dependency conflicts — If the CLI adds a dependency version that conflicts with your existing packages, manually adjust package.json after initialization.