Templates & `.env`

How genesis-env uses your committed template and your local secrets file. This page covers generate (including the default genv flow), init, and validate.

Concepts

Concept	File	Role
Template (committed)	`.env.template` or `.env.example`	Lists keys and optional defaults; safe to commit to git.
Local secrets	`.env`	Filled by generate; should stay local and gitignored; init helps add `.env` to `.gitignore`.

If both .env.template and .env.example exist in the project root, .env.template is used.

The genesis-env CLI does not require you to set any environment variables on your machine to run it. The variables you care about are the ones your application defines in its template.

How generate uses the template

The CLI reads the template from the project root, prompts once per variable (using optional defaults from KEY=value lines), then writes .env. It refuses to overwrite an existing .env without --force / -f (documented under Options / flags on the Commands page). Command forms (genv, genv generate, etc.) are on that page too.

Line rules: comments and blank lines are skipped. Each other line should define a variable, optionally with a default:

bash

# Comments are ignored
DATABASE_URL=
API_KEY=changeme
PORT=3000

Prompt text comes from each variable's name and optional default (the part after = on each line).

Template requirements

The template must live in the root directory (where you run the CLI).
The file must be UTF-8 encoded (UTF-16 is not supported).

`init` (scaffold)

Use genv init when you need a missing .env.template or a .gitignore entry for .env. Full syntax is under init on the Commands page. Typical messages include .env.template created, .gitignore created, or .env already ignored, depending on what already exists.

`validate`

Use genv validate after generate to confirm your local .env still matches the committed template. See validate on the Commands page.

Quick example: generate

bash

$ genv

Found .env.template

? DATABASE_URL:
? API_KEY (default: changeme):
? PORT (default: 3000):

Created .env

To overwrite an existing .env, use --force / -f as on the Commands page.

Why this flow

Saves time: no manual copying and editing of example env files.
Fewer missing keys: you walk through every key in the template before .env is written.
Easier onboarding: new contributors follow the same single command flow.
Runs locally: no network calls; nothing you type is sent anywhere.

Templates & .env