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

# Deploy CLI

> The praisonai deploy command group and praisonai-deploy console script

`praisonai deploy` runs, inspects, and tears down a deployment from the terminal.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai deploy run --file agents.yaml
```

> [!NOTE]
>
> **Platform support.** `praisonai-deploy` and `praisonai deploy` work on Linux, macOS, and Windows out of the box — the CLI forces UTF-8 on `stdout`/`stderr` at entry so the Rich emoji banners (🏥 🔍 📋 🚀 ❌) never crash on default Windows consoles (cp1252). No PowerShell/Terminal encoding tweaks required. Background API deploys also launch the child process with `sys.executable`, so the API server always starts under the same interpreter as the parent venv. Fixed in [PraisonAI PR #3611](https://github.com/MervinPraison/PraisonAI/pull/3611) and [PR #3608](https://github.com/MervinPraison/PraisonAI/pull/3608).

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    V[validate] --> P[plan]
    P --> R[run]
    R --> S[status]
    S --> D[destroy]

    classDef step fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef last fill:#8B0000,stroke:#7C90A0,color:#fff

    class V,P,R,S step
    class D last
```

## Quick Start

**1. Validate the config**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai deploy validate --file agents.yaml
```

**2. Run the deployment**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai deploy run --file agents.yaml
```

**3. Check status**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai deploy status --file agents.yaml
```

***

## Commands

The `praisonai deploy` group and the standalone `praisonai-deploy` console script share the same commands.

| Command | Description |
| - | - |
| `run` | Execute the deployment |
| `init` | Generate a sample `agents.yaml` with a `deploy:` section |
| `validate` | Validate the `deploy:` configuration |
| `plan` | Print the deployment plan without executing |
| `status` | Print the current deployment state |
| `doctor` | Check deployment readiness |
| `destroy` | Tear down the deployment |
| `docker` | Deploy as a Docker container |
| `aws` | Deploy to AWS |
| `azure` | Deploy to Azure |
| `gcp` | Deploy to Google Cloud |

### run / validate / plan / status / destroy

These commands read the `deploy:` section of an `agents.yaml` file.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai deploy run --file agents.yaml
praisonai deploy validate --file agents.yaml
praisonai deploy plan --file agents.yaml
praisonai deploy status --file agents.yaml
praisonai deploy destroy --file agents.yaml --yes
```

| Flag | Type | Default | Description |
| - | - | - | - |
| `--file`, `-f` | string | `agents.yaml` | Path to `agents.yaml` |
| `--type` | choice | — | `api`, `docker`, or `cloud` |
| `--provider` | choice | — | `aws`, `azure`, `gcp`, `fly`, `railway`, `render`, or any registered plugin (for `type=cloud`). Case-insensitive. |
| `--background` | flag | `false` | Run in background |
| `--json` | flag | `false` | Output as JSON |
| `--yes` | flag | `false` | Skip confirmation prompts |

> [!NOTE]
>
> `validate` is a strict schema check. It rejects misspelled field keys and misspelled section names with a clear `ValueError`, and for `type: cloud` it prints `Cluster:` alongside `Provider`, `Region`, and `Service` — previously the cluster name only appeared under `--json`, so a wrong `cluster_name` was invisible in the default output. See [PraisonAI PR #4308](https://github.com/MervinPraison/PraisonAI/pull/4308).

### How `deploy run --type api` starts the server

The generated Flask server subprocess uses the same Python interpreter as the CLI itself (`sys.executable`) and inherits the parent process environment, so it always resolves the same `praisonaiagents`/`flask` install and picks up secrets like `OPENAI_API_KEY` without extra wiring.

> [!NOTE]
>
> On Windows and multi-Python setups, a bare `python` on `PATH` may resolve to a different interpreter than the one running the CLI — that used to break the server with `ModuleNotFoundError: No module named 'flask'`. The interpreter is now pinned so the server always runs where the packages actually are.

### How `deploy destroy --type api` stops the server

`praisonai deploy destroy` finds the process bound to the API port and terminates it using OS-native tooling — no extra dependency to install.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    Start([praisonai deploy destroy]) --> OS{OS?}
    OS -->|Windows| WinD[netstat -ano<br/>find LISTENING PID]
    WinD --> WinK[taskkill /PID … /F]
    OS -->|macOS / Linux| UxD[lsof -ti :port]
    UxD --> UxK[os.kill pid, SIGTERM]
    WinK --> Done[Server stopped]
    UxK --> Done

    classDef start fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef q fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef step fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef done fill:#10B981,stroke:#7C90A0,color:#fff

    class Start start
    class OS q
    class WinD,WinK,UxD,UxK step
    class Done done
```

| Platform | Discover PID | Terminate |
| - | - | - |
| Windows | `netstat -ano` (LISTENING rows) | `taskkill /PID <pid> /F` |
| macOS / Linux | `lsof -ti :<port>` | `SIGTERM` via `os.kill` |

> [!NOTE]
>
> If the discovery binary is missing (rare — e.g. a stripped container image), the command reports `No API server running on port <port>` instead of raising. If *some* of the discovered PIDs can't be killed (permission error, gone process), destroy exits with `success=False` and lists the survivors in `error=`.

### init

Generate a starter config for any type.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai deploy init --file agents.yaml --type api
praisonai deploy init --file agents.yaml --type cloud --provider gcp
```

Provider names are case-insensitive, and a plugin name works the same way once its package is installed:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai deploy init --file agents.yaml --type cloud --provider hetzner
```

See [Custom cloud providers](https://praison.ai/docs/docs/features/deploy/custom-providers) to add your own target.

### doctor

Check that required host CLIs are present. See [Doctor](https://praison.ai/docs/docs/features/deploy/doctor).

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai deploy doctor --all
```

### docker / aws / azure / gcp

Provider shortcuts take the agent file as a positional argument.

> [tab] docker
>
> ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> praisonai deploy docker agents.yaml --tag v1
> ```
>
> | Flag | Alias | Description |
> | - | - | - |
> | `--tag` | `-t` | Docker image tag |

> [tab] aws
>
> ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> praisonai deploy aws agents.yaml --region us-east-1
> ```
>
> | Flag | Alias | Description |
> | - | - | - |
> | `--region` | `-r` | AWS region |

> [tab] gcp
>
> ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> praisonai deploy gcp agents.yaml --project my-project
> ```
>
> | Flag | Alias | Description |
> | - | - | - |
> | `--project` | `-p` | GCP project |

> [tab] azure
>
> ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> praisonai deploy azure agents.yaml --resource-group my-rg
> ```
>
> | Flag | Alias | Description |
> | - | - | - |
> | `--resource-group` | `-g` | Azure resource group |

***

## Standalone Script

Installing `praisonai-deploy` adds a `praisonai-deploy` console script that mirrors the `praisonai deploy` group.

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

***

## Troubleshooting

> [accordion] UnicodeEncodeError on Windows (older builds)
>
> Older `praisonai-deploy` builds crashed with `UnicodeEncodeError` on default Windows consoles because the Rich banner prefixes use emoji that cp1252 cannot encode. Every command (`doctor`, `validate`, `plan`, `run`, `api`, `docker`, `status`, `destroy`) was affected. Upgrade to the version that includes [PraisonAI PR #3611](https://github.com/MervinPraison/PraisonAI/pull/3611) — the CLI now reconfigures stdio to UTF-8 with `errors="replace"` at entry, so no workaround is required.

> [accordion] ModuleNotFoundError: No module named 'flask' on Windows
>
> A background API deploy could fail with `ModuleNotFoundError: No module named 'flask'` when a bare `python` resolved to a different interpreter than the parent venv. Upgrade to the version that includes [PraisonAI PR #3608](https://github.com/MervinPraison/PraisonAI/pull/3608) — the CLI now launches the child process with `sys.executable`, so the API server starts under the same interpreter as the parent.

> [accordion] Unknown deploy config key(s): dockerr
>
> A misspelled section like `dockerr:` (instead of `docker:`) now fails with `Unknown deploy config key(s): dockerr. Allowed keys: agents, api, cloud, docker, type`. Fix the spelling — the allowed keys are listed in the error message.

> [accordion] Extra inputs are not permitted (misspelled field)
>
> A misspelled field like `clustor_name` inside `cloud:` now fails with a pydantic `Extra inputs are not permitted` error naming the bad field. Fix the spelling — see the [Config Reference](https://praison.ai/docs/docs/features/deploy/config-reference) for the full list of allowed fields per block.

***

## Best Practices

> [accordion] Use --json for scripting
>
> `--json` on `status` returns machine-readable output you can pipe into other tools.

> [accordion] Confirm destroys in CI
>
> Pass `--yes` to `destroy` only in automation. Interactive runs should confirm before tearing down.

***

## Related

> [card] [Doctor](https://praison.ai/docs/docs/features/deploy/doctor)
>
> Preflight readiness checks

> [card] [Config Reference](https://praison.ai/docs/docs/features/deploy/config-reference)
>
> Every deploy field and default

> [card] [Custom Providers](https://praison.ai/docs/docs/features/deploy/custom-providers)
>
> Register your own cloud target


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