Skip to content
kix /docs
Install the CLI

How-to guide Start and inspect a Kix project

List clusters and packages

Use kix list to discover what a project exposes before choosing a cluster to check, build, or deploy. Run the commands from the directory containing the project’s flake.nix.

List clusters

Section titled “List clusters”

List every cluster registered with kix.lib.mkFlake:

kix-examples/ 
❱ kix list clusters
 NAME                                
 02-hello-world                      
 06-service-dep                      
 08-namespace-deps                   
 09-typed-options                    
 10-reuse-packages                   
 19-scorecards                       
 homelab-kind                        
 homelab-kind-db-resize              
 homelab-kind-env-stamped            
 homelab-kind-env-stamped-dev-change 
 homelab-kind-gateway                
 homelab-kind-gateway-migrate        
 homelab-kind-ns-rename              
 homelab-kind-pg17                   
 homelab-kind-pvc-resize             
 homelab-kind-storage-migrate        
 homelab-kind-tls                    
 homelab-kind-tls-migrate            
 homelab-kind-upgrade-broad          
 homelab-kind-upgrade-small          
 how-to-adoption                     
 how-to-adoption-takeover            
 how-to-application                  
 how-to-auto-instantiation           
 how-to-composition                  
 how-to-fragments                    
 how-to-helm-bridge                  
 how-to-multi-env                    
 how-to-package-cilium               
 how-to-package-monitoring           
 how-to-package-monitoring-loki      
 how-to-package-stackgres            
 how-to-package-storage              
 how-to-package-valkey               
 how-to-package-velero               
 how-to-package-victoria-metrics     
 how-to-platform-cloudflare-tunnel   
 how-to-platform-gateway             
 how-to-platform-hostpath            
 how-to-platform-ingress             
 how-to-platform-monitoring          
 how-to-platform-network-policy      
 how-to-platform-secrets             
 how-to-platform-sops                
 how-to-stateful-migration

The name in the first column is the value accepted by commands such as kix check, kix build, and kix deploy.

For a flake in another directory, pass its path explicitly:

❱ kix list clusters --flake ../infrastructure

The path may also be any flake reference accepted by Nix.

List package instances

Section titled “List package instances”

Select a cluster to see its evaluated package instances:

kix-examples/ 
❱ kix list packages --cluster how-to-application
 NAME              VERSION  STATUS                 
 platform-dns      -        import [kube-system]   
 platform-storage  -        import [kube-system]   
 preview           1.0.0    installed [how-to-app] 
 production        1.0.0    installed [how-to-app]

The output identifies each instance by namespace and name, along with its package version. Imports supplied by the cluster flavor also appear in the list, even when they do not render resources managed by Kix.

Use this command when you need to confirm that:

  • An instance was included by the cluster modules.
  • A package has the version you expect.
  • Automatic or flavor-provided instances were added.
  • The namespace and instance names match a later command or dependency.

Inspect the cluster in more detail

Section titled “Inspect the cluster in more detail”

list packages is intentionally compact. Use inspect to see the rendered resource inventory:

kix-examples/ offline capture 
❱ kix inspect how-to-application
Show outputHide output · 40 lines 
Cluster: how-to-application
Total resources: 17

Namespaces (3):
  (cluster-scoped) (5 resources)
  how-to-app (10 resources)
  kube-system (2 resources)

Resource kinds:
 Kind                      Count 
 PackageInstance           4     
 ConfigMap                 3     
 CustomResourceDefinition  2     
 Deployment                2     
 Namespace                 2     
 Service                   2     
 Activation                1     
 Job                       1     

Resources:
  (cluster-scoped):
    Activation/how-to-application-6rhi3wpk9iml
    CustomResourceDefinition/activations.kix.run
    CustomResourceDefinition/packageinstances.kix.run
    Namespace/how-to-app
    Namespace/kube-system
  how-to-app:
    ConfigMap/preview
    ConfigMap/production
    ConfigMap/production-health-script
    Deployment/preview
    Deployment/production
    Job/production-health
    PackageInstance/preview
    PackageInstance/production
    Service/preview
    Service/production
  kube-system:
    PackageInstance/platform-dns
    PackageInstance/platform-storage

Use graph when you need dependency edges. The evaluated cluster view exposes package parts and exported outputs.