Every command is a thin wrapper over one LibScope operation, so the CLI, the MCP server, the REST API and the SDK use the same parameters and defaults. Upgrading from 1.x? See Migrating to LibScope 2.0.
The usage lines and option tables on this page are generated from the CLI code (npm run docs:gen). libscope <command> --help prints the same text.
| Command | What it does |
|---|---|
add |
Add files, directories, URLs (optionally crawled) or repos |
search |
Search by meaning and keywords; interactive with no query |
ask |
Answer a question with the configured LLM |
docs |
Show, change, link, tag, rate and version single documents |
topics, tags |
Manage topics; list tags |
searches |
Save and re-run searches |
bulk |
Delete, retag or move every document that matches filters |
connect, sync, disconnect, connections |
Notion, Slack, Confluence, Obsidian, OneNote and doc sites |
pack, registry |
Knowledge packs and git pack registries |
serve |
MCP server, REST API or web dashboard |
config, workspace |
Settings and separate knowledge bases |
webhooks |
Signed POSTs on document events |
admin |
Reindex, find duplicates, backup/restore, statistics, prune |
doctor |
Check the setup; --fix creates the database and vector index |
These go before or after the command name.
Usage: libscope [options] <command>
| Option | Description |
|---|---|
-V, --version |
output the version number |
--json |
Print results as JSON |
-v, --verbose |
Debug logging, and stack traces on errors |
--log-level <level> |
Log level (default silent). One of: debug, info, warn, error, silent. |
--workspace <name> |
Use this workspace instead of the active one |
-h, --help shows the help of the program or of any command.
Every result shows document IDs (and chunk IDs for search hits), so you can pass them to the next command.
Errors. A failed command prints ✗ <message> and a next step on stderr, and exits with code 1. For example, an unknown document ID suggests libscope docs list, and a configuration problem suggests libscope doctor. Add --verbose to see the stack trace.
Progress. Long operations (directory imports, crawls, reindexing, pack installs) show a progress line on stderr when it is a terminal. The first command that needs the local embedding model prints one line while the model downloads (about 90 MB, first run only).
Commands that select documents (search, ask, docs list, searches save, bulk) share these flags:
| Flag | Description |
|---|---|
--topic <topic> |
Topic ID or name |
--library <name> |
Library name |
--lib-version <version> |
Library version (not on bulk) |
--source-type <type> |
library, topic, manual or model-generated |
--tags <a,b> |
Only documents with all these tags |
-n, --limit <n> |
Maximum results (ask: chunks used as context; not on bulk) |
Each source can be a file, a directory, a URL or a GitHub/GitLab repository URL. LibScope detects which one it is. A local file's absolute path is stored as its URL, so adding a changed file again replaces the old version.
libscope add ./guide.md --topic deployment --tags ops,runbook
libscope add ./docs --include "**/*.md" --exclude "drafts/**" --library my-lib --lib-version 2.1
libscope add ./docs --watch # keep re-indexing changed files (Ctrl+C to stop)
libscope add https://react.dev/learn --library react
libscope add https://docs.example.com --spider --max-pages 50 --path-prefix /guide
libscope add https://github.com/org/repo --branch main --path docs
libscope add ./docs --dry-run # list what would be addedUsage: libscope add <sources...>
Add files, directories, URLs or GitHub/GitLab repository URLs to the knowledge base.
| Option | Description |
|---|---|
--topic <topic> |
Topic (ID or name) |
--library <name> |
Library name |
--lib-version <version> |
Library version |
--source-type <type> |
Source type (library, topic, manual, model-generated) |
--tags <tags> |
Tags to add (comma-separated) |
--title <title> |
Title (one file or URL; default: detected) |
--format <ext> |
Read files as this format, e.g. .pdf |
--dedup <mode> |
Duplicate handling: skip, warn or force |
--expires <time> |
ISO 8601 time after which admin prune deletes the documents |
--include <globs> |
Directory: only files matching these globs (comma-separated) |
--exclude <globs> |
Directory: skip files matching these globs (comma-separated) |
--watch |
Directory: keep running and re-index files when they change |
--spider |
URL: also crawl linked pages |
--max-pages <n> |
Crawl: page limit (default 25, max 200) |
--max-depth <n> |
Crawl: link depth (default 2, max 5) |
--no-same-domain |
Crawl: also follow links to other domains |
--path-prefix <path> |
Crawl: only follow links under this path |
--exclude-urls <globs> |
Crawl: skip URLs matching these globs (comma-separated) |
--branch <name> |
Repository: branch (default: from the URL, else main) |
--path <dirs> |
Repository: only these subdirectories (comma-separated) |
--extensions <exts> |
Repository: file extensions (default .md,.mdx,.txt,.rst) |
--token <token> |
Repository: access token for a private repository |
--dry-run |
List what would be added without adding it |
With --json, add prints one result per source: { kind, documents: [{ documentId, title, chunkCount, source }], errors, skipped, planned?, crawl? }.
libscope search "authentication best practices" --library my-lib -n 10
libscope search "deploy process" --context 1 # show neighbouring chunks
libscope search --related <documentId|chunkId> # content similar to a document or chunk
libscope search # interactive search (on a terminal)Usage: libscope search [query]
Search by meaning and keywords. With no query on a terminal, start interactive search.
| Option | Description |
|---|---|
--related <id> |
Find content similar to this document or chunk ID instead |
--topic <topic> |
Only this topic (ID or name) |
--library <name> |
Only this library |
--lib-version <version> |
Only this library version |
--source-type <type> |
Only this source type (library, topic, manual, model-generated) |
--tags <tags> |
Only documents with all these tags (comma-separated) |
-n, --limit <n> |
Maximum results |
--offset <n> |
Results to skip (paging) |
--min-rating <n> |
Only documents rated at least this (1-5) |
--max-per-doc <n> |
At most this many chunks per document |
--context <n> |
Neighbouring chunks to show around each result (0-2) |
With no query and no --related, on a terminal, search starts interactive mode: type a query, see results, repeat. Type quit, exit or press Ctrl+D to leave. The filters given on the command line apply to every query.
libscope ask "How do I configure OAuth2?" --library my-lib -n 8
libscope ask "What changed in v2?" --model gpt-4o-miniUsage: libscope ask <question>
Answer a question from the knowledge base with the configured LLM.
| Option | Description |
|---|---|
--topic <topic> |
Only this topic (ID or name) |
--library <name> |
Only this library |
--lib-version <version> |
Only this library version |
--source-type <type> |
Only this source type (library, topic, manual, model-generated) |
--tags <tags> |
Only documents with all these tags (comma-separated) |
-n, --limit <n> |
Chunks to use as context (default 5) |
--min-rating <n> |
Only documents rated at least this (1-5) |
--model <model> |
LLM model for this question (default: llm.model) |
ask needs an LLM. With llm.provider set to auto (the default), LibScope uses OpenAI when an OpenAI API key is set, else Anthropic when an Anthropic key is set, else Ollama when llm.url is set or the embedding provider is Ollama. Without an LLM, ask fails with a hint; libscope doctor shows what is resolved. With llm.provider passthrough, ask prints the retrieved context instead of an answer.
List documents, newest first.
| Option | Description |
|---|---|
--topic <topic> |
Only this topic (ID or name) |
--library <name> |
Only this library |
--lib-version <version> |
Only this library version |
--source-type <type> |
Only this source type (library, topic, manual, model-generated) |
--tags <tags> |
Only documents with all these tags (comma-separated) |
-n, --limit <n> |
Maximum results |
--offset <n> |
Documents to skip (paging) |
Show a document with its tags, links and ratings.
| Option | Description |
|---|---|
--offset <n> |
Start the content at this character |
--max-length <n> |
Show at most this many characters of content |
List saved versions of a document.
Change a document's title, content, metadata or tags.
| Option | Description |
|---|---|
--title <title> |
New title |
--content <text> |
New content (re-chunked and re-embedded) |
--content-file <path> |
Read the new content from a file |
--library <name> |
New library name |
--lib-version <version> |
New library version |
--url <url> |
New URL |
--topic <topic> |
New topic (ID or name) |
--tags <tags> |
Replace the tags with these (comma-separated) |
Delete a document with its chunks, links and ratings.
| Option | Description |
|---|---|
-y, --yes |
Do not ask for confirmation |
Restore a saved version (the current state is saved first).
Rate a document from 1 (poor) to 5 (excellent).
| Option | Description |
|---|---|
--feedback <text> |
What is good or wrong |
--correction <text> |
Suggested replacement text |
--chunk <chunkId> |
Rate one chunk of the document |
Link one document to another.
| Option | Description |
|---|---|
--type <type> |
Link type: see_also, prerequisite, supersedes, related, references. Required. |
--label <text> |
Short description of the relationship |
Delete a link (link IDs are shown by docs links).
List the links of a document, or every link.
| Option | Description |
|---|---|
--type <type> |
Only this link type: see_also, prerequisite, supersedes, related, references |
List the documents to read first (following prerequisite links).
Add tags to a document (space- or comma-separated).
Remove tags from a document.
Suggest tags from a document's content.
| Option | Description |
|---|---|
-n, --limit <n> |
Maximum suggestions |
docs update --tags replaces all tags. Changing the content re-chunks and re-embeds the document.
libscope docs update <documentId> --title "New Title" --tags guide,v2
libscope docs update <documentId> --content-file ./updated.mdList topics with their document counts.
| Option | Description |
|---|---|
--parent <topic> |
Only direct subtopics of this topic (ID or name) |
Create a topic.
| Option | Description |
|---|---|
--description <text> |
What the topic covers |
--parent <topic> |
Parent topic (ID or name) |
Delete a topic (its documents are kept without a topic).
| Option | Description |
|---|---|
--delete-documents |
Also delete the topic's documents |
-y, --yes |
Do not ask for confirmation |
List all tags with their document counts.
<topic> is a topic ID or name everywhere.
Save a query and its filters.
| Option | Description |
|---|---|
--topic <topic> |
Only this topic (ID or name) |
--library <name> |
Only this library |
--lib-version <version> |
Only this library version |
--source-type <type> |
Only this source type (library, topic, manual, model-generated) |
--tags <tags> |
Only documents with all these tags (comma-separated) |
-n, --limit <n> |
Maximum results |
--min-rating <n> |
Only documents rated at least this (1-5) |
List saved searches.
| Option | Description |
|---|---|
-n, --limit <n> |
Maximum results |
--offset <n> |
Results to skip (paging) |
Run a saved search (name or ID).
Delete a saved search (name or ID).
bulk delete, bulk retag and bulk move change every document that matches the filters. At least one filter is required, and one call changes at most 1000 documents. Each command first shows how many documents match and asks for confirmation.
libscope bulk delete --library react --dry-run
libscope bulk retag --topic guides --add important,v2 --remove draft -y
libscope bulk move --library react --since 2024-01-01 --to frontend -yDelete matching documents.
| Option | Description |
|---|---|
--topic <topic> |
Only this topic (ID or name) |
--library <name> |
Only this library |
--source-type <type> |
Only this source type (library, topic, manual, model-generated) |
--tags <tags> |
Only documents with all these tags (comma-separated) |
--since <date> |
Only documents created on or after (ISO 8601) |
--before <date> |
Only documents created on or before (ISO 8601) |
--dry-run |
List the matching documents without changing them |
-y, --yes |
Do not ask for confirmation |
Add and/or remove tags on matching documents.
| Option | Description |
|---|---|
--topic <topic> |
Only this topic (ID or name) |
--library <name> |
Only this library |
--source-type <type> |
Only this source type (library, topic, manual, model-generated) |
--tags <tags> |
Only documents with all these tags (comma-separated) |
--since <date> |
Only documents created on or after (ISO 8601) |
--before <date> |
Only documents created on or before (ISO 8601) |
--dry-run |
List the matching documents without changing them |
-y, --yes |
Do not ask for confirmation |
--add <tags> |
Tags to add (comma-separated) |
--remove <tags> |
Tags to remove (comma-separated) |
Move matching documents to another topic.
| Option | Description |
|---|---|
--topic <topic> |
Only this topic (ID or name) |
--library <name> |
Only this library |
--source-type <type> |
Only this source type (library, topic, manual, model-generated) |
--tags <tags> |
Only documents with all these tags (comma-separated) |
--since <date> |
Only documents created on or after (ISO 8601) |
--before <date> |
Only documents created on or before (ISO 8601) |
--dry-run |
List the matching documents without changing them |
-y, --yes |
Do not ask for confirmation |
--to <topic> |
Destination topic (ID or name). Required. |
A connection is a saved connector configuration in ~/.libscope/connectors/<name>.json (mode 0600, credentials included).
Connector types: notion, slack, confluence, obsidian, onenote, docs (a documentation site). [source] is the vault path for obsidian and the URL for confluence and docs.
libscope connect notion --token secret_xxx
libscope connect slack --token xoxb-xxx --channels general,eng --exclude random
libscope connect confluence https://acme.atlassian.net --email me@acme.com --token xxx --spaces ENG
libscope connect obsidian ~/notes --topic-mapping frontmatter
libscope connect onenote --client-id <azure-app-id> # device-code sign-in
libscope connect docs https://docs.example.com --library example --max-pages 200
libscope connect notion --name work --schedule "0 */6 * * *" # second Notion connection, synced every 6 hoursRunning connect again for a saved connection changes only the settings you give and keeps the rest. For example, libscope connect notion --schedule off --no-sync removes the schedule.
Save a connection and sync it. Types: notion, slack, confluence, obsidian, onenote, docs. [source] is the vault path (obsidian) or the URL (confluence, docs). Running it again for a saved connection changes only the given settings.
| Option | Description |
|---|---|
--name <name> |
Connection name (default: the type) |
--schedule <cron> |
Sync on this cron schedule while libscope serve api runs ("off" removes it) |
--no-sync |
Save the connection without syncing now |
--token <token> |
notion, slack, confluence: API token; onenote: access token |
--exclude <list> |
Comma-separated: slack channels, notion page IDs, confluence spaces, obsidian globs |
--channels <list> |
slack: channel names or IDs (default all) |
--thread-mode <mode> |
slack: aggregate (one document per thread) or separate |
--email <email> |
confluence: user email (Cloud) |
--server |
confluence: Server/Data Center instead of Cloud |
--spaces <keys> |
confluence: space keys (default all) |
--topic-mapping <mode> |
obsidian: topics from folder (default) or frontmatter |
--notebook <name> |
onenote: one notebook (default all) |
--client-id <id> |
onenote: Azure app client ID for device sign-in |
--tenant-id <id> |
onenote: Azure tenant ID (default common) |
--site-type <type> |
docs: auto, sphinx, vitepress, doxygen or generic |
--library <name> |
docs: library name for the pages |
--lib-version <version> |
docs: library version for the pages |
--max-pages <n> |
docs: page limit (default 500) |
--max-depth <n> |
docs: link depth (default 10) |
--path-prefix <path> |
docs: only pages under this path |
Sync a saved connection with its saved settings, or all with --all.
| Option | Description |
|---|---|
--all |
Sync every saved connection |
Delete a connection's documents and its saved settings (including credentials).
| Option | Description |
|---|---|
--type <type> |
Connector type, when no saved connection has this name |
--keep-documents |
Only delete the saved settings |
-y, --yes |
Do not ask for confirmation |
List saved connections with their schedule and last sync.
libscope pack install react-docs # latest version
libscope pack install react-docs@1.2.0
libscope pack install react-docs --registry official # when several registries have react-docs
libscope pack install ./react-docs.json.gz
libscope pack create --name team-docs --topic engineering
libscope pack create --name react-docs --from ./react/docs --exclude "*.min.js"Pack names are looked up in the local copies of the registries; run libscope registry sync to update them. When more than one registry has the pack, the command fails and names the registries: choose one with --registry.
Install a pack from the configured registries (name or name@version) or a local .json/.json.gz file.
| Option | Description |
|---|---|
--registry <name> |
Look only in this registry |
--batch-size <n> |
Documents embedded per batch (default 10) |
--resume-from <n> |
Skip the first N documents (resume a partial install) |
--concurrency <n> |
Batches embedded in parallel (default 4) |
Remove an installed pack and its documents.
| Option | Description |
|---|---|
-y, --yes |
Do not ask for confirmation |
List installed packs, or the packs in the configured registries (--available).
| Option | Description |
|---|---|
--available |
List the packs in the configured registries |
--registry <name> |
With --available: only this registry |
Create a pack from indexed documents, or from files, folders and URLs (--from).
| Option | Description |
|---|---|
--name <name> |
Pack name. Required. |
--from <sources...> |
Files, folders or URLs to build the pack from |
--topic <topic> |
Only this topic's documents (without --from) |
--pack-version <version> |
Pack version (default 1.0.0) |
--description <text> |
Pack description |
--author <name> |
Pack author |
--license <license> |
Pack license |
--output <path> |
Output file (default <name>.json, or <name>.json.gz with --from) |
--extensions <exts> |
With --from: file extensions to include (comma-separated) |
--exclude <globs...> |
With --from: globs to skip |
--no-recursive |
With --from: do not walk subdirectories |
A registry is a git repository of packs. --registry <name> always means the name of a configured registry.
libscope registry add https://github.com/org/registry.git
libscope registry add git@github.com:team/packs.git --name team
libscope registry add file:///srv/libscope-packs.git --no-sync
libscope registry publish ./my-pack.json --registry my-registry --pack-version 1.0.0
libscope registry publish ./my-pack.json.gz --registry my-registry # next patch version
libscope registry publish ./my-pack.json --registry community --submit # push to a feature branch
libscope registry unpublish my-pack@1.0.0 --registry my-registryRegistry URLs can use https://, ssh://, git@host:path or file:///. libscope registry create ./my-registry creates a git repository with the registry folder structure. See the Registry Reference.
Add a git repository as a pack registry and clone it.
| Option | Description |
|---|---|
-n, --name <name> |
Registry name (default: from the URL) |
--no-sync |
Do not clone the registry now |
Remove a registry and delete its local clone.
| Option | Description |
|---|---|
-y, --yes |
Do not ask for confirmation |
List the configured registries.
Fetch the latest packs of one or all registries.
Search the packs in the configured registries.
| Option | Description |
|---|---|
--registry <name> |
Search only this registry |
Create an empty registry git repository.
Publish a pack file to a registry (commit and push).
| Option | Description |
|---|---|
--registry <name> |
Target registry. Required. |
--pack-version <semver> |
Version to publish (default: next patch version) |
-m, --message <msg> |
Git commit message |
--submit |
Push to a feature branch for a pull request instead of the main branch |
Remove one version of a pack from a registry (<name>@<version>).
| Option | Description |
|---|---|
--registry <name> |
Target registry. Required. |
-m, --message <msg> |
Git commit message |
-y, --yes |
Do not ask for confirmation |
libscope serve # MCP server on stdio
libscope serve api # REST API on http://localhost:3378
libscope serve dashboard --port 8080 # web dashboard (default port 3377)Usage: libscope serve [mode]
Start the MCP server on stdio (mcp, default), the REST API (api, port 3378) or the web dashboard (dashboard, port 3377).
| Option | Description |
|---|---|
--port <n> |
Port (api and dashboard) |
--host <host> |
Host to listen on (default localhost) |
Connection schedules (connect --schedule) run while serve api runs.
Show the effective configuration (API keys are masked).
Print the effective value of a key (API keys are masked).
Set a key in the user config file. Keys: embedding.provider, embedding.model, embedding.url, embedding.dimensions, llm.provider, llm.model, llm.url, openai.apiKey, anthropic.apiKey, database.path, indexing.maxDocumentSize, indexing.allowPrivateUrls, indexing.allowSelfSignedCerts, logging.level, mcp.toolsets. API keys are written to ~/.libscope/secrets.json (mode 0600), never to config.json.
Remove a key from the user config file (or secrets file for API keys).
Print the path of the user config file.
openai.apiKey and anthropic.apiKey are written to ~/.libscope/secrets.json (mode 0600), never to config.json; the LIBSCOPE_OPENAI_API_KEY / OPENAI_API_KEY and LIBSCOPE_ANTHROPIC_API_KEY / ANTHROPIC_API_KEY environment variables take precedence. See the configuration reference for every key.
A workspace is a separate knowledge base with its own database (~/.libscope/workspaces/<name>/libscope.db). The global --workspace <name> option and the LIBSCOPE_WORKSPACE environment variable select one for a single command.
Create a workspace.
List workspaces.
Make a workspace the active one.
Delete a workspace and its database.
| Option | Description |
|---|---|
-y, --yes |
Do not ask for confirmation |
List webhooks (secrets are never shown).
Register a webhook.
| Option | Description |
|---|---|
--events <events> |
Comma-separated: document.created, document.updated, document.deleted, document.rated, search.executed. Required. |
--secret <secret> |
HMAC-SHA256 signing secret (needs LIBSCOPE_SECRET_KEY) |
Delete a webhook.
Send a test event and show the HTTP status.
Events: document.created, document.updated, document.deleted, document.rated, search.executed. A secret signs each POST with HMAC-SHA256; storing it needs LIBSCOPE_SECRET_KEY.
Re-embed chunks with the configured embedding model.
| Option | Description |
|---|---|
--rebuild |
Recreate the vector index for the configured model, then re-embed all |
--doc <documentIds...> |
Only these documents |
--since <date> |
Only documents created on or after (ISO 8601) |
--before <date> |
Only documents created on or before (ISO 8601) |
--batch-size <n> |
Chunks per embedding call (default 50) |
Find duplicate and near-duplicate documents.
| Option | Description |
|---|---|
--threshold <n> |
Similarity threshold 0-1 (default 0.95) |
--strategy <strategy> |
exact, semantic or both (default) |
Delete documents whose expiry time has passed.
Write the whole knowledge base to a JSON file.
Import a file written by admin backup.
| Option | Description |
|---|---|
-y, --yes |
Do not ask for confirmation |
Counts, index, most returned and stale documents, and search analytics.
| Option | Description |
|---|---|
--days <n> |
Look-back days for stale documents and search analytics |
admin reindex --rebuild recreates the vector index for a new embedding model or vector size, then re-embeds every chunk. The other admin reindex filters do not apply with --rebuild.
libscope doctor # report only
libscope doctor --fix # also create the database and vector indexUsage: libscope doctor
Check the setup: config, workspace, database, embedding model, index and LLM.
| Option | Description |
|---|---|
--fix |
Create what is missing (database and vector index) |
doctor shows the config and secrets files, the active workspace and database path, the configured embedding model and the model the vector index was built with, and which LLM ask will use. It then lists checks with a fix for each warning or error, for example libscope admin reindex --rebuild when the index was built with a different embedding model. It exits with code 1 when a check fails.