Knowledge CLI

CLI commands for knowledge base management

Knowledge CLI Commands

The praisonai knowledge command group provides CLI access to knowledge base management.

Commands Overview

Command	Description
index	Add/index documents into a knowledge base
search	Search/retrieve from knowledge base
add	Alias for index
list	List available knowledge bases

Index Command

Add documents to a knowledge base.

praisonai knowledge index [OPTIONS] SOURCES...

Arguments

Argument	Description
SOURCES	Source files, directories, or URLs to index (required)

Options

Option	Short	Description	Default
--collection	-c	Collection/knowledge base name	default
--user-id	-u	User ID for scoping (required for mem0)	None
--agent-id	-a	Agent ID for scoping	None
--run-id	-r	Run ID for scoping	None
--backend	-b	Knowledge backend: mem0, chroma, internal	mem0
--config	-f	Config file path	None
--verbose	-v	Verbose output	False
--profile		Enable performance profiling	False
--profile-out		Save profile to JSON file	None

Examples

# Index a directory with user scope
praisonai knowledge index ./docs --user-id myuser

# Index with specific collection and agent scope
praisonai knowledge index paper.pdf --collection research --agent-id research_agent

# Index using chroma backend
praisonai knowledge index ./data --backend chroma

# Index with profiling
praisonai knowledge index ./docs --user-id myuser --profile --profile-out ./profile.json

# When embedding fails (e.g. bad OPENAI_API_KEY or wrong model), the index
# command now exits with a non-zero status so shell pipelines can detect it:
$ praisonai knowledge index ./docs --user-id myuser
✗ Failed to index ./docs: no chunks stored (no supported files found, or content could not be extracted)

Indexing failed for 1 of 1 source(s). Collection: default
$ echo $?
1

Exit Codes

Code	Meaning
0	Every source produced at least one stored chunk.
1	One or more sources produced no chunks — check the per-source ✗ lines above the summary. Common causes: unsupported file types in the directory, unreadable content, or an embedding failure (see Troubleshooting).

Chain commands with praisonai knowledge index … && … to run the next step only when every source indexes successfully.

Search Command

Search/retrieve from a knowledge base without LLM generation.

praisonai knowledge search [OPTIONS] QUERY

Arguments

Argument	Description
QUERY	Search query (required)

Options

Option	Short	Description	Default
--collection	-c	Collection to search	default
--user-id	-u	User ID for scoping (required for mem0)	None
--agent-id	-a	Agent ID for scoping	None
--run-id	-r	Run ID for scoping	None
--backend	-b	Knowledge backend: mem0, chroma, internal	mem0
--top-k	-k	Number of results to retrieve	5
--hybrid		Use hybrid retrieval (dense + BM25)	False
--config	-f	Config file path	None
--verbose	-v	Verbose output	False
--profile		Enable performance profiling	False

Examples

# Basic search with user scope
praisonai knowledge search "capital of France" --user-id myuser

# Search specific collection with more results
praisonai knowledge search "main findings" --collection research --top-k 10

# Hybrid search using chroma backend
praisonai knowledge search "Python tutorial" --hybrid --backend chroma

# Search with agent scope
praisonai knowledge search "company policy" --agent-id company_bot

Output

Results print as a Rich table with #, Score, Source, and Content columns:

┏━━━┳━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ # ┃ Score ┃ Source        ┃ Content                            ┃
┡━━━╇━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ 1 │ 0.95  │ geography.txt │ Paris is the capital of France.    │
│ 2 │ 0.82  │ europe.md     │ France is a country in Europe.     │
└───┴───────┴───────────────┴────────────────────────────────────┘

When nothing matches, the command prints:

No results found.

If search consistently returns No results found. for content you just indexed, the embedding call likely failed silently on an older build. Upgrade to the latest release (PR #2823), where indexing errors exit non-zero and print ✗ Failed to index …. See Troubleshooting.

Result normalisation

The CLI accepts results from all three backend return shapes — a typed SearchResult, a legacy dict with a "results" key, or a plain list. Custom backends don’t have to pick one format; the command normalises them all before display.

See Search Results for the SearchResult shape and how to consume it from Python.

List Command

List available knowledge bases/collections.

praisonai knowledge list [OPTIONS]

Options

Option	Short	Description	Default
--verbose	-v	Verbose output	False

Example

praisonai knowledge list

Output:

┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Collection   ┃ Path                              ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ default      │ ./.praison/knowledge/default      │
│ research     │ ./.praison/knowledge/research     │
└──────────────┴───────────────────────────────────┘

Scope Identifiers

The mem0 backend requires at least one scope identifier (--user-id, --agent-id, or --run-id). If none is provided, a warning will be shown and default_user will be used.

When to Use Each Scope

Scope	Use Case	Example
--user-id	Per-user knowledge isolation	Multi-tenant apps
--agent-id	Shared agent knowledge	Company FAQ bot
--run-id	Session-specific context	Conversation history

Backend Selection

mem0 (Default)

Best for production apps with multi-user support:

praisonai knowledge index ./docs --user-id alice --backend mem0

Chroma

Best for local development:

praisonai knowledge index ./docs --backend chroma

Internal

Lightweight built-in storage:

praisonai knowledge index ./docs --backend internal

Configuration File

You can provide a YAML configuration file:

# knowledge-config.yaml
knowledge:
  vector_store:
    provider: chroma
    config:
      collection_name: my_docs
      path: ./.praison/knowledge/my_docs
  retrieval:
    strategy: hybrid

praisonai knowledge index ./docs --config knowledge-config.yaml

Environment Variables

Variable	Default	What it controls
OPENAI_EMBEDDING_MODEL	text-embedding-3-small	Model used to embed chunks on index and query text on search. Applies to the chroma / internal backends. Set to text-embedding-3-large for higher-quality retrieval at ~6.5× the cost per token, or to any other OpenAI-compatible embedding model your provider supports.
OPENAI_API_KEY	(none)	Required by the default OpenAI embedder. A missing or invalid key surfaces as ✗ Failed to index …: no chunks stored and exit code 1.

Custom embedders configured via --config knowledge-config.yaml (see Configuration File) take precedence over OPENAI_EMBEDDING_MODEL — the env var is a convenience for the default OpenAI path only.

Profiling

Enable profiling to measure performance:

praisonai knowledge index ./docs --user-id myuser --profile --profile-out ./profile.json

The profile output includes:

• Wall time
• Peak memory usage
• Modules imported
• Top functions by time

Related Commands

• praisonai rag query - Answer questions with citations
• praisonai chat - Interactive chat with knowledge retrieval