Persistence CLI

CLI commands for database persistence

Persistence CLI

Command-line interface for database persistence management.

Installation

bash

pip install "praisonai[tools]"

Commands

Help

bash

praisonai persistence --help

Doctor

Validate database connectivity.

bash

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:

bash

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.

Diagram

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

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`

Run

Run an agent with persistence.

bash

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:

bash

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

Resume

Resume an existing session.

bash

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:

bash

# 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?"

Export

Export a session to a JSONL file.

bash

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

Options:

Option	Description
`--session-id ID`	Session to export (required)
`--conversation-url URL`	Conversation store URL
`--output FILE`	Output file path (default: `session-{id}.jsonl`)

Example:

bash

praisonai persistence export \
    --session-id "my-session" \
    --conversation-url "postgresql://localhost/db" \
    --output session.jsonl

The file holds one JSON line with this shape:

json

{
  "session_id": "my-session",
  "user_id": "default",
  "agent_id": "imported",
  "name": "...",
  "metadata": {},
  "created_at": 1730000000.0,
  "messages": [
    {"id": "...", "role": "user", "content": "Hello", "metadata": {}, "created_at": 1730000000.0}
  ]
}

Import

Import a session from a JSONL file.

bash

praisonai persistence import --file FILE [options]

Options:

Option	Description
`--file FILE`	JSONL file to import (required)
`--conversation-url URL`	Conversation store URL

Example:

bash

praisonai persistence import \
    --file session.jsonl \
    --conversation-url "postgresql://localhost/db"

On an async store, import uses the same fixed dispatch path shipped in PR #5380.

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

bash

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