Persistence CLI

CLI commands for database persistence

Persistence CLI

Command-line interface for database persistence management.

Invocations of praisonai persistence … shown here reach their handler as of PraisonAI PR #4329 (release ≥ the merge date, 2026-08-24). Older releases silently billed this exact command to an LLM at ~2.5k tokens with exit 0 — see issue #4327. Upgrade with pip install -U praisonai.

Installation

pip install "praisonai[tools]"

Commands

Help

praisonai persistence --help

Doctor

Validate database connectivity.

praisonai persistence doctor [options]

Options:

Option	Description
--conversation-url URL	Conversation store URL
--knowledge-url URL	Knowledge store URL
--state-url URL	State store URL
--all	Test all configured stores

Example:

praisonai persistence doctor \
    --conversation-url "postgresql://postgres:pass@localhost/db" \
    --knowledge-url "http://localhost:6333" \
    --state-url "redis://localhost:6379"

# Auto-detects libsql:// → turso, *.supabase.co → supabase, weaviate URL → weaviate
praisonai persistence doctor \
    --conversation-url "libsql://my-db.turso.io?authToken=***" \
    --knowledge-url    "http://my-cluster.weaviate.cloud" \
    --state-url        "redis://localhost:6379"

Backend Auto-Detection

praisonai persistence doctor inspects each --*-url and picks the matching store client automatically — the same rules the live persistence path uses.

Detection delegates to the canonical resolver PraisonAIDB._detect_backend, so the doctor recognises the same schemes as the live path.

Recognised schemes:

URL example	Detected backend	Store kind
postgresql://…, postgres://…	postgres	conversation
mysql://…	mysql	conversation
libsql://…	turso	conversation
sqlite://…, *.db	sqlite	conversation
https://…neon.tech	postgres	conversation
https://…cockroachlabs.cloud / .cockroachlabs.com	postgres	conversation
https://…xata.sh	postgres	conversation
postgresql://…supabase.com (direct Postgres)	postgres	conversation
https://…supabase.co / …supabase.com (REST)	supabase	conversation
http(s)://…qdrant… / :6333	qdrant	knowledge
chroma://… (special-cased)	chroma	knowledge
http(s)://…weaviate…	weaviate	knowledge
redis://…	redis	state

The serverless PostgreSQL family (.neon.tech, .cockroachlabs.cloud, .cockroachlabs.com, .xata.sh, .supabase.com) resolves to postgres when passed with a postgresql:// / postgres:// scheme. A Supabase host over http(s):// (.supabase.co / .supabase.com) resolves to the supabase REST backend instead.

Fallback defaults apply when the scheme is not recognised — the doctor keeps working using a lenient per-store default:

Option	Fallback backend
--conversation-url	sqlite
--knowledge-url	qdrant (with chroma:// special-case preserved)
--state-url	memory

Backend detection was aligned with the live persistence path in PraisonAI PR #4524 (release ≥ the merge date, 2026-08-28). On older releases libsql:// defaulted to sqlite, .supabase.co defaulted to sqlite, and Weaviate URLs defaulted to qdrant.

Run

Run an agent with persistence.

praisonai persistence run [options] "prompt"

Options:

Option	Description
--session-id ID	Session identifier
--user-id ID	User identifier (default: “default”)
--conversation-url URL	Conversation store URL
--knowledge-url URL	Knowledge store URL
--state-url URL	State store URL
--agent-name NAME	Agent name (default: “Assistant”)
--agent-instructions TEXT	Agent instructions
--dry-run	Show config without running

Example:

praisonai persistence run \
    --session-id "my-session" \
    --conversation-url "postgresql://localhost/db" \
    "Hello, my name is Alice"

Resume

Resume an existing session.

praisonai persistence resume --session-id ID [options]

Options:

Option	Description
--session-id ID	Session to resume (required)
--conversation-url URL	Conversation store URL
--show-history	Display conversation history
--continue "prompt"	Continue with new prompt

Example:

# Show history
praisonai persistence resume \
    --session-id "my-session" \
    --conversation-url "postgresql://localhost/db" \
    --show-history

# Continue conversation
praisonai persistence resume \
    --session-id "my-session" \
    --conversation-url "postgresql://localhost/db" \
    --continue "What's my name?"

Environment Variables

Variable	Description
PRAISON_CONVERSATION_URL	Default conversation store URL
PRAISON_KNOWLEDGE_URL	Default knowledge store URL
PRAISON_STATE_URL	Default state store URL
OPENAI_API_KEY	OpenAI API key for agent

export PRAISON_CONVERSATION_URL="postgresql://localhost/db"
export OPENAI_API_KEY="your-key"

# Now commands are simpler
praisonai persistence doctor --all
praisonai persistence run --session-id "my-session" "Hello!"

Troubleshooting

Connection refused:

• Check Docker containers are running
• Verify URL format and credentials

No API key:

• Set OPENAI_API_KEY environment variable