Build and manage libragen libraries from the command line. Create private, local RAG libraries that ground your AI in real documentation instead of stale training data.

Full documentation →

Installation

npm install -g @libragen/cli

Or use with npx:

npx @libragen/cli <command>

Using the CLI

Here's a typical workflow to get started:

1. Build a library from documentation

# From a GitHub repository
libragen build https://github.com/expressjs/express/tree/master/docs -o express.libragen

# From local files
libragen build ./internal-team-docs -o team-docs.libragen

2. Install and search your library

# Install to make it available globally
libragen install express.libragen

# Search with natural language
libragen query "how to set up middleware" -l express

These libraries are now accessible using the Libragen MCP server.

Set it up and chat with your docs using your AI agent of choice.

3. Manage your libraries

# See what's installed
libragen list

# Remove a library
libragen uninstall express

# Check for updates
libragen update --dry-run

See more examples and tips →

Commands

build (alias: b)

Build a library from source files or a git repository.

libragen build <source> [options]
libragen b <source> [options]

Arguments:

• source — Path to directory/files or git URL

Options:

| Option | Description | Default | |--------|-------------|---------| | -o, --output <path> | Output file or directory path | <name>.libragen | | -n, --name <name> | Library name | Directory/repo name | | -v, --version <version> | Library version | 1.0.0 | | -d, --description <text> | Library description | — | | --agent-description <text> | Description for AI agents | — | | --content-version <version> | Content version (e.g., v2.0.0) | — | | -i, --include <patterns> | Glob patterns to include | — | | -e, --exclude <patterns> | Glob patterns to exclude (added to defaults) | — | | --no-default-excludes | Disable default exclusions (node_modules, .git, etc.) | — | | --chunk-size <size> | Target chunk size in characters | 1000 | | --chunk-overlap <size> | Overlap between chunks | 100 | | --git-ref <ref> | Git branch, tag, or commit (remote git sources only) | — | | --git-repo-auth-token <token> | Auth token for private repos (remote git sources only) | — | | --license <licenses...> | SPDX license identifier(s) for the source content | Auto-detected for git |

Examples:

# Build from local directory (output to file)
libragen build ./src -o my-lib.libragen

# Build to directory (creates ./dist/<name>.libragen)
libragen build ./src -o ./dist

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

# Build from specific branch/tag
libragen build https://github.com/user/repo/tree/v1.0.0

# Build from subdirectory (path extracted from URL)
libragen build https://github.com/user/repo/tree/main/docs

# Build with explicit include filter
libragen build https://github.com/user/repo --include 'docs/**'

# Build from private repository
GITHUB_TOKEN=xxx libragen build https://github.com/org/private-repo

# Build with custom options
libragen build ./src \
   -o my-lib.libragen \
   -n "My Library" \
   -d "A helpful library" \
   --content-version "v2.0.0" \
   --include "**/*.ts" "**/*.md"

# Build with explicit license
libragen build ./src --license MIT

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

License Detection

When building from git repositories, licenses are automatically detected from common license files (LICENSE, LICENSE.md, LICENSE.txt, COPYING). The detected license is stored in the library metadata.

Behavior:

• Git sources: Auto-detected from LICENSE files if not explicitly provided
• Local sources: No auto-detection; use --license if needed
• Explicit --license: Always takes precedence over auto-detection

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

Git Repository Authentication

When building from private repositories, authentication tokens are resolved in this order:

1. Explicit --git-repo-auth-token parameter
2. Environment variables based on provider:
   • GitHub: GITHUB_TOKEN
   • GitLab: GITLAB_TOKEN or GL_TOKEN
   • Bitbucket: BITBUCKET_TOKEN
   • Custom GitLab: Set GITLAB_HOST to your instance domain

Supported URL formats:

# Basic repository URLs
https://github.com/org/repo
https://github.com/org/repo.git
https://gitlab.com/org/repo
https://bitbucket.org/org/repo

# Repository at specific ref (branch/tag/commit)
https://github.com/org/repo/tree/v1.0.0
https://github.com/org/repo/tree/main
https://gitlab.com/org/repo/-/tree/v1.0.0

# Specific directory at ref
https://github.com/org/repo/tree/main/docs
https://gitlab.com/org/repo/-/tree/main/src

# Specific file at ref
https://github.com/org/repo/blob/main/README.md
https://gitlab.com/org/repo/-/blob/v1.0.0/README.md

# Custom GitLab instances
https://gitlab.example.com/org/repo

query (alias: q)

Search a library for relevant content.

libragen query <query> [options]
libragen q <query> [options]

Arguments:

• query — Natural language search query

Options:

| Option | Description | Default | |--------|-------------|---------| | -l, --library <name-or-path> | Library name or path to .libragen file (required) | — | | -p, --path <paths...> | Project directory (will search /.libragen/libraries) | auto-detect + global | | -k, --top-k <number> | Number of results | 5 | | -r, --rerank | Enable cross-encoder reranking | false | | -c, --context <lines> | Lines of context around matches | 0 | | --json | Output as JSON | false |

Examples:

# Search by library name (uses resolution algorithm)
libragen query "authentication middleware" -l my-lib

# Search by explicit file path
libragen query "authentication middleware" -l ./my-lib.libragen

# Search with custom project directory
libragen query "error handling" -l my-lib -p ./my-project -k 10

# JSON output for scripting
libragen query "database connection" -l my-lib --json

inspect

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

libragen inspect <source> [options]

Arguments:

• source — Library file, packed collection, or URL

Options:

| Option | Description | |--------|-------------| | --json | Output as JSON |

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

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

list (alias: l)

List installed libraries.

libragen list [options]
libragen l [options]

Options:

| Option | Description | |--------|-------------| | -v, --verbose | Show detailed information (path, chunks, size, keywords, etc.) | | --show-path | Show the file path for each library | | -p, --path <paths...> | Project directory (will search /.libragen/libraries) | | --json | Output as JSON (includes path and location for each library) | | --libraries | Show only libraries | | --collections | Show only collections |

Output:

Each library shows:

• Name and version
• Location badge: [project] or [global]
• With --show-path: full file path
• With -v, --verbose: path, chunk count, file size, keywords, languages

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 or auto-detection.

install

Install a library from a file or collection.

libragen install <source> [options]

Arguments:

• source — Library file path or collection library name

Options:

| Option | Description | |--------|-------------| | -p, --path <paths...> | Project directory (will install to /.libragen/libraries) | | -f, --force | Overwrite existing library | | -c, --collection <url> | Collection URL to use | | --content-version <version> | Install specific content version | | -a, --all | Install all libraries including optional (for collections) |

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 collection (when configured)
libragen install some-library

uninstall (alias: u)

Remove an installed library.

libragen uninstall <name> [options]
libragen u <name> [options]

Options:

| Option | Description | |--------|-------------| | -p, --path <paths...> | Project directory (will search /.libragen/libraries) | | -c, --collection | Uninstall a collection (and unreferenced libraries) |

collection

Manage library collections.

libragen collection <subcommand>

Subcommands:

• list — List configured collections
• add <name> <url> — Add a collection
• remove <name> — Remove a collection
• search <query> — Search collections for libraries
• clear-cache — Clear the collection cache
• create <output> — Create a collection file (creates a template if no libraries specified)
• pack <collection> — Bundle a collection and libraries into a single .libragen-collection file
• unpack <file> — Extract a .libragen-collection file

Examples:

# List collections
libragen collection list

# Add a collection
libragen collection add my-collection https://example.com/collection.json

# Search for libraries
libragen collection search "react hooks"

# Create a collection template (edit manually)
libragen collection create my-docs.json

# Create a collection with libraries
libragen collection create my-docs.json \
  --library ./api-docs.libragen \
  --library ./guides.libragen

# Pack for sharing (creates .libragen-collection file)
libragen collection pack ./my-docs.json

# Unpack and install
libragen collection unpack my-docs.libragen-collection --install

update (alias: up)

Update libraries from their collections. Only works for libraries that were installed from a collection — libraries installed directly from .libragen files are not tracked and cannot be updated this way.

libragen update [name] [options]
libragen up [name] [options]

Arguments:

• name — Optional library name (updates all collection-tracked libraries if omitted)

Options:

| Option | Description | |--------|-------------| | -p, --path <paths...> | Project directory (will search /.libragen/libraries) | | -n, --dry-run | Show what would be updated without making changes | | -f, --force | Force update even if versions match |

config

Display current configuration and paths, including any project-local .libragen/libraries directories that would be used when querying.

libragen config [options]

Options:

| Option | Description | |--------|-------------| | --json | Output as JSON |

Output includes:

• Paths: Home, libraries, and models directories
• Active Library Paths: All paths that will be searched (project-local + global)
• Environment Variables: Any overrides via LIBRAGEN_HOME or LIBRAGEN_MODEL_CACHE

completions

Manage shell completions for bash, zsh, and fish.

libragen completions <action>

Actions:

| Action | Description | |--------|-------------| | install | Install completions (interactive) | | uninstall | Remove completions | | bash | Output bash completion script | | zsh | Output zsh completion script | | fish | Output fish completion script |

Examples:

# Interactive install
libragen completions install

# Add to shell profile manually
# Bash (~/.bashrc):
eval "$(libragen completions bash)"

# Zsh (~/.zshrc):
eval "$(libragen completions zsh)"

# Fish:
libragen completions fish > ~/.config/fish/completions/libragen.fish

Library Locations

Libraries are discovered and installed to different locations:

Default Installation Location

By default, all installations go to the global directory ($LIBRAGEN_HOME/libraries):

| Platform | Global Location | |----------|-----------------| | macOS | ~/Library/Application Support/libragen/libraries | | Linux | ~/.local/share/libragen/libraries | | Windows | %APPDATA%\libragen\libraries |

You can override this with the LIBRAGEN_HOME environment variable.

Library Discovery

When searching for libraries (e.g., libragen list, libragen query), libragen looks in:

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

Project-Specific Libraries (-p flag)

The -p flag automatically appends .libragen/libraries to the specified path:

# Install to ./my-project/.libragen/libraries
libragen install my-lib.libragen -p ./my-project

# List libraries in ./my-project/.libragen/libraries
libragen list -p ./my-project

# Use multiple project directories
libragen list -p ./project-a -p ./project-b

When -p is specified, only the transformed path(s) are used — no global directory, no auto-detection. This is useful for:

• Working with a specific project's libraries only
• Testing with isolated library sets
• CI/CD environments

Exit Codes

| Code | Description | |------|-------------| | 0 | Success | | 1 | Error (see stderr for details) |

Related

• @libragen/core — Core library
• @libragen/mcp — MCP server for AI assistants