Deploy CLI
The praisonai deploy command group and praisonai-deploy console script
praisonai deploy runs, inspects, and tears down a deployment from the terminal.
praisonai deploy run --file agents.yamlQuick Start
- Validate the config
bash praisonai deploy validate --file agents.yaml - Run the deployment
bash praisonai deploy run --file agents.yaml - Check status
bash 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.
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 |
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.
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.
| Platform | Discover PID | Terminate |
|---|---|---|
| Windows | netstat -ano (LISTENING rows) | taskkill /PID <pid> /F |
| macOS / Linux | lsof -ti :<port> | SIGTERM via os.kill |
init
Generate a starter config for any type.
praisonai deploy init --file agents.yaml --type api
praisonai deploy init --file agents.yaml --type cloud --provider gcpProvider names are case-insensitive, and a plugin name works the same way once its package is installed:
praisonai deploy init --file agents.yaml --type cloud --provider hetznerSee Custom cloud providers to add your own target.
doctor
Check that required host CLIs are present. See Doctor.
praisonai deploy doctor --alldocker / aws / azure / gcp
Provider shortcuts take the agent file as a positional argument.
docker
praisonai deploy docker agents.yaml --tag v1| Flag | Alias | Description |
|---|---|---|
--tag | -t | Docker image tag |
aws
praisonai deploy aws agents.yaml --region us-east-1| Flag | Alias | Description |
|---|---|---|
--region | -r | AWS region |
gcp
praisonai deploy gcp agents.yaml --project my-project| Flag | Alias | Description |
|---|---|---|
--project | -p | GCP project |
azure
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.
praisonai-deploy --helpTroubleshooting
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 — the CLI now reconfigures stdio to UTF-8 with errors="replace" at entry, so no workaround is required.
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 — the CLI now launches the child process with sys.executable, so the API server starts under the same interpreter as the parent.
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.
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 for the full list of allowed fields per block.
Best Practices
Use –json for scripting
--json on status returns machine-readable output you can pipe into other tools.
Confirm destroys in CI
Pass --yes to destroy only in automation. Interactive runs should confirm before tearing down.