Pyahu CLI

Your local development stack in a single command.

Website · Documentation · Releases

---

Pyahu CLI provisions a local development stack on a k3d cluster with lightweight Kubernetes manifests the CLI generates for you. One command brings up PostgreSQL, ZITADEL, RabbitMQ, Redis, Kafka, Kafka Connect with Debezium, and Kafka UI, with local TLS and predictable endpoints, and without turning your setup into a side project.

It is intentionally lightweight: k3d plus generated resources. Normal operation does not require kubectl or helm.

$ pyahu init --preset platform
$ pyahu up
✓ Checando dependências locais  (137ms)
✓ Cluster pyahu-local criado  (8.4s)
✓ Aguardando a API do Kubernetes  (3.1s)
✓ Configurando serviços: postgres, zitadel, rabbitmq, redis, kafka, kafka-connect, kafka-ui

✓ Pyahu local stack is ready

What it provisions

Service	Role	Endpoint
PostgreSQL	Relational database (optional read replicas)	localhost:5432
ZITADEL	Identity & OIDC over local HTTPS	https://zitadel.localhost
RabbitMQ	AMQP messaging + management UI	localhost:5672 · https://rabbitmq.localhost
Redis	Valkey key-value store, AOF on by default	localhost:6379
Kafka	Event streaming broker (KRaft)	localhost:9092
Kafka Connect	Declarative connectors and plugins, Debezium CDC	http://localhost:8083
Kafka UI	Topics, connectors and consumers	https://kafka-ui.localhost

HTTP UIs go through Traefik on host 80/443 with *.localhost hostnames and a shared local TLS certificate. TCP services and the Kafka Connect REST API use dedicated host ports.

Kafka Connect takes its plugins from the stack file, so a connector that does not ship with the Debezium image does not mean building one:

services:
  kafkaConnect:
    plugins:
      - name: redis-kafka-connect
        url: https://github.com/redis-field-engineering/redis-kafka-connect/releases/download/v1.1.0/redis-redis-kafka-connect-1.1.0.zip
        sha256: 7e4249ca356f702220cf09e9e150c8336e24824d7a72fce05d7999bf2a7e03df
      - name: redis-kafka-connect      # same name = same plugin directory, for an SMT
        file: connect-plugins/my-outbox-router.jar
    connectors:
      - name: orders-outbox
        kind: debezium.postgres
        optional: true                 # its table only exists after the app boots once
        tables: { include: [public.outbox] }

An optional connector whose source does not exist yet is a warning during pyahu up, not a failure; pyahu connectors apply registers it after the first boot, and pyahu connectors status reports every task, because a connector stays RUNNING while its only task is FAILED.

Install

Every release is published to GitHub Releases — binaries for macOS, Linux and Windows (amd64 and arm64), plus checksums.txt. Every install method below pulls from there.

mise

Pinning the CLI next to the rest of a project's toolchain is the recommended way: everyone on the team gets the same version, and it is recorded in the repo.

# in a project, writes to ./mise.toml
mise use "github:pyahu/cli@0.7.0"

# or for your user, everywhere
mise use -g "github:pyahu/cli@0.7.0"

mise install

# mise.toml
[tools]
"github:pyahu/cli" = "0.7.0"

Pyahu toolchain

The Pyahu toolchain already pins the CLI in its cloud profile, along with k3d, kubectl and the rest of the Kubernetes set. If you use it, you have the CLI:

export MISE_ENV=cloud    # add to your shell rc
mise install

Install script (macOS and Linux)

Downloads the release for your platform from GitHub Releases:

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

# pick an install dir, no sudo
curl -fsSL https://cli.pyahu.io/install.sh | sh -s -- --bin-dir "$HOME/.local/bin"

go install

go install github.com/pyahu/cli/cmd/pyahu@latest   # Go 1.26+

Staying up to date

The CLI warns when it is behind, and pyahu upgrade replaces a binary it owns after verifying the release checksum. A binary managed by mise is left to mise, and the command says so.

pyahu check-update
pyahu upgrade

Full instructions, manual download and shell completion: Installation docs.

Requirements

• Docker or Podman, running
• k3d 5.x

pyahu doctor checks these and your local ports before bringing the stack up.

Quick start

pyahu init --preset platform   # write pyahu.yaml (or --preset minimal)
pyahu doctor                   # validate Docker/Podman, k3d and ports
pyahu up                       # create the cluster and apply the services
pyahu certs trust              # trust the local CA for https://*.localhost

pyahu services                 # list services and endpoints
pyahu connectors apply         # register connectors whose source needed the app to boot
pyahu connectors status        # connector and task state; non-zero if any task is not RUNNING
eval "$(pyahu env)"            # load connection env vars into your shell
pyahu down                     # tear it all down

The default stack file is pyahu.yaml, discovered from the current directory upward. See the command reference for every command and flag.

Documentation

• Overview & getting started
• Commands
• Configuration
• Kafka Connect & Debezium
• Local certificates
• Backup & restore

Scope

The current v1 focus is local infrastructure only. Application deployment, remote clusters, and Telepresence-style workflows are intentionally out of scope.

Contributing

Contributions are welcome. See CONTRIBUTING.md for the dev setup, build/test commands, and conventions. Please read the Code of Conduct and report security issues per the security policy.

License

MIT © Pyahu