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

# Pure Mode (Suppress Plugins)

> Skip plugin discovery for a single run — clean, deterministic baseline

Pure Mode skips external-plugin discovery for a single run without touching your saved enable/disable state.

> [!NOTE]
>
> Running the long-lived gateway? `--pure` / `--no-plugins` also work on `praisonai gateway start`, where they persist across `restart` and additionally disable inbound YAML hooks. See [Gateway Safe Mode](https://praison.ai/docs/features/gateway-safe-mode.md).

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Pure Mode"
        Run[📝 CLI Run] --> Flag{🚦 --pure?}
        Flag -->|Yes| Skip[⏭️ Skip discovery]
        Flag -->|No| Discover[🔌 Load plugins]
        Skip --> Agent[🤖 Clean agent]
        Discover --> Agent
    end

    classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef check fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef skip fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef result fill:#10B981,stroke:#7C90A0,color:#fff

    class Run input
    class Flag check
    class Skip,Discover skip
    class Agent result
```

## Quick Start

**1. Use the CLI flag**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai run --pure "Summarise this file"
```

**2. Or set the env var**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
export PRAISONAI_NO_PLUGINS=1
praisonai chat
```

***

## How It Works

The CLI flag sets `PRAISONAI_NO_PLUGINS` only for the current run, then restores the prior value on return.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant CLI as CLI (chat / run / code)
    participant Scope as scoped_no_plugins()
    participant Manager as PluginManager
    participant Env as PRAISONAI_NO_PLUGINS

    User->>CLI: praisonai run --pure "task"
    CLI->>Scope: enter (--pure = True)
    Scope->>Env: set "1" (save prior value)
    CLI->>Manager: discover_entry_points()
    Manager->>Env: read
    Env-->>Manager: "1"
    Manager-->>CLI: 0 (short-circuit + notice)
    CLI->>Scope: exit
    Scope->>Env: restore prior value
    CLI-->>User: response (plugin-free run)
```

The `@scopes_no_plugins` decorator wraps each command, so suppression is restored on return and never leaks into a later in-process call. The run emits one log line: *"Running without external plugins (--pure / PRAISONAI\_NO\_PLUGINS)"*.

> [!NOTE]
>
> Pure Mode only changes **whether** entry-point plugins are discovered — it does not change precedence. Even in a normal (non-pure) run, entry-point plugins never override a shipped built-in: since [PR #4176](https://github.com/MervinPraison/PraisonAI/pull/4176) the base `PluginRegistry` skips any entry point whose name (case-insensitive) collides with a built-in. See [Plugin Precedence](https://praison.ai/docs/features/plugin-precedence.md).

***

## Configuration

Three surfaces suppress plugins. A constructor `disabled=True` wins; otherwise the env var decides.

| Surface | Precedence | Persists? | Use when |
| - | - | - | - |
| `PluginManager(disabled=True)` | 1 (wins) | No | Embedded Python, one call, deterministic |
| `--pure` / `--no-plugins` CLI flag | 2 | No — scoped, auto-restored | One CLI invocation |
| `PRAISONAI_NO_PLUGINS=1` env var | 3 | Only for the shell | Whole CI job / shell session |
| *(none)* — default | 4 | — | Normal use (backward-compatible) |

The env var accepts `true`, `1`, or `yes` (case-insensitive). Pure Mode never mutates `.praisonai/config.yaml` or any persisted enable/disable state.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    Q[Need to skip plugins?] --> A[One-off CLI run]
    Q --> B[Whole shell / CI job]
    Q --> C[Embedded Python — one call]
    A --> R1["praisonai run --pure"]
    B --> R2["export PRAISONAI_NO_PLUGINS=1"]
    C --> R3["PluginManager(disabled=True)"]

    classDef decision fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef option fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef result fill:#10B981,stroke:#7C90A0,color:#fff

    class Q decision
    class A,B,C option
    class R1,R2,R3 result
```

Python parity forces suppression regardless of the env var:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.plugins import PluginManager

manager = PluginManager(disabled=True)
manager.discover_entry_points()   # returns 0; no plugins loaded
```

***

## Common Patterns

Reproduce a CI failure without whatever plugin your machine has enabled:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai run --pure "Reproduce the failing task"
```

Debug a plugin regression by comparing a normal run with a plugin-free one:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai chat --no-plugins
```

Reuse in a notebook — one cell runs pure, the next picks plugins back up automatically:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai_code.cli.commands.run import run_main

run_main(pure=True)   # this call: no plugins
run_main()            # next call: plugins restored automatically
```

***

## Best Practices

> [accordion] Use --pure for bug reports
>
> Attach the plugin-free reproduction alongside the normal one — it makes obvious whether a plugin is involved.

> [accordion] Prefer the CLI flag over the env var for one-offs
>
> The flag's scope is guaranteed — it always restores the prior value on return.

> [accordion] Keep PRAISONAI\_NO\_PLUGINS out of your shell rc
>
> A persistent export defeats the one-shot contract and hides real plugin behaviour from every command.

> [accordion] Check plugins doctor to see which mode you're in
>
> `praisonai plugins doctor` tells you whether plugins are suppressed for the current process.

***

## Related

> [card] [Plugins CLI](https://praison.ai/docs/cli/plugins.md)
>
> List, enable, disable, and diagnose plugins

> [card] [Plugins](https://praison.ai/docs/features/plugins.md)
>
> Write, load, and configure plugins

> [card] [Gateway Safe Mode](https://praison.ai/docs/features/gateway-safe-mode.md)
>
> The same suppression for the long-lived gateway process


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