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

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

​Knowledge CLI Commands

​Commands Overview

​Index Command

​Arguments

​Options

​Examples

​Exit Codes

​Search Command

​Arguments

​Options

​Examples

​Output

​Result normalisation

​List Command

​Options

​Example

​Scope Identifiers

​When to Use Each Scope

​Backend Selection

​mem0 (Default)

​Chroma

​Internal

​Configuration File

​Environment Variables

​Profiling

​Related Commands

Knowledge CLI Commands

Commands Overview

Index Command

Arguments

Options

Examples

Exit Codes

Search Command

Arguments

Options

Examples

Output

Result normalisation

List Command

Options

Example

Scope Identifiers

When to Use Each Scope

Backend Selection

mem0 (Default)

Chroma

Internal

Configuration File

Environment Variables

Profiling

Related Commands