twf-cli

Design, visualize, and implement entire Temporal systems — namespaces, workers, workflows, and Nexus — as a validated, visual source of truth.

Write your architecture in .twf and a real parser, language server, and visualizer give you (and your AI agent) compiler-grade feedback on the whole system before you write a line of SDK code — then generate the workers and provision the infra from the same design.

• Catch design errors before code. A real parser and language server validate the whole system — undefined activities, broken Nexus routing, misplaced determinism — while it's still a design, not a production incident.
• See the whole deployment. An interactive graph of namespaces → workers → workflows, plus a tree view that expands calls inline. Architecture you can actually look at.
• One parseable source of truth. .twf is a file every teammate and every tool reads and validates — not architecture prose buried in a prompt.
• Design → running system. Generate Temporal Go SDK code and provision control-plane infra from the same .twf — or recover a deployment graph straight from production history with the sampler.

activity ReserveFunds(amount: Money) -> (Hold):
	reserve(amount)

activity CaptureFunds(hold: Hold) -> (Receipt):
	capture(hold)

workflow ChargeOrder(order: Order) -> (Receipt):
	signal Cancel():
		close fail("cancelled")

	activity ReserveFunds(order.amount) -> hold
		options:
			start_to_close_timeout: 30s
	activity CaptureFunds(hold) -> receipt
	close complete(receipt)

worker billing:
	workflow ChargeOrder
	activity ReserveFunds
	activity CaptureFunds

namespace payments:
	worker billing
		options:
			task_queue: "billing"

Workflow logic, the worker that hosts it, and the namespace topology — one readable file.

twf-cli is a thin wrapper around the bundled platform binary — same tool, same flags, same output as the standalone twf distribution, installable via pip.

Install

pip install twf-cli
twf --help

The wheel for your platform ships the matching twf binary. Supported platforms (one wheel each): macosx_11_0_arm64, macosx_10_15_x86_64, manylinux2014_x86_64, manylinux2014_aarch64, win_amd64.

The twf CLI

A single Go binary: parser, validator, deployment-graph extractor, and a full LSP server. Every command and flag is discoverable via twf --help and twf <command> --help.

Common options: --json (structured output) and --lenient (continue past resolve errors). The language server adds real-time diagnostics, completions, hover, go-to-definition, references, rename, code actions, folding, inlay hints, semantic tokens, and signature help.

Use as an MCP server

twf mcp runs a Model Context Protocol server over stdio — the agent entry point. The examples below launch it through npx, so Node.js and npm must be installed and npx must be available on PATH.

Claude Desktop

Add the twf entry to the existing mcpServers object in the Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "twf": {
      "command": "npx",
      "args": ["-y", "@temporal-architect/twf", "mcp"]
    }
  }
}

Restart Claude Desktop after saving the file.

Cursor

Create .cursor/mcp.json in a project to enable twf for that project, or use ~/.cursor/mcp.json to enable it globally. Both locations use the same Cursor MCP configuration shape:

{
  "mcpServers": {
    "twf": {
      "command": "npx",
      "args": ["-y", "@temporal-architect/twf", "mcp"]
    }
  }
}

Continue

Create .continue/mcpServers/twf.yaml at the top level of the workspace. Continue's standalone MCP blocks require the name, version, and schema metadata fields:

name: TWF MCP server
version: 0.0.1
schema: v1
mcpServers:
  - name: twf
    command: npx
    args:
      - "-y"
      - "@temporal-architect/twf"
      - "mcp"

The tools (twf_check, twf_parse, twf_symbols, twf_graph, twf_graph_chunks, twf_fmt, twf_spec_list, twf_spec_get) are thin wrappers over the same parser pipeline as the CLI, so their JSON is identical. twf_fmt returns the text twf fmt would write and writes nothing. The embedded language specification is exposed as resources at twf://spec and twf://spec/<slug>.

Subprocess use from Python

import subprocess, json

result = subprocess.run(
    ["twf", "parse", "workflow.twf"],
    capture_output=True, text=True, check=True,
)
ast = json.loads(result.stdout)

Versioning

Versions track the upstream temporal-architect Git tag, so 0.3.x of this package corresponds to v0.3.x of the toolchain.

License

MIT. See LICENSE.