turf
Turf — a drop-in replacement for Terraform with agentic superpowers. Alpha binary releases (turf CLI + turf-mcp-server).
Install / Use
claude mcp add turfbuild -- npx -y github:turfbuild/turfIf the server publishes to npm under a different name, use that package instead — check the repo README.
MCP Server
Model Context Protocol server
Quality Score
Category
OperationsSupported Platforms
Our assessment of turf
turf scores 84/100 on our quality scale, 556th of 763 Operations skills we index.
Its MCP Server is 35 KB long, well organised into 51 sections with 24 code examples: a thorough specification that gives an agent plenty to work with.
It has 10 GitHub stars, so there is little community track record yet; judge it on its content.
Maintenance, license and trust
- The repository was last updated 4 days ago, so turf is actively maintained.
- It is released under MPL-2.0, a copyleft license: you can use it, but modified versions you distribute must carry the same license.
- Its trust signals score 97/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands.
Automated pattern scan on 2026-11-21. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
turf compared with similar skills
All 4 of these similar skills score higher than turf; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| turf (this skill)by turfbuild | 84 | 10 | 4d ago | MCP Server |
| Agent-Reachby Panniantong | 100 | 114.0k | today | CLAUDE.md |
| hyperframesby heygen-com | 100 | 88.2k | today | CLAUDE.md |
| rufloby ruvnet | 100 | 82.3k | today | CLAUDE.md |
| headroomby headroomlabs-ai | 100 | 80.5k | today | CLAUDE.md |
Frequently asked questions
- How do I install turf?
- Run
claude mcp add turfbuild -- npx -y github:turfbuild/turf. The install tabs above show the steps for each supported agent. - Which AI agents does turf work with?
- It is written for Claude Code and Claude Desktop, as a MCP Server file. Other agents that read the same format can often use it too.
- Is turf safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. It is MPL-2.0-licensed and scores 97/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is turf still maintained?
- The repository was last updated 4 days ago, so turf is actively maintained.
Skill content
View source on GitHubturf
An AI-powered infrastructure management CLI built on the turf MCP
server — the Terraform-compatible infrastructure engine built for AI
agents: full support for Terraform HCL and the module registry, driven by
an AI agent and governed by the plan. turf drives the server through
cagent to plan and apply changes against
any OpenTofu provider.
It is intended as a showcase: a small, readable example of how to wrap the turf MCP server in a polished UX. The server is the product; this CLI is one way to consume it. Here's the CLI in action:
<video src="https://github.com/user-attachments/assets/49d5d672-1c0e-41e2-a6d8-76c348dc6d5b" poster="https://github.com/user-attachments/assets/66f701a5-37cc-4ef8-9c2b-c1a8da61a21e" controls muted playsinline width="100%"></video>
Install
Homebrew (recommended) — macOS and Linux
Installs the turf CLI, turf-mcp-server, turf-engine and turf-builtin-provider
from the latest release, with restate-server from Restate's tap. Homebrew loads a formula
from a third-party tap only when you name it, so the command names both:
brew install restatedev/tap/restate-server turfbuild/tap/turf
brew services start turf # the engine, now and at every login
turf-mcp-server engine status # the health check
turf --version
The same command upgrades a 0.x install, where brew upgrade turf alone stops at
restate-server. Later upgrades are brew upgrade turf.
Turf is free for noncommercial use. Commercial use, including a company's internal use, needs a license: see License and https://turf.build/licensing.
From source
Build just the CLI from this repository (the source is MPL-2.0):
go install github.com/turfbuild/turf@latest # → a `turf` binary
# or, from a clone:
make build # → bin/turf
The CLI launches turf-mcp-server as a subprocess and must be able to find
it. Install the server separately and ensure it is on PATH:
# Verify the server is reachable
which turf-mcp-server
# Or point the CLI at a specific binary
export TURF_MCP_SERVER=/path/to/turf-mcp-server
The CLI and the server are released together and must be from the same release: turf
launches the server with its own release's flags (--deadline, the five minutes it gives
each convergence call), which an older turf-mcp-server rejects at startup. When that
happens turf names the binary it ran and says to point it at a matching one. Setting
TURF_DEADLINE in the environment replaces the five minutes (the CLI then passes no
--deadline, so the server reads the variable).
Connect your agent
turf-mcp-server is a stdio MCP server, and this CLI is one of its clients. Register it
with the agent you already use — Claude Code, Claude Desktop, Cursor, Codex, Gemini CLI,
VS Code — in one command: it detects the agents on this machine, lets you pick, and writes
each config with the server's absolute path (Node 18+;
add-mcp is Neon's open-source installer).
npx add-mcp@2 "$(command -v turf-mcp-server)" --name turf -g
Without Node, the agent's own command does the same:
claude mcp add turf --scope user -- turf-mcp-server # Claude Code
codex mcp add turf -- turf-mcp-server # Codex CLI
gemini mcp add -s user turf turf-mcp-server # Gemini CLI
code --add-mcp '{"name":"turf","command":"turf-mcp-server"}' # VS Code
In Claude Code and Claude Desktop, Turf runs on your Claude subscription — no model API key.
Turf's prompts are slash commands there: /turf:guide walks through a use case on a
real example, /turf:up path/to/config deploys or reconciles a configuration, and
/turf:destroy path/to/config tears it down (arguments are one word each). Every
other client takes the same requests in words. Per-client setup, scopes and env vars:
github.com/turfbuild.
Usage
The CLI is Turf's standalone agent: the same server and engine, driven by a model you bring (see Model providers).
# Interactive infrastructure management (TUI)
turf chat
# Get started with a use-case walkthrough (type inside the session)
turf chat # then: /guide
# Deploy from HCL configuration in the current directory
turf up
# ...or target another directory (like `tofu -chdir=DIR`)
turf -C ./examples/azure-storage-container up
# Destroy everything in a configuration
turf -C ./examples/azure-storage-container destroy
# Use a specific model
turf --model anthropic/claude-sonnet-5 chat
# Run a one-shot request without the TUI (see Scripting with exec)
turf exec "what workspaces exist?"
# Authenticate to a private registry or TFE-compatible host (see Credentials)
turf login app.terraform.io
turf logout app.terraform.io
Type /guide inside turf chat to get started with what Turf is for, on real examples from
turf-examples: deploy the NVIDIA AI Cluster Runtime
(AICR) on a kind cluster, take a node through the day-2 maintenance runbook as Terraform actions,
a product that installs itself, promotion across environments, your TACO as the control plane, and
deploying with guardrails (/guide day 2, /guide guardrails, …).
Flags
| Flag | Env | Default | Description |
|----------------------|-------------------------|-----------------------------|--------------------------------------------------------------------------------------------------------------|
| --model | TURF_MODEL | auto | LLM as a named model, provider/model, or auto (see Model providers) |
| --base-url | TURF_MODEL_BASE_URL | (provider default) | Model endpoint for OpenAI-compatible servers (vLLM, LM Studio, gateways) |
| --mcp-server | TURF_MCP_SERVER | (PATH lookup) | Path to the turf-mcp-server binary |
| --tmp-dir | TURF_TMP_DIR | system temp | Per-run scratch dir for the server (scratch configurations) |
| --plugin-cache-dir | TURF_PLUGIN_CACHE_DIR | <user cache>/turf/plugins | Shared provider plugin cache, kept across runs; off disables it |
| --memory-path | | ./.turf/memory.db | SQLite memory database |
| --no-memory | | false | Disable persistent agent memory |
| --session-db | TURF_SESSION_DB | ./.turf/sessions.db | SQLite session-history database (chat/exec resume via --session/--continue) |
| --no-session | | false | Disable session persistence and resume |
| --chdir, -C | | | Switch to this directory before running |
| --allow-path | TURF_ALLOW_PATH | | Extra directory the file tools may read and write (auto-approved); repeatable, or a path list in the env var |
| --worktree[=name] | | | Run in a fresh git worktree of the working directory, on a throwaway branch (--worktree=name names it) |
| --worktree-base | | (HEAD) | Branch the --worktree from this ref instead |
| --log-file | TF_LOG_PATH | (stderr) | Write server logs to this file |
| --log-level | TF_LOG_CORE, TF_LOG | info | trace/debug/info/warn/error/off |
| --log-format | TF_LOG -JSON suffix | text | text or json |
| --debug | TURF_DEBUG | false | Log turf's own debug lines to <TURF_HOME>/turf.debug.log (warnings and errors always go there) |
| --theme | TURF_THEME | stadium | TUI theme name; overrides the saved choice for this run |
| --lean | TURF_LEAN | false | Run chat in the lean TUI (up/destroy on a terminal always use it) |
Per command, up/destroy/exec also take --yes (alias --auto-approve), and turf/chat/exec take --session <id|-N> and --continue/-c.
The three --log-* flags are pass-throughs to the turf-mcp-server subprocess. When unset, the TF_LOG_* env vars (matching OpenTofu's convention) reach the server through environment inheritance. Provider plugins also inherit these vars, so TF_LOG_PROVIDER=DEBUG enables plugin-side debug logging into the same sink as the server.
Credentials
turf login <hostname> obtains an API token for a Terraform-compatible host — a
private module registry, or a TFE-compatible backend such as HCP Terraform or
Scalr — and turf logout <hostname> removes it again. Like tofu login, both
require an explicit hostname; neither guesses a default.
The token is written to credentials.tfrc.json in your OpenTofu/Terraform CLI
configuration directory, in the same format those tools write, so a
co-installed tofu or terraform reads exactly what turf stores (and vice
versa):
| Platform | Path |
|---|---|
| macOS, Linux | ~/.terraform.d/credentials.tfrc.json |
| Linux, fresh install with XDG_CONFIG_HOME set and no ~/.terraform.d | $XDG_CONFIG_HOME/opentofu/credentials.tfrc.json |
| Windows | %APPDATA%\terraform.d\credentials.tfrc.json |
The file is written with mode 0600, and any unrelated settings already in it
(plugin_cache_dir, provider_installation, other hosts) are preserved.
turf uses these credentials for its own host-facing requests too — remote-protocol
state backends (HCP Terraform, Scalr, TFE) and the provider registry — so one
turf login covers turf and a co-installed tofu/terraform alike.
Note: that consumption lives in
turf-mcp-serverand landed after v0.11.1. Against v0.11.1 or earlier the file is still written correctly and still servestofu/terraform, but the server itself authenticates anonymously. Check withturf-mcp-server --version.
Most hosts, including HCP Terraform and Scalr, do not implement the OAuth login
protocol, so turf login opens their user-token page and reads back the token
you paste. Hosts that do advertise a login.v1 service get a full OAuth 2.0
authorization-code flow with PKCE instead. Eith
Truncated for display — read the full file on GitHub.
Related Skills
Agent-Reach
114.0kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
hyperframes
88.2kAI video you can actually edit. HyperFrames is a free, open-source AI video editor. Describe any video and get a real project you can change down to the frame.
ruflo
82.3k🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
headroom
80.5kCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
