---
title: CLI Reference
description: Complete command-line interface documentation
section: Reference
order: 10
---
The libragen CLI provides commands for building, querying, and managing RAG libraries.
## Global Options
These options work with all commands:
| Option | Description |
|--------|-------------|
| `--help`, `-h` | Show help for a command |
| `--cli-version`, `-V` | Show CLI version number |
## Commands
### `build`
Create a new library from source files.
```bash
libragen build <source> [options]
```
#### Arguments
| Argument | Description |
|----------|-------------|
| `source` | Directory or file to process |
#### Options
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--name`, `-n` | string | Required | Library name (creates `<name>-<version>.libragen`) |
| `--output`, `-o` | string | Current dir | Output directory |
| `--description`, `-d` | string | — | Library description |
| `--content-version` | string | — | Version tag for the content |
| `--include`, `-i` | string[] | — | Glob patterns to include |
| `--exclude`, `-e` | string[] | — | Glob patterns to exclude (added to defaults) |
| `--no-default-excludes` | boolean | `false` | Disable default exclusions |
| `--chunk-size` | number | `1000` | Target chunk size in characters |
| `--chunk-overlap` | number | `100` | Overlap between chunks |
| `--no-ast-chunking` | boolean | `false` | Disable AST-aware chunking for code files |
| `--context-mode` | string | `full` | Context mode for AST chunking: `none`, `minimal`, or `full` |
| `--license` | string[] | Auto-detected | SPDX license identifier(s) for the source |
| `--git-ref` | string | — | Git branch, tag, or commit (git sources only) |
| `--git-repo-auth-token` | string | — | Auth token for private repos |
#### Examples
```bash
# 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.
```bash
libragen query [options] <query>
```
#### Arguments
| Argument | Description |
|----------|-------------|
| `query` | Natural language search query |
#### Options
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--library`, `-l` | string | Required | Library name or path to .libragen file |
| `--path`, `-p` | string[] | auto-detect + global | Project directory (will search <path>/.libragen/libraries) |
| `--top-k`, `-k` | number | `10` | Number of results to return |
| `--content-version` | string | — | Filter by content version |
| `--format`, `-f` | string | `text` | Output format (`text`, `json`) |
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
```bash
# 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`):
```json
{
"results": [
{
"rank": 1,
"score": 0.89,
"source": "authentication.md",
"content": "To authenticate, pass your API key..."
}
]
}
```
---
### `list`
List installed libraries.
**Aliases:** `l`, `ls`
```bash
libragen list [options]
```
#### Options
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `-p, --path` | string[] | — | Project directory (will search <path>/.libragen/libraries) |
| `-v, --verbose` | boolean | `false` | Show detailed information (path, chunks, size, keywords) |
| `--show-path` | boolean | `false` | Show the file path for each library |
| `--json` | boolean | `false` | Output as JSON (includes path and location) |
| `--libraries` | boolean | `false` | Show only libraries |
| `--collections` | boolean | `false` | Show only collections |
#### 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
```bash
# 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.
```bash
libragen inspect <source> [options]
```
#### Arguments
| Argument | Description |
|----------|-------------|
| `source` | Library file, packed collection, or URL |
#### Options
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--json` | boolean | `false` | Output as JSON |
#### Examples
```bash
# 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.
```bash
libragen install <source> [options]
```
#### Options
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `-p, --path` | string[] | — | Project directory (will install to <path>/.libragen/libraries) |
| `-f, --force` | boolean | `false` | Overwrite existing library |
| `-c, --collection` | string | — | Collection URL to use |
| `--content-version` | string | — | Install specific content version |
| `-a, --all` | boolean | `false` | Install all libraries including optional (for collections) |
#### Examples
```bash
# 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.
```bash
libragen uninstall <name> [options]
```
#### Options
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `-p, --path` | string[] | — | Project directory (will search <path>/.libragen/libraries) |
| `-c, --collection` | boolean | `false` | Uninstall a collection (and unreferenced libraries) |
#### Examples
```bash
# 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.
```bash
libragen update [name] [options]
```
#### Arguments
| Argument | Description |
|----------|-------------|
| `name` | Optional library name to update (updates all if omitted) |
#### Options
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `-p, --path` | string[] | — | Project directory (will search <path>/.libragen/libraries) |
| `-n, --dry-run` | boolean | `false` | Show what would be updated without making changes |
| `-f, --force` | boolean | `false` | Force update even if versions match |
#### Examples
```bash
# 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.
```bash
libragen config [options]
```
#### Options
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--json` | boolean | `false` | Output as JSON |
#### Example
```bash
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:
```bash
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:
```bash
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
| Variable | Description |
|----------|-------------|
| `LIBRAGEN_HOME` | Override base directory for all libragen data |
| `LIBRAGEN_MODEL_CACHE` | Override model cache directory |
Use `libragen config` to see current values and which environment variables are active.
---
### `autocomplete`
Set up shell completions for bash, zsh, and fish.
```bash
libragen autocomplete [SHELL]
```
#### Arguments
| Argument | Description |
|----------|-------------|
| `SHELL` | Shell type: `bash`, `zsh`, or `fish` (optional) |
#### Examples
```bash
# 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.
```bash
libragen cli-update [options]
```
#### Options
| Option | Description |
|--------|-------------|
| `--check`, `-c` | Check for updates without installing |
#### Examples
```bash
# Update to latest version
libragen cli-update
# Check if updates are available
libragen cli-update --check
```
---
## Exit Codes
| Code | Description |
|------|-------------|
| `0` | Success |
| `1` | General error |
| `2` | Invalid arguments |
