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

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