> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Persistence CLI

> CLI commands for database persistence

# Persistence CLI

Command-line interface for database persistence management.

<Note>
  Invocations of `praisonai persistence …` shown here reach their handler as of PraisonAI PR [#4329](https://github.com/MervinPraison/PraisonAI/pull/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](https://github.com/MervinPraison/PraisonAI/issues/4327). Upgrade with `pip install -U praisonai`.
</Note>

## Installation

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
pip install "praisonai[tools]"
```

## Commands

### Help

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai persistence --help
```

### Doctor

Validate database connectivity.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Backend Auto-Detection"
        URL[🔗 --*-url] --> Detect[🧠 _detect_backend]
        Detect -->|known scheme| Matched[✅ Matched backend]
        Detect -->|unknown scheme| Fallback[⚠️ Lenient fallback]
    end

    classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef matched fill:#10B981,stroke:#7C90A0,color:#fff
    classDef fallback fill:#F59E0B,stroke:#7C90A0,color:#fff

    class URL input
    class Detect process
    class Matched matched
    class Fallback fallback
```

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 |

<Note>
  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.
</Note>

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

<Note>
  Backend detection was aligned with the live persistence path in PraisonAI PR [#4524](https://github.com/MervinPraison/PraisonAI/pull/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`.
</Note>

### Run

Run an agent with persistence.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai persistence run \
    --session-id "my-session" \
    --conversation-url "postgresql://localhost/db" \
    "Hello, my name is Alice"
```

### Resume

Resume an existing session.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "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}
  ]
}
```

<Note>
  Since PraisonAI PR [#5380](https://github.com/MervinPraison/PraisonAI/pull/5380), export works against `mode="async"` conversation URLs. Earlier releases raised `AttributeError: 'coroutine' object has no attribute 'session_id'` on async stores. See [Persistence Overview](/docs/persistence/overview#async-store-safe-session-export-import-pr-5380).
</Note>

### Import

Import a session from a JSONL file.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai persistence import --file FILE [options]
```

**Options:**

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

**Example:**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.