Skip to main content
Project variables define typed configuration values that are accessible throughout your templates. Define them once in colin.toml, then reference them anywhere via vars.*. Variables separate configuration from content. Rather than hardcoding values like environment names, dates, or feature flags into your documents, declare them as variables. This makes documents portable across environments and easier to update.

​
Defining Variables

Add variables to the [vars] section of your colin.toml. Variable names must be unique case-insensitively (e.g., apiKey and apikey cannot both exist).

​
Simple Syntax

As a shorthand for variables with defaults, assign values directly. Colin infers the type from the value:
colin.toml
[vars]
environment = "production"
debug = false
max_items = 100
Each value serves as the default, which can be overridden at runtime.

​
Typed Syntax

For more control, use subsections with explicit type declarations:
colin.toml
[vars.report_date]
type = "date"
default = "2024-01-15"

[vars.api_key]
type = "string"
optional = true
FieldDescriptionDefault
typeVariable type (see below)string
defaultDefault valueNone
optionalIf true, returns None when not providedfalse
TOML has no null value, so Colin uses optional = true to indicate a variable can be None. Without a default and without optional = true, a variable is required and Colin will error if it’s not provided.

​
Supported Types

Variable TypePython TypeExample Value
stringstr"production"
boolbooltrue, false
intint42
floatfloat3.14
datedatetime.date"2024-01-15"
timestampdatetime.datetime"2024-01-15T10:30:00"
Date and timestamp types parse ISO 8601 formatted strings.

​
Providing Values

Variables can be set through multiple sources. Colin resolves them in order of precedence:
  1. CLI --var flags (highest priority)
  2. Environment variables (COLIN_VAR_<NAME>)
  3. colin.toml defaults
  4. None if optional
  5. Error if required and not provided

​
CLI Overrides

Pass values at runtime with --var: 
colin run --var environment=staging --var debug=true
Multiple --var flags can be combined. Values are always strings on the CLI; Colin converts them to the declared type.

​
Environment Variables

Set variables through the environment using the COLIN_VAR_ prefix: 
export COLIN_VAR_API_KEY=sk-1234
export COLIN_VAR_DEBUG=true
colin run
Variable names are uppercased when looking up environment variables. A variable named api_key reads from COLIN_VAR_API_KEY.

​
Using Variables

Access variables in any template through the vars namespace:
models/report.md
# {{ vars.environment | title }} Status Report

Generated: {{ vars.report_date.strftime('%B %d, %Y') }}

{% if vars.debug %}
Debug mode is enabled. Max items: {{ vars.max_items }}
{% endif %}

​
Working with Types

Date and timestamp variables return Python objects, so you can call their methods directly: 
Report date: {{ vars.report_date.strftime('%B %d, %Y') }}
Build time: {{ vars.build_timestamp.isoformat() }}

​
Optional Variables

Optional variables return None when not provided. Use conditionals to handle missing values: 
{% if vars.historical_date %}
Historical analysis for {{ vars.historical_date }}
{% else %}
Current data analysis
{% endif %}

​
Template-Side Defaults

For dynamic defaults like the current date, use Jinja expressions directly in your templates: 
Report date: {{ vars.report_date or now().strftime('%Y-%m-%d') }}
If report_date is provided via CLI or environment variable, that value is used; otherwise, the expression after or provides the fallback.

​
Recompilation

Colin tracks which variables each document uses. When a variable’s value changes on the next compile (via --var or environment), only documents that accessed that variable will recompile. For example, if doc1.md uses vars.environment and doc2.md uses vars.debug, changing --var environment=staging will only recompile doc1.md.