API Reference

CLI

bumpver

Bump version number for recipe. By default prompts user for update increment (patch/minor/major) and changelog messsage. These can also be specified directly with the -v and -m flags.

Usage: jalapeno bumpver

Examples

# Prompt version increment and changelog message
jalapeno bumpver

# Specify recipe directory
jalapeno bumpver path/to/recipe

# Directly specify version and message
jalapeno bumpver -v v1.0.0 -m "Hello world"

Options

Name	Type	Default	Description
--dir, -d	string	.	Sets working directory
--message, -m	string		Optional changelog message
--no-color	bool	false	If specified, output won't contain any color
--no-input	bool	false	If set to true, the program will exit with an error code if it needs to wait for any user input. This is useful when running the program in CI/CD environment
--version, -v	string		New semver number for recipe

---

check

Check if there are newer versions available for recipes used in the project. By default it checks updates for all recipes, but it is possible to check updates for a specific recipe by using the --recipe flag.

Usage: jalapeno check

Examples

# Check updates for all recipes in the project
jalapeno check

# Check updates for a single recipe
jalapeno check --recipe my-recipe

# Upgrade recipes to the latest version if new versions are found
jalapeno check --upgrade

# Add check URL for recipe which does not have it yet
jalapeno check --recipe my-recipe --from oci://my-registry.com/my-recipe

Options

Name	Type	Default	Description
--ca-file	string		Server certificate authority file for the remote registry
--detailed-exitcode	bool	false	Returns a detailed exit code when the command exits. When provided, this argument changes the exit codes and their meanings to provide more granular information about what the resulting plan contains: 0 = Succeeded with no updates available, 1 = Error, 2 = Succeeded with updates available
--dir, -d	string	.	Sets working directory
--force-upgrade	bool	false	If upgrading, overwrite manual changes in the files with the new versions without prompting
--from	string		Add or override the URL used for checking updates for the recipe. Works only with --recipe flag
--insecure	bool	false	Allow connections to SSL registry without certs
--no-color	bool	false	If specified, output won't contain any color
--no-input	bool	false	If set to true, the program will exit with an error code if it needs to wait for any user input. This is useful when running the program in CI/CD environment
--password, -p	string		Password or personal access token used to log against the Docker registry
--plain-http	bool	false	Allow insecure connections to registry without SSL check
--recipe, -r	string		Name of the recipe to check for new versions
--registry-config	[]string	[]	Path of the authentication file
--timeout	duration	10s	Timeout in seconds for the command to run
--upgrade	bool	false	Upgrade recipes to the latest version if new versions are found
--username, -u	string		Username used to log against the Docker registry

---

create manifest

Usage: jalapeno create manifest

Examples

jalapeno create manifest

Options

Name	Type	Default	Description
--dir, -d	string	.	Sets working directory
--no-color	bool	false	If specified, output won't contain any color
--no-input	bool	false	If set to true, the program will exit with an error code if it needs to wait for any user input. This is useful when running the program in CI/CD environment

---

create recipe

Create a new recipe with the given name.

The following files will be created:

my-recipe
├── recipe.yml
├── templates
│   └── README.md
└── tests
    └── defaults
        ├── test.yml
        └── files
            └── README.md

Usage: jalapeno create recipe RECIPE_NAME

Examples

jalapeno create recipe my-recipe

Options

Name	Type	Default	Description
--dir, -d	string	.	Sets working directory
--no-color	bool	false	If specified, output won't contain any color
--no-input	bool	false	If set to true, the program will exit with an error code if it needs to wait for any user input. This is useful when running the program in CI/CD environment

---

create test

Usage: jalapeno create test

Examples

jalapeno create test

Options

Name	Type	Default	Description
--dir, -d	string	.	Sets working directory
--no-color	bool	false	If specified, output won't contain any color
--no-input	bool	false	If set to true, the program will exit with an error code if it needs to wait for any user input. This is useful when running the program in CI/CD environment

---

delete

Delete sauce(s) from the project. This will remove the rendered files and the sauce entry from sauces.yml.

Usage: jalapeno delete [SAUCE_ID]

Examples

# Delete a specific sauce
jalapeno list
jalapeno delete 21872763-f48e-4728-bc49-57f5898e098a

# Delete all sauces
jalapeno delete --all

Options

Name	Type	Default	Description
--all	bool	false	Delete all sauces from the project
--dir, -d	string	.	Sets working directory
--no-color	bool	false	If specified, output won't contain any color
--no-input	bool	false	If set to true, the program will exit with an error code if it needs to wait for any user input. This is useful when running the program in CI/CD environment

---

execute

Aliases: exec, e, run

Executes (renders) a recipe or manifest and outputs the files to the directory. Recipe URL can be a local path or a remote URL (ex. 'oci://docker.io/my-recipe').

Usage: jalapeno execute RECIPE_URL

Examples

# Execute local recipe
jalapeno execute path/to/recipe

# Execute recipe from OCI repository
jalapeno execute oci://ghcr.io/user/my-recipe:latest

# Execute recipe from OCI repository with inline authentication
jalapeno execute oci://ghcr.io/user/my-recipe:latest --username user --password pass

# Execute recipe from OCI repository with Docker authentication
docker login ghcr.io
jalapeno execute oci://ghcr.io/user/my-recipe:latest

# Execute a manifest which contains multiple recipes
jalapeno execute path/to/manifest.yml

# Execute recipe to different directory
jalapeno execute path/to/recipe --dir other/dir

# Execute recipe in a monorepo
jalapeno execute path/to/recipe --dir monorepo-root --subpath path/in/monorepo

# Set variable values with flags
jalapeno execute path/to/recipe --set MY_VAR=foo --set MY_OTHER_VAR=bar

# Set variable values with environment variables
export JALAPENO_VAR_MY_VAR=foo
jalapeno execute path/to/recipe

Options

Name	Type	Default	Description
--ca-file	string		Server certificate authority file for the remote registry
--delimiter	string	,	Delimiter used when setting table variables
--dir, -d	string	.	Sets working directory
--insecure	bool	false	Allow connections to SSL registry without certs
--no-color	bool	false	If specified, output won't contain any color
--no-input	bool	false	If set to true, the program will exit with an error code if it needs to wait for any user input. This is useful when running the program in CI/CD environment
--password, -p	string		Password or personal access token used to log against the Docker registry
--plain-http	bool	false	Allow insecure connections to registry without SSL check
--registry-config	[]string	[]	Path of the authentication file
--reuse-other-sauce-values, -r	bool	false	By default each sauce has their own set of values even if the variable names are same in both recipes. Setting this to true, values from other sauces will be reused if the variable names match
--set, -s	[]string	[]	Set values to be used in the templates. Example: --set "MY_VAR=foo"
--subpath	string		Subpath which is used as a path prefix when saving and loading the sauce files. Useful for monorepos.
--timeout	duration	10s	Timeout in seconds for the command to run
--username, -u	string		Username used to log against the Docker registry

---

list

List installed sauce(s) in the project.

Usage: jalapeno list

Examples

# List sauces in the project
jalapeno list

Options

Name	Type	Default	Description
--dir, -d	string	.	Sets working directory
--no-color	bool	false	If specified, output won't contain any color
--no-input	bool	false	If set to true, the program will exit with an error code if it needs to wait for any user input. This is useful when running the program in CI/CD environment

---

pull

Pull a recipe from OCI repository and save it locally. You can authenticate by using the --username and --password flags or logging in first with docker login.

Usage: jalapeno pull URL

Examples

# Pull recipe from OCI repository
jalapeno pull ghcr.io/user/recipe:latest

# Pull recipe from OCI repository with inline authentication
jalapeno pull oci://ghcr.io/user/my-recipe:latest --username user --password pass

# Pull recipe from OCI repository with Docker authentication
docker login ghcr.io
jalapeno pull oci://ghcr.io/user/my-recipe:latest

# Pull recipe to different directory
jalapeno pull oci://ghcr.io/user/my-recipe:latest --dir other/dir

Options

Name	Type	Default	Description
--ca-file	string		Server certificate authority file for the remote registry
--dir, -d	string	.	Sets working directory
--insecure	bool	false	Allow connections to SSL registry without certs
--no-color	bool	false	If specified, output won't contain any color
--no-input	bool	false	If set to true, the program will exit with an error code if it needs to wait for any user input. This is useful when running the program in CI/CD environment
--password, -p	string		Password or personal access token used to log against the Docker registry
--plain-http	bool	false	Allow insecure connections to registry without SSL check
--registry-config	[]string	[]	Path of the authentication file
--timeout	duration	10s	Timeout in seconds for the command to run
--username, -u	string		Username used to log against the Docker registry

---

push

Push a recipe to OCI repository (e.g. Docker registry). The version of the recipe will be used as a tag for the image. You can authenticate by using the --username and --password flags or logging in first with docker login.

Usage: jalapeno push RECIPE_PATH TARGET_URL

Examples

# Push recipe to OCI repository
jalapeno push path/to/recipe ghcr.io/user/recipe

# Push recipe to OCI repository with inline authentication
jalapeno push path/to/recipe oci://ghcr.io/user/my-recipe --username user --password pass

# Push recipe to OCI repository with Docker authentication
docker login ghcr.io
jalapeno push path/to/recipe oci://ghcr.io/user/my-recipe

Options

Name	Type	Default	Description
--ca-file	string		Server certificate authority file for the remote registry
--insecure	bool	false	Allow connections to SSL registry without certs
--latest, -l	bool	false	Additionally push the recipe to 'latest' tag
--no-color	bool	false	If specified, output won't contain any color
--no-input	bool	false	If set to true, the program will exit with an error code if it needs to wait for any user input. This is useful when running the program in CI/CD environment
--password, -p	string		Password or personal access token used to log against the Docker registry
--plain-http	bool	false	Allow insecure connections to registry without SSL check
--registry-config	[]string	[]	Path of the authentication file
--timeout	duration	10s	Timeout in seconds for the command to run
--username, -u	string		Username used to log against the Docker registry

---

test

Run tests for the recipe.

Usage: jalapeno test [RECIPE_PATH]

Examples

# Run recipe tests
jalapeno test path/to/recipe

# Bootstrap a new test case
jalapeno test path/to/recipe --create

# Update test file snapshots with the current outputs
jalapeno test path/to/recipe --update-snapshots

Options

Name	Type	Default	Description
--no-color	bool	false	If specified, output won't contain any color
--no-input	bool	false	If set to true, the program will exit with an error code if it needs to wait for any user input. This is useful when running the program in CI/CD environment
--update-snapshots, -u	bool	false	Update test file snapshots

---

upgrade

Upgrade a recipe in a project with a newer version. Recipe URL can be a local path or a remote URL (ex. 'oci://docker.io/my-recipe').

Usage: jalapeno upgrade RECIPE_URL

Examples

# Upgrade recipe with local recipe
jalapeno upgrade path/to/recipe

# Upgrade recipe with remote recipe from OCI repository
jalapeno upgrade oci://ghcr.io/user/my-recipe:v2.0.0

# Upgrade recipe with remote recipe from OCI repository with inline authentication
jalapeno upgrade oci://ghcr.io/user/my-recipe:v2.0.0 --username user --password pass

# Upgrade recipe with remote recipe from OCI repository with Docker authentication
docker login ghcr.io
jalapeno upgrade oci://ghcr.io/user/my-recipe:v2.0.0

# Upgrade recipe to different directory
jalapeno upgrade path/to/recipe --dir other/dir

# Set values for new variables introduced in the upgrade
jalapeno upgrade path/to/recipe --set NEW_VAR=foo

Options

Name	Type	Default	Description
--ca-file	string		Server certificate authority file for the remote registry
--delimiter	string	,	Delimiter used when setting table variables
--dir, -d	string	.	Sets working directory
--force, -f	bool	false	Overwrite manual changes in the files with the new versions without prompting
--insecure	bool	false	Allow connections to SSL registry without certs
--no-color	bool	false	If specified, output won't contain any color
--no-input	bool	false	If set to true, the program will exit with an error code if it needs to wait for any user input. This is useful when running the program in CI/CD environment
--password, -p	string		Password or personal access token used to log against the Docker registry
--plain-http	bool	false	Allow insecure connections to registry without SSL check
--registry-config	[]string	[]	Path of the authentication file
--reuse-old-values	bool	true	Automatically set values for variables which already have a value in the existing sauce
--reuse-other-sauce-values, -r	bool	false	By default each sauce has their own set of values even if the variable names are same in both recipes. Setting this to true, values from other sauces will be reused if the variable names match
--sauce-id	string		If the project contains multiple sauces with the same recipe, specify the ID of the sauce to be upgraded
--set, -s	[]string	[]	Set values to be used in the templates. Example: --set "MY_VAR=foo"
--timeout	duration	10s	Timeout in seconds for the command to run
--username, -u	string		Username used to log against the Docker registry

---

validate

Validate a recipe in a local path.

Usage: jalapeno validate RECIPE_PATH

Examples

jalapeno validate path/to/recipe

Options

Name	Type	Default	Description
--dir, -d	string	.	Sets working directory
--no-color	bool	false	If specified, output won't contain any color
--no-input	bool	false	If set to true, the program will exit with an error code if it needs to wait for any user input. This is useful when running the program in CI/CD environment

---

why

Explains where a file comes from in the project, e.g. is the file create by a recipe or user

Usage: jalapeno why FILEPATH

Examples

jalapeno why path/to/file

Options

Name	Type	Default	Description
--dir, -d	string	.	Sets working directory
--no-color	bool	false	If specified, output won't contain any color
--no-input	bool	false	If set to true, the program will exit with an error code if it needs to wait for any user input. This is useful when running the program in CI/CD environment

---

Recipe schema (recipe.yml)

Source code

Attribute	Type	Default	Description
apiVersion	string	v1	Version of the recipe metadata API schema. Currently should have value "v1".
name	string		Name of the recipe.
version	string		Version of the recipe. Must be valid semver.
description	string		Description of what the recipe does.
source	string		URL to source code for this recipe.
templateExtension	string		File extension of files in "templates" directory which should be templated. Files not matched by this extension will be copied as-is. If left empty (the default), all files will be templated.
initHelp	string		A message which will be shown to an user after a successful recipe execution. Can be used to guide the user on what should be done next in the project directory. Supports templating.
ignorePatterns	[]string		Glob patterns for ignoring generated files from future recipe upgrades. Ignored files will not be regenerated even if their templates change in future versions of the recipe.
vars	[]Variable		An array of variables which can be used in templates. The user will be prompted to provide the value for the variable if not set with --set flag.

Variable

Source code

Attribute	Type	Default	Description
name	string		The name of the variable. It is also used as an unique identifier, so two variables cannot have the same name.
description	string		Description of the variable. Will be shown to the user when "show help" is activated.
default	string		Default value of the variable.
confirm	bool	false	If set to true, the prompt will be a yes/no question, and the value type will be boolean.
optional	bool	false	If set to true, the variable can be left empty.
options	[]string		The user selects the value from a list of options.
multi	bool	false	If set to true, the user can select multiple options defined by the options property.
validators	[]Validator		Validators for the variable.
if	string		Makes the variable conditional based on the result of the expression. The result of the evaluation needs to be a boolean value. Uses https://github.com/expr-lang/expr.
columns	[]string		Set the variable as a table type with columns defined by this property.

Validator

Source code

Attribute	Type	Default	Description
pattern	string		Regular expression pattern to match the input against.
help	string		If the regular expression validation fails, this help message will be shown to the user.
column	string		Apply the validator to a column if the variable type is table.
unique	bool		When targeting table columns, set this to true to make sure that the values in the column are unique.

Test schema (test.yml)

Source code

Attribute	Type	Default	Description
values	map[string]any		Values to use to render the recipe templates. Map key is the name of the variable and value is the variable value.
expectedInitHelp	string		Expected initHelp of the recipe when rendered with the values specified in the test.
ignoreExtraFiles	bool		If true, the test will pass even though templates generated more files than the test specifies. This is useful when creating specific test cases for large recipes.

Sauce schema (sauces.yml)

Source code

Attribute	Type	Default	Description
apiVersion	string	v1	Version of the sauce API schema. Currently should have value "v1".
recipe	Recipe		The recipe which was used to render the sauce.
values	map[string]any		Values which were used to execute the recipe.
files	map[string]File		Files generated by the recipe.
id	string		Random unique ID whose value is determined on first render and stays the same on subsequent re-renders (upgrades) of the sauce. Can be used for example as a seed for template random functions to provide the same result on each template.
from	string		Defines the repository where updates should be checked for the recipe.
subpath	string		Subpath which is used as a path prefix when saving and loading the sauce files. This is commonly used in monorepos.

Manifest schema (manifest.yml)

Source code

Attribute	Type	Default	Description
apiVersion	string	v1	Version of the manifest API schema. Currently should have value "v1".
recipes	[]ManifestRecipe		Recipes to execute when the manifest is applied.

Manifest recipe

Source code

Attribute	Type	Default	Description
name	string		The name of the recipe.
version	string		The version of the recipe.
repository	string		The repository where the recipe is located. Can be a local path or remote URL.
values	map[string]any		Values which were used to execute the recipe.