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](https://github.com/Templetry/engine/releases/latest)) — 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

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 --set key=value --feature name templetry render --template --out --set key=value templetry verify --template --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:

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\ \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 svg-term-cli@2.1.1 --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.