Skip to content

Modules

Jump to bottom
Gubarz edited this page May 19, 2026 · 2 revisions

Modules

Modules let you define a variable once and reuse it across many cheats.

Defining a module

Use export in a <!-- cheat --> block to name a reusable set of variable definitions:

<!-- cheat
export docker_container
var container = docker ps --format "{{.Names}}" --- --header "Container"
-->

A module can export multiple variables:

<!-- cheat
export kube_context
var context   = kubectl config get-contexts -o name --- --header "Context"
var namespace = kubectl --context $context get ns -o name \
    --- --map "cut -d/ -f2" --header "Namespace"
-->

Using a module

Use import to pull all of a module's variables into another cheat:

## Docker: tail logs

```sh title:"Follow container logs"
docker logs -f $container
```
<!-- cheat
import docker_container
-->

The imported $container variable works exactly as if it were defined inline.

Multiple imports

A cheat can import multiple modules:

<!-- cheat
import docker_container
import kube_context
-->

Variables are resolved in import order: all of docker_container's vars first, then kube_context's.

Module location

The export block doesn't need to be attached to a visible cheat. A common pattern is a dedicated modules.md file with export-only blocks:

# Modules

<!-- cheat
export git_branch
var branch = git branch --format="%(refname:short)" --- --header "Branch"
-->

<!-- cheat
export docker_container
var container = docker ps --format "{{.Names}}" --- --header "Container"
-->

These blocks have no heading or code fence, so they don't appear in the picker - they exist purely to be imported.

Nested imports

Modules can import other modules. This lets you compose reusable variable sets from smaller building blocks:

<!-- cheat
export docker_container
var container = docker ps --format "{{.Names}}" --- --header "Container"
-->

<!-- cheat
export kube_context
var context = kubectl config get-contexts -o name --- --header "Context"
-->

<!-- cheat
export kube_full
import kube_context
var namespace = kubectl --context $context get ns -o name \
    --- --map "cut -d/ -f2" --header "Namespace"
-->

A consumer imports the top-level module and gets everything it depends on:

## Kubernetes: get pods

```sh title:"List pods in a namespace"
kubectl get pods -n $namespace --context $context
```
<!-- cheat
import kube_full
-->

import kube_full pulls in kube_context transitively, so both $context and $namespace are available without listing each import.

Rules

  • Module names must be unique across your entire cheats path. Duplicate exports are reported on load and flagged by the Linting.
  • An import that doesn't resolve to any exported module is an error.
  • Modules can import other modules - nested imports resolve transitively.

See also

Clone this wiki locally