CLI Commands
The cata CLI orchestrates runtime operations for Catallaxy labs. It evaluates Nix expressions, applies manifests to clusters, and manages secrets, PKI, and images.
Most commands require a --flake argument pointing to your lab flake:
cata --flake '.#homelab.local' <command>
Lab Lifecycle
cata lab up
Provision all clusters, render manifests, and apply them phase by phase.
cata lab up
cata lab down
Stop lab clusters. Preserves state — clusters can be restarted with lab up.
cata lab down
cata lab destroy
Destroy lab completely — deletes clusters, cloud resources, services, and network. Not reversible.
cata lab destroy
cata lab init
Initialize lab infrastructure without applying manifests.
cata lab init
cata lab status
Show the status of all clusters and services.
cata lab status
cata lab list
List all labs defined in the flake.
cata lab list
cata lab plan
Show the computed deployment plan without executing.
cata lab plan
cata lab plan --teardown # show teardown plan
cata lab lint
Validate rendered manifests against property checks.
cata lab lint
cata lab lint --skip image-pin,crd-schema # skip specific checks
cata lab lint --path /nix/store/...-lab-* # lint a pre-built package
cata lab apply
Apply manifests to all clusters without provisioning.
cata lab apply
cata lab apply --phase operators # specific phase
Lab Publishing
cata lab publish
Render manifests and push to a Git repository for GitOps consumption.
cata lab publish
cata lab publish --pr # create a pull request
cata lab publish --dry-run # preview without pushing
Lab Ops
cata lab ops <args...>
Run lab-defined operational commands.
cata lab ops idm init-user lab-admin
cata lab ops database shell
Local Environment
cata lab dns
Configure local DNS resolution for lab domains.
cata lab dns --setup
cata lab dns --teardown
cata lab trust
Install or remove the lab CA from the system trust store.
cata lab trust --setup
cata lab trust --teardown
cata lab trust --export # print CA PEM to stdout
Cluster Lifecycle
cata cluster up
Provision and apply manifests to a single cluster.
cata cluster up core
cata cluster down
Stop a single cluster (alias: cluster destroy).
cata cluster down core
Apply
cata apply <cluster>
Apply manifests to a cluster with fine-grained control.
cata apply core
cata apply core --phase networking
cata apply core --dry-run
cata apply core --force # bypass GitOps strategy check
PKI
cata pki init
Initialize the PKI CA for a cluster (generates root CA if needed).
cata pki init core
cata pki issue <user>
Issue a client certificate for a user.
cata pki issue admin
cata pki provision <user>
Write a certificate to a YubiKey PIV slot.
cata pki provision admin
cata pki list
List CA and certificate status.
cata pki list core
cata pki kubeconfig <user>
Generate a kubeconfig entry using the client certificate.
cata pki kubeconfig admin
Secrets
cata secrets generate
Generate SOPS-encrypted secret files for all stores.
cata secrets generate
cata secrets edit <store>
Decrypt, edit, and re-encrypt a secrets store.
cata secrets edit cloud-creds
cata secrets decrypt <store>
Decrypt a store to stdout.
cata secrets decrypt cloud-creds
cata secrets encrypt <file>
Encrypt a plaintext file.
cata secrets encrypt secrets.yaml
cata secrets encrypt secrets.yaml --output secrets.enc.yaml
cata secrets rotate <store>
Rotate encryption keys on a SOPS file.
cata secrets rotate cloud-creds
cata secrets list
Show all stores, managed secrets, and projections.
cata secrets list
Images
cata images list
List all container images used by a lab.
cata images list
cata images mirror
Mirror lab images to a target registry using crane.
cata images mirror --registry ghcr.io/my-org
cata images mirror --registry ghcr.io/my-org --dry-run
cata images prefetch
Prefetch lab images into a local registry (e.g., Zot).
cata images prefetch --registry localhost:5050
Kubeconfig
cata kubeconfig sync
Sync kubeconfig entries for lab clusters.
cata kubeconfig sync
Code Generation
cata generate
Generate Kubernetes API types from OpenAPI specs and CRDs (development use).
nix run .#generate-k8s-types