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

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

<Steps>
  <Step title="Use the CLI flag">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai run --pure "Summarise this file"
    ```
  </Step>

  <Step title="Or set the env var">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    export PRAISONAI_NO_PLUGINS=1
    praisonai chat
    ```
  </Step>
</Steps>

***

## 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)"*.

***

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

<AccordionGroup>
  <Accordion title="Use --pure for bug reports">
    Attach the plugin-free reproduction alongside the normal one — it makes obvious whether a plugin is involved.
  </Accordion>

  <Accordion title="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>

  <Accordion title="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>

  <Accordion title="Check plugins doctor to see which mode you're in">
    `praisonai plugins doctor` tells you whether plugins are suppressed for the current process.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Plugins CLI" icon="plug" href="/docs/cli/plugins">
    List, enable, disable, and diagnose plugins
  </Card>

  <Card title="Plugins" icon="puzzle-piece" href="/docs/features/plugins">
    Write, load, and configure plugins
  </Card>
</CardGroup>