Overview

The Pyahu CLI is the local entry point for the Pyahu Platform: a faithful subset of the real experience, running on your machine. It spins up a development stack on k3d/k3s using Kubernetes resources generated by the CLI itself, without you having to write manifests, kubectl, or helm.

It is real Kubernetes, with Traefik, PersistentVolumes, ConfigMaps, and Secrets. The CLI does not hide k8s from the developer; it makes provisioning and operation easier, and the cluster stays yours to inspect (pyahu kubeconfig) whenever you want.

Quick install

curl -fsSL https://cli.pyahu.io/install.sh | sh

Other methods (script, go install, manual download) and the prerequisites are in Installation.

First cluster

pyahu init --preset platform   # cria o pyahu.yaml
pyahu doctor                   # valida Docker/Podman, k3d e portas
pyahu up                       # cria o cluster e aplica os serviços

When it finishes, pyahu up prints the cluster, the namespace, the kubeconfig path, and the connection variables ready to paste.

Tip

Run the commands in your project directory. The CLI looks for the pyahu.yaml from the current directory upward, so any subfolder of the project sees the same stack.

Services in the platform preset

Service	Local endpoint
PostgreSQL	localhost:5432
PostgreSQL (read replicas)	localhost:5433 when readReplicas > 0
ZITADEL	https://zitadel.localhost
RabbitMQ	localhost:5672
RabbitMQ Management	https://rabbitmq.localhost
Kafka	localhost:9092
Kafka Connect	http://localhost:8083
Debezium	configured via Kafka Connect
Kafka UI	https://kafka-ui.localhost

The HTTP UIs (ZITADEL, RabbitMQ, Kafka UI) go through Traefik on 80/443 with *.localhost hostnames and the local certificate. The TCP services (PostgreSQL, Kafka, RabbitMQ AMQP) and the Kafka Connect REST endpoint keep dedicated ports.

The minimal preset spins up only PostgreSQL. See Configuration to adjust services, ports, and credentials.

Connect your apps

# imprime as variáveis de conexão (shell, dotenv ou json)
pyahu env
eval "$(pyahu env)"

To see everything that is running and its endpoints:

pyahu services
pyahu describe postgres

The full reference for each command is in Commands.

Local TLS

When ZITADEL is enabled, the CLI issues a local certificate for *.localhost. Trust the CA on the host once to use https://zitadel.localhost without warnings:

pyahu certs trust

Details in Local certificates.

Cleanup

pyahu down                 # remove o cluster k3d
pyahu down --keep-cluster  # mantém o cluster, remove só o namespace da stack

If you change ports after the cluster already exists, recreate it. k3d pins the port mappings at creation time:

pyahu down
pyahu up