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

# Update Hint

> Non-blocking notice that a newer PraisonAI is available, refreshed in a detached background process

The update hint prints a one-line "a newer version is available" notice at start-up, refreshing its cache in a fully detached background process so it never blocks or slows the CLI.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    A[praisonai run ...]:::agent --> B[Read cache]:::config
    B -->|Newer available| C[stderr hint]:::process
    B --> D[Spawn detached child]:::tool
    D --> E[Refresh cache for next start]:::success
    C --> F[Command runs normally]:::success

    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef tool fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef process fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef success fill:#10B981,stroke:#7C90A0,color:#fff
    classDef config fill:#6366F1,stroke:#7C90A0,color:#fff
```

## Quick Start

<Steps>
  <Step title="See the hint">
    Run any command. If a newer release is cached, PraisonAI prints this to stderr:

    ```
    A newer PraisonAI is available: 4.6.145 -> 4.6.146. Run: praisonai upgrade
    ```
  </Step>

  <Step title="Opt out">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    export PRAISONAI_NO_UPDATE_CHECK=1
    ```

    Suppresses both the hint and the background refresh.
  </Step>
</Steps>

***

## How It Works

Every text-mode, non-quiet start reads a cached version file, prints a hint if a newer release is known, then warms the cache for the *next* start in a detached child.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant CLI as praisonai
    participant Cache as state/update_check.json
    participant Child as detached child

    User->>CLI: praisonai run "..."
    CLI->>Cache: read (no network)
    Cache-->>CLI: latest = 4.6.146
    CLI-->>User: stderr hint (if newer)
    CLI->>Child: spawn (start_new_session)
    Child->>Cache: refresh from PyPI
    CLI-->>User: command runs normally
```

| Aspect                     | Behaviour                                                                     |                                 |
| -------------------------- | ----------------------------------------------------------------------------- | ------------------------------- |
| Cache location             | `<user_config_dir>/state/update_check.json`                                   |                                 |
| Cache TTL                  | 24 hours                                                                      |                                 |
| Where it prints            | stderr, text mode only                                                        |                                 |
| Parent-process network I/O | Never — the parent only reads the cache                                       |                                 |
| Refresh process            | Fully detached child (`start_new_session=True` on POSIX; \`CREATE\_NO\_WINDOW | DETACHED\_PROCESS\` on Windows) |

<Note>
  The hint **never blocks start-up, never performs network I/O in the parent process, and never raises.** A missing, stale, or unwritable cache simply yields no hint.
</Note>

***

## Options

Control the hint with one environment variable.

| Variable                    | Values                                      | Description                                              |
| --------------------------- | ------------------------------------------- | -------------------------------------------------------- |
| `PRAISONAI_NO_UPDATE_CHECK` | `1`, `true`, `yes`, `on` (case-insensitive) | Suppress both the hint and the background cache refresh. |

The hint is also suppressed automatically in `--output json` mode — only text mode emits it.

***

## Common Patterns

Disable the hint for a single command.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
PRAISONAI_NO_UPDATE_CHECK=1 praisonai run "2+2"
```

Disable it permanently in CI by exporting the variable in your environment.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
export PRAISONAI_NO_UPDATE_CHECK=1
```

***

## Best Practices

<AccordionGroup>
  <Accordion title="Leave it on for interactive use">
    The hint costs nothing at start-up (cache-only read) and reminds you when a fix or feature ships. Keep it enabled on developer machines.
  </Accordion>

  <Accordion title="Opt out in CI and headless jobs">
    Set `PRAISONAI_NO_UPDATE_CHECK=1` in pipelines to avoid stderr noise and the background refresh spawn.
  </Accordion>

  <Accordion title="Warm the cache with --check">
    `praisonai upgrade --check` refreshes the same cache, so a one-off check makes the next start's hint accurate without waiting for the 24h TTL.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="praisonai upgrade" icon="arrow-up" href="/docs/features/praisonai-upgrade">
    Update the CLI in place
  </Card>

  <Card title="praisonai uninstall" icon="trash" href="/docs/features/praisonai-uninstall">
    Cleanly remove the managed install
  </Card>
</CardGroup>