CLI Reference

The libragen CLI provides commands for building, querying, and managing RAG libraries.

Global Options

These options work with all commands:

Commands

build

Create a new library from source files.

libragen build <source> [options]

Arguments

Options

Examples

# Basic build
libragen build ./docs --name my-docs

# With version and description
libragen build ./docs \
  --name my-api \
  --description "API documentation" \
  --content-version 2.1.0

# Custom chunk settings
libragen build ./docs \
  --name my-docs \
  --chunk-size 1024 \
  --chunk-overlap 100

# Exclude patterns
libragen build ./docs \
  --name my-docs \
  --exclude "**/node_modules/**" \
  --exclude "**/test/**"

# Build from git repository
libragen build https://github.com/user/repo --name repo-docs

# Build with explicit license
libragen build ./docs --name my-docs --license MIT

# Build with multiple licenses (dual licensing)
libragen build ./docs --name my-docs --license MIT Apache-2.0

# Disable AST chunking (use text-based chunking only)
libragen build ./src --name my-code --no-ast-chunking

# Use minimal context for AST chunking (smaller chunks)
libragen build ./src --name my-code --context-mode minimal

License Detection

When building from git repositories, licenses are automatically detected from LICENSE files (LICENSE, LICENSE.md, LICENSE.txt, COPYING).

• Git sources: Auto-detected if not explicitly provided
• Local sources: Use --license to specify
• Explicit --license: Always takes precedence

Supported licenses: MIT, Apache-2.0, GPL-3.0, GPL-2.0, LGPL-3.0, LGPL-2.1, BSD-3-Clause, BSD-2-Clause, ISC, Unlicense, MPL-2.0, CC0-1.0, AGPL-3.0

AST-Aware Code Chunking

By default, libragen uses AST-aware chunking for supported code files. This produces higher-quality embeddings by:

• Respecting language boundaries — Chunks align with functions, classes, and methods instead of arbitrary character positions
• Including semantic context — Each chunk includes scope chain, imports, and sibling entities
• Contextualizing for embeddings — A special contextualizedText is generated that includes file path, scope, and signatures

Supported languages: TypeScript, JavaScript, Python, Rust, Go, Java

Context modes:

• full (default) — Include all available context (scope chain, imports, siblings, signatures)
• minimal — Include only essential context (scope chain, entity signatures)
• none — No additional context (raw code only)

Non-code files (Markdown, JSON, text, etc.) always use text-based chunking.

query

Search a library with natural language.

libragen query [options] <query>

Arguments

Options

The -l option accepts either:

• A library name (e.g., my-lib) — resolved using the library discovery algorithm
• A file path (e.g., ./my-lib.libragen) — used directly

When using a library name, the resolution algorithm searches:

1. Project-local directories (.libragen/libraries/ in cwd)
2. Global library directory (~/.libragen/libraries/)
3. Any paths specified with -p

Examples

# Query by library name (uses resolution algorithm)
libragen query --library my-docs "How do I authenticate?"

# Query by explicit file path
libragen query -l ./my-docs.libragen "How do I authenticate?"

# Query with custom project directory
libragen query -l my-docs -p ./my-project "error handling"

# Get more results as JSON
libragen query -l my-docs -k 20 -f json "error handling"

# Query specific version
libragen query -l my-api --content-version 2.0.0 "rate limits"

Output Format

Text output (default):

[1] authentication.md (score: 0.89)
    To authenticate, pass your API key in the Authorization header...

[2] getting-started.md (score: 0.82)
    First, obtain an API key from the dashboard...

JSON output (--format json):

{
  "results": [
    {
      "rank": 1,
      "score": 0.89,
      "source": "authentication.md",
      "content": "To authenticate, pass your API key..."
    }
  ]
}

list

List installed libraries.

Aliases: l, ls

libragen list [options]

Options

Output

Each library displays:

• Name and version
• Location badge: [project] or [global] indicating where the library was found
• Path (with --show-path or -v): full file path to the .libragen file

The location badge helps identify which libraries come from project-local directories vs the global directory.

Library Discovery

By default, libragen discovers libraries from:

1. Project directory — If .libragen/libraries/ exists in the current directory, it’s searched first
2. Global directory — $LIBRAGEN_HOME/libraries (always included)

When -p is specified, the path is transformed to <path>/.libragen/libraries and only that path is searched—no global directory, no auto-detection.

Examples

# List all libraries (auto-detected + global)
libragen list

# List with file paths shown
libragen list --show-path

# List only project-local libraries
libragen list -p ./my-project

# List from multiple specific paths
libragen list -p ./libs -p ./vendor/libs

# JSON output for scripting (includes path and location)
libragen list --json

Example output:

📚 Installed Libraries (2)

  my-docs v1.0.0 [project]
  react-docs v19.0.0 [global]

With --show-path:

📚 Installed Libraries (2)

  my-docs v1.0.0 [project]
    /path/to/project/.libragen/libraries/my-docs-1.0.0.libragen

  react-docs v19.0.0 [global]
    /Users/you/.libragen/libraries/react-docs-19.0.0.libragen

inspect

Inspect the contents of a library (.libragen) or packed collection (.libragen-collection) file.

libragen inspect <source> [options]

Arguments

Options

Examples

# Inspect a library file
libragen inspect my-lib.libragen

# Inspect a packed collection
libragen inspect my-collection.libragen-collection

# Inspect from URL
libragen inspect https://example.com/my-lib.libragen

# JSON output for scripting
libragen inspect my-lib.libragen --json

Output (library)

📚 Library Contents

  File:    /path/to/my-lib.libragen
  Size:    1.23 MB

  Metadata:
    Name:        my-lib
    Version:     1.0.0
    Description: My library description
    Content:     v2.0.0 (semver)
    Schema:      v3
    Created:     2024-01-15T10:30:00.000Z

  Stats:
    Chunks:      1,234
    Sources:     42 files

  Embedding:
    Model:       Xenova/bge-small-en-v1.5
    Dimensions:  384

  Source:
    Type:        git
    URL:         https://github.com/user/repo
    Ref:         main
    Commit:      abc12345

  License(s):
    • MIT

Output (packed collection)

📦 Collection Contents

  File: /path/to/my-collection.libragen-collection
  Size: 5.67 MB

  Metadata:
    Name:    my-collection
    Version: 1.0.0
    Desc:    My collection description

  Libraries (3):
    • api-docs.libragen (1.2 MB)
    • guides.libragen (2.3 MB)
    • tutorials.libragen (2.17 MB)

Install with:
  libragen install /path/to/my-collection.libragen-collection

install

Install a library from a collection or URL.

libragen install <source> [options]

Options

Examples

# Install from file (defaults to $LIBRAGEN_HOME/libraries)
libragen install ./my-lib.libragen

# Install to a project directory (creates ./my-project/.libragen/libraries)
libragen install ./my-lib.libragen -p ./my-project

# Install to multiple project directories (first path is used for install)
libragen install ./my-lib.libragen -p ./project-a -p ./project-b

# Install from URL
libragen install https://example.com/my-lib-1.0.0.libragen

uninstall

Remove an installed library.

libragen uninstall <name> [options]

Options

Examples

# Uninstall from auto-detected paths
libragen uninstall my-docs

# Uninstall from specific project only
libragen uninstall my-docs -p ./my-project

update

Update installed libraries to newer versions from their collections.

libragen update [name] [options]

Arguments

Options

Examples

# Update all libraries
libragen update

# Update specific library
libragen update react-docs

# Preview updates without applying
libragen update --dry-run

# Update only project-local libraries
libragen update -p ./my-project

config

Display current libragen configuration and paths.

libragen config [options]

Options

Example

libragen config

⚙️  Libragen Configuration

  Version:  0.1.0

  Paths:
    Home:       ~/Library/Application Support/libragen
    Libraries:  ~/Library/Application Support/libragen/libraries
    Models:     ~/Library/Application Support/libragen/models

  Active Library Paths (in priority order):
    🌐 ~/Library/Application Support/libragen/libraries (global)
    (no project-local .libragen/libraries found in cwd)

  Environment Variables:
    (none set, using defaults)

With a project-local .libragen/libraries directory:

cd /my/project
libragen config

⚙️  Libragen Configuration

  Version:  0.1.0

  Paths:
    Home:       ~/Library/Application Support/libragen
    Libraries:  ~/Library/Application Support/libragen/libraries
    Models:     ~/Library/Application Support/libragen/models

  Active Library Paths (in priority order):
    📁 /my/project/.libragen/libraries (project-local)
    🌐 ~/Library/Application Support/libragen/libraries (global)

  Environment Variables:
    (none set, using defaults)

With environment variable overrides:

LIBRAGEN_HOME=/custom/path libragen config

⚙️  Libragen Configuration

  Version:  0.1.0

  Paths:
    Home:       /custom/path (from LIBRAGEN_HOME)
    Libraries:  /custom/path/libraries
    Models:     /custom/path/models

  Active Library Paths (in priority order):
    🌐 /custom/path/libraries (global)
    (no project-local .libragen/libraries found in cwd)

  Environment Variables:
    LIBRAGEN_HOME=/custom/path

Environment Variables

Use libragen config to see current values and which environment variables are active.

autocomplete

Set up shell completions for bash, zsh, and fish.

libragen autocomplete [SHELL]

Arguments

Examples

# Display autocomplete installation instructions
libragen autocomplete

# Set up for specific shell
libragen autocomplete bash
libragen autocomplete zsh
libragen autocomplete fish

Features

Shell completions provide:

• Command completion - Tab-complete all libragen commands
• Option completion - Tab-complete command options
• Typo suggestions - Get suggestions when you mistype a command

cli-update

Update the libragen CLI to the latest version.

libragen cli-update [options]

Options

Examples

# Update to latest version
libragen cli-update

# Check if updates are available
libragen cli-update --check

Exit Codes