Timoni

https://github.com/stefanprodan/timoni
Admin
Timoni is a package manager for Kubernetes, powered by CUE and inspired by Helm, designed to improve...
Tokens:100,644
Snippets:847
Trust Score:9.7
License:Apache-2.0
Update:1 week ago
Show doc for...
Tokens:
Raw
### Setup Timoni and run version

Source: https://github.com/stefanprodan/timoni/blob/main/docs/github-actions.mdx

Add these steps to a GitHub workflow to install Timoni and run the CLI. The action installs the release matching the ref used to reference it; pinning to a release tag or commit SHA installs that release, while referencing a branch installs the latest stable release.

```yaml
steps:
  - name: Setup Timoni
    uses: stefanprodan/timoni/actions/setup@v{{TIMONI_VERSION}}
  - name: Run Timoni
    run: timoni version
```

--------------------------------

### Install Timoni from source

Source: https://github.com/stefanprodan/timoni/blob/main/docs/install.mdx

Build and install Timoni from source using Go 1.27 or later.

```shell
go install github.com/stefanprodan/timoni/cmd/timoni@latest
```

--------------------------------

### Install or upgrade an instance

Source: https://github.com/stefanprodan/timoni/blob/main/skills/timoni/SKILL.md

Applies a module to install or upgrade an instance. Use -n for namespace, -v for version, and -f for values file.

```shell
timoni -n <ns> apply <name> oci://<repo> -v <version> -f values.cue
```

--------------------------------

### Use the version output

Source: https://github.com/stefanprodan/timoni/blob/main/docs/github-actions.mdx

Example of using the action's `version` output to print the installed Timoni version. The action must be given an `id` to reference its outputs.

```yaml
steps:
  - name: Setup Timoni
    id: timoni
    uses: stefanprodan/timoni/actions/setup@v{{TIMONI_VERSION}}
  - name: Print the installed version
    run: echo "Timoni ${{ steps.timoni.outputs.version }}"
```

--------------------------------

### Install Timoni with Scoop

Source: https://github.com/stefanprodan/timoni/blob/main/docs/install.mdx

Install the latest release on Windows using Scoop. The cue dependency will be installed if necessary.

```shell
scoop install timoni
```

--------------------------------

### Install Timoni with zypper

Source: https://github.com/stefanprodan/timoni/blob/main/docs/install.mdx

Install the latest release on openSUSE using zypper. Separate commands are provided to set up shell autocompletion for Bash, Fish, and Zsh.

```shell
zypper install timoni
```

```shell
zypper install timoni-bash-completion
zypper install timoni-fish-completion
zypper install timoni-zsh-completion
```

--------------------------------

### Create values.cue file

Source: https://github.com/stefanprodan/timoni/blob/main/cmd/timoni/testdata/module/README.md

Example values file to override default configuration. Create this file as my-values.cue and apply it with the --values flag.

```cue
values: {
    team: "timoni"
    metadata: labels: testing: "true"
    domain: "example.com"
    ns: enabled: true
}
```

--------------------------------

### Install CUE CLI with Homebrew

Source: https://github.com/stefanprodan/timoni/blob/main/docs/cue/walkthrough.mdx

Install the CUE CLI using Homebrew. The CUE CLI is used in this guide for evaluating and validating standalone CUE expressions, though Timoni embeds the CUE engine and formatter.

```bash
brew install cue
```

--------------------------------

### Default Flux installation bundle (CUE)

Source: https://github.com/stefanprodan/timoni/blob/main/docs/flux-aio.mdx

Defines a Bundle file for installing Flux with default settings, enabling helm, kustomize, and notification controllers. Apply with `timoni bundle apply -f flux-aio.cue`.

```cue
bundle: {
    apiVersion: "v1alpha1"
    name:       "flux-aio"
    instances: {
        "flux": {
            module: url: "oci://ghcr.io/stefanprodan/modules/flux-aio"
            namespace: "flux-system"
            values: {
                controllers: {
                    helm: enabled:         true
                    kustomize: enabled:    true
                    notification: enabled: true
                }
                hostNetwork:     false
                securityProfile: "privileged"
            }
        }
    }
}
```

```shell
timoni bundle apply -f flux-aio.cue
```

--------------------------------

### Minimal Bundle example

Source: https://github.com/stefanprodan/timoni/blob/main/docs/bundle.mdx

Shows a minimal Bundle with apiVersion v1alpha1, name podinfo, and one instance. The instance specifies the module URL and namespace.

```cue
bundle: {
	apiVersion: "v1alpha1"
	name:       "podinfo"
	instances: {
		podinfo: {
			module: url: "oci://ghcr.io/stefanprodan/modules/podinfo"
			namespace: "podinfo"
		}
	}
}
```

--------------------------------

### Runtime example with clusters in CUE

Source: https://github.com/stefanprodan/timoni/blob/main/docs/bundle-runtime.mdx

Example Runtime definition with three clusters grouped into staging and production environments. The cluster names and groups can be mapped to Bundle fields using @timoni() attributes.

```cue
runtime: {
	apiVersion: "v1alpha1"
	name:       "fleet"
	clusters: {
		"preview-us-1": {
			group:       "staging"
			kubeContext: "eks-us-west-2"
		}
		"prod-us-1": {
			group:       "production"
			kubeContext: "eks-us-west-1"
		}
		"prod-eu-1": {
			group:       "production"
			kubeContext: "eks-eu-west-1"
		}
	}
}
```

--------------------------------

### Create custom values file (my-values.cue)

Source: https://github.com/stefanprodan/timoni/blob/main/blueprints/starter/README.md

Example values.cue file to customize the blueprint instance, setting CPU and memory resource requests.

```cue
values: {
	resources: requests: {
		cpu:    "100m"
		memory: "128Mi"
	}
}
```

--------------------------------

### Install Timoni with arkade

Source: https://github.com/stefanprodan/timoni/blob/main/docs/install.mdx

Install the latest release on Windows, macOS, or Linux using arkade.

```shell
arkade get timoni
```

--------------------------------

### service.cue example

Source: https://github.com/stefanprodan/timoni/blob/main/docs/cue/walkthrough.mdx

Defines an nginx Service using the #Service schema. This example is used to demonstrate validation; modifying the port or name to invalid values triggers errors.

```cue
package main

// Set the schema
nginxSvc: #Service

nginxSvc: {
    metadata: name: "nginx"
    spec: {
        selector: "app.kubernetes.io/name": "nginx"
        ports: [{
            name:       "http"
            port:       80
            targetPort: "http"
        }]
    }
}
```

--------------------------------

### Apply blueprint with default values

Source: https://github.com/stefanprodan/timoni/blob/main/blueprints/starter/README.md

Installs the blueprint module using timoni with default configuration. Replace <container-registry-url> with the actual registry URL.

```shell
timoni -n default apply blueprint oci://<container-registry-url>
```

--------------------------------

### Install Timoni with Nix

Source: https://github.com/stefanprodan/timoni/blob/main/docs/install.mdx

Install Timoni using nix-env or with Flakes. The Nix package sets up shell autocompletion for Bash, Fish, and Zsh.

```shell
nix-env -i timoni
```

```shell
nix profile install nixpkgs#timoni
```

--------------------------------

### Install Timoni with yay (AUR)

Source: https://github.com/stefanprodan/timoni/blob/main/docs/install.mdx

Install the latest release on Arch Linux using yay or another AUR helper. Use timoni-bin to install the upstream binaries.

```shell
yay -S timoni
```

```shell
yay -S timoni-bin
```

--------------------------------

### Install Flux helm-controller with flux-aio bundle

Source: https://github.com/stefanprodan/timoni/blob/main/docs/flux-helm-interop.mdx

Defines a Timoni bundle that installs the flux-aio module with the helm controller enabled and kustomize and notification controllers disabled. Apply with 'timoni bundle apply -f flux-aio.cue'.

```cue
bundle: {
    apiVersion: "v1alpha1"
    name:       "flux-aio"
    instances: {
        "flux": {
            module: url: "oci://ghcr.io/stefanprodan/modules/flux-aio"
            namespace: "flux-system"
            values: {
                controllers: {
                    helm: enabled:         true
                    kustomize: enabled:    false
                    notification: enabled: false
                }
                hostNetwork:     false
                securityProfile: "privileged"
            }
        }
    }
}
```

```shell
timoni bundle apply -f flux-aio.cue
```

--------------------------------

### Install Timoni with Homebrew

Source: https://github.com/stefanprodan/timoni/blob/main/docs/quickstart.mdx

Use this command to install Timoni on macOS via Homebrew. Requires a system with writable /tmp.

```shell
brew install timoni
```

--------------------------------

### Install Timoni with Homebrew

Source: https://github.com/stefanprodan/timoni/blob/main/docs/install.mdx

Install Timoni on macOS or Linux using the Homebrew formula. The formula sets up shell autocompletion for Bash, Fish, and Zsh.

```shell
brew install timoni
```

```shell
brew install stefanprodan/tap/timoni
```

--------------------------------

### Example repo structure for local modules

Source: https://github.com/stefanprodan/timoni/blob/main/docs/bundle.mdx

Shows a typical repository layout with `modules` and `bundles` directories, used when referencing local modules from a bundle file.

```shell
├── modules
│   ├── app1
│   └── app2
└── bundles
    └── apps-test.cue

```

--------------------------------

### Install Timoni with mise

Source: https://github.com/stefanprodan/timoni/blob/main/docs/install.mdx

Install the latest release on macOS, Linux, or Windows using mise. Note that shell autocompletion must be configured manually.

```shell
mise use timoni
```

--------------------------------

### Apply podinfo module with timoni apply

Source: https://github.com/stefanprodan/timoni/blob/main/docs/quickstart.mdx

Installs the latest stable version of podinfo in the 'test' namespace. The command pulls the module from the container registry, creates resources, and waits for readiness.

```shell
timoni -n test apply podinfo oci://ghcr.io/stefanprodan/modules/podinfo
```

```text
pulling oci://ghcr.io/stefanprodan/modules/podinfo:latest
using module timoni.sh/podinfo version 6.14.0
installing podinfo in namespace test
Namespace/test created
ServiceAccount/test/podinfo created
Service/test/podinfo created
Deployment/test/podinfo created
waiting for 3 resource(s) to become ready...
all resources are ready
```

--------------------------------

### Timoni instance management commands

Source: https://github.com/stefanprodan/timoni/blob/main/docs/concepts.mdx

Commands for installing, upgrading, uninstalling, listing, inspecting, and checking the status of module instances. The install and upgrade commands are aliases of timoni apply.

```shell
timoni install <name> oci://<module-url> -v <semver> -n <namespace>
```

```shell
timoni upgrade <name> oci://<module-url> -v <semver> -f <path/to/values.cue>
```

```shell
timoni uninstall <name> -n <namespace>
```

```shell
timoni list -n <namespace>
```

```shell
timoni inspect [module|values|resources] <name> -n <namespace>
```

```shell
timoni status <name> -n <namespace>
```

--------------------------------

### Install Timoni skills with gh CLI

Source: https://github.com/stefanprodan/timoni/blob/main/docs/ai-agents.mdx

Retrieves the skills from the Timoni GitHub repository. Requires the `gh` CLI to be authenticated.

```shell
gh skill install stefanprodan/timoni
```

--------------------------------

### Example Kubernetes Deployment output from timoni build

Source: https://github.com/stefanprodan/timoni/blob/main/docs/cue/module/initialization.mdx

Shows the generated Deployment metadata from the build command. The labels app.kubernetes.io/managed-by, name, and version are set by Timoni.

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app.kubernetes.io/managed-by: timoni
    app.kubernetes.io/name: nginx
    app.kubernetes.io/version: 0.0.0-devel
  name: nginx
  namespace: test
```

--------------------------------

### Render docs locally with make docs-preview

Source: https://github.com/stefanprodan/timoni/blob/main/CONTRIBUTING.md

Generates the CLI reference, copies agent skills, validates the site, and starts a local preview. Requires Node.js 18+. The site is served at http://localhost:3000 by default.

```shell
make docs-preview
```

--------------------------------

### Install Timoni skills with the skills CLI

Source: https://github.com/stefanprodan/timoni/blob/main/docs/ai-agents.mdx

Installs the Timoni agent skills for supported agents (Claude Code, Cursor, Codex, Copilot and others). The command discovers the skills from the Timoni website and places them in the agent's skills directory.

```shell
npx skills add https://timoni.sh
```

--------------------------------

### Install or upgrade bundle with timoni bundle apply

Source: https://github.com/stefanprodan/timoni/blob/main/docs/bundle.mdx

Applies the instances defined in a bundle file. Pulls module versions, merges values, applies resources, and updates inventory. Use --validate=false to disable CRD validation.

```shell
timoni bundle apply -f bundle.cue
```

--------------------------------

### Install Timoni AI Agent Skills and Connect MCP Server

Source: https://github.com/stefanprodan/timoni/blob/main/README.md

These commands set up AI agent integration: install Timoni agent skills and connect the docs MCP server for Claude. Run them to enable agents to operate Timoni end-to-end.

```shell
npx skills add https://timoni.sh # Install the skills for your agent
claude mcp add --transport http timoni-docs https://timoni.sh/mcp # Connect the docs MCP server

```

--------------------------------

### Bundle with two instances for export

Source: https://github.com/stefanprodan/timoni/blob/main/docs/bundle.mdx

Defines a bundle with two instances (`frontend` and `backend`) using the same podinfo module. This is used as an example for `timoni bundle build --output-dir`.

```cue
bundle: {
	apiVersion: "v1alpha1"
	name:       "podinfo"
	instances: {
		frontend: {
			module: url: "oci://ghcr.io/stefanprodan/modules/podinfo"
			namespace: "frontend"
		}
		backend: {
			module: url: "oci://ghcr.io/stefanprodan/modules/podinfo"
			namespace: "backend"
		}
	}
}

```

--------------------------------

### Build, Apply, Preview, and Delete a Timoni Bundle

Source: https://github.com/stefanprodan/timoni/blob/main/README.md

These commands manage the full lifecycle of a Timoni bundle: optionally render the bundle without applying, preview changes with --diff, apply to install or upgrade, and delete to uninstall. Use the bundle.cue file that defines the deployment.

```shell
timoni bundle build  -f ./bundle.cue # Render without applying (optional)
timoni bundle apply  -f ./bundle.cue --diff # Preview changes before applying
timoni bundle apply  -f ./bundle.cue # Install or upgrade
timoni bundle delete -f ./bundle.cue # Uninstall

```

--------------------------------

### Configure service with service.cue

Source: https://github.com/stefanprodan/timoni/blob/main/docs/cue/walkthrough.mdx

Sets the #Service schema and provides a concrete nginx service configuration, specifying metadata name/namespace and spec type, selector, and ports. This example is used to demonstrate optional field validation.

```cue
package main

// Set the schema
nginxSvc: #Service

nginxSvc: {
    metadata: {
        name:      "nginx"
        namespace: "default"
    }
    spec: {
        type: "ClusterIP"
        selector: "app.kubernetes.io/name": "nginx"
        ports: [{
            name: "http"
            port: 80
        }]
    }
}
```

--------------------------------

### Output directory tree from bundle build

Source: https://github.com/stefanprodan/timoni/blob/main/docs/bundle.mdx

Shows the directory structure generated by `timoni bundle build --output-dir`. Each instance gets a subdirectory, and each resource is a file named `<group>_<version>_<kind>_<name>.yaml`.

```text
manifests
├── backend
│   ├── apps_v1_deployment_backend.yaml
│   ├── v1_service_backend.yaml
│   └── v1_serviceaccount_backend.yaml
└── frontend
    ├── apps_v1_deployment_frontend.yaml
    ├── v1_service_frontend.yaml
    └── v1_serviceaccount_frontend.yaml

```

--------------------------------

### Apply a Timoni bundle with --runtime-from-env

Source: https://github.com/stefanprodan/timoni/blob/main/skills/timoni/SKILL.md

Runs 'timoni bundle apply' with --runtime-from-env, which sources variables from the process environment instead of a cluster. No -r runtime file is needed. The example sets REDIS_PASS from the environment variable $SECRET.

```shell
REDIS_PASS=$SECRET timoni bundle apply -f bundle.cue --runtime-from-env
```

--------------------------------

### Timoni entry point with instance and apply

Source: https://github.com/stefanprodan/timoni/blob/main/docs/cue/module/initialization.mdx

The timoni.cue entry point injects instance name, namespace, and user config, then applies the generated objects.

```cue
timoni: {
	instance: templates.#Instance & {
		config: values
		config: metadata: {
			name:      string @tag(name)
			namespace: string @tag(namespace)
		}
	}

	apply: app: [for obj in instance.objects {obj}]
}

```

--------------------------------

### Create a module

Source: https://github.com/stefanprodan/timoni/blob/main/skills/timoni/SKILL.md

Initializes a new module using the starter blueprint.

```shell
timoni mod init <name> --blueprint oci://ghcr.io/stefanprodan/timoni/blueprints/starter
```

--------------------------------

### Apply bundle to all clusters

Source: https://github.com/stefanprodan/timoni/blob/main/docs/bundle-multi-cluster.mdx

Installs or upgrades the instances defined in the bundle to all clusters in the order defined in the runtime. If the apply fails on a staging cluster, Timoni stops execution and does not continue with production.

```shell
timoni bundle apply -f bundle.cue -r runtime.cue
```

```text
b:apps > c:preview-eu-1 > applying 1 instance(s) on staging
b:apps > c:preview-eu-1 > i:podinfo > applying module timoni.sh/podinfo version 6.14.1
b:apps > c:preview-eu-1 > i:podinfo > installing podinfo in namespace apps
b:apps > c:preview-eu-1 > i:podinfo > Namespace/apps created
b:apps > c:preview-eu-1 > i:podinfo > applying app
b:apps > c:preview-eu-1 > i:podinfo > ServiceAccount/apps/podinfo created
b:apps > c:preview-eu-1 > i:podinfo > Service/apps/podinfo created
b:apps > c:preview-eu-1 > i:podinfo > Deployment/apps/podinfo created
b:apps > c:preview-eu-1 > i:podinfo > app resources ready
b:apps > c:preview-eu-1 > i:podinfo > applying test
b:apps > c:preview-eu-1 > i:podinfo > Job/apps/podinfo-test created
b:apps > c:preview-eu-1 > i:podinfo > test resources ready
b:apps > c:preview-eu-1 > applied successfully in 22s
b:apps > c:prod-eu-1 > applying 1 instance(s) on production
b:apps > c:prod-eu-1 > i:podinfo > applying module timoni.sh/podinfo version 6.14.1
b:apps > c:prod-eu-1 > i:podinfo > installing podinfo in namespace apps
b:apps > c:prod-eu-1 > i:podinfo > Namespace/apps created
b:apps > c:prod-eu-1 > i:podinfo > applying app
b:apps > c:prod-eu-1 > i:podinfo > ServiceAccount/apps/podinfo created
b:apps > c:prod-eu-1 > i:podinfo > Service/apps/podinfo created
b:apps > c:prod-eu-1 > i:podinfo > Deployment/apps/podinfo created
b:apps > c:prod-eu-1 > i:podinfo > app resources ready
b:apps > c:prod-eu-1 > i:podinfo > applying test
b:apps > c:prod-eu-1 > i:podinfo > Job/apps/podinfo-test created
b:apps > c:prod-eu-1 > i:podinfo > test resources ready
b:apps > c:prod-eu-1 > applied successfully in 44s
```

--------------------------------

### Example of a module's OCI manifest

Source: https://github.com/stefanprodan/timoni/blob/main/docs/module.mdx

Shows the JSON structure of a Timoni module OCI manifest, including the config, layers, and annotations. The manifest includes the module version in the tag and metadata in annotations.

```json
{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "config": {
    "mediaType": "application/vnd.timoni.config.v1+json",
    "size": 342,
    "digest": "sha256:62b6006cf2a56d7cfc8287164b25e47d9bc17b282aeb0701535897960ee13cbf"
  },
  "layers": [
    {
      "mediaType": "application/vnd.timoni.content.v1.tar+gzip",
      "size": 121873,
      "digest": "sha256:fff54591c495da1b19c647da5946c2e93c309e1389b3ac1a17ed293f2bb539fc",
      "annotations": {
        "sh.timoni.content.type": "module/vendor"
      }
    },
    {
      "mediaType": "application/vnd.timoni.content.v1.tar+gzip",
      "size": 7837,
      "digest": "sha256:e6af46874ac539bb63ac6ccf269bbc520c1e6ce5bc7180934cfa17b8cfc5a1b1",
      "annotations": {
        "sh.timoni.content.type": "module"
      }
    }
  ],
  "annotations": {
    "org.opencontainers.image.created": "2023-12-30T22:19:40Z",
    "org.opencontainers.image.description": "Get started blueprint for timoni.sh modules.",
    "org.opencontainers.image.documentation": "https://timoni.sh",
    "org.opencontainers.image.licenses": "Apache-2.0",
    "org.opencontainers.image.revision": "7a0566468fa4d49e3be269ad16f447c06e47de63",
    "org.opencontainers.image.source": "https://github.com/stefanprodan/timoni",
    "org.opencontainers.image.version": "0.19.0-rc.1",
    "sh.timoni.images": "docker.io/nginxinc/nginx-unprivileged:1-alpine@sha256:c3fed6436b61d2bf2201ec032c35c000871f7ed062dea5d586bc6bf4d0fdd140"
  }
}
```

--------------------------------

### Build bundle and grep redis URL

Source: https://github.com/stefanprodan/timoni/blob/main/docs/bundle-secrets.mdx

Shows how to set environment variables and build the bundle, then grep for the redis URL in the output.

```console
$ export REDIS_HOST=redis.svc
$ export REDIS_PASS=testpass
$ timoni bundle build -f bundle.cue --runtime-from-env | grep redis
        - --cache-server=tcp://:testpass@redis.svc:6379
```

--------------------------------

### Initialize a module with timoni mod init

Source: https://github.com/stefanprodan/timoni/blob/main/docs/cue/module/initialization.mdx

Run this command in the current directory to create a new module named 'myapp' using the starter blueprint. The blueprint creates a simple module that deploys an NGINX web server.

```shell
timoni mod init myapp \
--blueprint oci://ghcr.io/stefanprodan/timoni/blueprints/starter
```

--------------------------------

### Single cluster workflow: build, up, push, deploy

Source: https://github.com/stefanprodan/timoni/blob/main/test/README.md

Build the Timoni binary, create a cluster named 'timoni' with the local registry, push the blueprint module, and deploy the bundle. Run from the test directory.

```shell
make build
cd test
make up
make push
make deploy
```

--------------------------------

### Run the test suite with make

Source: https://github.com/stefanprodan/timoni/blob/main/CONTRIBUTING.md

Run the full test suite. Requires go >= 1.24, cue >= 0.13, and make >= 4.4.

```shell
make
```

--------------------------------

### List bundle instances with timoni list --bundle

Source: https://github.com/stefanprodan/timoni/blob/main/docs/bundle.mdx

Run `timoni list --bundle podinfo -A` to list all instances in the bundle named `podinfo` across all namespaces. The output shows the instance name, namespace, module OCI reference, version, last applied time, and bundle name.

```sh
timoni list --bundle podinfo -A
```

```text
NAME    NAMESPACE         MODULE                                          VERSION LAST APPLIED          BUNDLE
podinfo podinfo           oci://ghcr.io/stefanprodan/modules/podinfo      6.14.0   2024-03-03T16:20:07Z  podinfo
redis   podinfo           oci://ghcr.io/stefanprodan/modules/redis        8.10.1   2024-03-03T16:20:00Z  podinfo
```

--------------------------------

### Define #Instance with objects list

Source: https://github.com/stefanprodan/timoni/blob/main/docs/cue/module/initialization.mdx

The #Instance definition takes a #Config object and returns a list of objects containing #Deployment and #Service types.

```cue
#Instance: {
	config: #Config

	objects: {
		deploy: #Deployment & {#config: config}
		service: #Service & {#config: config}
	}
}

```

--------------------------------

### Zsh: Install completion script into fpath directory

Source: https://github.com/stefanprodan/timoni/blob/main/docs/install.mdx

Alternatively, install the completion script into one of the directories in your ${fpath}. The commands show how to find the directories and move the script for oh-my-zsh or zprezto.

```shell
echo "${fpath// /\n}" | grep -i completion
timoni completion zsh > _timoni

mv _timoni ~/.oh-my-zsh/completions  # oh-my-zsh
mv _timoni ~/.zprezto/modules/completion/external/src/  # zprezto
```

--------------------------------

### Typical module layout from starter blueprint

Source: https://github.com/stefanprodan/timoni/blob/main/skills/timoni/SKILL.md

Shows the conventional directory structure for a Timoni module, including cue.mod, templates, images.cue, timoni.cue, and other files. This layout is a convention, not a contract.

```text
myapp/
├── cue.mod/
│   ├── gen/           # vendored Kubernetes API and CRD schemas
│   ├── pkg/           # timoni.sh/core/v1alpha1 schemas
│   └── module.cue     # module: "timoni.sh/myapp"
├── templates/
│   ├── config.cue     # #Config schema with defaults, #Instance
│   ├── deployment.cue # #Deployment: {#config: #Config, ...}
│   └── service.cue
├── images.cue         # container images defaults (repository, tag, digest)
├── timoni.cue         # entry point: values, timoni.instance, timoni.apply
├── timoni.ignore      # files excluded from mod push
├── values.cue         # placeholder for user values
├── README.md
└── LICENSE
```

--------------------------------

### Apply podinfo module with values file using timoni apply

Source: https://github.com/stefanprodan/timoni/blob/main/docs/quickstart.mdx

Runs timoni apply to upgrade the podinfo instance in the test namespace using the qos-values.cue file. The output shows the upgrade process and resource status.

```shell
timoni -n test apply podinfo oci://ghcr.io/stefanprodan/modules/podinfo \
  --values qos-values.cue
```

```text
pulling oci://ghcr.io/stefanprodan/modules/podinfo:latest
using module timoni.sh/podinfo version 6.14.1
upgrading podinfo in namespace test
ServiceAccount/test/podinfo unchanged
Service/test/podinfo unchanged
Deployment/test/podinfo configured
resources are ready
```

--------------------------------

### Run manual tests with locally built binary

Source: https://github.com/stefanprodan/timoni/blob/main/CONTRIBUTING.md

Run manual tests using the locally built Timoni binary. Replace <command> with the desired subcommand.

```shell
./bin/timoni <command>
```

--------------------------------

### Bare metal Flux installation with Cilium (CUE)

Source: https://github.com/stefanprodan/timoni/blob/main/docs/flux-aio.mdx

Installs Flux on a bare metal cluster with `hostNetwork: true` and deploys the latest Cilium CNI via the flux-helm-release module. Note the host network ports and the need for KUBERNETES_SERVICE_HOST/PORT env vars on clusters without kube-proxy.

```cue
bundle: {
    apiVersion: "v1alpha1"
    name:       "flux-aio"
    instances: {
        "flux": {
            module: url: "oci://ghcr.io/stefanprodan/modules/flux-aio"
            namespace: "flux-system"
            values: {
                hostNetwork:     true
                securityProfile: "privileged"
            }
        }
        "cilium": {
            module: url: "oci://ghcr.io/stefanprodan/modules/flux-helm-release"
            namespace: "flux-system"
            values: {
                repository: url: "https://helm.cilium.io"
                chart: {
                    name:    "cilium"
                    version: "*"
                }
                helmValues: {
                    operator: replicas: 1
                    ipam: mode:         "kubernetes"
                }
                sync: targetNamespace: "kube-system"
            }
        }
    }
}
```

```cue
values: env: {
    "KUBERNETES_SERVICE_HOST": "<host>"
    "KUBERNETES_SERVICE_PORT": "<port>"
}
```

--------------------------------

### Get bundle status

Source: https://github.com/stefanprodan/timoni/blob/main/skills/timoni/SKILL.md

Shows the status of a bundle, either from a file or by name.

```shell
timoni bundle status -f bundle.cue
```

```shell
timoni bundle status <name>
```

--------------------------------

### Fleet workflow: build, fleet-up, push, fleet-deploy

Source: https://github.com/stefanprodan/timoni/blob/main/test/README.md

Create the 'timoni-staging' and 'timoni-production' clusters with the local registry, push the blueprint module, and deploy the bundle to both clusters using the runtime definition.

```shell
make build
cd test
make fleet-up
make push
make fleet-deploy
```

--------------------------------

### Cloud Flux installation with AWS IRSA and persistence (CUE)

Source: https://github.com/stefanprodan/timoni/blob/main/docs/flux-aio.mdx

Installs Flux on a managed Kubernetes cluster (e.g., EKS) with host network disabled, persistent storage for the artifacts cache, and AWS Workload Identity for ECR access. For Azure, set provider to `azure` and identity to the Azure Client ID; for GCP, set provider to `gcp` and identity to the GCP Identity Name.

```cue
bundle: {
    apiVersion: "v1alpha1"
    name:       "flux-aio"
    instances: {
        "flux": {
            module: url: "oci://ghcr.io/stefanprodan/modules/flux-aio"
            namespace: "flux-system"
            values: {
                hostNetwork:     false
                securityProfile: "privileged"
                workload: {
                    identity: "arn:aws:iam::111122223333:role/my-role"
                    provider: "aws"
                }
                persistence: {
                    enabled:      true
                    storageClass: "standard"
                    size:         "8Gi"
                }
            }
        }
    }
}
```

--------------------------------

### Example of sh.timoni.images annotation value

Source: https://github.com/stefanprodan/timoni/blob/main/docs/module.mdx

Shows the format of the sh.timoni.images annotation when multiple images are present: comma-separated and sorted alphabetically.

```text
docker.io/curlimages/curl:8.21.0@sha256:7c12...,docker.io/nginx:1.31.4-alpine@sha256:db35...
```

--------------------------------

### Build module and copy to registry with skopeo

Source: https://github.com/stefanprodan/timoni/blob/main/docs/cue/module/publishing.mdx

Builds a module to an OCI archive and copies it to a registry using skopeo. The version is required and becomes the manifest version annotation and local reference name. Use --format=oci-layout for directory output. Local outputs are unsigned; existing output paths are rejected.

```shell
timoni mod build ./modules/my-app -v 1.0.0 -o ./my-app-1.0.0.oci.tar
skopeo copy oci-archive:./my-app-1.0.0.oci.tar docker://ghcr.io/org/modules/app:1.0.0
```

--------------------------------

### Apply bundle with timoni bundle apply

Source: https://github.com/stefanprodan/timoni/blob/main/docs/bundle-distribution.mdx

Deploy an app from a bundle and runtime file using timoni bundle apply, specifying the Kubernetes context.

```shell
timoni bundle apply \
  -f app.bundle.cue \
  --runtime app.runtime.cue \
  --kube-context my-test-cluster
```

--------------------------------

### List instances

Source: https://github.com/stefanprodan/timoni/blob/main/skills/timoni/SKILL.md

Lists all instances across all namespaces.

```shell
timoni list -A
```

--------------------------------

### Apply Redis module with specific version

Source: https://github.com/stefanprodan/timoni/blob/main/examples/redis/README.md

Installs a specific module version (8.10.1) of the Redis module. Use this to pin the module version for reproducibility.

```shell
timoni -n default apply redis oci://ghcr.io/stefanprodan/modules/redis -v 8.10.1
```

--------------------------------

### Custom values.cue for a Timoni instance

Source: https://github.com/stefanprodan/timoni/blob/main/docs/concepts.mdx

Example values.cue that enables ingress, autoscaling, and monitoring for a module instance. These values are merged with the module's defaults.

```cue
values: {
	ingress: {
		enabled:   true
		className: "nginx"
		host:      "app.example.com"
	}
	autoscaling: enabled: true
	monitoring: enabled:  true
}
```

--------------------------------

### Render a bundle to files

Source: https://github.com/stefanprodan/timoni/blob/main/skills/timoni/SKILL.md

Renders the bundle manifests to a directory.

```shell
timoni bundle build -f bundle.cue --output-dir ./manifests
```

--------------------------------

### Verify podinfo module signature with Cosign keyless

Source: https://github.com/stefanprodan/timoni/blob/main/docs/cue/module/signing.mdx

Example verification of the podinfo module using keyless signing. Uses GitHub Actions as the OIDC issuer.

```shell
cosign verify ghcr.io/stefanprodan/modules/podinfo:latest \
  --certificate-identity-regexp="^https://github.com/stefanprodan/podinfo.*$" \
  --certificate-oidc-issuer=https://token.actions.githubusercontent.com
```

--------------------------------

### Apply module with default values

Source: https://github.com/stefanprodan/timoni/blob/main/cmd/timoni/testdata/module/README.md

Creates an instance of the module using default configuration values. Replace the placeholder with the actual container registry URL.

```shell
timoni -n module apply module oci://<container-registry-url>
```

--------------------------------

### Generate Cosign key pair

Source: https://github.com/stefanprodan/timoni/blob/main/docs/cue/module/signing.mdx

Generates a new Cosign key pair (cosign.key and cosign.pub) for signing modules. Requires Cosign v2 binary installed and in PATH.

```shell
cosign generate-key-pair
```

--------------------------------

### Apply bundle with wait and timeout

Source: https://github.com/stefanprodan/timoni/blob/main/docs/bundle.mdx

Applies the bundle with readiness checks enabled and a timeout of 5 minutes. If an instance's resource fails to become ready, the command exits with an error.

```shell
timoni bundle apply --wait --timeout=5m -f bundle.cue
```

--------------------------------

### Generated service.yaml output

Source: https://github.com/stefanprodan/timoni/blob/main/docs/cue/walkthrough.mdx

The YAML output generated from the service.cue example. It shows the resulting Kubernetes Service manifest, and notably omits the `targetPort` field because it is optional and not set.

```yaml
apiVersion: v1
kind: Service
metadata:
  name: nginx
  namespace: default
spec:
  selector:
    app.kubernetes.io/name: nginx
  ports:
    - name: http
      protocol: TCP
      port: 80
```

--------------------------------

### Module structure created by timoni mod init

Source: https://github.com/stefanprodan/timoni/blob/main/docs/cue/module/initialization.mdx

Shows the directory layout created by the init command. The 'myapp' directory contains cue.mod, templates, and various configuration files.

```sh
myapp
├── cue.mod
│   ├── gen # Kubernetes APIs and CRDs schemas
│   ├── pkg # Timoni APIs schemas
│   └── module.cue # Module metadata
├── templates
│   ├── config.cue # Config schema and default values
│   ├── deployment.cue # Kubernetes Deployment template
│   └── service.cue # Kubernetes Service template
├── images.cue # Container images defaults
├── timoni.cue # Timoni entry point
├── timoni.ignore # Timoni ignore rules
├── values.cue # Timoni values placeholder 
├── LICENSE # Module license
└── README.md # Module documentation
```

--------------------------------

### Show the README of a module

Source: https://github.com/stefanprodan/timoni/blob/main/skills/timoni/SKILL.md

Displays the README of a module, either from a registry or a local path.

```shell
timoni mod show readme oci://<repo> -v <version>
```

--------------------------------

### Add custom annotations with timoni mod push

Source: https://github.com/stefanprodan/timoni/blob/main/docs/module.mdx

Command to push a module with custom annotations using the --annotation flag. The example sets license, documentation, and description annotations.

```shell
timoni mod push ./path/to/module oci://docker.io/org/app-module -v 1.0.0 \
  --annotation='org.opencontainers.image.licenses=Apache-2.0' \
  --annotation='org.opencontainers.image.documentation=https://app.org/docs' \
  --annotation='org.opencontainers.image.description=A timoni.sh module for my app.'
```

--------------------------------

### Runtime values for with CUE expression in CUE

Source: https://github.com/stefanprodan/timoni/blob/main/docs/bundle-runtime.mdx

Example of extracting a field using a CUE expression in the for map. The expression iterates over conditions to find the Ready status and extracts the revision from the artifact.

```cue
runtime: {
	apiVersion: "v1alpha1"
	name:       "production"
	values: [
		{
			query: "k8s:source.toolkit.fluxcd.io/v1:GitRepository:flux-system:cluster"
			for: {
				"GIT_REVISION": "obj.status.artifact.revision"
				"GIT_STATUS":   "[for c in obj.status.conditions if c.type == \"Ready\" {c.status}][0]"
			}
		},
	]
}
```

--------------------------------

### List all instances with timoni list -A

Source: https://github.com/stefanprodan/timoni/blob/main/docs/quickstart.mdx

Lists all instances in the cluster. The output shows the instance name, namespace, module OCI URL, version, last applied time, and bundle.

```shell
timoni list -A
```

```text
NAME   	NAMESPACE	MODULE                                    	VERSION	LAST APPLIED        	BUNDLE 
podinfo	test    	oci://ghcr.io/stefanprodan/modules/podinfo	6.14.0 	2024-01-20T19:51:17Z	- 
```

--------------------------------

### Register the MCP server with the Codex CLI

Source: https://github.com/stefanprodan/timoni/blob/main/docs/ai-agents.mdx

Registers the Timoni docs MCP server with the Codex CLI using the `codex mcp add` command. Requires the Codex CLI to be installed and authenticated.

```shell
codex mcp add timoni-docs --url https://timoni.sh/mcp
```

--------------------------------

### Status and readiness of an instance

Source: https://github.com/stefanprodan/timoni/blob/main/skills/timoni/SKILL.md

Shows the status and readiness of an instance.

```shell
timoni -n <ns> status <name>
```

--------------------------------

### Run a single Go test with -run flag

Source: https://github.com/stefanprodan/timoni/blob/main/AGENTS.md

Runs a single test in the cmd/timoni package using the -run flag. This is useful for targeted testing during development. Note that tests in cmd/timoni require envtest to be installed.

```shell
go test ./cmd/timoni/... -run TestApply -v
```

--------------------------------

### Build runtime command and output

Source: https://github.com/stefanprodan/timoni/blob/main/docs/bundle-runtime.mdx

Command to build the runtime from runtime.cue, showing the values present on the cluster. The output displays the resolved values including a certificate.

```sh
timoni runtime build -f runtime.cue
```

```text
ACCOUNT_ID: 1234567890
REGION: us-west-2
REDIS_PASS: password
REDIS_CA:
  -----BEGIN CERTIFICATE-----
  MIIC/jCCAeagAwIBAgIBADANBgkqhkiG9w0BAQsFADAVMRMwEQYDVQQDEwprdWJl
  cm5ldGVzMB4XDTIzMDgxMDE1MTA1MFoXDTMzMDgwNzE1MTA1MFowFTETMBEGA1UE
  AxMKa3ViZXJuZXRlczCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAJgA
  mOniTayGyXG51eYeb1oJGCszRlZv4ci2kzLC0H4YCph6TXDEawrsvyuzGe7fwp4t
  Jq2fQiJgKbibOjHcOwhYqp1lJDu37p6WsLvx/RxbkHoVX8X2n7n1BVS5MbQ81on9
  BdXkff71g8n3HmJo8ZN1abEW434tHFwjjGMDzFoqxTnNM+qMKegxAtTPVbjV4X+5
  4/95L7T0XNd97XnunSUAEJRroMTRuaBAcYz81N0ix3Mc0T+G16aV127R0ZFkPlS8
  bzjA1NGgbiveX7i7n9mNG4Gy7iElP0iidtdrA6loxWYLW1jmEH5/pWQnki7s3OrK
  /94xrQ2MaDpXUzcoc0cCAwEAAaNZMFcwDgYDVR0PAQH/BAQDAgKkMA8GA1UdEwEB
  /wQFMAMBAf8wHQYDVR0OBBYEFJ7f9QzKWA/BQJSRinKne4FZNzScMBUGA1UdEQQO
  MAyCCmt1YmVybmV0ZXMwDQYJKoZIhvcNAQELBQADggEBAAhGgYFB90Rkexgh56q8
  n8uC4XQF6OTJJf/4A9VXNbiZhG+PUYkMUyqeOSOq+IztJVOffuG9ZutYQtJYCX7g
  TUQmZxeKAw1MAMEWAELmNVdbG6Y6YZ14v8SI+TADqeqcIkmDEkACygfeHKdEFOfV
  LoRAc3Zn32byP5M6EVjTXWvb+UbVt7umoBOCbMo3BEF71TEDI5Oww6y3YxDM9/Y7
  MCTu+0XHZNGDgprmci6fzLv8PV0C6eiuUrrBM237WOfk4BYL6pmCDcCWo6aP2cH7
  Y5zcVBxKUs/h5bZfLJFuwXJC5zWudNLOAtNtFhctMwDoNaKYq720g/GmEroq4wgA
  tBI=
  -----END CERTIFICATE-----
```

--------------------------------

### service.cue: Instantiate #HeadlessService for nginx

Source: https://github.com/stefanprodan/timoni/blob/main/docs/cue/walkthrough.mdx

Creates an instance of #HeadlessService named nginxSvc, setting the metadata name and spec selector and ports. The type and clusterIP fields are fixed by the schema and cannot be overridden.

```cue
package main

nginxSvc: #HeadlessService & {
    metadata: name: "nginx"
    spec: {
        selector: "app.kubernetes.io/name": "nginx"
        ports: [{
            name:       "http"
            port:       80
        }]
    }
}

```

--------------------------------

### Bundle using runtime cluster attributes in CUE

Source: https://github.com/stefanprodan/timoni/blob/main/docs/bundle-runtime.mdx

Shows how to map the cluster name and group from a Runtime to Bundle fields using @timoni() attributes. The example uses conditional replicas based on the environment group.

```cue
bundle: {
	_cluster: string @timoni(runtime:string:TIMONI_CLUSTER_NAME)
	_env:     string @timoni(runtime:string:TIMONI_CLUSTER_GROUP)

	apiVersion: "v1alpha1"
	name:       "apps"
	instances: {
		app: {
			module: url: "oci://ghcr.io/stefanprodan/modules/podinfo"
			namespace: "apps"
			values: {
				ui: message: "Hosted by \(_cluster)"
				if _env == "staging" {
					replicas: 1
				}
				if _env == "production" {
					replicas: 2
				}
			}
		}
	}
}
```

--------------------------------

### Build a Timoni bundle

Source: https://github.com/stefanprodan/timoni/blob/main/docs/bundle.mdx

Command to build the bundle and print the resulting Kubernetes resources for all instances. The output shows the YAML for each instance, with deployments omitted for brevity.

```sh
timoni bundle build -f podinfo.bundle.cue
```

```yaml
---
# Instance: redis
---
apiVersion: v1
kind: ServiceAccount
metadata:
  labels:
    app.kubernetes.io/part-of: redis
    app.kubernetes.io/version: 8.10.1
  name: redis
  namespace: podinfo
---
# Redis deployments omitted for brevity
---
# Instance: podinfo
---
apiVersion: v1
kind: ServiceAccount
metadata:
  labels:
    app.kubernetes.io/name: podinfo
    app.kubernetes.io/version: 6.14.0
  name: podinfo
  namespace: podinfo
---
# Podinfo deployment omitted for brevity
```

--------------------------------

### Apply a module instance with timoni apply

Source: https://github.com/stefanprodan/timoni/blob/main/docs/cue/module/initialization.mdx

Creates the module instance on a Kubernetes cluster and waits for the Deployment and Service to become ready. If the namespace does not exist, Timoni creates it.

```shell
timoni -n test apply nginx .
```

--------------------------------

### Preview a bundle

Source: https://github.com/stefanprodan/timoni/blob/main/skills/timoni/SKILL.md

Shows a diff of the bundle changes without applying them.

```shell
timoni bundle apply -f bundle.cue --diff
```

--------------------------------

### Build a generic artifact archive

Source: https://github.com/stefanprodan/timoni/blob/main/skills/timoni/SKILL.md

Builds an OCI archive of a directory without a registry.

```shell
timoni artifact build -f ./dir -t <tag> -o out.oci.tar
```

--------------------------------

### Build bundle to directory

Source: https://github.com/stefanprodan/timoni/blob/main/docs/bundle.mdx

Builds the bundle and writes manifests to a directory using `--output-dir`. The output directory is created if missing, existing files are overwritten, but stale files are not removed.

```shell
timoni bundle build -f podinfo.cue --output-dir ./manifests

```
Tokens:
Raw