Templetry

Templetry Engine

The core of Templetry: a pure Go library + thin CLI that renders ready-to-work repositories from compilable templates.

_{Scaffold, edit, then update: the template's new commit is merged three ways (base render, your project, new render), so its changes land and your edit stays. Recorded from the real CLI against a small fixture template (see Development).}

Status: 🚀 stable v1 (latest release) — the manifest, directives, answers-file and registry schemas plus the CLI surface are stable public API under the compatibility policy (ADR-0013).

Since v1.0: templetry update (three-way merge), templetry verify in Docker, lazy pieces (pieces/add), YAML/TOML patches, feature requires/conflicts and presets, multi-forge template hosting (github:, gitlab:, gitea: source schemes) and the templetry-mcp server. Since v1.10 forms carry a taxonomy (kinds/languages/frameworks) and templetry list filters on it. Output paths are hardened against escapes and platform quirks; the directive scanner is fuzz-tested.

Principles (from the wiki)

• The engine doesn't know what a framework is — all knowledge lives in each template's template.yml (ADR-0002).
• Templates compile — three transformation mechanisms: identity-map renaming, comment directives, structured patches (ADR-0003).
• Pure core, effectful edges — deterministic: same inputs, byte-identical output.

Architecture

Package	Responsibility
manifest	Parse + validate template.yml, derive casings
source	Obtain the template as an in-memory FileSet
planner	(manifest, inputs, FileSet) → Plan — pure
ops	Operation types as data
render	Execute a Plan against a virtual file tree
verify	Run the template's verify command in Docker
update	The update cycle: re-render with recorded inputs, diff, three-way merge
answers	The .templetry-answers.yml record: one deterministic reader/emitter
piece	Lazy pieces (ADR-0014): decoupled units with their own lifecycle
cmd/templetry	Thin CLI: list, init, plan, render, verify, update, pieces, add, version
cmd/templetry-mcp	MCP server (stdio): the engine's verbs as tools for AI agents

Design rationale: study I · study II.

Install

Pick one (Homebrew, Scoop, the install script and the release archives also ship templetry-mcp):

1. Homebrew (macOS, Linux) — brew install Templetry/tap/templetry (tap).
2. Scoop (Windows) — scoop bucket add templetry https://github.com/Templetry/scoop-bucket then scoop install templetry (bucket).
3. Install script (macOS, Linux) — curl -fsSL https://raw.githubusercontent.com/Templetry/engine/main/install.sh | sh (see install.sh; TEMPLETRY_VERSION pins a tag, TEMPLETRY_BIN_DIR picks the folder).
4. Binary — download your platform's executable from Releases, rename it to templetry (or templetry.exe) and put it on your PATH.
5. Go toolchain — go install github.com/Templetry/engine/cmd/templetry@latest (installs to $(go env GOPATH)/bin).
6. From source — clone and go build -o templetry ./cmd/templetry.

Then:

templetry list                                  # browse the official catalog
templetry list --kind database --language go --tags   # filter it
templetry init kmp/single-module --out my-app \
  --set "project_name=My App" --set "base_package=com.me.myapp"
templetry plan --template <dir> --set key=value --feature name
templetry render --template <dir> --out <dir> --set key=value
templetry verify --template <dir> --set key=value    # render to a temp dir and compile it in Docker
templetry update ./my-app                            # preview a template update (--apply to write)
templetry pieces ./my-app                            # lazy pieces the template ships
templetry add axios-api ./my-app --set api_base=/v2  # adopt a piece into a living project

MCP server (AI agents)

templetry-mcp (in the same releases) speaks the Model Context Protocol over stdio — no dependencies, no configuration. It exposes seven tools: list_templates, get_form_schema, plan, render, update, list_pieces and add_piece, so an agent can browse the catalog, scaffold a ready-to-work project, adopt pieces and keep it all updated. Copy-paste configuration for the common clients follows; the server is a plain executable, so any other MCP client works the same way. It is listed on the official MCP registry as io.github.Templetry/templetry-mcp and published automatically after each release.

Where the binary is

If templetry-mcp is on your PATH, use the bare name templetry-mcp as the command. Some apps (Claude Desktop especially) do not inherit your shell PATH, so give them the absolute path:

Installed with	Path
Homebrew, Apple Silicon	/opt/homebrew/bin/templetry-mcp
Homebrew, Intel Mac / Linux	/usr/local/bin/templetry-mcp (Linux brew: /home/linuxbrew/.linuxbrew/bin/templetry-mcp)
install.sh	~/.local/bin/templetry-mcp (or /usr/local/bin/templetry-mcp when run as root); write the full home path in JSON, ~ is not expanded
Scoop (Windows)	C:\Users\<you>\scoop\shims\templetry-mcp.exe
Downloaded release binary	wherever you put it

where templetry-mcp (Windows) or command -v templetry-mcp prints the right one.

Claude Code

claude mcp add templetry -- templetry-mcp            # this project, private to you
claude mcp add --scope user templetry -- templetry-mcp   # every project
claude mcp list

Claude Desktop

Edit claude_desktop_config.json (Settings > Developer > Edit Config; macOS ~/Library/Application Support/Claude/, Windows %APPDATA%\Claude\) and restart the app:

{
  "mcpServers": {
    "templetry": {
      "command": "/opt/homebrew/bin/templetry-mcp"
    }
  }
}

On Windows use "command": "C:\Users\<you>\scoop\shims\templetry-mcp.exe".

Cursor

.cursor/mcp.json in a project, or ~/.cursor/mcp.json for all projects:

{
  "mcpServers": {
    "templetry": {
      "command": "templetry-mcp"
    }
  }
}

VS Code

.vscode/mcp.json in the workspace (or "MCP: Open User Configuration" for every workspace). Note the key is servers, not mcpServers:

{
  "servers": {
    "templetry": {
      "type": "stdio",
      "command": "templetry-mcp"
    }
  }
}

The server takes no arguments and no environment; to work against a private catalog the agent passes registry on each tool call.

Documentation

Usage guides live in the wiki: getting started, using templates, using pieces, keeping projects updated, authoring templates, AI agents and MCP. Normative behaviour is in spec/.

Development

go build ./...
go test ./...          # CI also runs -race and golangci-lint v2

update merges with git merge-file, so git must be on PATH for its tests. No test touches the network or needs Docker:

• internal/forgetest is an in-memory GitHub (codeload tarballs and the commits API) behind http.DefaultClient, so init → edit → update runs end to end against templates the test publishes, commit by commit.
• internal/fakedocker puts a copy of the test binary on PATH as docker, recording what verify would have run.
• Both binaries are tested in-process: templetry through run(args, stdout, stderr) and templetry-mcp through serve(in, out), a JSON-RPC session over pipes.

The demo above is recorded the same way, so it always shows real output. To regenerate it:

TEMPLETRY_DEMO_CAST=$PWD/docs/demo.cast go test ./cmd/templetry -run TestRecordDemo -count=1
npx [email protected] --in docs/demo.cast --out docs/demo.svg --window --no-cursor

License

Apache License 2.0 — use it for anything, including commercially, with an explicit patent grant. The templates and the desktop app live in their own repos under MIT.