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.

bash

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

bash

# 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

bash

# 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.

bash

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

bash

# 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.

bash

praisonai knowledge list [OPTIONS]

Options

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

Example

bash

praisonai knowledge list

Output:

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

Scope Identifiers

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:

bash

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

Chroma

Best for local development:

bash

praisonai knowledge index ./docs --backend chroma

Internal

Lightweight built-in storage:

bash

praisonai knowledge index ./docs --backend internal

Configuration File

You can provide a YAML configuration file:

yaml

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

bash

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`.

Profiling

Enable profiling to measure performance:

bash

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