Turf

turf

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:

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

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

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):

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-server and landed after v0.11.1. Against v0.11.1 or earlier the file is still written correctly and still serves tofu/terraform, but the server itself authenticates anonymously. Check with turf-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. Either way turf shows you where the token will be stored and asks for confirmation before writing it.

For CI, pipe the token instead of typing it:

echo "$TFE_TOKEN" | turf login --token-stdin tfe.example.com

Prefer a pipe over a herestring (<<<), which materializes the token in a temporary file in some shells. Without --token-stdin, turf login refuses to run with stdin redirected rather than hanging on a prompt nobody can answer.

Precedence when a host is configured more than once follows OpenTofu's: a TF_TOKEN_<hostname> environment variable wins over the credentials file, which wins over a credentials helper. turf login warns when the token it is about to write would be shadowed by such a variable, and turf logout warns when one will keep authenticating you after the stored token is gone.

Two limitations relative to tofu login: turf does not detect a credentials block hand-written in .terraformrc/.tofurc (such a block silently keeps winning over the file turf writes), and it does not support credentials helpers. Note also that turf logout only forgets the token locally — it does not revoke it on the host, so revoke it there if it has leaked.

Scripting with exec

turf exec runs a single natural-language request against the model (set with --model) without launching the TUI, streaming the run to stdout. It is the entry point for driving turf from a script, a CI job, or another agent — the same real model and tools as chat, just headless.

# A message argument — quoting is optional; words are joined into one request
turf exec create a random_pet named demo
turf exec "create a random_pet named demo"

# Use -- to pass a message that begins with a dash
turf exec -- --dry-run first, then apply

# Read the request from stdin
echo "what workspaces exist?" | turf exec
turf exec - < request.txt

The process exits non-zero if the run fails, so exec composes with normal shell error handling (set -e, &&, CI steps).

--json — machine-readable event stream. With --json, turf emits one JSON object per line for every runtime event (agent text, tool calls, tool results, warnings, errors) instead of formatted text. This is the reliable way to assert on a run from a script even though model prose is non-deterministic — you match on structure (which tools ran, whether an error occurred), not wording:

# Which turf tools did the run invoke?
turf exec --json "create a random_pet" | jq -r 'select(.type=="tool_call") | .tool_call.function.name'

# A failed run exits non-zero; its error goes to stderr, not into the event stream
turf exec --json "reconcile the stack" > events.jsonl || echo "run failed" >&2

--yes / --auto-approve — unattended runs. exec is non-interactive, so nobody can answer the agent's approval questions. Without --yes they are declined: anything that needs your yes — a destroy, a replace, an import, an invoke — is not applied and stays waiting at its approval point, where a later interactive turf can pick it up. (The agent still approves a low-risk plan — only creates and in-place updates — itself, as it does at a terminal.) --yes answers those questions yes, and approves any other tool call that would ask on stdin, so the run proceeds with no human at the keyboard. turf's own tools never ask for permission. The same rule holds for turf up and turf destroy run without a terminal (a pipe, CI). Use --hide-tool-calls to print only the agent's prose.

exec still launches turf-mcp-server, so it must be on PATH (see Install). For repeatable runs with no cloud credentials or cost, point it at HCL using OpenTofu's credential-free providers (null, local, random, tls).

Model providers

turf runs on any model provider that Docker's docker-agent runtime supports — select one with --model provider/model (env TURF_MODEL). The default is auto: turf picks the first provider whose credentials are set, falling back to a keyless local model, so it runs out of the box — pin a specific default in turf.yaml. Docker's providers overview lists the full matrix and each provider's exact configuration.

turf needs a tool-calling model. Every turf action runs through tools, so the model must support tool (function) calling. The cloud models below all qualify; for local models, choose a tool-capable one (see below) — a model without it fails with does not support tools.

Local models — no API key, no cost

Run the model entirely on your own machine — no API key, no cost, and your infrastructure prompts stay off third-party APIs. Local models need two things configured that cloud models do not: a tool-capable model, and a context window large enough for turf's prompt.

turf's prompt is ~27k tokens before you type anything. turf exposes two dozen infrastructure tools plus their workflow instructions, and that goes in every request. Docker Model Runner's default window is far smaller, so an unconfigured local model rejects turf's very first message with exceeds the available context size. Set context_size and it works.

Docker Model Runner (bundled with Docker Desktop) — pull the model, then declare it in a turf.yaml:

docker model pull ai/qwen3     # once — fetch the model

# ~/.turf/turf.yaml (global) or <project>/.turf/turf.yaml
model: local

models:
  local:
    provider: dmr
    model: ai/qwen3
    provider_opts:
      # turf's own prompt is ~27k tokens, so Model Runner's default window
      # rejects the first request. 64k leaves working room for plan and state
      # tool results. Lower it if the model won't fit in memory — the engine
      # reserves cache for the whole window up front, so memory use scales
      # with this number.
      context_size: 65536

Then just turf chat. The config file is required for this: context_size is a per-model setting, so --model dmr/ai/qwen3 on its own cannot carry it and will fall back to the runner's default window. turf discovers the local Model Runner automatically; set MODEL_RUNNER_HOST to point at a remote runner. See Docker's Model Runner guide.

Ollama (if you already run it):

turf --model ollama/llama3.2   # defaults to http://localhost:11434

Ollama has the same context problem but a different knob — provider_opts does not reach it. Size its window with OLLAMA_CONTEXT_LENGTH (or num_ctx in a Modelfile) before starting the server.

Pick a tool-capable local model — DMR's ai/qwen3, or on Ollama one of llama3.1/llama3.2, qwen2.5, or the mistral family. Older or smaller builds (plain llama3, tiny 1B GGUFs) often lack tool support and fail with does not support tools.

Cloud providers

Export the matching API key, then select the model. A representative set:

turf inherits docker-agent's full provider list — including Azure OpenAI and GitHub Copilot. See the providers overview for every option.

Custom OpenAI-compatible endpoints

For any OpenAI-compatible server (vLLM, LM Studio, an internal gateway), use the openai provider and override the endpoint with --base-url (env TURF_MODEL_BASE_URL):

turf --model openai/my-model --base-url http://localhost:8000/v1

Configuration file (turf.yaml)

Beyond the flags, a project can pin its model configuration in a turf.yaml, read from two locations in increasing precedence (project overrides global):

• ~/.turf/turf.yaml — per-user global (override the home dir with TURF_HOME)
• <project>/.turf/turf.yaml — versioned alongside your infra config

Overall model precedence is --model / TURF_MODEL > turf.yaml model: > auto. A minimal file:

# Default selector: a named model below, an inline provider/model, or "auto".
model: smart

models:
  # Try each candidate in order; pick the first whose credentials are set. A
  # candidate is an inline provider/model OR the name of another entry here —
  # which is how the local fallback below keeps its provider_opts.
  smart:
    first_available:
      - anthropic/claude-sonnet-5
      - openai/gpt-4o
      - local                 # keyless local fallback (defined below)
  # Docker Model Runner. context_size is required for local models: turf's own
  # prompt is ~27k tokens and the runner's default window is far smaller. See
  # Local models above.
  local:
    provider: dmr
    model: ai/qwen3
    provider_opts:
      context_size: 65536
  # A named model that targets a custom provider (defined below).
  house:
    provider: myhouse
    model: my-model

# Custom providers, referenced by models by name — e.g. an internal
# OpenAI-compatible gateway. Credentials are read from the named env var.
providers:
  myhouse:
    provider: openai
    base_url: https://gateway.internal/v1
    token_key: MY_HOUSE_KEY

The models: and providers: values follow docker-agent's model/provider schema, so per-model tuning fields (temperature, max_tokens, …) and a top-level models_gateway: work here too. The same file also carries the branding: overlay. For a complete project, see the CLI configuration example.

Troubleshooting

turf won't start

could not start the model … API key … is required — turf could not reach an LLM. Either set the key for your provider, or switch to a keyless local model — which needs a turf.yaml, not just a --model flag (see Local models).

unknown provider … / invalid model format … — --model must be a named model from turf.yaml or a provider/model ref (e.g. anthropic/claude-sonnet-5, google/gemini-pro-latest). Check the prefix against the providers overview.

turf-mcp-server not found on PATH — the CLI launches the server as a subprocess and must find it. Install it and put it on PATH, or point at it explicitly (see Install):

export TURF_MCP_SERVER=/path/to/turf-mcp-server

model failed: … does not support tools

turf drives everything through tools, so the model must support tool (function) calling — many local models don't. Switch to a tool-capable model: DMR's ai/qwen3, or on Ollama one of llama3.1/llama3.2, qwen2.5, or mistral rather than plain llama3. See Model providers.

model failed: … exceeds the available context size

A local model is running with a context window smaller than turf's prompt. turf sends ~27k tokens before you type anything (two dozen infrastructure tools and their workflow instructions), and Docker Model Runner's default window is far smaller — so the very first message is rejected.

Declare the model in a turf.yaml with a context_size that fits, then run turf chat with no --model flag — the setting is per-model, so --model dmr/ai/qwen3 alone cannot carry it:

model: local
models:
  local:
    provider: dmr
    model: ai/qwen3
    provider_opts:
      context_size: 65536

See Local models. On Ollama the equivalent knob is OLLAMA_CONTEXT_LENGTH.

The machine bogs down while a local model runs

The inference engine reserves cache for the whole context window up front, so memory use scales with context_size — a large window on a large model can exhaust RAM and push the machine into swap. Lower context_size (32768 is the practical floor given turf's ~27k prompt) or pick a smaller model.

Theming

turf ships five built-in terrain themes — a play on turf's own name, the astroturf pun: the same astroturf imagined in a different terrain, each palette drawn from that place's natural objects. The terrain tints the HCL syntax colors and the create / destroy / change status colors, but those keep their meaning (create stays green, destroy red, change amber) so a plan stays legible:

The default is stadium. cagent's built-ins (and the legacy calm-roots) remain selectable in the theme picker: /settings → Appearance → Theme in turf chat (there is no /theme command). Themes are loaded and saved from turf's own config home — ~/.turf (override with TURF_HOME) — so turf never reads or writes ~/.cagent.

To use a custom theme, drop a YAML file at ~/.turf/themes/<name>.yaml and pick it in the theme picker (/settings → Appearance → Theme). A partial file is merged onto the built-in default, so you only specify the colors you want to change. Edits hot-reload while the picker is open, and your selection persists across restarts.

To preview a theme without changing your saved choice, launch with --theme (or set TURF_THEME):

turf --theme tokyo-night chat

# ~/.turf/themes/my-brand.yaml
version: 1
name: "My Brand"
colors:
  text_primary: "#C0C0C0"
markdown:
  heading: "#7AA2F7"
  link: "#7AA2F7"

Co-branding

A distributor can give turf their own look and voice without forking it, using a branding: section in turf.yaml. It merges from the same two locations, so a brand can be set once per machine (~/.turf/turf.yaml) or per project (<project>/.turf/turf.yaml), and a project file can override a single key while inheriting the rest.

branding:
  # Default theme — a theme *ref*, not a path: one of turf's terrain themes, or
  # your own dropped at ~/.turf/themes/<name>.yaml (see Theming).
  theme: surf

  # Welcome banner for the lean TUI, as a path relative to this turf.yaml.
  # Plain text is fine — each line is drawn in the theme's accent color.
  banner: taco-banner.txt

  # Replaces turf's built-in chat welcome text.
  welcome_message: |
    Welcome to Taco — infrastructure management with governance built in.

  # Appended to turf's persona as extra standing guidance.
  additional_instructions: |
    Treat platform policy as a gate: evaluate the plan against the workspace's
    policy set before asking the user to approve it.

Branding is look and voice only — it does not rename turf. There is no name key: the binary, the TUI status bar, and the agent badge all still say turf, so a co-branded turf is still recognizably turf. The tool namespace is likewise fixed at turf_* (the timeline renderers, the /tools grouping, and the pre-approval allow-list all depend on it), and no gate is relaxed — the pre-approved tool list, the mutation confirmations, and the filesystem sandbox are all in code.

Two things worth knowing. theme: sets the default — a theme saved in the picker and --theme both still win, so a user keeps control of their own look. And additional_instructions is prompt content from a config file: it can steer the agent's behavior, so treat a turf.yaml from an untrusted source with the same care as any script you would run. A misconfigured brand degrades rather than fails — an unreadable banner or theme falls back to turf's own with a warning.

For worked examples, see the integrations in the examples repo.

Skills

You can teach turf your own procedures by dropping SKILL.md files into turf-owned locations. Each skill is a directory:

~/.turf/skills/<name>/SKILL.md          # global: org best practices, migration playbooks
<project>/.turf/skills/<name>/SKILL.md  # project: versioned alongside your infra config

turf scans only these two locations (override the global one with TURF_HOME) — it never reads ~/.claude, ~/.codex, or ~/.agents. A project skill overrides a global skill of the same name. The working-dir location is exactly <cwd>/.turf/skills — there is no walk up the tree, so what loads is predictable from where you launch turf.

A SKILL.md needs YAML frontmatter with at least name and description (the description is what turf matches a request against). Keep the body lean and push detail into supporting files, loaded on demand:

---
name: azure-migration
description: Adopt hand-built Azure resources into managed state. Use when the user says "adopt" or "import our existing".
# context: fork   # optional — run this skill as an isolated sub-agent
---

# Azure migration playbook

Adopt-then-reconcile; never create before importing.

1. Import each existing resource (ID formats: see references/import-ids.md).
2. Plan — an `adopt id=…` row with no change means clean adoption; `~` or `-/+` means drift to reconcile.

~/.turf/skills/azure-migration/
  SKILL.md
  references/
    import-ids.md      # loaded on demand when the skill needs it

These are separate from turf's built-in infrastructure workflows (which the agent already knows) — your skills add to them, they don't replace them.

For a working project skill you can copy, see the CLI configuration example.

Architecture

turf (this binary)                      your agent (Claude Code, Cursor, Codex, …)
   │                                       │
   │  cagent runtime + LLM                 │  the agent's own model
   │  (local via Docker Model Runner /     │
   │   Ollama, or cloud: Anthropic /       │
   │   OpenAI / Google / …)                │
   ▼                                       ▼
turf-mcp-server (separate binary, on PATH; MCP over stdio)
   │
   ▼
the Turf engine (turf-engine + restate-server; `brew services start turf`)
   │
   ▼
OpenTofu providers (downloaded on demand)

The CLI never imports turf's server code. The only contract is the MCP protocol spoken over stdio.

Examples

Runnable examples live in turfbuild/turf-examples.

• Configuring the CLI — a per-project turf setup: a .turf/turf.yaml with credential-based first_available model fallback and named models, plus a project .turf/skills/ skill. Copy it as a starting point for your own .turf/ directory.
• Infrastructure configurations — ordinary HCL you drive with turf -C <dir>: a local Kubernetes kind cluster (CRD + custom resource, or a Helm release; credential-free, Docker only), Azure and GCP modules, and language/feature tours (Terraform Actions, Turf-native actions).

License

The turf CLI — the source in this repository — is the Covered Software, licensed under the Mozilla Public License 2.0 (MPL-2.0). See LICENSE. Copyright © The Turf Authors.

Turf as a whole — this CLI combined with turf-mcp-server, turf-engine and turf-builtin-provider, distributed together in every release archive and by the Homebrew formula — is the MPL-2.0 Larger Work, licensed under the PolyForm Noncommercial License 1.0.0 (SPDX: PolyForm-Noncommercial-1.0.0). MPL-2.0 expressly permits combining the Covered Software into such a Larger Work under other terms.

• Free for personal use, research, study, and for educational, public research, charitable and government institutions.
• Commercial use requires a license, including use inside a company. Free 60-day evaluations and production subscriptions are available; see https://turf.build/licensing or email [email protected].

turf license prints the license and the third-party notices (NOTICE); turf --version states the license in one line.

Telemetry

Turf sends anonymous usage telemetry to Turf LLC by default: the version, the platform, counts of resources, changes and runs, and an anonymous installation id. It never includes resource contents, credentials, state, variable values or names. The Turf engine sends it; the CLI and the components Turf is built on send nothing. The field list and the endpoint are in docs/telemetry.md and at https://turf.build/telemetry.

• turf telemetry off turns it off, then restart the engine: brew services restart turf. turf telemetry status shows the setting and the installation id.
• TURF_TELEMETRY=off or DO_NOT_TRACK=1 in the engine's environment also turns it off. For the Homebrew service that environment is turf.env (~/.homebrew/services/turf.env), not your shell.
• With Homebrew's analytics off (brew analytics off or HOMEBREW_NO_ANALYTICS), the Homebrew service starts with it off.