portworld 0.2.2

PortWorld CLI for setup, self-hosting, and managed deploy workflows

PortWorld CLI

Command-line interface for bootstrapping, validating, and deploying PortWorld — the open-source runtime for voice-and-vision AI assistants.

Install

Recommended (with uv):

uv tool install portworld

With pipx:

pipx install portworld

Bootstrap installer (installs uv, Python 3.11+, and Node.js tooling if missing):

curl -fsSL --proto '=https' --tlsv1.2 https://raw.githubusercontent.com/portworld/PortWorld/main/install.sh | bash

Agent skill (Cursor, Codex, others)

Install the portworld-cli-autopilot skill so agents get consistent bootstrap and operator commands (Agent Skills format):

npx skills add portworld/PortWorld --skill portworld-cli-autopilot -a cursor -a codex -y

Direct install of the skill folder only:

npx skills add https://github.com/portworld/PortWorld/tree/main/skills/portworld-cli-autopilot -y

See skills/README.md for --list, -g (global), and telemetry options.

Requirements

• macOS or Linux
• Python 3.11+
• Docker for local published-workspace runs

Quickstart

Initialize a local workspace, configure providers, and start the backend:

portworld init

Validate and inspect:

portworld doctor --target local
portworld status

portworld init supports two setup modes:

• quickstart — guided onboarding with beginner-friendly defaults
• manual — guided onboarding with advanced choices like local source runtime

Force either mode with --setup-mode quickstart or --setup-mode manual.

Commands

Command	Description
portworld init	Run the onboarding wizard, write config, and execute the selected local or managed path
portworld doctor	Validate local or managed deployment readiness
portworld deploy	Deploy to a managed cloud target
portworld status	Inspect workspace and deploy state
portworld logs	Read managed deployment logs
portworld config	Inspect or edit project configuration
portworld providers	Browse supported realtime, vision, search, and cloud providers
portworld extensions	Manage extension manifests and install state
portworld update cli	Show the recommended CLI upgrade command
portworld update deploy	Redeploy the active managed target
portworld ops	Lower-level operator tasks (see below)

Operator Tasks

portworld ops check-config                   # validate local config
portworld ops check-config --full-readiness  # full preflight with provider validation
portworld ops bootstrap-storage              # initialize storage
portworld ops export-memory --output /tmp/portworld-memory-export.zip

Deploy Workflows

Supported managed targets: GCP Cloud Run, AWS ECS/Fargate, Azure Container Apps.

Readiness Check

portworld doctor --target gcp-cloud-run    --gcp-project <project> --gcp-region <region>
portworld doctor --target aws-ecs-fargate  --aws-region <region>
portworld doctor --target azure-container-apps --azure-subscription <sub> --azure-resource-group <rg> --azure-region <region>

Deploy

portworld deploy gcp-cloud-run   --project <project> --region <region>
portworld deploy aws-ecs-fargate --region <region>
portworld deploy azure-container-apps --subscription <sub> --resource-group <rg> --region <region>

Logs

portworld logs gcp-cloud-run       --since 24h --limit 50
portworld logs aws-ecs-fargate     --since 24h --limit 50
portworld logs azure-container-apps --since 24h --limit 50

Redeploy

portworld update deploy
portworld update deploy --tag <image-tag>

Source Checkout

Use a repo checkout when developing PortWorld itself:

git clone https://github.com/portworld/PortWorld.git
cd PortWorld
pipx install . --force
portworld init

Updating

Upgrade the CLI:

uv tool upgrade portworld

Install a pinned version:

uv tool install "portworld==<version>"

Upgrade via the bootstrap installer:

curl -fsSL --proto '=https' --tlsv1.2 https://raw.githubusercontent.com/portworld/PortWorld/main/install.sh | bash -s -- --version v<version>

Production Caution

Managed cloud workflows are supported, but some infrastructure defaults favor quick bring-up over locked-down security:

• AWS: one-click deploy provisions RDS with public accessibility and broad ingress
• Azure: one-click deploy provisions PostgreSQL with public access

Review and harden these defaults before exposing a deployment to the public internet.

Links

• Repository
• Backend README — runtime, API reference, configuration
• iOS README — iOS app setup, Meta DAT, permissions
• Getting Started — extended onboarding guide
• Changelog
• CLI Release Process

License

MIT — see LICENSE.