module.toml Manifest Reference

The module.toml file is the manifest at the root of every rescile module. It defines the module’s identity, declares the parameters it accepts, specifies the asset and input schemas it expects from the consuming project, and configures data generators that fetch or scaffold data automatically before the graph is built.

When a module is loaded via --module, rescile reads this file first to validate parameters, assets, and inputs before any graph processing begins. It also drives the bootstrap command and dependency resolution via rescile-ce mod.

[module]
name = "my-module"
version = "1.0.0"
description = "A custom module"
rescile_version = ">=0.1.85"

schemas = ["./schemas/infrastructure.schema.json"]

[dependencies.other_module]
url = "https://github.com/rescile/other.git"
resource_aliases = { "old_type" = "new_type" }

[params.env]
description = "Environment variable"
default = "dev"
required = false

[generators.fetch_data]
target_input = "config.json"
command = ["script.sh"]
env = ["TOKEN={{ env.TOKEN }}"]
ttl = "1h"
condition = "on_missing"

[generators.fetch_data.secrets.my_token]
collection = "my-app-secrets"
secret = "API_TOKEN"

[module] — Module Identity

Declares the module’s name, version, human-readable description, and the minimum rescile version it requires. These fields are displayed in the rescile dashboard and used during dependency resolution.

For detailed usage see Using Modules.

[dependencies] — Module Dependencies

Declares other modules this module depends on. Three declaration formats are supported: a simple Git URL string, a detailed { git = "...", tag = "..." } table, or a release archive { url = "...", version = "..." } table. An optional resource_aliases map transparently remaps resource type names from the imported module to avoid naming conflicts in the global graph.

Dependencies are resolved recursively. Use rescile-ce mod lock to pin them to exact commits for reproducible builds.

For the full reference including lockfile commands see Module Dependencies & Lockfiles.

[params] — Module Parameters

Declares the named parameters a module accepts at runtime via --module-params. Each parameter entry can specify a description, a default value, whether it is required, and an allowed_values list for validation. Declared parameters are made available as global Tera variables in all models/, compliance/, and output/ files of the module.

Parameters are also exposed to action constraint templates as {{ params.<name> }} (for example, hostname:{{ params.runner_hostname }}) and returned in the /api/engine-info endpoint as module_params.

For usage examples see The Data Directory — Parameters Make Modules Reusable.

Schema Declarations

Modules can bind their resources to central schemas. When schemas are bound, the validator checks required properties, relations, capability coverage, and CSV value conformance. See Schema Validation for the full validation behavior.

schemas = [...]

Load one or more schema sources for the whole module:

schemas = ["./schemas/infrastructure.schema.json"]

[[schema]]

Bind a schema to specific resources:

[[schema]]
schema = "./schemas/infrastructure.schema.json"
resources = ["virtual_machine", "network"]

[[implements]], [[requires]], [[offers]]

Declare how the module relates to a published schema:

[[implements]]
schema = "rescile/infrastructure"
version = "20260729"
resources = ["virtual_machine"]

[[offers]]
schema = "rescile/infrastructure"
resource = "virtual_machine"
verb = "provision"
action = "lxd-provision"

Per-asset override

Override the schema used for a single CSV asset:

[assets."virtual_machines.csv"]
schema = "./schemas/custom-vm.schema.json"

[assets] — Asset Import Directives

Deprecation notice: The columns and bootstrap fields inside [assets] are deprecated. Define expectations with central schemas (see Schema Declarations) and ship starter CSV rows in the module’s assets/ directory instead, copying them with rescile-ce bootstrap.

The following fields remain valid import-time directives with no schema equivalent: name_template, match_on, resource_type, schema, extends, and description.

Declares import-time directives and optional per-asset schema overrides for CSV asset files. Each entry can set an explicit resource_type, a name_template that dynamically rewrites the primary key (name property), match_on rules that filter rows before they are imported, a per-asset schema override, a satellite extends marker, and an optional description. The legacy columns validation table and bootstrap string are still parsed but should be replaced by central schemas and module starter files.

For the modern approach see Bootstrapping a Project and Asset Management — Module Asset Configurations.

Shared asset types across modules: if two modules declare column specifications for the same asset file, startup fails with Asset '<file>' has conflicting column specifications ... Please use resource_alias to resolve the conflict. When your module merely references a type owned by another module (e.g. system, team), ship its reference CSV rows without an [assets."<file>"] block and declare expectations via schemas. See Composing Multiple Modules.

[input] — Input Schema & Bootstrap (Deprecated)

Deprecation notice: The [input] and [[inputs]] blocks are deprecated. Place starter JSON input files in the module’s input/ directory and copy them with rescile-ce bootstrap. Central schemas can validate structure when needed.

Declares the JSON input files the module expects in the consuming project’s data/input/ directory. Each entry defines the expected format (currently object_of_objects), optional fields validation, and a legacy bootstrap string.

For the modern approach see Bootstrapping a Project and Input Management.

[generators] — Data Generators

Configures commands that rescile executes automatically to fetch or scaffold asset and input data before the graph is built. Each generator entry specifies a target_input or target_asset, the runner to execute, optional securely mapped secrets from the Vault, env variable mappings, from_stdout capture, a ttl cache duration, and a condition trigger (always, on_missing).

Scripts placed in the module’s generators/ directory are automatically added to PATH during execution. Generators in untrusted modules require explicit approval via --trust-modules in CI environments.

For the complete generator reference including security and validation behaviour see Data Generators.